find_deformable_surface_modelT_find_deformable_surface_modelFindDeformableSurfaceModelFindDeformableSurfaceModel (Operator)

Name

find_deformable_surface_modelT_find_deformable_surface_modelFindDeformableSurfaceModelFindDeformableSurfaceModel — Find the best match of a deformable surface model in a 3D scene.

Signature

find_deformable_surface_model( : : DeformableSurfaceModel, ObjectModel3D, RelSamplingDistance, MinScore, GenParamName, GenParamValue : Score, DeformableSurfaceMatchingResult)

Herror T_find_deformable_surface_model(const Htuple DeformableSurfaceModel, const Htuple ObjectModel3D, const Htuple RelSamplingDistance, const Htuple MinScore, const Htuple GenParamName, const Htuple GenParamValue, Htuple* Score, Htuple* DeformableSurfaceMatchingResult)

void FindDeformableSurfaceModel(const HTuple& DeformableSurfaceModel, const HTuple& ObjectModel3D, const HTuple& RelSamplingDistance, const HTuple& MinScore, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* Score, HTuple* DeformableSurfaceMatchingResult)

HTuple HObjectModel3D::FindDeformableSurfaceModel(const HDeformableSurfaceModel& DeformableSurfaceModel, double RelSamplingDistance, const HTuple& MinScore, const HTuple& GenParamName, const HTuple& GenParamValue, HDeformableSurfaceMatchingResultArray* DeformableSurfaceMatchingResult) const

double HObjectModel3D::FindDeformableSurfaceModel(const HDeformableSurfaceModel& DeformableSurfaceModel, double RelSamplingDistance, double MinScore, const HTuple& GenParamName, const HTuple& GenParamValue, HDeformableSurfaceMatchingResult* DeformableSurfaceMatchingResult) const

HTuple HDeformableSurfaceModel::FindDeformableSurfaceModel(const HObjectModel3D& ObjectModel3D, double RelSamplingDistance, const HTuple& MinScore, const HTuple& GenParamName, const HTuple& GenParamValue, HDeformableSurfaceMatchingResultArray* DeformableSurfaceMatchingResult) const

double HDeformableSurfaceModel::FindDeformableSurfaceModel(const HObjectModel3D& ObjectModel3D, double RelSamplingDistance, double MinScore, const HTuple& GenParamName, const HTuple& GenParamValue, HDeformableSurfaceMatchingResult* DeformableSurfaceMatchingResult) const

static HTuple HDeformableSurfaceMatchingResult::FindDeformableSurfaceModel(const HDeformableSurfaceModel& DeformableSurfaceModel, const HObjectModel3D& ObjectModel3D, double RelSamplingDistance, const HTuple& MinScore, const HTuple& GenParamName, const HTuple& GenParamValue, HDeformableSurfaceMatchingResultArray* DeformableSurfaceMatchingResult)

double HDeformableSurfaceMatchingResult::FindDeformableSurfaceModel(const HDeformableSurfaceModel& DeformableSurfaceModel, const HObjectModel3D& ObjectModel3D, double RelSamplingDistance, double MinScore, const HTuple& GenParamName, const HTuple& GenParamValue)

static void HOperatorSet.FindDeformableSurfaceModel(HTuple deformableSurfaceModel, HTuple objectModel3D, HTuple relSamplingDistance, HTuple minScore, HTuple genParamName, HTuple genParamValue, out HTuple score, out HTuple deformableSurfaceMatchingResult)

HTuple HObjectModel3D.FindDeformableSurfaceModel(HDeformableSurfaceModel deformableSurfaceModel, double relSamplingDistance, HTuple minScore, HTuple genParamName, HTuple genParamValue, out HDeformableSurfaceMatchingResult[] deformableSurfaceMatchingResult)

double HObjectModel3D.FindDeformableSurfaceModel(HDeformableSurfaceModel deformableSurfaceModel, double relSamplingDistance, double minScore, HTuple genParamName, HTuple genParamValue, out HDeformableSurfaceMatchingResult deformableSurfaceMatchingResult)

HTuple HDeformableSurfaceModel.FindDeformableSurfaceModel(HObjectModel3D objectModel3D, double relSamplingDistance, HTuple minScore, HTuple genParamName, HTuple genParamValue, out HDeformableSurfaceMatchingResult[] deformableSurfaceMatchingResult)

double HDeformableSurfaceModel.FindDeformableSurfaceModel(HObjectModel3D objectModel3D, double relSamplingDistance, double minScore, HTuple genParamName, HTuple genParamValue, out HDeformableSurfaceMatchingResult deformableSurfaceMatchingResult)

static HTuple HDeformableSurfaceMatchingResult.FindDeformableSurfaceModel(HDeformableSurfaceModel deformableSurfaceModel, HObjectModel3D objectModel3D, double relSamplingDistance, HTuple minScore, HTuple genParamName, HTuple genParamValue, out HDeformableSurfaceMatchingResult[] deformableSurfaceMatchingResult)

double HDeformableSurfaceMatchingResult.FindDeformableSurfaceModel(HDeformableSurfaceModel deformableSurfaceModel, HObjectModel3D objectModel3D, double relSamplingDistance, double minScore, HTuple genParamName, HTuple genParamValue)

Description

The operator find_deformable_surface_modelfind_deformable_surface_modelFindDeformableSurfaceModelFindDeformableSurfaceModelFindDeformableSurfaceModel finds the best match of the deformable surface model DeformableSurfaceModelDeformableSurfaceModelDeformableSurfaceModelDeformableSurfaceModeldeformableSurfaceModel in the 3D scene ObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3D. The deformable surface model must have been created previously with, for example, create_deformable_surface_modelcreate_deformable_surface_modelCreateDeformableSurfaceModelCreateDeformableSurfaceModelCreateDeformableSurfaceModel.

The matching requires that the 3D object model ObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3D contains points and normals. The following combinations are possible:

Note that triangles or polygons in the passed scene are ignored. Instead, only the vertices are used for matching. It is thus in general not recommended to use this operator on meshed scenes, such as CAD data. Instead, such a scene must be sampled beforehand using sample_object_model_3dsample_object_model_3dSampleObjectModel3dSampleObjectModel3dSampleObjectModel3d to create points and normals. When using noisy point clouds, e.g., from time-of-flight cameras, the generic parameter 'scene_normal_computation'"scene_normal_computation""scene_normal_computation""scene_normal_computation""scene_normal_computation" should be set to 'mls'"mls""mls""mls""mls" in order to obtain more robust results (see below).

First, points are sampled uniformly from the scene passed in ObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3D. The sampling distance is controlled with the parameter RelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistancerelSamplingDistance, and is given relative to the diameter of the surface model. Decreasing RelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistancerelSamplingDistance leads to more sampled points, and in turn to a more stable but slower matching. Increasing RelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistancerelSamplingDistance reduces the number of sampled scene points, which leads to a less stable but faster matching. For an illustration showing different values for RelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistancerelSamplingDistance, please refer to the operator create_deformable_surface_modelcreate_deformable_surface_modelCreateDeformableSurfaceModelCreateDeformableSurfaceModelCreateDeformableSurfaceModel.

The operator get_deformable_surface_matching_resultget_deformable_surface_matching_resultGetDeformableSurfaceMatchingResultGetDeformableSurfaceMatchingResultGetDeformableSurfaceMatchingResult can be used to retrieve the sampled scene points for visual inspection. For a robust matching it is recommended that at least 50-100 scene points are sampled for each object instance.

The method first finds an approximate position of the object. This position is then refined. The generic parameters controlling the deformation are described further down.

If a match was found, the score of the match is returned in ScoreScoreScoreScorescore and a deformable surface matching result handle is returned in DeformableSurfaceMatchingResultDeformableSurfaceMatchingResultDeformableSurfaceMatchingResultDeformableSurfaceMatchingResultdeformableSurfaceMatchingResult. Details of the matching result, such as the deformed model and the position of the reference points, can be queried with the operator get_deformable_surface_matching_resultget_deformable_surface_matching_resultGetDeformableSurfaceMatchingResultGetDeformableSurfaceMatchingResultGetDeformableSurfaceMatchingResult using the result handle.

The score is normalized between 0 and 1 and represents the amount of model surface visible in the scene. A value of 1 represents a perfect match. The parameter MinScoreMinScoreMinScoreMinScoreminScore can be used to filter the result. A match is returned only if its score exceeds the value of MinScoreMinScoreMinScoreMinScoreminScore.

The parameters GenParamNameGenParamNameGenParamNameGenParamNamegenParamName and GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue are used to set generic parameters. Both get a tuple of equal length, where the tuple passed to GenParamNameGenParamNameGenParamNameGenParamNamegenParamName contains the names of the parameters to set, and the tuple passed to GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue contains the corresponding values. The possible parameter names and values are described below.

'scene_normal_computation'"scene_normal_computation""scene_normal_computation""scene_normal_computation""scene_normal_computation":

This parameter controls the normal computation of the sampled scene. In the default mode 'fast'"fast""fast""fast""fast", normals are computed based on a small neighborhood of points. In the mode 'mls'"mls""mls""mls""mls", normals are computed based on a larger neighborhood and using the more complex but more accurate 'mls'"mls""mls""mls""mls" method. A more detailed description of the 'mls'"mls""mls""mls""mls" method can be found in the description of the operator surface_normals_object_model_3dsurface_normals_object_model_3dSurfaceNormalsObjectModel3dSurfaceNormalsObjectModel3dSurfaceNormalsObjectModel3d. The 'mls'"mls""mls""mls""mls" mode is intended for noisy data, such as images from time-of-flight cameras.

Value list: 'fast'"fast""fast""fast""fast", 'mls'"mls""mls""mls""mls"

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

'pose_ref_num_steps'"pose_ref_num_steps""pose_ref_num_steps""pose_ref_num_steps""pose_ref_num_steps":

Number of iterations for the refinement. Increasing the number of iteration leads to a more accurate position at the expense of runtime. However, once convergence is reached, the accuracy can no longer be increased, even if the number of steps is increased.

Suggested values: 1, 10, 25, 50

Default value: 25

Assertion: 'pose_ref_num_steps'"pose_ref_num_steps""pose_ref_num_steps""pose_ref_num_steps""pose_ref_num_steps" > 0

'pose_ref_dist_threshold_rel'"pose_ref_dist_threshold_rel""pose_ref_dist_threshold_rel""pose_ref_dist_threshold_rel""pose_ref_dist_threshold_rel":

Set the distance threshold for refinement relative to the diameter of the surface model. Only scene points that are closer to the object than this distance are used for the optimization. Scene points further away are ignored.

Suggested values: 0.05, 0.1, 0.25, 0.3

Default value: 0.25

Assertion: 0 < 'pose_ref_dist_threshold_rel'"pose_ref_dist_threshold_rel""pose_ref_dist_threshold_rel""pose_ref_dist_threshold_rel""pose_ref_dist_threshold_rel"

'pose_ref_dist_threshold_abs'"pose_ref_dist_threshold_abs""pose_ref_dist_threshold_abs""pose_ref_dist_threshold_abs""pose_ref_dist_threshold_abs":

Set the distance threshold for dense pose refinement as absolute value. See 'pose_ref_dist_threshold_rel'"pose_ref_dist_threshold_rel""pose_ref_dist_threshold_rel""pose_ref_dist_threshold_rel""pose_ref_dist_threshold_rel" for a detailed description. Only one of the parameters 'pose_ref_dist_threshold_rel'"pose_ref_dist_threshold_rel""pose_ref_dist_threshold_rel""pose_ref_dist_threshold_rel""pose_ref_dist_threshold_rel" and 'pose_ref_dist_threshold_abs'"pose_ref_dist_threshold_abs""pose_ref_dist_threshold_abs""pose_ref_dist_threshold_abs""pose_ref_dist_threshold_abs" can be set. If both are set, only the value of the last parameter is used.

Assertion: 0 < 'pose_ref_dist_threshold_abs'"pose_ref_dist_threshold_abs""pose_ref_dist_threshold_abs""pose_ref_dist_threshold_abs""pose_ref_dist_threshold_abs"

'pose_ref_scoring_dist_rel'"pose_ref_scoring_dist_rel""pose_ref_scoring_dist_rel""pose_ref_scoring_dist_rel""pose_ref_scoring_dist_rel":

Set the distance threshold for scoring relative to the diameter of the surface model. See the following 'pose_ref_scoring_dist_abs'"pose_ref_scoring_dist_abs""pose_ref_scoring_dist_abs""pose_ref_scoring_dist_abs""pose_ref_scoring_dist_abs" for a detailed description. Only one of the parameters 'pose_ref_scoring_dist_rel'"pose_ref_scoring_dist_rel""pose_ref_scoring_dist_rel""pose_ref_scoring_dist_rel""pose_ref_scoring_dist_rel" and 'pose_ref_scoring_dist_abs'"pose_ref_scoring_dist_abs""pose_ref_scoring_dist_abs""pose_ref_scoring_dist_abs""pose_ref_scoring_dist_abs" can be set. If both are set, only the value of the last parameter is used.

Suggested values: 0.1, 0.05, 0.03, 0.005

Default value: 0.03

Assertion: 0 < 'pose_ref_scoring_dist_rel'"pose_ref_scoring_dist_rel""pose_ref_scoring_dist_rel""pose_ref_scoring_dist_rel""pose_ref_scoring_dist_rel"

'pose_ref_scoring_dist_abs'"pose_ref_scoring_dist_abs""pose_ref_scoring_dist_abs""pose_ref_scoring_dist_abs""pose_ref_scoring_dist_abs":

Set the distance threshold for scoring. Only scene points that are closer to the object than this distance are considered to be 'on the model' when computing the score after the refinement. All other scene points are considered not to be on the model. The value should correspond to the amount of noise on the coordinates of the scene points. Only one of the parameters 'pose_ref_scoring_dist_rel'"pose_ref_scoring_dist_rel""pose_ref_scoring_dist_rel""pose_ref_scoring_dist_rel""pose_ref_scoring_dist_rel" and 'pose_ref_scoring_dist_abs'"pose_ref_scoring_dist_abs""pose_ref_scoring_dist_abs""pose_ref_scoring_dist_abs""pose_ref_scoring_dist_abs" can be set. If both are set, only the value of the last parameter is used.

Execution Information

This operator returns a handle. Note that the state of an instance of this handle type may be changed by specific operators even though the handle is used as an input parameter by those operators.

This operator supports cancelling timeouts and interrupts.

Parameters

DeformableSurfaceModelDeformableSurfaceModelDeformableSurfaceModelDeformableSurfaceModeldeformableSurfaceModel (input_control)  deformable_surface_model HDeformableSurfaceModel, HTupleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the deformable surface model.

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

Handle of the 3D object model containing the scene.

RelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistancerelSamplingDistance (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

Scene sampling distance relative to the diameter of the surface model.

Default value: 0.05

Suggested values: 0.1, 0.07, 0.05, 0.04, 0.03

Restriction: 0 < RelSamplingDistance < 1

MinScoreMinScoreMinScoreMinScoreminScore (input_control)  real HTupleHTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)

Minimum score of the returned match.

Default value: 0

Restriction: MinScore >= 0

GenParamNameGenParamNameGenParamNameGenParamNamegenParamName (input_control)  attribute.name-array HTupleHTupleHtuple (string) (string) (HString) (char*)

Names of the generic parameters.

Default value: []

List of values: 'pose_ref_dist_threshold_abs'"pose_ref_dist_threshold_abs""pose_ref_dist_threshold_abs""pose_ref_dist_threshold_abs""pose_ref_dist_threshold_abs", 'pose_ref_dist_threshold_rel'"pose_ref_dist_threshold_rel""pose_ref_dist_threshold_rel""pose_ref_dist_threshold_rel""pose_ref_dist_threshold_rel", 'pose_ref_num_steps'"pose_ref_num_steps""pose_ref_num_steps""pose_ref_num_steps""pose_ref_num_steps", 'pose_ref_scoring_dist_abs'"pose_ref_scoring_dist_abs""pose_ref_scoring_dist_abs""pose_ref_scoring_dist_abs""pose_ref_scoring_dist_abs", 'pose_ref_scoring_dist_rel'"pose_ref_scoring_dist_rel""pose_ref_scoring_dist_rel""pose_ref_scoring_dist_rel""pose_ref_scoring_dist_rel", 'scene_normal_computation'"scene_normal_computation""scene_normal_computation""scene_normal_computation""scene_normal_computation"

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

Values of the generic parameters.

Default value: []

Suggested values: 'fast'"fast""fast""fast""fast", 'mls'"mls""mls""mls""mls", 0, 1, 10, 25, 50, 0.05, 0.1, 0.25, 0.3, 0.05, 0.03, 0.005

ScoreScoreScoreScorescore (output_control)  real(-array) HTupleHTupleHtuple (real) (double) (double) (double)

Score of the found instances of the surface model.

DeformableSurfaceMatchingResultDeformableSurfaceMatchingResultDeformableSurfaceMatchingResultDeformableSurfaceMatchingResultdeformableSurfaceMatchingResult (output_control)  deformable_surface_matching_result(-array) HDeformableSurfaceMatchingResult, HTupleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the matching result.

Result

find_deformable_surface_modelfind_deformable_surface_modelFindDeformableSurfaceModelFindDeformableSurfaceModelFindDeformableSurfaceModel 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, xyz_to_object_model_3dxyz_to_object_model_3dXyzToObjectModel3dXyzToObjectModel3dXyzToObjectModel3d, get_object_model_3d_paramsget_object_model_3d_paramsGetObjectModel3dParamsGetObjectModel3dParamsGetObjectModel3dParams, read_deformable_surface_modelread_deformable_surface_modelReadDeformableSurfaceModelReadDeformableSurfaceModelReadDeformableSurfaceModel, create_deformable_surface_modelcreate_deformable_surface_modelCreateDeformableSurfaceModelCreateDeformableSurfaceModelCreateDeformableSurfaceModel, get_deformable_surface_model_paramget_deformable_surface_model_paramGetDeformableSurfaceModelParamGetDeformableSurfaceModelParamGetDeformableSurfaceModelParam, add_deformable_surface_model_reference_pointadd_deformable_surface_model_reference_pointAddDeformableSurfaceModelReferencePointAddDeformableSurfaceModelReferencePointAddDeformableSurfaceModelReferencePoint, add_deformable_surface_model_sampleadd_deformable_surface_model_sampleAddDeformableSurfaceModelSampleAddDeformableSurfaceModelSampleAddDeformableSurfaceModelSample

Possible Successors

refine_deformable_surface_modelrefine_deformable_surface_modelRefineDeformableSurfaceModelRefineDeformableSurfaceModelRefineDeformableSurfaceModel, get_deformable_surface_matching_resultget_deformable_surface_matching_resultGetDeformableSurfaceMatchingResultGetDeformableSurfaceMatchingResultGetDeformableSurfaceMatchingResult, clear_deformable_surface_matching_resultclear_deformable_surface_matching_resultClearDeformableSurfaceMatchingResultClearDeformableSurfaceMatchingResultClearDeformableSurfaceMatchingResult, clear_object_model_3dclear_object_model_3dClearObjectModel3dClearObjectModel3dClearObjectModel3d

Alternatives

refine_deformable_surface_modelrefine_deformable_surface_modelRefineDeformableSurfaceModelRefineDeformableSurfaceModelRefineDeformableSurfaceModel

See also

refine_deformable_surface_modelrefine_deformable_surface_modelRefineDeformableSurfaceModelRefineDeformableSurfaceModelRefineDeformableSurfaceModel

Module

3D Metrology