ClassesClassesClassesClasses | | | | Operators

create_surface_modelcreate_surface_modelCreateSurfaceModelcreate_surface_modelCreateSurfaceModelCreateSurfaceModel (Operator)

Name

create_surface_modelcreate_surface_modelCreateSurfaceModelcreate_surface_modelCreateSurfaceModelCreateSurfaceModel — Create the data structure needed to perform surface-based matching.

Signature

create_surface_model( : : ObjectModel3D, RelSamplingDistance, GenParamName, GenParamValue : SurfaceModelID)

Herror create_surface_model(const Hlong ObjectModel3D, double RelSamplingDistance, const char* GenParamName, const char* GenParamValue, Hlong* SurfaceModelID)

Herror T_create_surface_model(const Htuple ObjectModel3D, const Htuple RelSamplingDistance, const Htuple GenParamName, const Htuple GenParamValue, Htuple* SurfaceModelID)

Herror create_surface_model(const HTuple& ObjectModel3D, const HTuple& RelSamplingDistance, const HTuple& GenParamName, const HTuple& GenParamValue, Hlong* SurfaceModelID)

HSurfaceModel HObjectModel3D::CreateSurfaceModel(const HTuple& RelSamplingDistance, const HTuple& GenParamName, const HTuple& GenParamValue) const

void HSurfaceModel::CreateSurfaceModel(const HObjectModel3D& ObjectModel3D, const HTuple& RelSamplingDistance, const HTuple& GenParamName, const HTuple& GenParamValue)

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)

void HOperatorSetX.CreateSurfaceModel(
[in] VARIANT ObjectModel3D, [in] VARIANT RelSamplingDistance, [in] VARIANT GenParamName, [in] VARIANT GenParamValue, [out] VARIANT* SurfaceModelID)

IHSurfaceModelX* HObjectModel3DX.CreateSurfaceModel(
[in] double RelSamplingDistance, [in] VARIANT GenParamName, [in] VARIANT GenParamValue)

void HSurfaceModelX.CreateSurfaceModel(
[in] IHObjectModel3DX* ObjectModel3D, [in] double RelSamplingDistance, [in] VARIANT GenParamName, [in] VARIANT 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)

Description

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

Parallelization

Parameters

ObjectModel3DObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3D (input_control)  object_model_3d HObjectModel3D, HTupleHTupleHObjectModel3D, HTupleHObjectModel3DX, VARIANTHtuple (integer) (IntPtr) (Hlong) (Hlong) (Hlong) (Hlong)

Handle of the 3D object model.

RelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistancerelSamplingDistance (input_control)  real HTupleHTupleHTupleVARIANTHtuple (real) (double) (double) (double) (double) (double)

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

GenParamNameGenParamNameGenParamNameGenParamNameGenParamNamegenParamName (input_control)  attribute.name(-array) HTupleHTupleHTupleVARIANTHtuple (string) (string) (HString) (char*) (BSTR) (char*)

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"

GenParamValueGenParamValueGenParamValueGenParamValueGenParamValuegenParamValue (input_control)  attribute.value(-array) HTupleHTupleHTupleVARIANTHtuple (string / real / integer) (string / double / int / long) (HString / double / Hlong) (char* / double / Hlong) (BSTR / double / Hlong) (char* / double / Hlong)

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

SurfaceModelIDSurfaceModelIDSurfaceModelIDSurfaceModelIDSurfaceModelIDsurfaceModelID (output_control)  surface_model HSurfaceModel, HTupleHTupleHSurfaceModel, HTupleHSurfaceModelX, VARIANTHtuple (integer) (IntPtr) (Hlong) (Hlong) (Hlong) (Hlong)

Handle of the surface model.

Result

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

Possible Predecessors

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

Possible Successors

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

Alternatives

read_surface_modelread_surface_modelReadSurfaceModelread_surface_modelReadSurfaceModelReadSurfaceModel

See also

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

References

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.

Module

3D Metrology


ClassesClassesClassesClasses | | | | Operators