Function Name: Determine Spatial Inclusion

Definition

Determines whether a SEDRIS object is contained within the user-specified spatial area. SE_DetermineSpatialInclusion() supplements the normal method of filtering objects by spatial location, i.e. the use of search boundaries with component iterators (see SE_CreateSpatialSearchBoundary() ).

While SE_DetermineSpatialInclusion() can be used with any SEDRIS object, its intended use is to find out more information about the relationship of an object returned by a component iterator to the search bounds used in that iterator. The canonical example is to have the component iterator created with a partial inclusion choice, then to check objects for full inclusion with SE_DetermineSpatialInclusion().

In addition to determining whether a SEDRIS object is partly or completely inside the user-defined search bounds, this function, unlike an SE_SEARCH_BOUNDARY, will also determine whether a 2- or 3-dimensional object completely includes the spatial search area.

Returns

SE_NULL_REQUIRED_PARAMETER - and none of the output parameters are modified, if search_bounds_ptr is NULL, or if all the output parameters are NULL.

SE_UNRESOLVED_START_OBJECT - if object_in is an unresolved SEDRIS object. In this case, *object_fully_included_out_ptr, *object_partly_included_out_ptr, and *object_includes_search_bounds_out_ptr are set to SE_FALSE if provided.

SE_UNRESOLVED_OBJECT - and the output parameters are set as for SE_UNRESOLVED_START_OBJECT, if an unresolved object was encountered and could not be resolved.

SE_FAILURE - and the output parameters are set as for SE_UNRESOLVED_START_OBJECT, if

1. an invalid boundary was specified by the bounds parameter (e.g., the minimal and maximal points aren't in the same SRF),
2. if an invalid search_bounds_closure, search_quality, or search_dimension was specified, or
3. the determination of the object/search area relationship couldn't be made, or
4. the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

Prototype

Parameters Notes

object_in

 the object to test for inclusion.

search_bounds_ptr

 the boundary definition; defines the spatial search
    area by ranges in each of its coordinates. If the search is 2-D, then
    the height values are ignored. See SE_SEARCH_BOUNDS for more details.

search_bounds_closure

 determines whether the spatial search area
    includes its boundaries. See SE_SEARCH_BOUNDS_CLOSURE_ENUM for more
    details.

search_quality

 determines whether to use a point, bounding box, or exact
    search. See SE_SEARCH_QUALITY_ENUM for more details.

search_dimension

 whether 2D, 3D, or both kinds of objects are
    considered. See SE_SEARCH_DIMENSION_ENUM for more details.

object_fully_included_out_ptr

 a pointer to an SE_BOOLEAN
    variable in the user's memory space, used to indicate whether
    the object is strictly included in the search bounds.

object_partly_included_out_ptr

 a pointer to an SE_BOOLEAN
    variable in the user's memory space, used to indicate whether
    the object's intersection with the search bounds is non-empty.
    If NULL, no check is made for partial inclusion.

object_includes_search_bounds_out_ptr

 a pointer to an
    SE_BOOLEAN variable in the user's memory space, used to indicate whether
    the object's intersection with the search bounds is the search area
    itself.

  Note that *object_includes_search_bounds_out_ptr can only be true in
  the following cases:
  - search_dimension is set to SE_2D_SEARCH and the object is an aggregate
    containing a <Feature Face>, <Surface Geometry>, <Data Table>, or
    <Volume Geometry>

  - search_dimension is SE_3D_ONLY_SEARCH and the object is an aggregate
    containing a <Volume Geometry> or <Data Table>.

  Otherwise the question is meaningless (a point or linear object can't
  contain a region).