Entity Boxing

From DocR21

An ENTITY box is a rectangular bounding box, aligned with the axes, that completely contains a topological entity. A bounding box is not necessarily of minimal size because it is often much faster to calculate a loose box than a tight box. It is possible to obtain bounding boxes with different levels of tightness.

Interfaces

Each topological entity that possesses a bounding box has a bound() method. This will return a pointer to the cached bounding box associated with the entity. If a particular bounding box has not been calculated or has been invalidated, the bound() method will return a NULL pointer. So we suggest that, rather than using the bound() method, you use one of the global functions (defined in getbox.hxx) listed in the table below. Each function in the table returns the bounding box associated with a topological entity if the bounding box pointer is non-NULL, or will calculate one for you if the pointer is NULL. The functions can also be called with a tightness flag which will compute a tighter box than the default cached box.

In addition to the above functions, there are also API functions (defined in intrapi.hxx) called api_get_entity_box that calculate bounding boxes. The recommended API is

outcome api_get_entity_box( const ENTITY_LIST   &ent_list,
                    SPAposition         &min_pt,
                    SPAposition         &max_pt,
                    SPAboxing_options   * box_options,
                    AcisOptions         * ao)

which takes a SPAboxing_options as input. There is also a similar API which takes an ENTITY* instead of an ENTITY_LIST&.

The SPAboxing_options argument allows you to specify a working coordinate system (WCS) in order to compute the bounding box relative to that WCS. The boxing options also enable you to specify the tightness of the computed box by setting a SPAboxing_mode.

The settings for the SPAboxing_mode are

A loose box is the quickest bounding box that can be computed. It can be much bigger than a tight or exact box.

A tight box aims to obtain a closer fit to the entity. The API guarantees to return the tightest bounding box for toroidal faces by default. To obtain the tightest bounding box for spherical or spline faces you should set the boxing mode to SPAboxing_tight in the SPAboxing_options argument.

An exact box shrink-wraps a body so that each face of the box touches the body. Likewise, an exact box of a face encloses the face so that the box touches the edges of the face. An exact box will take longer to compute than a tight or loose box.

Tips

• For good performance do not use an exact box unless you really need one. For most uses, a default box is adequate and since these are cached, they may already have been computed.

Scheme Example (Torus boxes)

In the following Scheme example, we construct two bounding boxes for a toroidal BODY. The first is a loose box which is simply the box containing the entire torus surface. The second box is the default torus box which is tight.

(define tor (solid:torus 0 0 0 50 20))
(define blk (solid:block 0 -100 -50 100 100 50))
(bool:subtract tor blk)
(define blk2 (solid:block -100 0 -50 100 100 50))
(bool:subtract tor blk2)
; Compute a loose box around the toroidal BODY
(define bx1 (entity:box-new tor #t "loose"))
; Compute a default (tight) box around the toroidal BODY
(define bx2 (entity:box-new tor #t "default"))

Scheme Example (Spline boxes)

This Scheme example shows that the tight box for a spline FACE is not always particularly tight. The tightest box is obtained by using the "exact" flag.

; Create a spline grid face.
(define grid (splgrid))
(define points1 (list
    (position -50 -50 0) (position 0 -50 50)
    (position 50 -50 0) (position -50 0 50)
    (position 0 0 100) (position 50 0 50)
    (position -50 50 0) (position 0 50 50)
    (position 50 50 0)))
(splgrid:set-point-list grid points1 3 3)
(define vectors1
    (list (gvector 1 0 1)
    (gvector 1 0 1) (gvector 1 0 1)))
(splgrid:set-u-tanvec-list grid vectors1 #t)
(set! vectors1
    (list (gvector 1 0 -1)
    (gvector 1 0 -1)
    (gvector 1 0 -1)))
(splgrid:set-u-tanvec-list grid vectors1 #f)
(define vectors2
    (list (gvector 0 1 1)
    (gvector 0 1 1) (gvector 0 1 1)))
(splgrid:set-v-tanvec-list grid vectors2 #t)
(set! vectors2
    (list (gvector 0 1 -1)
    (gvector 0 1 -1) (gvector 0 1 -1)))
(splgrid:set-v-tanvec-list grid vectors2 #f)
(define grid1 (face:spline-grid grid #t))
; Compute a tight box around the spline FACE
(entity:box-new grid1 #t "tight")
; Compute an exact box around the spline FACE
(entity:box-new grid1 #t "exact")

Scheme Example (Effect of a transform)

Applying a transform to an ENTITY can have a dramatic effect on the resulting bounding box. Applying a rotation to the torus example we can see that both the loose and tight boxes do not enclose the toroidal BODY closely. A truely tight box is achieved by the exact box.

(define tor (solid:torus 0 0 0 50 20))
(define blk (solid:block 0 -100 -50 100 100 50))
(bool:subtract tor blk)
(define blk2 (solid:block -100 0 -50 100 100 50))
(bool:subtract tor blk2)
(define tr (transform:rotation (position 5 5 5) 30))
(entity:transform tor tr)
; Compute a loose box around the toroidal BODY
(define bx1 (entity:box-new tor #t "loose"))
; Compute a default (tight) box around the toroidal BODY
(define bx2 (entity:box-new tor #t "default"))
; Compute an exact box around the toroidal BODY
(define bx3 (entity:box-new tor #t "exact"))

Note: When boxing entities with transforms applied, a tighter fitting bounding box may be obtained if the transforms are fixed by applying api_change_body_trans (or in Scheme entity:fix-transform).

Implementation

• SchemeExt:entity:box-new - exercises api_get_entity_box.

See Also

• Entity Extrema