sample_object_model_3dT_sample_object_model_3dSampleObjectModel3dSampleObjectModel3dsample_object_model_3d (Operator)
Name
sample_object_model_3dT_sample_object_model_3dSampleObjectModel3dSampleObjectModel3dsample_object_model_3d — Sample a 3D object model.
Signature
void SampleObjectModel3d(const HTuple& ObjectModel3D, const HTuple& Method, const HTuple& SamplingParam, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* SampledObjectModel3D)
static HObjectModel3DArray HObjectModel3D::SampleObjectModel3d(const HObjectModel3DArray& ObjectModel3D, const HString& Method, const HTuple& SamplingParam, const HTuple& GenParamName, const HTuple& GenParamValue)
HObjectModel3D HObjectModel3D::SampleObjectModel3d(const HString& Method, double SamplingParam, const HTuple& GenParamName, const HTuple& GenParamValue) const
HObjectModel3D HObjectModel3D::SampleObjectModel3d(const char* Method, double SamplingParam, const HTuple& GenParamName, const HTuple& GenParamValue) const
HObjectModel3D HObjectModel3D::SampleObjectModel3d(const wchar_t* Method, double SamplingParam, const HTuple& GenParamName, const HTuple& GenParamValue) const
(
Windows only)
static void HOperatorSet.SampleObjectModel3d(HTuple objectModel3D, HTuple method, HTuple samplingParam, HTuple genParamName, HTuple genParamValue, out HTuple sampledObjectModel3D)
static HObjectModel3D[] HObjectModel3D.SampleObjectModel3d(HObjectModel3D[] objectModel3D, string method, HTuple samplingParam, HTuple genParamName, HTuple genParamValue)
HObjectModel3D HObjectModel3D.SampleObjectModel3d(string method, double samplingParam, HTuple genParamName, HTuple genParamValue)
def sample_object_model_3d(object_model_3d: MaybeSequence[HHandle], method: str, sampling_param: MaybeSequence[Union[float, int]], gen_param_name: Sequence[str], gen_param_value: Sequence[Union[int, str, float]]) -> Sequence[HHandle]
def sample_object_model_3d_s(object_model_3d: MaybeSequence[HHandle], method: str, sampling_param: MaybeSequence[Union[float, int]], gen_param_name: Sequence[str], gen_param_value: Sequence[Union[int, str, float]]) -> HHandle
Description
sample_object_model_3dsample_object_model_3dSampleObjectModel3dSampleObjectModel3dsample_object_model_3d creates a sampled version of the 3D object
model ObjectModel3DObjectModel3DObjectModel3DobjectModel3Dobject_model_3d and returns it in SampledObjectModel3DSampledObjectModel3DSampledObjectModel3DsampledObjectModel3Dsampled_object_model_3d.
Depending on the method used, SamplingParamSamplingParamSamplingParamsamplingParamsampling_param controls the minimum
distance or the number of points in SampledObjectModel3DSampledObjectModel3DSampledObjectModel3DsampledObjectModel3Dsampled_object_model_3d.
The created 3D object model is returned in SampledObjectModel3DSampledObjectModel3DSampledObjectModel3DsampledObjectModel3Dsampled_object_model_3d.
Using sample_object_model_3dsample_object_model_3dSampleObjectModel3dSampleObjectModel3dsample_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_3dsimplify_object_model_3dSimplifyObjectModel3dSimplifyObjectModel3dsimplify_object_model_3d should be used instead.
If the input object model ObjectModel3DObjectModel3DObjectModel3DobjectModel3Dobject_model_3d contains only points
(no faces, 3D primitive or lines),
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
closer than SamplingParamSamplingParamSamplingParamsamplingParamsampling_param to any point that was earlier added to
the output model.
- 'accurate'"accurate""accurate""accurate""accurate":
-
The method 'accurate'"accurate""accurate""accurate""accurate" goes through the points of the 3D object
model ObjectModel3DObjectModel3DObjectModel3DobjectModel3Dobject_model_3d and calculates whether any other points are
within a sphere with the radius SamplingParamSamplingParamSamplingParamsamplingParamsampling_param around the
examined point.
If there are no other points, the original point is stored
in SampledObjectModel3DSampledObjectModel3DSampledObjectModel3DsampledObjectModel3Dsampled_object_model_3d.
If there are other points, the center of gravity of these
points (including the original point) is stored in
SampledObjectModel3DSampledObjectModel3DSampledObjectModel3DsampledObjectModel3Dsampled_object_model_3d.
This procedure is repeated with the remaining points until there
are no points left.
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 GenParamNameGenParamNameGenParamNamegenParamNamegen_param_name and GenParamValueGenParamValueGenParamValuegenParamValuegen_param_value, 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 GenParamNameGenParamNameGenParamNamegenParamNamegen_param_name and
GenParamValueGenParamValueGenParamValuegenParamValuegen_param_value 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_3dXyzToObjectModel3dXyzToObjectModel3dxyz_to_object_model_3d).
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 SamplingParamSamplingParamSamplingParamsamplingParamsampling_param (which is given in
pixel) and selects one 3D point per square. The selected point
is stored in SampledObjectModel3DSampledObjectModel3DSampledObjectModel3DsampledObjectModel3Dsampled_object_model_3d with an adapted zoomed
image coordinate in the XYZ-mapping.
The method behaves similar to applying zoom_image_factorzoom_image_factorZoomImageFactorZoomImageFactorzoom_image_factor 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
SamplingParamSamplingParamSamplingParamsamplingParamsampling_param corresponds to a distance in pixels, not to a
distance in 3D space.
- 'furthest_point'"furthest_point""furthest_point""furthest_point""furthest_point":
-
The method 'furthest_point'"furthest_point""furthest_point""furthest_point""furthest_point" iteratively adds the point of the
input object to the output object that is furthest from all points
already added to the output model. This usually leads to a reasonably
uniform sampling.
For this method, the desired number of points in the output model is
passed in SamplingParamSamplingParamSamplingParamsamplingParamsampling_param.
If that number exceeds the number of points in the input object,
then all points of the input object are returned.
The first point added to the output object is the point that is
furthest away from the center of the axis aligned bounding box
around the points of the input object.
The methods 'fast_compute_normals'"fast_compute_normals""fast_compute_normals""fast_compute_normals""fast_compute_normals", 'xyz_mapping_compute_normals'"xyz_mapping_compute_normals""xyz_mapping_compute_normals""xyz_mapping_compute_normals""xyz_mapping_compute_normals",
and 'furthest_point_compute_normals'"furthest_point_compute_normals""furthest_point_compute_normals""furthest_point_compute_normals""furthest_point_compute_normals" select the same points
as the method name without '_compute_normals'"_compute_normals""_compute_normals""_compute_normals""_compute_normals", but additionally calculate 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
xyz_to_object_model_3dxyz_to_object_model_3dXyzToObjectModel3dXyzToObjectModel3dxyz_to_object_model_3d.
For some methods, if present, normals, XYZ-mapping or extended point attributes are
copied to the output model. If a dense XYZ-mapping is wanted for further processing,
'xyz_mapping'"xyz_mapping""xyz_mapping""xyz_mapping""xyz_mapping" or 'xyz_mapping_compute_normals'"xyz_mapping_compute_normals""xyz_mapping_compute_normals""xyz_mapping_compute_normals""xyz_mapping_compute_normals" should be chosen.
Required data:
MethodMethodMethodmethodmethod |
requires and adapts XYZ-mapping |
requires normals |
| 'fast'"fast""fast""fast""fast" |
|
|
|
'fast_compute_normals'"fast_compute_normals""fast_compute_normals""fast_compute_normals""fast_compute_normals" |
|
|
|
'accurate'"accurate""accurate""accurate""accurate" |
|
|
|
'accurate_use_normals'"accurate_use_normals""accurate_use_normals""accurate_use_normals""accurate_use_normals" |
|
x |
|
'xyz_mapping'"xyz_mapping""xyz_mapping""xyz_mapping""xyz_mapping" |
x |
|
|
'xyz_mapping_compute_normals'"xyz_mapping_compute_normals""xyz_mapping_compute_normals""xyz_mapping_compute_normals""xyz_mapping_compute_normals" |
x |
|
|
'furthest_point'"furthest_point""furthest_point""furthest_point""furthest_point" |
|
|
|
'furthest_point_compute_normals'"furthest_point_compute_normals""furthest_point_compute_normals""furthest_point_compute_normals""furthest_point_compute_normals" |
|
|
Copied attributes:
MethodMethodMethodmethodmethod |
XYZ-mapping |
normals |
ext. point attrib. |
|
'fast'"fast""fast""fast""fast" |
x |
x |
x |
|
'fast_compute_normals'"fast_compute_normals""fast_compute_normals""fast_compute_normals""fast_compute_normals" |
x |
x |
x |
|
'accurate'"accurate""accurate""accurate""accurate" |
x |
x |
|
|
'accurate_use_normals'"accurate_use_normals""accurate_use_normals""accurate_use_normals""accurate_use_normals" |
x |
x |
|
|
'xyz_mapping'"xyz_mapping""xyz_mapping""xyz_mapping""xyz_mapping" |
|
x |
x |
|
'xyz_mapping_compute_normals'"xyz_mapping_compute_normals""xyz_mapping_compute_normals""xyz_mapping_compute_normals""xyz_mapping_compute_normals" |
|
x |
x |
|
'furthest_point'"furthest_point""furthest_point""furthest_point""furthest_point" |
x |
x |
x |
|
'furthest_point_compute_normals'"furthest_point_compute_normals""furthest_point_compute_normals""furthest_point_compute_normals""furthest_point_compute_normals" |
x |
x |
x
|
Computed attributes:
MethodMethodMethodmethodmethod |
computes normals from XYZ-mapping |
|
'fast'"fast""fast""fast""fast" |
|
|
'fast_compute_normals'"fast_compute_normals""fast_compute_normals""fast_compute_normals""fast_compute_normals" |
x |
|
'accurate'"accurate""accurate""accurate""accurate" |
|
|
'accurate_use_normals'"accurate_use_normals""accurate_use_normals""accurate_use_normals""accurate_use_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" |
x |
|
'furthest_point'"furthest_point""furthest_point""furthest_point""furthest_point" |
|
|
'furthest_point_compute_normals'"furthest_point_compute_normals""furthest_point_compute_normals""furthest_point_compute_normals""furthest_point_compute_normals" |
x
|
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.
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
or outwards.
Note that planes and cylinders must have finite extent.
If the input object model contains lines, the lines are sampled with the
given distance SamplingParamSamplingParamSamplingParamsamplingParamsampling_param.
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 SamplingParamSamplingParamSamplingParamsamplingParamsampling_param accepts either one value, which is
then used for all 3D object models passed in ObjectModel3DObjectModel3DObjectModel3DobjectModel3Dobject_model_3d, or one
value per input object model. If SamplingParamSamplingParamSamplingParamsamplingParamsampling_param is a distance in 3D
space the unit is the usual HALCON-internal unit 'm'"m""m""m""m".
Execution Information
- Multithreading type: reentrant (runs in parallel with non-exclusive operators).
- Multithreading scope: global (may be called from any thread).
- Processed without parallelization.
This operator supports canceling timeouts and interrupts.
Parameters
ObjectModel3DObjectModel3DObjectModel3DobjectModel3Dobject_model_3d (input_control) object_model_3d(-array) → HObjectModel3D, HTupleMaybeSequence[HHandle]HTupleHtuple (handle) (IntPtr) (HHandle) (handle)
Handle of the 3D object model to be sampled.
MethodMethodMethodmethodmethod (input_control) string → HTuplestrHTupleHtuple (string) (string) (HString) (char*)
Selects between the different subsampling methods.
Default:
'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", 'furthest_point'"furthest_point""furthest_point""furthest_point""furthest_point", 'furthest_point_compute_normals'"furthest_point_compute_normals""furthest_point_compute_normals""furthest_point_compute_normals""furthest_point_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"
SamplingParamSamplingParamSamplingParamsamplingParamsampling_param (input_control) real(-array) → HTupleMaybeSequence[Union[float, int]]HTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)
Sampling distance or number of points.
Number of elements:
SamplingParam == 1 || SamplingParam == ObjectModel3D
Default:
0.05
GenParamNameGenParamNameGenParamNamegenParamNamegen_param_name (input_control) string-array → HTupleSequence[str]HTupleHtuple (string) (string) (HString) (char*)
Names of the generic parameters that can be adjusted.
Default:
[]
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"
GenParamValueGenParamValueGenParamValuegenParamValuegen_param_value (input_control) number-array → HTupleSequence[Union[int, str, float]]HTupleHtuple (real / integer / string) (double / int / long / string) (double / Hlong / HString) (double / Hlong / char*)
Values of the generic parameters that can be
adjusted.
Default:
[]
Suggested values:
1, 2, 5, 10, 20, 0.1, 0.25, 0.5
SampledObjectModel3DSampledObjectModel3DSampledObjectModel3DsampledObjectModel3Dsampled_object_model_3d (output_control) object_model_3d(-array) → HObjectModel3D, HTupleSequence[HHandle]HTupleHtuple (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_3dSampleObjectModel3dSampleObjectModel3dsample_object_model_3d returns 2 (
H_MSG_TRUE)
if all parameters
are correct. If necessary, an exception is raised.
Possible Predecessors
read_object_model_3dread_object_model_3dReadObjectModel3dReadObjectModel3dread_object_model_3d,
gen_plane_object_model_3dgen_plane_object_model_3dGenPlaneObjectModel3dGenPlaneObjectModel3dgen_plane_object_model_3d,
gen_sphere_object_model_3dgen_sphere_object_model_3dGenSphereObjectModel3dGenSphereObjectModel3dgen_sphere_object_model_3d,
gen_cylinder_object_model_3dgen_cylinder_object_model_3dGenCylinderObjectModel3dGenCylinderObjectModel3dgen_cylinder_object_model_3d,
gen_box_object_model_3dgen_box_object_model_3dGenBoxObjectModel3dGenBoxObjectModel3dgen_box_object_model_3d,
gen_sphere_object_model_3d_centergen_sphere_object_model_3d_centerGenSphereObjectModel3dCenterGenSphereObjectModel3dCentergen_sphere_object_model_3d_center,
xyz_to_object_model_3dxyz_to_object_model_3dXyzToObjectModel3dXyzToObjectModel3dxyz_to_object_model_3d
Possible Successors
get_object_model_3d_paramsget_object_model_3d_paramsGetObjectModel3dParamsGetObjectModel3dParamsget_object_model_3d_params,
clear_object_model_3dclear_object_model_3dClearObjectModel3dClearObjectModel3dclear_object_model_3d
Alternatives
simplify_object_model_3dsimplify_object_model_3dSimplifyObjectModel3dSimplifyObjectModel3dsimplify_object_model_3d,
smooth_object_model_3dsmooth_object_model_3dSmoothObjectModel3dSmoothObjectModel3dsmooth_object_model_3d
Module
3D Metrology