10. Distance Computation Tools
10.1. Distance computation
- class cloudComPy.DistanceComputationTools
Bases:
pybind11_object
Several entity-to-entity distances computation algorithms (cloud-cloud, cloud-mesh, etc.).
- static computeApproxCloud2CloudDistance(comparedCloud: _cloudComPy.GenericIndexedCloudPersist, referenceCloud: _cloudComPy.GenericIndexedCloudPersist, octreeLevel: int = 7, maxSearchDist: float = 0, progressCb: _cloudComPy.GenericProgressCallback = None, compOctree: _cloudComPy.DgmOctree = None, refOctree: _cloudComPy.DgmOctree = None) List[float]
Computes approximate distances between two point clouds.
This methods uses an exact Distance Transform to approximate the real distances. Therefore, the greater the octree level is (it is used to determine the grid step), the finer the result will be (but more memory and time will be needed).
- Parameters
comparedCloud (GenericIndexedCloudPersist) – the compared cloud
referenceCloud (GenericIndexedCloudPersist) – the reference cloud
octreeLevel (int,optional) – the octree level at which to compute the Distance Transform, default 7
maxSearchDist (double,optional) – Maximum search distance, default 0.
progressCb (GenericProgressCallback,optional) – the client application can get some notification of the process progress through this callback mechanism (see GenericProgressCallback) default None, not available yet.
compOctree (DgmOctree,optional) – the pre-computed octree of the compared cloud (warning: both octrees must have the same cubical bounding-box - it is automatically computed if 0)
refOctree (DgmOctree,optional) – the pre-computed octree of the reference cloud (warning: both octrees must have the same cubical bounding-box - it is automatically computed if 0)
- Returns
a list of statistics (min, max, mean, variance, max error) or an empty list if problem
- Return type
list
- static computeApproxCloud2MeshDistance(arg0: _cloudComPy.GenericIndexedCloudPersist, arg1: _cloudComPy.GenericIndexedMesh) List[float]
Computes approximate distances between a point cloud and a mesh.
- Parameters
pointCloud (GenericIndexedCloudPersist) – the compared cloud (the distances will be computed on these points)
mesh (GenericIndexedMesh) – the reference mesh
- Returns
a list of statistics (min, max, mean, variance, max error) or an empty list if problem
- Return type
list
- static computeCloud2CloudDistances(comparedCloud: _cloudComPy.GenericIndexedCloudPersist, referenceCloud: _cloudComPy.GenericIndexedCloudPersist, params: _cloudComPy.Cloud2CloudDistancesComputationParams, progressCb: _cloudComPy.GenericProgressCallback = None, compOctree: _cloudComPy.DgmOctree = None, refOctree: _cloudComPy.DgmOctree = None) int
Computes the “nearest neighbour distance” between two point clouds (formerly named “Hausdorff distance”).
The main algorithm and its different versions (with or without local modeling) are described in Daniel Girardeau-Montaut’s PhD manuscript (Chapter 2, section 2.3). It is the standard way to compare directly two dense (and globally close) point clouds.
WARNING The current scalar field of the compared cloud should be enabled. By default it will be reset to NAN_VALUE but one can avoid this by defining the Cloud2CloudDistanceComputationParams::resetFormerDistances parameters to False. But even in this case, only values above Cloud2CloudDistanceComputationParams::maxSearchDist will remain untouched.
WARNING Max search distance (Cloud2CloudDistanceComputationParams::maxSearchDist > 0) is not compatible with the determination of the Closest Point Set (Cloud2CloudDistanceComputationParams::CPSet)
- Parameters
comparedCloud (GenericIndexedCloudPersist) – the compared cloud (the distances will be computed on these points)
referenceCloud (GenericIndexedCloudPersist) – the reference cloud (the distances will be computed relatively to these points)
params (Cloud2CloudDistancesComputationParams) – distance computation parameters
progressCb (GenericProgressCallback,optional) – the client application can get some notification of the process progress through this callback mechanism (see GenericProgressCallback) default None, not available yet.
compOctree (DgmOctree,optional) – the pre-computed octree of the compared cloud (warning: both octrees must have the same cubical bounding-box - it is automatically computed if 0)
refOctree (DgmOctree,optional) – the pre-computed octree of the reference cloud (warning: both octrees must have the same cubical bounding-box - it is automatically computed if 0)
- Returns
>0 if ok, a negative value otherwise
- Return type
int
- static computeCloud2MeshDistances(pointCloud: _cloudComPy.GenericIndexedCloudPersist, mesh: _cloudComPy.GenericIndexedMesh, params: _cloudComPy.Cloud2MeshDistancesComputationParams, progressCb: _cloudComPy.GenericProgressCallback = None, cloudOctree: _cloudComPy.DgmOctree = None) int
Computes the distance between a point cloud and a mesh.
The algorithm, inspired from METRO by Cignoni et al., is described in Daniel Girardeau-Montaut’s PhD manuscript (Chapter 2, section 2.2). It is the general way to compare a point cloud with a triangular mesh.
- Parameters
pointCloud (GenericIndexedCloudPersist) – the compared cloud (the distances will be computed on these points)
mesh (GenericIndexedMesh) – the reference mesh (the distances will be computed relatively to its triangles)
params (Cloud2MeshDistancesComputationParams) – parameters
progressCb (GenericProgressCallback,optional) – the client application can get some notification of the process progress through this callback mechanism (see GenericProgressCallback) default None, not available yet.
cloudOctree (DgmOctree,optional) – the pre-computed octree of the compared cloud (warning: its bounding box should be equal to the union of both point cloud and mesh bbs and it should be cubical - it is automatically computed if 0)
- Returns
>0 if ok, a negative value otherwise
- Return type
int
- static determineBestOctreeLevel(compCloud: _cloudComPy.ccPointCloud, refMesh: _cloudComPy.GenericIndexedMesh = None, refCloud: _cloudComPy.ccPointCloud = None, maxSearchDist: float = 0) int
compute the best octree level to use for cloud to mesh or cloud distance calculation (C2M or C2C).
WARNING if a scalar field “Approx. distances” is present in the compared cloud, it will be used for the determination: in case of several distance computations with different clouds or meshes, remove it before the call.
- Parameters
compCloud (ccPointCloud) – the compared cloud (the distances will be computed on these points)
refMesh (GenericIndexedMesh,optional) – the reference mesh, default None (if None, referenceCloud must be provided). (the distances will be computed relatively to its triangles)
refCloud (ccPointCloud,optional) – the reference cloud, default None (if None, mesh must be provided). (the distances will be computed relatively to these points)
maxSearchDist (double,optional) – Maximum search distance, default 0.
- Returns
the best octree level to use for C2M or C2C.
- Return type
int
10.2. Distance computation parameters
- class cloudComPy.Cloud2CloudDistancesComputationParams
Bases:
pybind11_object
Cloud-to-cloud “Hausdorff” distance computation parameters
- property CPSet
Container of (references to) points to store the ‘Closest Point Set’.
The Closest Point Set corresponds to (the reference to) each compared point’s closest neighbour. warning Not compatible with max search distance (see maxSearchDist). Default None
- getSplitDistance(self: _cloudComPy.Cloud2CloudDistancesComputationParams, arg0: int) _cloudComPy.ScalarField
Split distances (one scalar field per dimension: X, Y and Z).
Default None
- property kNNForLocalModel
Number of neighbours for nearest neighbours search (local model).
For local models only (i.e. ignored if localModel = NO_MODEL). Ignored if useSphericalSearchForLocalModel is True. Default 0
- property localModel
Type of local 3D modeling to use.
Default: NO_MODEL. Otherwise see CC_LOCAL_MODEL_TYPES.
- property maxSearchDist
Maximum search distance (true distance won’t be computed if greater).
Set to -1 to deactivate (default). WARNING Not compatible with closest point set determination (see CPSet)
- property maxThreadCount
Maximum number of threads to use (default 0 = max).
- property multiThread
Whether to use multi-thread (default) or single thread mode.
If maxSearchDist > 0, single thread mode will be forced.
- property octreeLevel
Level of subdivision of the octree at witch to apply the distance computation algorithm.
TODO: If set to 0 (default) the algorithm will try to guess the best level automatically.
- property radiusForLocalModel
Radius for nearest neighbours search (local model).
For local models only (i.e. ignored if localModel = NO_MODEL). Ignored if useSphericalSearchForLocalModel is True. Default 0
- property resetFormerDistances
Whether to keep the existing distances as is (if any) or not.
By default, any previous distances/scalar values stored in the ‘enabled’ scalar field will be reset before computing them again.
- property reuseExistingLocalModels
Whether to use an approximation for local model computation.
For local models only (i.e. ignored if localModel = NO_MODEL). Computation is much faster but less “controlled”. Default False
- setSplitDistances(self: _cloudComPy.Cloud2CloudDistancesComputationParams, arg0: int) bool
Split distances (one scalar field per dimension: X, Y and Z).
To activate split distance, fill this with the cloud size, it will create 3 scalar fields to store the X, Y and Z distances. These scalar fields are not associated to the cloud. (that can be done explicitely later).
Default None
- property useSphericalSearchForLocalModel
Whether to use a fixed number of neighbors or a (sphere) radius for nearest neighbours search.
For local models only (i.e. ignored if localModel = NO_MODEL). Default False
- class cloudComPy.Cloud2MeshDistancesComputationParams
Bases:
pybind11_object
Cloud-to-mesh distances computation parameters.
- property CPSet
Container of (references to) points to store the ‘Closest Point Set’.
The Closest Point Set corresponds to (the reference to) each compared point’s closest neighbour. warning Not compatible with max search distance (see maxSearchDist). Default None
- property flipNormals
Whether triangle normals should be computed in the ‘direct’ order (True) or ‘indirect’ (False).
Default False
- property maxSearchDist
Maximum search distance (true distance won’t be computed if greater).
Set to -1 to deactivate (default). WARNING Not compatible with closest point set determination (see CPSet)
- property maxThreadCount
Maximum number of threads to use (default 0 = max).
- property multiThread
Whether to use multi-thread (default) or single thread mode.
If maxSearchDist > 0, single thread mode will be forced.
- property octreeLevel
Level of subdivision of the octree at witch to apply the distance computation algorithm.
TODO: If set to 0 (default) the algorithm will try to guess the best level automatically.
- property signedDistances
Whether to compute signed distances or not.
If True, the computed distances will be signed (in this case, the Distance Transform can’t be used and therefore useDistanceMap will be ignored). Default False
- property useDistanceMap
Use distance map (acceleration).
If True the distances will be approximated by a Distance Transform. WARNING Incompatible with signed distances or Closest Point Set. Default False