sample_object_model_3d — Sample a 3D object model.
sample_object_model_3d creates a sampled version of the 3D object
ObjectModel3D which consists of points that have the
SampleDistance to each other.
The created 3D object model is returned in
sample_object_model_3d is recommended if complex point clouds
are to be thinned out for faster postprocessing or if primitives are to be
converted to point clouds.
Note that if the 3D object model is triangulated and should be simplified by
preserving its original geometry as good as possible,
simplify_object_model_3d should be used instead.
If the input object model
ObjectModel3D contains only points,
several sampling methods are available which can be selected using
The default method 'fast' adds all points from the input model which are not close to any point that was earlier added to the output model. If present, normals, XYZ-mapping and extended point attributes are copied to the output model.
The method 'fast_compute_normals' selects the same points
as the method 'fast', but additionally calculates the
normals for all points that were selected.
For this, the input object model must either contain normals, which are
copied, or it must contain a XYZ-mapping attribute from which the
normals are computed. The z-component of the calculated normal
vectors is always positive. The XYZ-mapping is created by
The method 'accurate' goes through the points of the 3D object
ObjectModel3D and calculates whether any other points are
within a sphere with the radius
SampleDistance around the
If there are no other points, the original point is stored
If there are other points, the center of gravity of these
points (including the original point) is stored in
This procedure is repeated with the remaining points until there
are no points left.
Extended attributes of the input 3D object model are not copied, but
normals and XYZ-mapping are copied.
For this method, a noise removal is possible by specifying a
value for 'min_num_points'
GenParamValue, which removes all
interpolated points that had less than the specified number of neighbor
points in the original model.
The method 'accurate_use_normals' requires normals in the
input 3D object model and interpolates only points with similar
The similarity depends on the angle between the normals. The threshold
of the angle can be specified in
GenParamValue with 'max_angle_diff'.
The default value is 180 degrees.
Additionally, outliers can be removed as described in the method
'accurate', by setting the generic parameter
The method 'xyz_mapping' can only be applied to 3D object models
that contain an XYZ-mapping (for example, if it was created using
This mapping stores for each 3D point its original image coordinates.
The method 'xyz_mapping' subdivides those original images into
squares with side length
SampleDistance (which is given in
pixel) and selects one 3D point per square.
The method behaves similar to applying
the original XYZ-images.
Note that this method does not use the 3D-coordinates of the points for
the point selection, only their 2D image coordinates.
It is important to notice that for this method, the parameter
SampleDistance corresponds to a distance in pixels, not to a
distance in 3D space as for the other methods.
The method 'xyz_mapping_compute_normals' selects the same points as the method 'xyz_mapping', but additionally calculates the normals for all points that were selected. The z-component of the normal vectors is always positive. If the input object model contains normals, those normals are copied to the output. Otherwise, the normals are computed based on the XYZ-mapping.
If the input object model contains faces (triangles or polygons) or is
a 3D primitive, the surface is sampled with the given
In this case, the method specified in
Method is ignored.
The directions of the computed normals depend on the face orientation of the
model. Usually, the orientation of the faces does not vary within one
CAD model, which results in a set of normals that is either pointing inwards
Note that planes and cylinders must have finite extent.
If the input object model contains lines, the lines are sampled with the
The sampling process approximates surfaces by creating new points in the output object model. Therefore, any extended attributes from the input object model are discarded.
For mixed input object models, the sampling priority is (from top to bottom) faces, lines, primitives and points, i.e., only the objects of the highest priority are sampled.
SampleDistance accepts either one value, which is
then used for all 3D object models passed in
ObjectModel3D, or one
value per input object model. The unit of the sample distance is the usual
HALCON-internal unit 'm'.
This operator supports cancelling timeouts and interrupts.
Handle of the 3D object model to be sampled.
Selects between the different subsampling methods.
Default value: 'fast'
List of values: 'accurate', 'accurate_use_normals', 'fast', 'fast_compute_normals', 'xyz_mapping', 'xyz_mapping_compute_normals'
→(real / integer)
Number of elements: SampleDistance == 1 || SampleDistance == ObjectModel3D
Default value: 0.05
Names of the generic parameters that can be adjusted.
Default value: 
List of values: 'max_angle_diff', 'min_num_points'
→(real / integer / string)
Values of the generic parameters that can be adjusted.
Default value: 
Suggested values: 1, 2, 5, 10, 20, 0.1, 0.25, 0.5
Handle of the 3D object model that contains the sampled points.
Number of elements: SampledObjectModel3D == ObjectModel3D
gen_box_object_model_3d ([0,0,0,0,0,0,0],3,2,1, ObjectModel3D) sample_object_model_3d (ObjectModel3D, 'fast', 0.05, , , \ SampledObjectModel3D) dev_get_window (WindowHandle) visualize_object_model_3d (WindowHandle, SampledObjectModel3D, \ , , , , , , , PoseOut)
sample_object_model_3d returns TRUE if all parameters
are correct. If necessary, an exception is raised.