| Operators |
distance_object_model_3d — Compute the distances of the points of one 3D object model to another 3D object model.
distance_object_model_3d( : : ObjectModel3DFrom, ObjectModel3DTo, Pose, MaxDistance, GenParamName, GenParamValue : )
The operator distance_object_model_3d computes the distances of the points in the 3D object model ObjectModel3DFrom to the points, triangles, polygons, or primitive in the 3D object model ObjectModel3DTo. The distances are stored as an extended attribute named '&distance' in the 3D object model ObjectModel3DFrom. This attribute can subsequently be queried with get_object_model_3d_params or be processed with select_points_object_model_3d or other operators that use extended attributes.
The target data (points, triangles, polygons, or primitive) is selected based on the attributes contained in ObjectModel3DTo. 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' (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.
MaxDistance can be used to limit the range of the distance values to be computed. If MaxDistance is set to 0, all distances are computed. If MaxDistance is set to another value, points whose distance would exceed MaxDistance are not processed and set to MaxDistance. Thus, setting MaxDistance to a value different than 0 can significantly speed up the execution of this operator.
If Pose is a non-empty tuple, it must contain a pose which is applied to the points in ObjectModel3DFrom before computing the distances. The pose can be inverted using the generic parameter '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 ObjectModel3DTo to speed up the distance computation. Those data structures can be precomputed using the operator prepare_object_model_3d. This allows multiple calls to distance_object_model_3d 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_3d can additionally perform the triangulation and save it to the object to further speed-up the distance_object_model_3d operator. This triangulation is only performed when the generic parameter 'distance_to' is set to 'triangles'. Note that this triangulation, contrary to that of the operator triangulate_object_model_3d, 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 ObjectModel3DFrom by setting the generic parameter 'store_closest_index' to 'true' (see below). The index is stored as extended attribute named '&closest_index' in the 3D object model ObjectModel3DFrom. Note that the closest index can not be computed when using the 'voxel' method. If a point's distance to its closest element exceeds the maximum distance set in MaxDistance, 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' has to be set to 'true'. Note that signed distances can not be computed when using the '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'.
The following methods are available to compute the distances from points to points:
For each point in ObjectModel3DFrom, the distances to all points in ObjectModel3DTo 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 ObjectModel3DTo.
The points in ObjectModel3DTo 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 ObjectModel3DTo. However, the search time is not constant, and can vary significantly depending on the position of the query points in ObjectModel3DFrom.
The points in ObjectModel3DTo 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 ObjectModel3DFrom and the number of points in ObjectModel3DTo.
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_3d on ObjectModel3DTo with Purpose set to 'distance_computation'.
For computing the distances to triangles, the following methods are supported:
For each point in ObjectModel3DFrom, the distances to all triangles in ObjectModel3DTo 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 ObjectModel3DTo.
The triangles in ObjectModel3DTo 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 ObjectModel3DTo. However, the search time is not constant, and can vary significantly depending on the position of the query points in ObjectModel3DFrom.
The triangles in ObjectModel3DTo 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 ObjectModel3DFrom and the number of triangles in ObjectModel3DTo.
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_3d on ObjectModel3DTo with Purpose set to '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' and '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.
Since ObjectModel3DTo 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_3d or fit_primitives_object_model_3d 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_params with parameter 'primitive_parameter_pose' and create a new plane using gen_plane_object_model_3d.
The following table lists the different target data types, methods, and their properties. The search time is the approximate time per point in ObjectModel3DFrom. N is the number of target elements in ObjectModel3DTo.
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_3d
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_3d
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 GenParamName and GenParamValue, respectively. All of the following parameters are optional.
This parameter can be used to explicitly set the target data to which the distances are computed.
(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.
Compute the distance to the primitive contained in ObjectModel3DTo.
Compute the distance to the triangles contained in ObjectModel3DTo.
Compute the distance to the points contained in ObjectModel3DTo.
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.
(Default) Use the default method for the used target data type.
Use a linear search for computing the distances.
Use a KD-Tree for computing the distances.
Use a voxel structure for computing the distances.
This parameter can be used to invert the pose given in Pose.
(Default) The pose is not inverted.
The pose is inverted.
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' in ObjectModel3DFrom. 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 '&'.
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', or relative to the diameter of the axis aligned bounding box, using 'sampling_dist_rel'. By default, '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_params. Note that the creation of the voxel data structure is very time consuming, and is usually performed offline using prepare_object_model_3d (see above).
This parameter can be used to return the index of the closest point or triangle in the extended attribute '&closest_index'.
(Default) The index is not returned.
The index is returned.
This parameter can be used to calculate signed distances of the points in the 3D object model ObjectModel3DFrom to the points, triangles or primitive in the 3D object model ObjectModel3DTo.
(Default) Unsigned distances are returned.
Signed distances are returned.
Dependent on the available target data (points, triangles or primitive) the following particularities have to be considered:
The computation of signed distances is only supported for the methods 'kd-tree' and '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_mod.
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.
When calculating signed distances to a cylindrical, spherical or box-shaped primitive, the points of the 3D object model ObjectModel3DFrom 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.
Handle of the source 3D object model.
Handle of the target 3D object model.
Pose of the source 3D object model in the target 3D object model.
Default value: []
Maximum distance of interest.
Default value: 0
Names of the generic input parameters.
Default value: []
List of values: 'distance_to', 'invert_pose', 'method', 'output_attribute', 'sampling_dist_abs', 'sampling_dist_rel', 'signed_distances', 'store_closest_index'
Values of the generic input parameters.
Default value: []
List of values: 'auto', 'false', 'kd-tree', 'linear', 'points', 'polygons', 'primitive', 'triangles', 'true', 'voxel'
distance_object_model_3d returns 2 (H_MSG_TRUE) if all parameters are correct. If necessary, an exception is raised.
prepare_object_model_3d, read_object_model_3d, find_surface_model, xyz_to_object_model_3d
get_object_model_3d_params, render_object_model_3d, disp_object_model_3d, clear_object_model_3d
3D Metrology
| Operators |