Name
create_surface_modelcreate_surface_modelCreateSurfaceModelcreate_surface_modelCreateSurfaceModelCreateSurfaceModel — Create the data structure needed to perform surface-based matching.
void CreateSurfaceModel(const HTuple& ObjectModel3D, const HTuple& RelSamplingDistance, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* SurfaceModelID)
HSurfaceModel HObjectModel3D::CreateSurfaceModel(double RelSamplingDistance, const HTuple& GenParamName, const HTuple& GenParamValue) const
HSurfaceModel HObjectModel3D::CreateSurfaceModel(double RelSamplingDistance, const HString& GenParamName, const HString& GenParamValue) const
HSurfaceModel HObjectModel3D::CreateSurfaceModel(double RelSamplingDistance, const char* GenParamName, const char* GenParamValue) const
void HSurfaceModel::HSurfaceModel(const HObjectModel3D& ObjectModel3D, double RelSamplingDistance, const HTuple& GenParamName, const HTuple& GenParamValue)
void HSurfaceModel::HSurfaceModel(const HObjectModel3D& ObjectModel3D, double RelSamplingDistance, const HString& GenParamName, const HString& GenParamValue)
void HSurfaceModel::HSurfaceModel(const HObjectModel3D& ObjectModel3D, double RelSamplingDistance, const char* GenParamName, const char* GenParamValue)
void HSurfaceModel::CreateSurfaceModel(const HObjectModel3D& ObjectModel3D, double RelSamplingDistance, const HTuple& GenParamName, const HTuple& GenParamValue)
void HSurfaceModel::CreateSurfaceModel(const HObjectModel3D& ObjectModel3D, double RelSamplingDistance, const HString& GenParamName, const HString& GenParamValue)
void HSurfaceModel::CreateSurfaceModel(const HObjectModel3D& ObjectModel3D, double RelSamplingDistance, const char* GenParamName, const char* GenParamValue)
static void HOperatorSet.CreateSurfaceModel(HTuple objectModel3D, HTuple relSamplingDistance, HTuple genParamName, HTuple genParamValue, out HTuple surfaceModelID)
HSurfaceModel HObjectModel3D.CreateSurfaceModel(double relSamplingDistance, HTuple genParamName, HTuple genParamValue)
HSurfaceModel HObjectModel3D.CreateSurfaceModel(double relSamplingDistance, string genParamName, string genParamValue)
public HSurfaceModel(HObjectModel3D objectModel3D, double relSamplingDistance, HTuple genParamName, HTuple genParamValue)
public HSurfaceModel(HObjectModel3D objectModel3D, double relSamplingDistance, string genParamName, string genParamValue)
void HSurfaceModel.CreateSurfaceModel(HObjectModel3D objectModel3D, double relSamplingDistance, HTuple genParamName, HTuple genParamValue)
void HSurfaceModel.CreateSurfaceModel(HObjectModel3D objectModel3D, double relSamplingDistance, string genParamName, string genParamValue)
The operator create_surface_modelcreate_surface_modelCreateSurfaceModelcreate_surface_modelCreateSurfaceModelCreateSurfaceModel creates a model for surface-based
matching for the 3D object model ObjectModel3DObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3D.
The 3D object model can, for example, have been read previously from a file
by using read_object_model_3dread_object_model_3dReadObjectModel3dread_object_model_3dReadObjectModel3dReadObjectModel3d, or been created by using
xyz_to_object_model_3dxyz_to_object_model_3dXyzToObjectModel3dxyz_to_object_model_3dXyzToObjectModel3dXyzToObjectModel3d.
The created surface model is returned in SurfaceModelIDSurfaceModelIDSurfaceModelIDSurfaceModelIDSurfaceModelIDsurfaceModelID.
The creation of the surface model requires that the 3D object model
contains points and normals. The following combinations are possible:
Note that the direction and orientation (inward or outward) of the normals
of the model are important for matching.
The surface model is created by sampling the 3D object model with a certain
distance.
The sampling distance must be specified in the parameter
RelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistancerelSamplingDistance and is parametrized relative to the diameter
of the axis-parallel bounding box of the 3d object model.
For example, if RelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistancerelSamplingDistance is set to 0.05 and
the diameter of ObjectModel3DObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3D is '10 cm'"10 cm""10 cm""10 cm""10 cm""10 cm", the points
sampled from the object's surface will be approximately '5 mm'"5 mm""5 mm""5 mm""5 mm""5 mm"
apart.
The sampled points are used for the approximate matching in the
operator find_surface_modelfind_surface_modelFindSurfaceModelfind_surface_modelFindSurfaceModelFindSurfaceModel (see below).
The sampled points can be obtained with the operator
get_surface_model_paramget_surface_model_paramGetSurfaceModelParamget_surface_model_paramGetSurfaceModelParamGetSurfaceModelParam using the value 'sampled_model'"sampled_model""sampled_model""sampled_model""sampled_model""sampled_model".
Note that outlier points in the object model should be avoided, as they would
corrupt the diameter.
Reducing RelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistancerelSamplingDistance leads to more points, and in turn
to a more stable but slower matching. Increasing
RelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistancerelSamplingDistance leads to less points, and in turn to a less
stable but faster matching.
The sampled points are used for finding the object model in a scene by using
the operator find_surface_modelfind_surface_modelFindSurfaceModelfind_surface_modelFindSurfaceModelFindSurfaceModel.
For this, all possible pairs of points from the point set are examined, and
the distance and relative surface orientation of each pair is computed. Both
values are discretized and stored for matching. The generic parameters
'feat_step_size_rel'"feat_step_size_rel""feat_step_size_rel""feat_step_size_rel""feat_step_size_rel""feat_step_size_rel" and 'feat_angle_resolution'"feat_angle_resolution""feat_angle_resolution""feat_angle_resolution""feat_angle_resolution""feat_angle_resolution" can be
used to set the discretization of the distance and the orientation angles,
respectively (see below).
The 3D object model is sampled a second time for the pose refinement.
The second sampling is done with a smaller sampling distance, leading to
more points.
The generic parameter 'pose_ref_rel_sampling_distance'"pose_ref_rel_sampling_distance""pose_ref_rel_sampling_distance""pose_ref_rel_sampling_distance""pose_ref_rel_sampling_distance""pose_ref_rel_sampling_distance" sets the
sampling distance relative to the object's diameter.
Decreasing the value results in a more accurate pose refinement but a
larger model and a slower model generation and matching.
Increasing the value leads to a less accurate pose refinement but
a smaller model and faster model generation and matching (see below).
The generic parameter pair GenParamNameGenParamNameGenParamNameGenParamNameGenParamNamegenParamName and GenParamValueGenParamValueGenParamValueGenParamValueGenParamValuegenParamValue
are used to set additional parameters for the model generation.
GenParamNameGenParamNameGenParamNameGenParamNameGenParamNamegenParamName contains the tuple of parameter names that shall be
set and GenParamValueGenParamValueGenParamValueGenParamValueGenParamValuegenParamValue contains the corresponding values.
The following values are possible for GenParamNameGenParamNameGenParamNameGenParamNameGenParamNamegenParamName:
- 'model_invert_normals'"model_invert_normals""model_invert_normals""model_invert_normals""model_invert_normals""model_invert_normals":
-
Invert the orientation of the surface normals of the model.
The normal orientation needs to be known for the model generation.
If both the model and the scene are aquired with the same setup,
the normals will already point in the same direction.
If the model was loaded from a CAD file, the normals might point
into the opposite direction. If you experience the effect that the
model is found on the 'outside' of the scene surface and the
model was created from a CAD file, try to set this parameter to
'true'"true""true""true""true""true".
Also, make sure that the normals in the CAD file all point either
outward or inward, i.e., are oriented consistently.
The normal direction is irrelevant for the pose refinement of
the surface model. Therefore, if the object model is only used with the
operator refine_surface_model_poserefine_surface_model_poseRefineSurfaceModelPoserefine_surface_model_poseRefineSurfaceModelPoseRefineSurfaceModelPose, the value of
'model_invert_normals'"model_invert_normals""model_invert_normals""model_invert_normals""model_invert_normals""model_invert_normals" has no effect on the result.
Possible values: 'false'"false""false""false""false""false", 'true'"true""true""true""true""true"
Default value: 'false'"false""false""false""false""false"
- 'pose_ref_rel_sampling_distance'"pose_ref_rel_sampling_distance""pose_ref_rel_sampling_distance""pose_ref_rel_sampling_distance""pose_ref_rel_sampling_distance""pose_ref_rel_sampling_distance":
-
Set the sampling distance for the pose refinement relative to the
object's diameter.
Decreasing this value leads to a more accurate pose refinement but a
larger model and slower model generation and refinement.
Increasing the value leads to a less accurate pose refinement but a
smaller model and faster model generation and matching.
Suggested values: 0.05, 0.02, 0.01,
0.005
Default value: 0.01
Assertion: 0 < 'pose_ref_rel_sampling_distance'"pose_ref_rel_sampling_distance""pose_ref_rel_sampling_distance""pose_ref_rel_sampling_distance""pose_ref_rel_sampling_distance""pose_ref_rel_sampling_distance" < 1
- 'feat_step_size_rel'"feat_step_size_rel""feat_step_size_rel""feat_step_size_rel""feat_step_size_rel""feat_step_size_rel":
-
Set the discretization distance of the point pair distance relative to
the object's diameter.
This value defaults to the value of RelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistancerelSamplingDistance.
It is not recommended to change this value.
For very noisy scenes, the value can be increased to improve the
robustness of the matching against noisy points.
Suggested values: 0.1, 0.05, 0.03
Default value: Value of RelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistancerelSamplingDistance
Assertion: 0 < 'feat_step_size_rel'"feat_step_size_rel""feat_step_size_rel""feat_step_size_rel""feat_step_size_rel""feat_step_size_rel" < 1
- 'feat_angle_resolution'"feat_angle_resolution""feat_angle_resolution""feat_angle_resolution""feat_angle_resolution""feat_angle_resolution":
-
Set the discretization of the point pair orientation as the number of
subdivisions of the angle.
It is recommended to not change this value.
Increasing the value increases the precision of the matching but
decreases the robustness against incorrect normal directions.
Decreasing the value decreases the precision of the matching but
increases the robustness against incorrect normal directions.
For very noisy scenes where the normal directions can not be computed
accurately, the value can be set to 25 or 20.
Suggested values: 20, 25, 30
Default value: 30
Assertion: 'feat_angle_resolution'"feat_angle_resolution""feat_angle_resolution""feat_angle_resolution""feat_angle_resolution""feat_angle_resolution" > 1
- Multithreading type: exclusive (runs in parallel only with independent operators).
- Multithreading scope: global (may be called from any thread).
- Processed without parallelization.
Handle of the 3D object model.
Sampling distance relative to the object's diameter
Default value: 0.03
Suggested values: 0.1, 0.05, 0.03, 0.02, 0.01
Restriction: 0 < RelSamplingDistance < 1
Names of the generic parameters.
Default value: []
Suggested values: 'model_invert_normals'"model_invert_normals""model_invert_normals""model_invert_normals""model_invert_normals""model_invert_normals", 'pose_ref_rel_sampling_distance'"pose_ref_rel_sampling_distance""pose_ref_rel_sampling_distance""pose_ref_rel_sampling_distance""pose_ref_rel_sampling_distance""pose_ref_rel_sampling_distance", 'feat_step_size_rel'"feat_step_size_rel""feat_step_size_rel""feat_step_size_rel""feat_step_size_rel""feat_step_size_rel", 'feat_angle_resolution'"feat_angle_resolution""feat_angle_resolution""feat_angle_resolution""feat_angle_resolution""feat_angle_resolution"
Values of the generic parameters.
Default value: []
Suggested values: 0, 1, 'true'"true""true""true""true""true", 'false'"false""false""false""false""false", 0.005, 0.01, 0.02, 0.05, 0.1
Handle of the surface model.
create_surface_modelcreate_surface_modelCreateSurfaceModelcreate_surface_modelCreateSurfaceModelCreateSurfaceModel returns 2 (H_MSG_TRUE) if all parameters are
correct. If necessary, an exception is raised.
read_object_model_3dread_object_model_3dReadObjectModel3dread_object_model_3dReadObjectModel3dReadObjectModel3d,
xyz_to_object_model_3dxyz_to_object_model_3dXyzToObjectModel3dxyz_to_object_model_3dXyzToObjectModel3dXyzToObjectModel3d,
get_object_model_3d_paramsget_object_model_3d_paramsGetObjectModel3dParamsget_object_model_3d_paramsGetObjectModel3dParamsGetObjectModel3dParams
find_surface_modelfind_surface_modelFindSurfaceModelfind_surface_modelFindSurfaceModelFindSurfaceModel,
refine_surface_model_poserefine_surface_model_poseRefineSurfaceModelPoserefine_surface_model_poseRefineSurfaceModelPoseRefineSurfaceModelPose,
get_surface_model_paramget_surface_model_paramGetSurfaceModelParamget_surface_model_paramGetSurfaceModelParamGetSurfaceModelParam,
write_surface_modelwrite_surface_modelWriteSurfaceModelwrite_surface_modelWriteSurfaceModelWriteSurfaceModel,
clear_surface_modelclear_surface_modelClearSurfaceModelclear_surface_modelClearSurfaceModelClearSurfaceModel
read_surface_modelread_surface_modelReadSurfaceModelread_surface_modelReadSurfaceModelReadSurfaceModel
find_surface_modelfind_surface_modelFindSurfaceModelfind_surface_modelFindSurfaceModelFindSurfaceModel,
refine_surface_model_poserefine_surface_model_poseRefineSurfaceModelPoserefine_surface_model_poseRefineSurfaceModelPoseRefineSurfaceModelPose,
read_surface_modelread_surface_modelReadSurfaceModelread_surface_modelReadSurfaceModelReadSurfaceModel,
write_surface_modelwrite_surface_modelWriteSurfaceModelwrite_surface_modelWriteSurfaceModelWriteSurfaceModel,
clear_surface_modelclear_surface_modelClearSurfaceModelclear_surface_modelClearSurfaceModelClearSurfaceModel
Bertram Drost, Markus Ulrich, Nassir Navab, Slobodan Ilic: “Model
Globally, Match Locally: Efficient and Robust 3D Object Recognition.”
Computer Vision and Pattern Recognition, pp. 998-1005, 2010.
3D Metrology