Points (object)¶
The Points object implements a point cloud geometry. All its data is contained in its GeometryAttributes container that can be retrieved by calling Points.getAttributes.
Point sizes¶
A size attribute can be defined by Points.getOrCreateSizesAttribute or Points.setSizesAttribute. This attribute will then be used by helpers such as Points.getSize, and the point bounding spheres defined by the size will be used to compute points’ volume for SpatialQueryable functions such as Points.raycast.
If no size attribute is defined, the Points.defaultPointSize constant will be used as the size for all points.
Members¶
| GeometryAttributes | attributes | Container for all attributes. |
| String | debugName | Name that will be printed in descriptions. |
| UInt32 | structureVersion | Version of the geometry structure itself, excluding the GeometryAttributes content. |
| Boolean | computeGPUBoundingVolume | If positions are on the GPU: if true, the bounding volume is computed, else an infinite bbox is returned. |
| ThreadsafeMetaDataContainer | metaData | Container for holding various user data (Geometry specific), such as the BoundingBox cache data, or raycast acceleration structures and data (Octree). |
| Scalar | defaultPointSize | used for get/setSize if sizesAttribute is not specified (see Point sizes) |
| Ref<ScalarAttribute> | sizesAttribute | used for get/setSize if specified (see Point sizes) |
/*
** Example: Points
*/
require Geometry;
operator entry() {
Points points = Points();
points.getOrCreateSizesAttribute();
points.resize( 5 );
for( Size i = 0; i < 5; ++i ) {
points.setPointPosition( i, Vec3( 0, i, 0 ) );
points.setSize( i, (i+1) * 0.1f );
}
report( points.getDesc(true, false) );
}
/*
** Output:
Points: Points pointCount: 5 nbAttributeVectors: 2
Attributes: nb elements = 5
0: positions={x:+0.0,y:+0.0,z:+0.0} pointSizes=+0.1
1: positions={x:+0.0,y:+1.0,z:+0.0} pointSizes=+0.2
2: positions={x:+0.0,y:+2.0,z:+0.0} pointSizes=+0.3
3: positions={x:+0.0,y:+3.0,z:+0.0} pointSizes=+0.4
4: positions={x:+0.0,y:+4.0,z:+0.0} pointSizes=+0.5
*/
Methods¶
ImportExportHelpers methods¶
| _getPointsAsExternalArray ? ( io Float32 values<>, in Size components ) | |
| _getPointsAsExternalArray_d ? ( io Float64 values<>, in Size components ) |
SpatialQueryable methods¶
| Boolean | areGeometryLocationsEquivalent ? ( in GeometryLocation location0, in GeometryLocation location1 ) |
| Ref<SpatialQuery> | beginSpatialQuery ? () |
| endSpatialQuery ? ( in Ref<SpatialQuery> query ) | |
| GeometryLocation | getClosest ? ( in Vec3 position, in Vec3 scaling, in Scalar maxUnscaledDistance ) |
| getLocationAttributeIndicesAndWeights ? ( in GeometryLocation location, io LocalL16UInt32Array attributeIndices, io LocalL16ScalarArray weights ) | |
| Vec3 | getLocationBoundingSphereCoordinate ? ( in GeometryLocation location ) |
| Size | getLocationPointIndex ? ( in GeometryLocation location ) |
| Vec3 | getPositionAtLocation ? ( in GeometryLocation location ) |
| Boolean | isLocationAtPointCenter ? ( in GeometryLocation location ) |
| prepareForSpatialQueries ? ( in Size approximateNumberOfQueries, in GenericValueContainer options ) | |
| GeometryLocation | raycast ? ( in Ray ray, in Boolean doubleSided, in Scalar coneThreshold, in Scalar maxDistance ) |
| removeSpatialQueryAcceleration ! () |
Methods in detail¶
copy constructor
Points ( in String debugName )
Constructor taking the string to be used as the name.
| debugName | the name displayed in debugging |
Points ()
Points._setPointsFromExternalArray! ( in Float32 values<>, in Size components )
Sets the point positions from a Float32 array.
Points._setPointsFromExternalArray_d! ( in Float64 values<>, in Size components )
Sets the point positions from a Float64 array.
Points.addPlane! ( in Xfo xfo, in Scalar length, in Scalar width, in Integer lengthRows, in Integer widthRows )
Adds a transformed plane (grid) of points
Points.addPoint! ( in Vec3 pos )
Adds a point at position pos
Size Points.addPoints! ( in Size count )
Adds N points and returns the index of the first of the consecutive indices.
Points.addPoints! ( in Vec3 positions[] )
Adds a point for each position in the positions array
Points.applyTransform! ( in Mat44 transform )
Geometry interface: transforms the positions of the geometry (and normals if applicable)
Points.applyTransform! ( in Xfo transform )
Geometry interface: transforms the positions of the geometry (and normals if applicable)
Points.clear! ()
Clears all data, including points and attributes. Version will be incremented.
clone method
Points.cloneMembersTo? ( io Points that )
Points.convertToCPU! ()
Points.convertToGPU! ()
Points.copy! ( in Geometry src )
Copies the content from the source Geometry.
Points.copy! ( in Points src )
Copies the content from the source Points.
Size Points.elementCount? ()
Geometry interface: returns the number of points
Vec3[] Points.getAllPointPositions? ()
Geometry interface: returns all point positions
Ref<GeometryAttributes> Points.getAttributes? ()
Returns the associated attribute container, if any.
注釈
the usage and meaning of attribute values is geometry specific.
LocalBoundingVolume Points.getBoundingVolume? ()
Returns the bounding volume of the geometry, as computed from the positions attribute. This function will cache the bounding box given a specific version of the positions attribute, and will update it lazily, in a thread-safe fashion. The internal cache is stored in the BaseGeometry.metaData container.
String Points.getDebugName? ()
Returns the debug name used when constructing the geometry.
String Points.getDesc? ( in Boolean withAttributes, in Boolean useUnitTestPrint )
Returns a String description of the Points.
| withAttributes | include the attribute values in the desc. |
LocalBoundingVolume Points.getElementBoundingVolume? ( in Size index )
Geometry interface: return the bounding volume of a point (takes into account the size if applicable: see Point sizes)
Returns the memory location id. CPU = 0, GPU = 1, VSM = 2;
Ref<ThreadsafeMetaDataContainer> Points.getMetaData? ()
Returns the metaData container for this Geometry.
Ref<ScalarAttribute> Points.getOrCreateSizesAttribute! ()
Returns the point size attribute, or creates it if not there (see Point sizes).
Vec3 Points.getPointPosition? ( in Size point )
Returns the position of a point.
Scalar Points.getSize? ( in Size point )
Returns the size of a point (see Point sizes)
UInt32 Points.getStructureVersion? ()
Returns the version of the geometry structure including the the attribute set (but not attribute values).
Returns the version of the geometry including attribute values
Points.incrementPositionsVersion! ()
Helper for incrementing the version of the positions attribute after value changes. See Attribute versioning for more information.
Points.incrementSizesVersion! ()
Helper for incrementing the version of the sizes attribute after value changes (see Point sizes). See Attribute versioning for more information.
Size Points.pointCount? ()
Returns the number of points.
Points.resize! ( in Size newSize )
Changes the number of points, adding or truncating the last ones.
Points.setAllPointPositions! ( in Vec3 positions[] )
Geometry interface: sets all point positions
Points.setPointPosition! ( in Size point, in Vec3 position )
Sets the positions of a point.
注釈
Once positions have been set, call Points.incrementPositionsVersion (see Attribute versioning)
Points.setSize! ( in Size point, in Scalar size )
Sets the size of a point, if a size attribute has been set with Points.getOrCreateSizesAttribute or Points.setSizesAttribute.
注釈
Once sizes have been set, call Points.incrementSizesVersion (see Attribute versioning)
Points.setSizesAttribute! ( in Ref<ScalarAttribute> sizesAttribute )
Defines the attribute that will be used for ‘setSize’ and ‘getSize’ (see Point sizes)
Size Points.size? ()
Returns the number of points.
ImportExportHelpers methods¶
Points._getPointsAsExternalArray? ( io Float32 values<>, in Size components )
Gets the point positions as a Float32 array.
Points._getPointsAsExternalArray_d? ( io Float64 values<>, in Size components )
Gets the point positions as a Float64 array.
SpatialQueryable methods¶
Boolean Points.areGeometryLocationsEquivalent? ( in GeometryLocation location0, in GeometryLocation location1 )
バージョン 1.13.0 で追加.
Returns true if the geometry locations are equal or equivalent for this geometry.
注釈
For a PolygonMesh, geometry locations on points and edges can be different but equivalent when defined at the junction of different triangles (different polygon and/or triangle, but same point or edge location).
Ref<SpatialQuery> Points.beginSpatialQuery? ()
Returns a local SpatialQuery object for issuing one or multiple queries. The returned SpatialQuery object must be locally released by calling SpatialQueryable.endSpatialQuery, and should not be used afterward.
Points.endSpatialQuery? ( in Ref<SpatialQuery> query )
Releases (recycles) a query object previously obtained by a call to SpatialQueryable.beginSpatialQuery .
GeometryLocation Points.getClosest? ( in Vec3 position, in Vec3 scaling, in Scalar maxUnscaledDistance )
Gets the closest location of the Points geometry, taking into account the point sizes if applicable (see Point sizes). See SpatialQueryable.getClosest for more details about this function and parameters.
注釈
For a sized particle, the returned location can include point’s bounding sphere’s position, and Points.getPositionAtLocation will return a position on point’s bounding sphere, if applicable.
Points.getLocationAttributeIndicesAndWeights? ( in GeometryLocation location, io LocalL16UInt32Array attributeIndices, io LocalL16ScalarArray weights )
For a GeometryLocation returned by this SpatialQueryable, returns the attribute indices and weights required to linearly interpolate attribute values. The GeometryLocation must be valid. See ジオメトリロケーション構造 for more details.
Vec3 Points.getLocationBoundingSphereCoordinate? ( in GeometryLocation location )
Sized points’ GeometryLocation can encode a spherical coordinate relative to their bounding sphere. For a sized point, returns a vector corresponding to point sphere’s local coordinate, otherwise, returns :ref:`Vec3 <vec3>`(0,0,0). It returns a vector of unit length corresponding to the surface a sphere of radius 1, such that the actual position can be computed as:
Size pointIndex = points.getPointIndex( location );
Vec3 position = points.getPosition( pointIndex ) + points.getBoundingSphereCoordinate( location ) * points.getSize( pointIndex );
Size Points.getLocationPointIndex? ( in GeometryLocation location )
Returns the point index corresponding to the location.
Vec3 Points.getPositionAtLocation? ( in GeometryLocation location )
Evaluates the position attribute at a specific location. For a sized particle, the returned position might be a position on its bounding sphere surface when applicable (eg: resulting from a Points.raycast or Points.getClosest call). See Points.getLocationBoundingSphereCoordinate for more information.
Boolean Points.isLocationAtPointCenter? ( in GeometryLocation location )
Returns ‘true’ if the point location is defined at point’s center. See Points.getLocationBoundingSphereCoordinate for more details relatively to sized points’ GeometryLocation positions.
Points.prepareForSpatialQueries? ( in Size approximateNumberOfQueries, in GenericValueContainer options )
Builds an acceleration structure that will accelerate future queries such as SpatialQueryable.raycast or SpatialQueryable.getClosest . For built-in Geometry types, the default acceleration structure is the Octree, however it is possible to use a SparseGrid (see options parameter description). See 高速化構造 for more details about acceleration structures.
Important: prepareForSpatialQueries must be called if geometry’s structure or positions changed. Otherwise, the acceleration will be silently disabled.
Because building an acceleration structure incurs memory and computation overhead, this function should be called only when multiple queries are expected. The acceleration structure will remain attached to the geometry so it can be reused and incrementally updated, unless SpatialQueryable.removeSpatialQueryAcceleration is explicitly called.
注釈
Calling prepareForSpatialQueries is not threadsafe, and must be called before issuing parallel queries.
| options | can be null, values are implementation specific, and can be configured by calling one of these: PrepareForSpatialQueries_setOctree, PrepareForSpatialQueries_setOctreeMaxDepth, PrepareForSpatialQueries_setSparseGrid, PrepareForSpatialQueries_setSparseGridCellSize, PrepareForSpatialQueries_setSparseGridAutoCellSizeMultiplier . |
| approximateNumberOfQueries | an approximation of the number of queries (eg: raycast) that will be issued. Structures such as the Octree with choose their level of precision accordingly, to provide an optimal balance between build and query costs. |
GeometryLocation Points.raycast? ( in Ray ray, in Boolean doubleSided, in Scalar coneThreshold, in Scalar maxDistance )
Raycasts the Points geometry, taking into account the point sizes if applicable (see Point sizes). See SpatialQueryable.raycast for more details about this function and parameters.
注釈
For a sized particle, the returned location can include point’s bounding sphere’s position, and Points.getPositionAtLocation will return a position on point’s bounding sphere, if applicable.
Points.removeSpatialQueryAcceleration! ()
Releases the cached acceleration structure created by SpatialQueryable.prepareForSpatialQueries, which will reduce memory usage. However, if future queries are expected for the same geometry (even if modified), calling this method can significatively reduce the performance, as the next SpatialQueryable.prepareForSpatialQueries will need to fully fully reallocate and rebuild on acceleration structure (prevents potential incremental updates).
