distance_object_model_3dT_distance_object_model_3dDistanceObjectModel3dDistanceObjectModel3d (Operator)

Name

distance_object_model_3dT_distance_object_model_3dDistanceObjectModel3dDistanceObjectModel3d — Compute the distances of the points of one 3D object model to another 3D object model.

Signature

distance_object_model_3d( : : ObjectModel3DFrom, ObjectModel3DTo, Pose, MaxDistance, GenParamName, GenParamValue : )

Herror T_distance_object_model_3d(const Htuple ObjectModel3DFrom, const Htuple ObjectModel3DTo, const Htuple Pose, const Htuple MaxDistance, const Htuple GenParamName, const Htuple GenParamValue)

void DistanceObjectModel3d(const HTuple& ObjectModel3DFrom, const HTuple& ObjectModel3DTo, const HTuple& Pose, const HTuple& MaxDistance, const HTuple& GenParamName, const HTuple& GenParamValue)

void HObjectModel3D::DistanceObjectModel3d(const HObjectModel3D& ObjectModel3DTo, const HPose& Pose, const HTuple& MaxDistance, const HTuple& GenParamName, const HTuple& GenParamValue) const

void HObjectModel3D::DistanceObjectModel3d(const HObjectModel3D& ObjectModel3DTo, const HPose& Pose, double MaxDistance, const HString& GenParamName, const HString& GenParamValue) const

void HObjectModel3D::DistanceObjectModel3d(const HObjectModel3D& ObjectModel3DTo, const HPose& Pose, double MaxDistance, const char* GenParamName, const char* GenParamValue) const

void HObjectModel3D::DistanceObjectModel3d(const HObjectModel3D& ObjectModel3DTo, const HPose& Pose, double MaxDistance, const wchar_t* GenParamName, const wchar_t* GenParamValue) const   (Windows only)

static void HOperatorSet.DistanceObjectModel3d(HTuple objectModel3DFrom, HTuple objectModel3DTo, HTuple pose, HTuple maxDistance, HTuple genParamName, HTuple genParamValue)

void HObjectModel3D.DistanceObjectModel3d(HObjectModel3D objectModel3DTo, HPose pose, HTuple maxDistance, HTuple genParamName, HTuple genParamValue)

void HObjectModel3D.DistanceObjectModel3d(HObjectModel3D objectModel3DTo, HPose pose, double maxDistance, string genParamName, string genParamValue)

Description

The operator distance_object_model_3ddistance_object_model_3dDistanceObjectModel3dDistanceObjectModel3dDistanceObjectModel3d computes the distances of the points in the 3D object model ObjectModel3DFromObjectModel3DFromObjectModel3DFromObjectModel3DFromobjectModel3DFrom to the points, triangles, polygons, or primitive in the 3D object model ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo. The distances are stored as an extended attribute named '&distance'"&distance""&distance""&distance""&distance" in the 3D object model ObjectModel3DFromObjectModel3DFromObjectModel3DFromObjectModel3DFromobjectModel3DFrom. This attribute can subsequently be queried with get_object_model_3d_paramsget_object_model_3d_paramsGetObjectModel3dParamsGetObjectModel3dParamsGetObjectModel3dParams or be processed with select_points_object_model_3dselect_points_object_model_3dSelectPointsObjectModel3dSelectPointsObjectModel3dSelectPointsObjectModel3d or other operators that use extended attributes.

The target data (points, triangles, polygons, or primitive) is selected based on the attributes contained in ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo. It is selected based on the presence of the data in the following precedence: Primitive, triangles, polygons, and points. As alternative to this automatic target data selection, the target data type can also be set with the generic parameter 'distance_to'"distance_to""distance_to""distance_to""distance_to" (see below). Generic, non-triangular polygons are internally triangulated by the operator before the distance to the resulting triangles is calculated. Thus, calling the operator with triangulated objects is faster than calling it with objects having different polygon faces.

MaxDistanceMaxDistanceMaxDistanceMaxDistancemaxDistance can be used to limit the range of the distance values to be computed. If MaxDistanceMaxDistanceMaxDistanceMaxDistancemaxDistance is set to 0, all distances are computed. If MaxDistanceMaxDistanceMaxDistanceMaxDistancemaxDistance is set to another value, points whose distance would exceed MaxDistanceMaxDistanceMaxDistanceMaxDistancemaxDistance are not processed and set to MaxDistanceMaxDistanceMaxDistanceMaxDistancemaxDistance. Thus, setting MaxDistanceMaxDistanceMaxDistanceMaxDistancemaxDistance to a value different than 0 can significantly speed up the execution of this operator.

If PosePosePosePosepose is a non-empty tuple, it must contain a pose which is applied to the points in ObjectModel3DFromObjectModel3DFromObjectModel3DFromObjectModel3DFromobjectModel3DFrom before computing the distances. The pose can be inverted using the generic parameter 'invert_pose'"invert_pose""invert_pose""invert_pose""invert_pose" (see below).

Depending on the target data type (points, triangles, or primitive), several methods for computing the distances are available. Some of these methods compute a data structure on the elements of ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo to speed up the distance computation. Those data structures can be precomputed using the operator prepare_object_model_3dprepare_object_model_3dPrepareObjectModel3dPrepareObjectModel3dPrepareObjectModel3d. This allows multiple calls to distance_object_model_3ddistance_object_model_3dDistanceObjectModel3dDistanceObjectModel3dDistanceObjectModel3d to re-use the data structure, thus saving the time to re-compute it for each call. For objects with non-triangular polygon faces, the operator prepare_object_model_3dprepare_object_model_3dPrepareObjectModel3dPrepareObjectModel3dPrepareObjectModel3d can additionally perform the triangulation and save it to the object to further speed-up the distance_object_model_3ddistance_object_model_3dDistanceObjectModel3dDistanceObjectModel3dDistanceObjectModel3d operator. This triangulation is only performed when the generic parameter 'distance_to'"distance_to""distance_to""distance_to""distance_to" is set to 'triangles'"triangles""triangles""triangles""triangles". Note that this triangulation, contrary to that of the operator triangulate_object_model_3dtriangulate_object_model_3dTriangulateObjectModel3dTriangulateObjectModel3dTriangulateObjectModel3d, does not clear out the polygons attribute.

When computing the distance to points or to triangles, the operator can optionally return the index of the closest point or triangle for each point in ObjectModel3DFromObjectModel3DFromObjectModel3DFromObjectModel3DFromobjectModel3DFrom by setting the generic parameter 'store_closest_index'"store_closest_index""store_closest_index""store_closest_index""store_closest_index" to 'true'"true""true""true""true" (see below). The index is stored as extended attribute named '&closest_index'"&closest_index""&closest_index""&closest_index""&closest_index" in the 3D object model ObjectModel3DFromObjectModel3DFromObjectModel3DFromObjectModel3DFromobjectModel3DFrom. Note that the closest index can not be computed when using the 'voxel'"voxel""voxel""voxel""voxel" method. If a point's distance to its closest element exceeds the maximum distance set in MaxDistanceMaxDistanceMaxDistanceMaxDistancemaxDistance, the closest index is set to -1.

Optionally, signed distances to points, triangles or to a primitive can be calculated. Therefore, the generic parameter 'signed_distances'"signed_distances""signed_distances""signed_distances""signed_distances" has to be set to 'true'"true""true""true""true". Note that signed distances can not be computed when using the 'voxel'"voxel""voxel""voxel""voxel" method in combination with point to point distances.

In the following, the different target types and methods are explained, and their advantages and disadvantages are described. Note that the operator automatically selects a default method depending on the target data type. This method can be overridden using the generic parameter 'method'"method""method""method""method".

Distance to points:

The following methods are available to compute the distances from points to points:

Linear search:

For each point in ObjectModel3DFromObjectModel3DFromObjectModel3DFromObjectModel3DFromobjectModel3DFrom, the distances to all points in ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo are computed, and the smallest distance is used. This method requires no precomputed data structure, and is the fastest for a small number of points in ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo.

KD-Tree:

The points in ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo are organized in a KD-Tree, which speeds up the search for the closest point. The construction of the tree is very efficient. The search time is approximately logarithmic to the number of points in ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo. However, the search time is not constant, and can vary significantly depending on the position of the query points in ObjectModel3DFromObjectModel3DFromObjectModel3DFromObjectModel3DFromobjectModel3DFrom.

Voxel:

The points in ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo are organized in a voxel structure. This voxel structure allows searching in almost constant time, i.e., independent from the position of the query points in ObjectModel3DFromObjectModel3DFromObjectModel3DFromObjectModel3DFromobjectModel3DFrom and the number of points in ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo.

Note that the preparation of this data structure takes several seconds or minutes. However, it is possible to perform a precomputation using prepare_object_model_3dprepare_object_model_3dPrepareObjectModel3dPrepareObjectModel3dPrepareObjectModel3d on ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo with Purpose set to 'distance_computation'"distance_computation""distance_computation""distance_computation""distance_computation".

Distance to triangles:

For computing the distances to triangles, the following methods are supported:

Linear search:

For each point in ObjectModel3DFromObjectModel3DFromObjectModel3DFromObjectModel3DFromobjectModel3DFrom, the distances to all triangles in ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo are computed, and the smallest distance is used. This method requires no precomputed data structure, and is the fastest for a small number of triangles in ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo.

KD-Tree:

The triangles in ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo are organized in a KD-Tree, which speeds up the search for the closest triangle. The construction of the tree is efficient. The search time is approximately logarithmic to the number of triangles in ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo. However, the search time is not constant, and can vary significantly depending on the position of the query points in ObjectModel3DFromObjectModel3DFromObjectModel3DFromObjectModel3DFromobjectModel3DFrom.

Voxel:

The triangles in ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo are organized in a voxel structure. This voxel structure allows searching in almost constant time, i.e., independent from the position of the query points in ObjectModel3DFromObjectModel3DFromObjectModel3DFromObjectModel3DFromobjectModel3DFrom and the number of triangles in ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo.

Note that the preparation of this data structure takes several seconds or minutes. However, it is possible to perform a precomputation using prepare_object_model_3dprepare_object_model_3dPrepareObjectModel3dPrepareObjectModel3dPrepareObjectModel3d on ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo with Purpose set to 'distance_computation'"distance_computation""distance_computation""distance_computation""distance_computation". For creating the voxel data structure, the triangles are sampled. The corresponding sampling distance can be set with the generic parameters 'sampling_dist_rel'"sampling_dist_rel""sampling_dist_rel""sampling_dist_rel""sampling_dist_rel" and 'sampling_dist_abs'"sampling_dist_abs""sampling_dist_abs""sampling_dist_abs""sampling_dist_abs".

By default, a relative sampling distance of 0.03 is used. See below for a more detailed description of the sampling distance. Note that this data structure is only approximate. It is possible that some of the distances are off by around 10% of the sampling distance. In these cases, the returned distances will always be larger than the actual distances.

Distance to primitive:

Since ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo can contain only one primitive, the distances from the query points to this primitive are computed linearly. The creation or usage of a data structure is not possible.

Note that computing the distance to primitive planes fitted with segment_object_model_3dsegment_object_model_3dSegmentObjectModel3dSegmentObjectModel3dSegmentObjectModel3d or fit_primitives_object_model_3dfit_primitives_object_model_3dFitPrimitivesObjectModel3dFitPrimitivesObjectModel3dFitPrimitivesObjectModel3d can be slow, since those planes contain a complex convex hull of the points that were used to fit the plane. If only the distance to the plane is required, and the boundary should be ignored, it is recommended to obtain the plane pose using get_object_model_3d_paramsget_object_model_3d_paramsGetObjectModel3dParamsGetObjectModel3dParamsGetObjectModel3dParams with parameter 'primitive_parameter_pose'"primitive_parameter_pose""primitive_parameter_pose""primitive_parameter_pose""primitive_parameter_pose" and create a new plane using gen_plane_object_model_3dgen_plane_object_model_3dGenPlaneObjectModel3dGenPlaneObjectModel3dGenPlaneObjectModel3d.

The following table lists the different target data types, methods, and their properties. The search time is the approximate time per point in ObjectModel3DFromObjectModel3DFromObjectModel3DFromObjectModel3DFromobjectModel3DFrom. N is the number of target elements in ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo.

Target Method Creation Approx. Search Properties Data Time Time ---------------------------------------------------------------------------- points linear 0 O(N) - No precomputation - Fastest for small N - Default for N<100 points kd-tree O(N log(N)) O(log(N)) - Fast structure creation - Non-constant search time - Default for N>=100 points voxel O(N log(N)) O(log(log(N))) - Slow structure creation - Very fast search - Default for precomputation with distance_object_model_3ddistance_object_model_3dDistanceObjectModel3dDistanceObjectModel3dDistanceObjectModel3d triangles linear 0 O(N) - No precomputation - Fastest for small N - Default triangles kd-tree O(N log(N)) O(log(N)) - Fast structure creation - Non-constant search time triangles voxel O(N log(N)) O(log(log(N))) - Slow structure creation - Requires sampling distance - Very fast search - Small error possible - Default for precomputation with distance_object_model_3ddistance_object_model_3dDistanceObjectModel3dDistanceObjectModel3dDistanceObjectModel3d primitive linear 0 O(1)

Additionally to the parameters described above, the following parameters can be set to influence the distance computation. If desired, these parameters and their corresponding values can be specified by using GenParamNameGenParamNameGenParamNameGenParamNamegenParamName and GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue, respectively. All of the following parameters are optional.

'distance_to'"distance_to""distance_to""distance_to""distance_to"

This parameter can be used to explicitly set the target data to which the distances are computed.

'auto'"auto""auto""auto""auto"

(Default) Automatically set the target data. The following list of attributes is queried, and the first appearing attribute from the list is used as target data: Primitive, Triangle, Point.

'primitive'"primitive""primitive""primitive""primitive"

Compute the distance to the primitive contained in ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo.

'triangles'"triangles""triangles""triangles""triangles"

Compute the distance to the triangles contained in ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo.

'points'"points""points""points""points"

Compute the distance to the points contained in ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo.

'method'"method""method""method""method"

This parameter can be used to explicitly set the method to be used for the distance computation. Note that not all methods are available for all target data types. For the list of possible pairs of target data type and method, see above.

'auto'"auto""auto""auto""auto"

(Default) Use the default method for the used target data type.

'linear'"linear""linear""linear""linear"

Use a linear search for computing the distances.

'kd-tree'"kd-tree""kd-tree""kd-tree""kd-tree"

Use a KD-Tree for computing the distances.

'voxel'"voxel""voxel""voxel""voxel"

Use a voxel structure for computing the distances.

'invert_pose'"invert_pose""invert_pose""invert_pose""invert_pose"

This parameter can be used to invert the pose given in PosePosePosePosepose.

'false'"false""false""false""false"

(Default) The pose is not inverted.

'true'"true""true""true""true"

The pose is inverted.

'output_attribute'"output_attribute""output_attribute""output_attribute""output_attribute"

This parameter can be used to set the name of the attribute in which the distances are stored. By default, the distances are stored in an extended attribute named '&distance'"&distance""&distance""&distance""&distance" in ObjectModel3DFromObjectModel3DFromObjectModel3DFromObjectModel3DFromobjectModel3DFrom. However, if the same 3D object model is used for different calls of this operator, the result of the previous call would be overwritten. This can be avoided by changing the name of the extended attribute. Valid extended attribute names start with a '&'"&""&""&""&".

'sampling_dist_rel'"sampling_dist_rel""sampling_dist_rel""sampling_dist_rel""sampling_dist_rel", 'sampling_dist_abs'"sampling_dist_abs""sampling_dist_abs""sampling_dist_abs""sampling_dist_abs"

These parameters are used when computing the distances to triangles using the voxel method. For this, the triangles need to be sampled. The sampling distance can be set either in absolute terms, using 'sampling_dist_abs'"sampling_dist_abs""sampling_dist_abs""sampling_dist_abs""sampling_dist_abs", or relative to the diameter of the axis aligned bounding box, using 'sampling_dist_rel'"sampling_dist_rel""sampling_dist_rel""sampling_dist_rel""sampling_dist_rel". By default, 'sampling_dist_rel'"sampling_dist_rel""sampling_dist_rel""sampling_dist_rel""sampling_dist_rel" is set to 0.03. Only one of the two parameters can be set. The diameter of the axis aligned bounding box can be queried using get_object_model_3d_paramsget_object_model_3d_paramsGetObjectModel3dParamsGetObjectModel3dParamsGetObjectModel3dParams. Note that the creation of the voxel data structure is very time consuming, and is usually performed offline using prepare_object_model_3dprepare_object_model_3dPrepareObjectModel3dPrepareObjectModel3dPrepareObjectModel3d (see above).

'store_closest_index'"store_closest_index""store_closest_index""store_closest_index""store_closest_index"

This parameter can be used to return the index of the closest point or triangle in the extended attribute '&closest_index'.

'false'"false""false""false""false"

(Default) The index is not returned.

'true'"true""true""true""true"

The index is returned.

'signed_distances'"signed_distances""signed_distances""signed_distances""signed_distances"

This parameter can be used to calculate signed distances of the points in the 3D object model ObjectModel3DFromObjectModel3DFromObjectModel3DFromObjectModel3DFromobjectModel3DFrom to the points, triangles or primitive in the 3D object model ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo.

'false'"false""false""false""false"

(Default) Unsigned distances are returned.

'true'"true""true""true""true"

Signed distances are returned.

Dependent on the available target data (points, triangles or primitive) the following particularities have to be considered:

Distance to points:

The computation of signed distances is only supported for the methods 'kd-tree'"kd-tree""kd-tree""kd-tree""kd-tree" and 'linear search'"linear search""linear search""linear search""linear search". However, signed distances can only be calculated if point normals are available for the points in the 3D object model or attached via the operator set_object_model_3d_attrib_modset_object_model_3d_attrib_modSetObjectModel3dAttribModSetObjectModel3dAttribModSetObjectModel3dAttribMod.

Distance to triangles:

Signed distances can be calculated for all methods listed above. The operator returns a negative distance, if the dot product with the normal vector of the triangle is less than zero. Otherwise, the distance is positive.

Distance to primitive:

When calculating signed distances to a cylindrical, spherical or box-shaped primitive, the points of the 3D object model ObjectModel3DFromObjectModel3DFromObjectModel3DFromObjectModel3DFromobjectModel3DFrom inside the primitive obtain a negative distance, whereas all others have a positive distance. When calculating signed distances to planes, all points beneath the plane obtain a negative distance, whereas all others have a positive one.

Execution Information

Parameters

ObjectModel3DFromObjectModel3DFromObjectModel3DFromObjectModel3DFromobjectModel3DFrom (input_control)  object_model_3d HObjectModel3D, HTupleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the source 3D object model.

ObjectModel3DToObjectModel3DToObjectModel3DToObjectModel3DToobjectModel3DTo (input_control)  object_model_3d HObjectModel3D, HTupleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the target 3D object model.

PosePosePosePosepose (input_control)  pose HPose, HTupleHTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)

Pose of the source 3D object model in the target 3D object model.

Default value: []

MaxDistanceMaxDistanceMaxDistanceMaxDistancemaxDistance (input_control)  number HTupleHTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)

Maximum distance of interest.

Default value: 0

GenParamNameGenParamNameGenParamNameGenParamNamegenParamName (input_control)  attribute.name(-array) HTupleHTupleHtuple (string) (string) (HString) (char*)

Names of the generic input parameters.

Default value: []

List of values: 'distance_to'"distance_to""distance_to""distance_to""distance_to", 'invert_pose'"invert_pose""invert_pose""invert_pose""invert_pose", 'method'"method""method""method""method", 'output_attribute'"output_attribute""output_attribute""output_attribute""output_attribute", 'sampling_dist_abs'"sampling_dist_abs""sampling_dist_abs""sampling_dist_abs""sampling_dist_abs", 'sampling_dist_rel'"sampling_dist_rel""sampling_dist_rel""sampling_dist_rel""sampling_dist_rel", 'signed_distances'"signed_distances""signed_distances""signed_distances""signed_distances", 'store_closest_index'"store_closest_index""store_closest_index""store_closest_index""store_closest_index"

GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue (input_control)  attribute.value(-array) HTupleHTupleHtuple (string / integer / real) (string / int / long / double) (HString / Hlong / double) (char* / Hlong / double)

Values of the generic input parameters.

Default value: []

List of values: 'auto'"auto""auto""auto""auto", 'false'"false""false""false""false", 'kd-tree'"kd-tree""kd-tree""kd-tree""kd-tree", 'linear'"linear""linear""linear""linear", 'points'"points""points""points""points", 'polygons'"polygons""polygons""polygons""polygons", 'primitive'"primitive""primitive""primitive""primitive", 'triangles'"triangles""triangles""triangles""triangles", 'true'"true""true""true""true", 'voxel'"voxel""voxel""voxel""voxel"

Result

distance_object_model_3ddistance_object_model_3dDistanceObjectModel3dDistanceObjectModel3dDistanceObjectModel3d returns 2 (H_MSG_TRUE) if all parameters are correct. If necessary, an exception is raised.

Possible Predecessors

prepare_object_model_3dprepare_object_model_3dPrepareObjectModel3dPrepareObjectModel3dPrepareObjectModel3d, read_object_model_3dread_object_model_3dReadObjectModel3dReadObjectModel3dReadObjectModel3d, find_surface_modelfind_surface_modelFindSurfaceModelFindSurfaceModelFindSurfaceModel, xyz_to_object_model_3dxyz_to_object_model_3dXyzToObjectModel3dXyzToObjectModel3dXyzToObjectModel3d

Possible Successors

get_object_model_3d_paramsget_object_model_3d_paramsGetObjectModel3dParamsGetObjectModel3dParamsGetObjectModel3dParams, render_object_model_3drender_object_model_3dRenderObjectModel3dRenderObjectModel3dRenderObjectModel3d, disp_object_model_3ddisp_object_model_3dDispObjectModel3dDispObjectModel3dDispObjectModel3d, clear_object_model_3dclear_object_model_3dClearObjectModel3dClearObjectModel3dClearObjectModel3d

See also

prepare_object_model_3dprepare_object_model_3dPrepareObjectModel3dPrepareObjectModel3dPrepareObjectModel3d

Module

3D Metrology