sample_object_model_3dT_sample_object_model_3dSampleObjectModel3dSampleObjectModel3d (Operator)

Name

sample_object_model_3dT_sample_object_model_3dSampleObjectModel3dSampleObjectModel3d — Sample a 3D object model.

Signature

sample_object_model_3d( : : ObjectModel3D, Method, SampleDistance, GenParamName, GenParamValue : SampledObjectModel3D)

Herror T_sample_object_model_3d(const Htuple ObjectModel3D, const Htuple Method, const Htuple SampleDistance, const Htuple GenParamName, const Htuple GenParamValue, Htuple* SampledObjectModel3D)

void SampleObjectModel3d(const HTuple& ObjectModel3D, const HTuple& Method, const HTuple& SampleDistance, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* SampledObjectModel3D)

static HObjectModel3DArray HObjectModel3D::SampleObjectModel3d(const HObjectModel3DArray& ObjectModel3D, const HString& Method, const HTuple& SampleDistance, const HTuple& GenParamName, const HTuple& GenParamValue)

HObjectModel3D HObjectModel3D::SampleObjectModel3d(const HString& Method, double SampleDistance, const HTuple& GenParamName, const HTuple& GenParamValue) const

HObjectModel3D HObjectModel3D::SampleObjectModel3d(const char* Method, double SampleDistance, const HTuple& GenParamName, const HTuple& GenParamValue) const

HObjectModel3D HObjectModel3D::SampleObjectModel3d(const wchar_t* Method, double SampleDistance, const HTuple& GenParamName, const HTuple& GenParamValue) const   (Windows only)

static void HOperatorSet.SampleObjectModel3d(HTuple objectModel3D, HTuple method, HTuple sampleDistance, HTuple genParamName, HTuple genParamValue, out HTuple sampledObjectModel3D)

static HObjectModel3D[] HObjectModel3D.SampleObjectModel3d(HObjectModel3D[] objectModel3D, string method, HTuple sampleDistance, HTuple genParamName, HTuple genParamValue)

HObjectModel3D HObjectModel3D.SampleObjectModel3d(string method, double sampleDistance, HTuple genParamName, HTuple genParamValue)

Description

sample_object_model_3dsample_object_model_3dSampleObjectModel3dSampleObjectModel3dSampleObjectModel3d creates a sampled version of the 3D object model ObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3D which consists of points that have the minimum distance SampleDistanceSampleDistanceSampleDistanceSampleDistancesampleDistance to each other. The created 3D object model is returned in SampledObjectModel3DSampledObjectModel3DSampledObjectModel3DSampledObjectModel3DsampledObjectModel3D.

Using sample_object_model_3dsample_object_model_3dSampleObjectModel3dSampleObjectModel3dSampleObjectModel3d 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_3dsimplify_object_model_3dSimplifyObjectModel3dSimplifyObjectModel3dSimplifyObjectModel3d should be used instead.

If the input object model ObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3D contains only points, several sampling methods are available which can be selected using the parameter MethodMethodMethodMethodmethod:

'fast'"fast""fast""fast""fast"

: The default method 'fast'"fast""fast""fast""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.

'fast_compute_normals'"fast_compute_normals""fast_compute_normals""fast_compute_normals""fast_compute_normals"

: The method 'fast_compute_normals'"fast_compute_normals""fast_compute_normals""fast_compute_normals""fast_compute_normals" selects the same points as the method 'fast'"fast""fast""fast""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 XYZ-mapping is created by xyz_to_object_model_3dxyz_to_object_model_3dXyzToObjectModel3dXyzToObjectModel3dXyzToObjectModel3d.

'accurate'"accurate""accurate""accurate""accurate"

: The method 'accurate'"accurate""accurate""accurate""accurate" goes through the points of the 3D object model ObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3D and calculates whether any other points are within a sphere with the radius SampleDistanceSampleDistanceSampleDistanceSampleDistancesampleDistance around the examined point. If there are no other points, the original point is stored in SampledObjectModel3DSampledObjectModel3DSampledObjectModel3DSampledObjectModel3DsampledObjectModel3D. If there are other points, the center of gravity of these points (including the original point) is stored in SampledObjectModel3DSampledObjectModel3DSampledObjectModel3DSampledObjectModel3DsampledObjectModel3D. 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'"min_num_points""min_num_points""min_num_points""min_num_points" in GenParamNameGenParamNameGenParamNameGenParamNamegenParamName and GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue, which removes all interpolated points that had less than the specified number of neighbor points in the original model.

'accurate_use_normals'"accurate_use_normals""accurate_use_normals""accurate_use_normals""accurate_use_normals"

: The method 'accurate_use_normals'"accurate_use_normals""accurate_use_normals""accurate_use_normals""accurate_use_normals" requires normals in the input 3D object model and interpolates only points with similar normals. The similarity depends on the angle between the normals. The threshold of the angle can be specified in GenParamNameGenParamNameGenParamNameGenParamNamegenParamName and GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue with 'max_angle_diff'"max_angle_diff""max_angle_diff""max_angle_diff""max_angle_diff". The default value is 180 degrees. Additionally, outliers can be removed as described in the method 'accurate'"accurate""accurate""accurate""accurate", by setting the generic parameter 'min_num_points'"min_num_points""min_num_points""min_num_points""min_num_points".

'xyz_mapping'"xyz_mapping""xyz_mapping""xyz_mapping""xyz_mapping"

: The method 'xyz_mapping'"xyz_mapping""xyz_mapping""xyz_mapping""xyz_mapping" can only be applied to 3D object models that contain an XYZ-mapping (for example, if it was created using xyz_to_object_model_3dxyz_to_object_model_3dXyzToObjectModel3dXyzToObjectModel3dXyzToObjectModel3d). This mapping stores for each 3D point its original image coordinates. The method 'xyz_mapping'"xyz_mapping""xyz_mapping""xyz_mapping""xyz_mapping" subdivides those original images into squares with side length SampleDistanceSampleDistanceSampleDistanceSampleDistancesampleDistance (which is given in pixel) and selects one 3D point per square.

The method behaves similar to appying zoom_image_factorzoom_image_factorZoomImageFactorZoomImageFactorZoomImageFactor onto 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 SampleDistanceSampleDistanceSampleDistanceSampleDistancesampleDistance corresponds to a distance in pixels, not to a distance in 3D space as for the other methods.

'xyz_mapping_compute_normals'"xyz_mapping_compute_normals""xyz_mapping_compute_normals""xyz_mapping_compute_normals""xyz_mapping_compute_normals"

: The method 'xyz_mapping_compute_normals'"xyz_mapping_compute_normals""xyz_mapping_compute_normals""xyz_mapping_compute_normals""xyz_mapping_compute_normals" selects the same points as the method 'xyz_mapping'"xyz_mapping""xyz_mapping""xyz_mapping""xyz_mapping", but additionally calculates the normals for all points that were selected. 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 distance. In this case, the method specified in MethodMethodMethodMethodmethod is ignored. Note that planes and cylinders must have finite extent. If the input object model contains lines, the lines are sampled with the given distance.

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.

The parameter SampleDistanceSampleDistanceSampleDistanceSampleDistancesampleDistance accepts either one value, which is then used for all 3D object models passed in ObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3D, or one value per input object model. The unit of the sample distance is the usual HALCON-internal unit 'm'"m""m""m""m".

Execution Information

This operator supports cancelling timeouts and interrupts.

Parameters

ObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3D (input_control)  object_model_3d(-array) HObjectModel3D, HTupleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the 3D object model to be sampled.

MethodMethodMethodMethodmethod (input_control)  string HTupleHTupleHtuple (string) (string) (HString) (char*)

Selects between the different subsampling methods.

Default value: 'fast' "fast" "fast" "fast" "fast"

List of values: 'accurate'"accurate""accurate""accurate""accurate", 'accurate_use_normals'"accurate_use_normals""accurate_use_normals""accurate_use_normals""accurate_use_normals", 'fast'"fast""fast""fast""fast", 'fast_compute_normals'"fast_compute_normals""fast_compute_normals""fast_compute_normals""fast_compute_normals", 'xyz_mapping'"xyz_mapping""xyz_mapping""xyz_mapping""xyz_mapping", 'xyz_mapping_compute_normals'"xyz_mapping_compute_normals""xyz_mapping_compute_normals""xyz_mapping_compute_normals""xyz_mapping_compute_normals"

SampleDistanceSampleDistanceSampleDistanceSampleDistancesampleDistance (input_control)  real(-array) HTupleHTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)

Sampling distance.

Number of elements: SampleDistance == 1 || SampleDistance == ObjectModel3D

Default value: 0.05

GenParamNameGenParamNameGenParamNameGenParamNamegenParamName (input_control)  string-array HTupleHTupleHtuple (string) (string) (HString) (char*)

Names of the generic parameters that can be adjusted.

Default value: []

List of values: 'max_angle_diff'"max_angle_diff""max_angle_diff""max_angle_diff""max_angle_diff", 'min_num_points'"min_num_points""min_num_points""min_num_points""min_num_points"

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

Values of the generic parameters that can be adjusted.

Default value: []

Suggested values: 1, 2, 5, 10, 20, 0.1, 0.25, 0.5

SampledObjectModel3DSampledObjectModel3DSampledObjectModel3DSampledObjectModel3DsampledObjectModel3D (output_control)  object_model_3d(-array) HObjectModel3D, HTupleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the 3D object model that contains the sampled points.

Number of elements: SampledObjectModel3D == ObjectModel3D

Example (HDevelop)

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)

Result

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

Possible Predecessors

read_object_model_3dread_object_model_3dReadObjectModel3dReadObjectModel3dReadObjectModel3d, gen_plane_object_model_3dgen_plane_object_model_3dGenPlaneObjectModel3dGenPlaneObjectModel3dGenPlaneObjectModel3d, gen_sphere_object_model_3dgen_sphere_object_model_3dGenSphereObjectModel3dGenSphereObjectModel3dGenSphereObjectModel3d, gen_cylinder_object_model_3dgen_cylinder_object_model_3dGenCylinderObjectModel3dGenCylinderObjectModel3dGenCylinderObjectModel3d, gen_box_object_model_3dgen_box_object_model_3dGenBoxObjectModel3dGenBoxObjectModel3dGenBoxObjectModel3d, gen_sphere_object_model_3d_centergen_sphere_object_model_3d_centerGenSphereObjectModel3dCenterGenSphereObjectModel3dCenterGenSphereObjectModel3dCenter, xyz_to_object_model_3dxyz_to_object_model_3dXyzToObjectModel3dXyzToObjectModel3dXyzToObjectModel3d

Possible Successors

get_object_model_3d_paramsget_object_model_3d_paramsGetObjectModel3dParamsGetObjectModel3dParamsGetObjectModel3dParams, clear_object_model_3dclear_object_model_3dClearObjectModel3dClearObjectModel3dClearObjectModel3d

Alternatives

simplify_object_model_3dsimplify_object_model_3dSimplifyObjectModel3dSimplifyObjectModel3dSimplifyObjectModel3d, smooth_object_model_3dsmooth_object_model_3dSmoothObjectModel3dSmoothObjectModel3dSmoothObjectModel3d

Module

3D Metrology