SpatialQuery (interface)

The SpatialQuery interface wraps a temporary query object that holds the spatial query context for a given SpatialQueryable geometry. To be valid, this query object needs to be used between a SpatialQueryable.beginSpatialQuery and SpatialQueryable.endSpatialQuery bracket, which allows to recycle the SpatialQuery to avoid the cost of memory allocations. See ジオメトリを用いた空間分析群(Spatial queries)の使用 and 空間分析(SpatialQuery)オブジェクトの使用 for more details.

SpatialQuery SpatialQuery SpatialQuery LinesSpatialQuery LinesSpatialQuery LinesSpatialQuery->SpatialQuery PointsSpatialQuery PointsSpatialQuery PointsSpatialQuery->SpatialQuery PolygonMeshSpatialQuery PolygonMeshSpatialQuery PolygonMeshSpatialQuery->SpatialQuery

Functions

GeometryLocation getClosest ! ( in Vec3 position, in Vec3 scaling, in Scalar maxUnscaledDistance )
Size getElementsInBBox ! ( in Vec3 min, in Vec3 max )
Size getElementsInBSphere ! ( in Vec3 center, in Scalar radius )
Size getLineIntersections ! ( in Vec3 start, in Vec3 end, in UInt8 lineIntersectionType )
Size getQueriedElement ? ( in Size index )
GeometryLocation getQueriedLocation ? ( in Size index )
GeometryLocation raycast ! ( in Ray ray, in Boolean doubleSided, in Scalar coneThreshold, in Scalar maxDistance )

Functions in detail

GeometryLocation SpatialQuery.getClosest! ( in Vec3 position, in Vec3 scaling, in Scalar maxUnscaledDistance )

Finds the closest position of a Geometry from a specified local position, returns the result as a GeometryLocation . A hit was found if GeometryLocation.isValid is true. A scaling factor needs to be specified for proper support of non-uniform scaling, since it can influence the result. Properly calling SpatialQueryable.prepareForSpatialQueries beforehand can increase significatively the performance of multiple raycasts.

注釈

this function is threadsafe, as long as the Geometry is not modified, and SpatialQueryable.prepareForSpatialQueries is not called during this function.

maxUnscaledDistance cutoff distance for the raycast. To have no distance limit, pass <= 0 or SCALAR_INFINITE. The maxUnscaledDistance is defined in non-scaled space (world space, before ‘scaling’ is applied).

Size SpatialQuery.getElementsInBBox! ( in Vec3 min, in Vec3 max )

Gets the elements intersecting a local bounding box. The definition of an element is Geometry-specific (polygon for PolygonMesh, segment for Lines, point for Points). The number of intersected elements is returned, and individual element indices must be gathered with the SpatialQuery.getQueriedElement before issuing another query.

Important: the returned values is a conservative approximation since only the bounding volume of the elements will be considered (eg: polygon’s bounding box for a PolygonMesh). This implies that some elements that are returned might not actually touch the queried bounding box (but are close to it). For more precision, the caller must perform additional filtering.

注釈

The choice to use SpatialQuery.getQueriedElement instead of simply returning an array of element indices avoids to allocate heap memory, which increases the performance.

Size SpatialQuery.getElementsInBSphere! ( in Vec3 center, in Scalar radius )

Gets the elements intersecting a local bounding sphere. The definition of an element is Geometry-specific (polygon for PolygonMesh, segment for Lines, point for Points). The number of intersected elements is returned, and individual element indices must be gathered with the SpatialQuery.getQueriedElement before issuing another query.

Important: the returned values is a conservative approximation since only the bounding volume of the elements will be considered (eg: polygon’s bounding box for a PolygonMesh). This implies that some elements that are returned might not actually touch the queried bounding sphere (but are close to it). For more precision, the caller must perform additional filtering.

注釈

The choice to use SpatialQuery.getQueriedElement instead of simply returning an array of element indices avoids to allocate heap memory, which increases the performance.

Size SpatialQuery.getLineIntersections! ( in Vec3 start, in Vec3 end, in UInt8 lineIntersectionType )

バージョン 1.13.0 で追加.

Gathers all intersections from a line, semi-line or line segment. The number of intersections is returned, and individual GeometryLocation can be retrieved using SpatialQuery.getQueriedLocation . Intersections will be sorted in the start to end direction.

  • if lineIntersectionType == SpatialQuery_lineIntersection : intersects with an infinite line passing through start and end
  • if lineIntersectionType == SpatialQuery_semiLineIntersection : intersects with a semi-line starting at start, passing through end and continuing infinitely in that direction
  • if lineIntersectionType == SpatialQuery_segmentIntersection : intersects with a segment starting at start and ending at end

Size SpatialQuery.getQueriedElement? ( in Size index )

Returns an element index gathered from a call to SpatialQuery.getElementsInBBox or SpatialQuery.getElementsInBSphere . The total element count is the returned value from these methods. Stored element indices are only valid until another query call is made.

注釈

The choice to use SpatialQuery.getQueriedElement instead of simply returning an array of element indices avoids to allocate heap memory, which increases the performance.

GeometryLocation SpatialQuery.getQueriedLocation? ( in Size index )

バージョン 1.13.0 で追加.

Returns a location gathered from a call to SpatialQuery.getLineIntersections . The total element count is the returned value from that method. Stored locations are only valid until another query call is made.

注釈

The choice to use SpatialQuery.getQueriedLocation instead of simply returning an array of locations avoids to allocate heap memory, which increases the performance.

GeometryLocation SpatialQuery.raycast! ( in Ray ray, in Boolean doubleSided, in Scalar coneThreshold, in Scalar maxDistance )

Raycasts a Geometry and returns the result as a GeometryLocation . A hit was found if GeometryLocation.isValid is true. Properly calling SpatialQueryable.prepareForSpatialQueries beforehand can increase significatively the performance of multiple raycasts.

注釈

this function is threadsafe, as long as the Geometry is not modified, and SpatialQueryable.prepareForSpatialQueries is not called during this function.

doubleSided intersections for both surface sides will be returned
coneThreshold if not 0, raycast with a thin cone, which is mostly used for selection in a projected view. The value of coneThreshold represents the radius of a cone of height 1. If < 0, surface geometries will use 0, while line/points will use -x. When `coneThreshold` is not 0, no spatial acceleration is provided (slow).
maxDistance defines a cutoff distance for the raycast. To have no distance limit, pass <= 0 or SCALAR_INFINITE