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.).

__init__(*args, **kwargs)

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.

The method generates a new scalar field giving, for each node in a cloud, an approximate distance between this node and the other cloud.

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.

The method generates a new scalar field giving, for each node in a cloud, an approximate distance between this node and the other cloud.

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 method generates a new scalar field giving, for each node in a cloud, the distance between this node and the other cloud.

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 method generates a new scalar field giving, for each node in the cloud, the distance between this node and the 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

__init__(self: _cloudComPy.Cloud2CloudDistancesComputationParams) → None

Default constructor

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

__init__(self: _cloudComPy.Cloud2MeshDistancesComputationParams) → None

Default constructor

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