General Information about Spatial Searches

For an overview and a list of Spatial Search functions, see Spatial Searches.

The functions described in this section allow for spatial searches of structure networks. The portion of the structure network to be searched is specified, and a set of filters much like the invisibility and highlight filters are specified to limit the set of eligible primitives. A search aperture is also specified. The first output primitive that satisfies the filter criteria and is within the search aperture is returned.

Search Context

For an overview and a list of Spatial Search functions, see Spatial Searches.

A search context is a PEX resource that contains all of the search criteria to be used when spatially searching a structure network. Two of the attributes that specify search criteria contain name set resource identifiers. If name sets are created, bound to a search context, then freed, the contents of the name sets remain, because they are still referenced by the search context. However, if the search context is queried, the value PEXAlreadyFreed is returned for any such freed name sets, because they no longer have valid resource identifiers by which they can be referenced.

A search context resource contains the following attributes. All attributes became available with PEX 5.0, except text font table, which became available in PEX 5.2:

search position

specifies the search reference position in world coordinates.

search distance

specifies a distance from the search reference position in world coordinates. The search position and distance specify a search aperture. Whether the aperture is considered to be a sphere or a cube is implementation-dependent. If the search distance is less than or equal to zero, a primitive must intersect the search position to be considered within the search aperture.

start path

defines the structure network path used as the starting point for the search. The search traversal begins at the element following the one indicated by the start path.

search ceiling

defines the ceiling of the search operation. The search ceiling is an index into the list of element references contained in the search start path. Index one refers to the first path element in the list. Searching stops when the end of the structure specified by the search ceiling is reached. If the ceiling is one, the search effectively operates without a ceiling and terminates at the end of the first structure in the start path.

model clip flag

specifies whether model clipping must be performed during the search operations. If True, modeling clipping is performed using the modeling clipping attributes as they are encountered during the search traversal. If False, no model clipping is performed and model clipping attributes encountered during the traversal are effectively ignored.

normal list

a list of name set resource identifier pairs. Each pair of name sets is considered to be a filter to be used in the search traversal. A primitive's name set attribute must have at least one name in common with the inclusion name set of each filter, and must have no names in common with the exclusion name set of each filter, to be eligible for the search.

inverted list

a list of name set resource identifier pairs. Each pair of name sets is considered to be a filter that is inverted and used in the search traversal. A primitive's name set attribute must have no names in common with the inclusion name set of each inverted filter, or must have at least one name in common with the exclusion name set of each inverted filter, to be eligible for the search.

text font table

A resource identifier of the text font table which is used to resolve references by Text Font output commands. When the text font table is Null, the font assumed by the implementation is implementation-dependent. If you wish to reference no text font table, use the null resource identifier None. (PEX 5.2)

Use the PEXSearchNetwork function to perform a search operation once all of the search criteria attributes have been established. To search, the structure network specified is conceptually traversed starting at the element following the element specified by the start path. Each output primitive is transformed to world coordinates and compared against the search aperture to determine proximity. For text and annotation text primitives, only the transformed origin of the text string is used to determine proximity. If the transformed primitive's geometry places it within the search aperture, its name set attribute is checked against the normal list and against the inverted list to determine eligibility.

The search is successful if an output primitive is found which satisfies the search filter criteria and is within the search aperture. The path to the first such primitive found is returned, and the start path attribute of the search context is set to the found path. This allows the next search operation on the same search context to continue from just after the found primitive.

If no such primitive is found before the end of the structure indicated by the search ceiling is reached, then the search is unsuccessful, NULL is returned as the found path, and the start path attribute is not changed.