find_surface_modelT_find_surface_modelFindSurfaceModelfind_surface_modelFindSurfaceModelFindSurfaceModel (Operator)

Name

find_surface_modelT_find_surface_modelFindSurfaceModelfind_surface_modelFindSurfaceModelFindSurfaceModel — Find the best matches of a surface model in a 3D scene.

Signature

Description

The operator find_surface_modelfind_surface_modelFindSurfaceModelfind_surface_modelFindSurfaceModelFindSurfaceModel finds the best matches of the surface model SurfaceModelIDSurfaceModelIDSurfaceModelIDSurfaceModelIDSurfaceModelIDsurfaceModelID in the 3D scene ObjectModel3DObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3D. The surface model SurfaceModelIDSurfaceModelIDSurfaceModelIDSurfaceModelIDSurfaceModelIDsurfaceModelID must have been created previously with create_surface_modelcreate_surface_modelCreateSurfaceModelcreate_surface_modelCreateSurfaceModelCreateSurfaceModel or read_surface_modelread_surface_modelReadSurfaceModelread_surface_modelReadSurfaceModelReadSurfaceModel.

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

• points and point normals;

• points and a 2D-Mapping, e.g. an XYZ image triple converted with xyz_to_object_model_3dxyz_to_object_model_3dXyzToObjectModel3dxyz_to_object_model_3dXyzToObjectModel3dXyzToObjectModel3d.

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_3dSampleObjectModel3dsample_object_model_3dSampleObjectModel3dSampleObjectModel3d 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""scene_normal_computation" should be set to 'mls'"mls""mls""mls""mls""mls" in order to obtain more robust results (see below).

The 3D pose of the found object instance is returned in PosePosePosePosePosepose. It describes the pose of the surface model in the scene coordinate system. The pose refers to the original coordinate system of the 3D object model that was passed to create_surface_modelcreate_surface_modelCreateSurfaceModelcreate_surface_modelCreateSurfaceModelCreateSurfaceModel. Additionally, for each match a score is returned in ScoreScoreScoreScoreScorescore. The value and interpretation of the score depends on whether pose refinement is enabled or not. If pose refinement is disabled, the score is the approximate number of points from the subsampled scene that lie on the found object. If pose refinement is enabled, the approximate fraction of the object's surface that is visible in the scene is returned, as value between 0 and 1. Both score types are described in more detail below.

The parameter MinScoreMinScoreMinScoreMinScoreMinScoreminScore can be used to filter the results. Only matches with a score exceeding the value of MinScoreMinScoreMinScoreMinScoreMinScoreminScore are returned. If MinScoreMinScoreMinScoreMinScoreMinScoreminScore is set to zero, all matches are returned.

If ReturnResultHandleReturnResultHandleReturnResultHandleReturnResultHandleReturnResultHandlereturnResultHandle is set to 'true'"true""true""true""true""true", a surface matching result handle is returned in SurfaceMatchingResultIDSurfaceMatchingResultIDSurfaceMatchingResultIDSurfaceMatchingResultIDSurfaceMatchingResultIDsurfaceMatchingResultID. Additional details of the matching process can be queried with the operator get_surface_matching_resultget_surface_matching_resultGetSurfaceMatchingResultget_surface_matching_resultGetSurfaceMatchingResultGetSurfaceMatchingResult using that handle. The returned handle must be freed by using clear_surface_matching_resultclear_surface_matching_resultClearSurfaceMatchingResultclear_surface_matching_resultClearSurfaceMatchingResultClearSurfaceMatchingResult to avoid memory leaks.

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

The matching is divided into three steps:

1. Approximate matching: The approximate poses of the instances of the surface model in the scene are searched.

   First, points are sampled uniformly from the scene passed in ObjectModel3DObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3D. The sampling distance is controlled with the parameter RelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistancerelSamplingDistance, and is given relative to the diameter of the surface model. Decreasing RelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistancerelSamplingDistance leads to more sampled points, and in turn to a more stable but slower matching. Increasing RelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistancerelSamplingDistance reduces the number of sampled scene points, which leads to a less stable but faster matching. For an illustration showing different values for RelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistancerelSamplingDistance, please refer to the operator create_surface_modelcreate_surface_modelCreateSurfaceModelcreate_surface_modelCreateSurfaceModelCreateSurfaceModel. The operator get_surface_matching_resultget_surface_matching_resultGetSurfaceMatchingResultget_surface_matching_resultGetSurfaceMatchingResultGetSurfaceMatchingResult 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.

   A set of key points is selected from the sampled scene points. The number of selected key points is controlled with the parameter KeyPointFractionKeyPointFractionKeyPointFractionKeyPointFractionKeyPointFractionkeyPointFraction. For example, if the value is set to 0.1, 10% of the sampled scene points are used as key points. For stable results it is important that each instance of the object is covered by several key points. Increasing KeyPointFractionKeyPointFractionKeyPointFractionKeyPointFractionKeyPointFractionkeyPointFraction means that more key points are selected from the scene, resulting in a slower but more stable matching. Decreasing KeyPointFractionKeyPointFractionKeyPointFractionKeyPointFractionKeyPointFractionkeyPointFraction has the inverse effect and results in a faster but less stable matching. The operator get_surface_matching_resultget_surface_matching_resultGetSurfaceMatchingResultget_surface_matching_resultGetSurfaceMatchingResultGetSurfaceMatchingResult can be used to retrieve the selected key points for visual inspection.

   For each selected key point, the optimum pose of the surface model is computed under the assumption that the key point lies on the surface of the object. This is done by pairing the key point with all other sampled scene points and finding the point pairs on the surface model that have a similar distance and relative orientation. The similarity is defined by the 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" in create_surface_modelcreate_surface_modelCreateSurfaceModelcreate_surface_modelCreateSurfaceModelCreateSurfaceModel. The pose for which the largest number of points from the sampled scene lie on the object is considered to be the best pose for this key point. The number of sampled scene points on the object is considered to be the score of the pose.

   From all key points the poses with the best scores are then selected and used as approximate poses. The maximum number of returned poses is set with the generic parameter 'num_matches'"num_matches""num_matches""num_matches""num_matches""num_matches". If the pose refinement is disabled, the score described above is returned for each pose in ScoreScoreScoreScoreScorescore. The value of the score depends on the amount of surface of the instance that is visible in the scene and on the sampling rate of the scene. Only poses whose score exceeds MinScoreMinScoreMinScoreMinScoreMinScoreminScore are returned. To determine a good threshold for MinScoreMinScoreMinScoreMinScoreMinScoreminScore, it is recommended to test the matching on several scenes.

   Note that the resulting poses from this step are only approximate. The error in the pose is proportional to the sampling rates of the surface model given in create_surface_modelcreate_surface_modelCreateSurfaceModelcreate_surface_modelCreateSurfaceModelCreateSurfaceModel, and is typically less than 5% of the object's diameter.

   The following generic parameters control the approximate matching and can be set with GenParamNameGenParamNameGenParamNameGenParamNameGenParamNamegenParamName and GenParamValueGenParamValueGenParamValueGenParamValueGenParamValuegenParamValue:

   'num_matches'"num_matches""num_matches""num_matches""num_matches""num_matches":

   Sets the maximum number of matches that are returned.

   Suggested values: 1, 2, 5

   Default value: 1

   Assertion: 'num_matches'"num_matches""num_matches""num_matches""num_matches""num_matches" > 0

   'max_overlap_dist_rel'"max_overlap_dist_rel""max_overlap_dist_rel""max_overlap_dist_rel""max_overlap_dist_rel""max_overlap_dist_rel":

   For efficiency reasons, the maximum overlap can not be defined in 3D. Instead, only the minimum distance between the centers of the axis-aligned bounding boxes of two matches can be specified with 'max_overlap_dist_rel'. The value is set relative to the diameter of the object. Once an object with a high ScoreScoreScoreScoreScorescore is found, all other matches are suppressed if the centers of their bounding boxes lie too close to the center of the first object. If the resulting matches must not overlap each other, the value for 'max_overlap_dist_rel' should be set to 1.0. Note that only one of the parameters 'max_overlap_dist_rel'"max_overlap_dist_rel""max_overlap_dist_rel""max_overlap_dist_rel""max_overlap_dist_rel""max_overlap_dist_rel" and 'max_overlap_dist_abs'"max_overlap_dist_abs""max_overlap_dist_abs""max_overlap_dist_abs""max_overlap_dist_abs""max_overlap_dist_abs" should be set. If both are set, only the value of the last parameter is used.

   Suggested values: 0.1, 0.5, 1

   Default value: 0.5

   Assertion: 'max_overlap_dist_rel'"max_overlap_dist_rel""max_overlap_dist_rel""max_overlap_dist_rel""max_overlap_dist_rel""max_overlap_dist_rel" >= 0

   'max_overlap_dist_abs'"max_overlap_dist_abs""max_overlap_dist_abs""max_overlap_dist_abs""max_overlap_dist_abs""max_overlap_dist_abs":

   This parameter has the same effect as the parameter 'max_overlap_dist_rel'. Note that in contrast to 'max_overlap_dist_rel', the value for 'max_overlap_dist_abs' is set as an absolute value. See 'max_overlap_dist_rel', above, for a description of the effect of this parameter. Note that only one of the parameters 'max_overlap_dist_rel'"max_overlap_dist_rel""max_overlap_dist_rel""max_overlap_dist_rel""max_overlap_dist_rel""max_overlap_dist_rel" and 'max_overlap_dist_abs'"max_overlap_dist_abs""max_overlap_dist_abs""max_overlap_dist_abs""max_overlap_dist_abs""max_overlap_dist_abs" should be set. If both are set, only the value of the last parameter is used.

   Suggested values: 1, 2, 3

   Assertion: 'max_overlap_dist_abs'"max_overlap_dist_abs""max_overlap_dist_abs""max_overlap_dist_abs""max_overlap_dist_abs""max_overlap_dist_abs" >= 0

   'scene_normal_computation'"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""fast", normals are computed based on a small neighborhood of points. In the mode 'mls'"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""mls" method. A more detailed description of the 'mls'"mls""mls""mls""mls""mls" method can be found in the description of the operator surface_normals_object_model_3dsurface_normals_object_model_3dSurfaceNormalsObjectModel3dsurface_normals_object_model_3dSurfaceNormalsObjectModel3dSurfaceNormalsObjectModel3d. The 'mls'"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""fast", 'mls'"mls""mls""mls""mls""mls"

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

2. Sparse pose refinement: In this second step, the approximate poses found in the previous step are further refined. This increases the accuracy of the poses and the significance of the score value.

   The sparse pose refinement uses the sampled scene points from the approximate matching. The pose is optimized such that the distances from the sampled scene points to the plane of the closest model point are minimal. The plane of each model point is defined as the plane perpendicular to its normal.

   The sparse pose refinement is enabled by default. It can be disabled by setting the generic parameter 'sparse_pose_refinement'"sparse_pose_refinement""sparse_pose_refinement""sparse_pose_refinement""sparse_pose_refinement""sparse_pose_refinement" to 'false'"false""false""false""false""false". Since each key point produces one pose candidate, the total number of pose candidates to be optimized is proportional to the number of key points. For large scenes with much clutter, i.e., scene parts that do not belong to the object of interest, it can be faster to disable the sparse pose refinement.

   The score of each pose is recomputed after the sparse pose refinement by counting the number of model points that have a correspondent scene point, and dividing it by the total number of points on the model. This results in a value between 0 and 1 that is approximately the fraction of the model surface that is visible in the scene (see below). This score is more accurate and stable than the score coming from the approximate matching. It still depends on the sampling distance of the scene set in RelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistancerelSamplingDistance.

   The following generic parameters control the sparse pose refinement and can be set with GenParamNameGenParamNameGenParamNameGenParamNameGenParamNamegenParamName and GenParamValueGenParamValueGenParamValueGenParamValueGenParamValuegenParamValue:

   'sparse_pose_refinement'"sparse_pose_refinement""sparse_pose_refinement""sparse_pose_refinement""sparse_pose_refinement""sparse_pose_refinement":

   Enables or disables the sparse pose refinement.

   Value list: 'true'"true""true""true""true""true", 'false'"false""false""false""false""false"

   Default value: 'true'"true""true""true""true""true"

   'score_type'"score_type""score_type""score_type""score_type""score_type":

   Set the type of the score that is returned. Several different scores can be computed and returned after the pose refinement. This parameter has no effect if both the sparse and the dense pose refinement are disabled.

   Note that for the computation of the score after the sparse pose refinement, the sampled scene points are used. For the computation of the score after the dense pose refinement, all scene points are used (see below). The score value after the sparse pose refinement therefore depends on the sampling distance of the scene.

   The following score types are supported:

   'num_scene_points'"num_scene_points""num_scene_points""num_scene_points""num_scene_points""num_scene_points":

   Compute a weighted count of the number of sampled scene points that lie on the surface of the found object. Each point is weighted based on the distance to the found object. This score is more accurate and stable than the score coming from the approximate matching. It depends on the sampling distance of the scene set in RelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistanceRelSamplingDistancerelSamplingDistance. The returned score will be between zero and the number of points in the sampled scene.

   'num_model_points'"num_model_points""num_model_points""num_model_points""num_model_points""num_model_points":

   Count the number of sampled model points that were detected in the scene. A model point is defined to be 'detected' if there is a scene point close to it. The returned score will be between zero and the number of points in the sampled model.

   'model_point_fraction'"model_point_fraction""model_point_fraction""model_point_fraction""model_point_fraction""model_point_fraction":

   Compute the fraction of visible model points by dividing the score value from 'num_model_points'"num_model_points""num_model_points""num_model_points""num_model_points""num_model_points" by the number of model points. The returned score will be between zero and one, and is approximately the fraction of the model surface that is visible in the scene. This is the default score type.

   Value list: 'model_point_fraction'"model_point_fraction""model_point_fraction""model_point_fraction""model_point_fraction""model_point_fraction", 'num_scene_points'"num_scene_points""num_scene_points""num_scene_points""num_scene_points""num_scene_points", 'num_model_points'"num_model_points""num_model_points""num_model_points""num_model_points""num_model_points"

   Default value: 'model_point_fraction'"model_point_fraction""model_point_fraction""model_point_fraction""model_point_fraction""model_point_fraction"

   'pose_ref_use_scene_normals'"pose_ref_use_scene_normals""pose_ref_use_scene_normals""pose_ref_use_scene_normals""pose_ref_use_scene_normals""pose_ref_use_scene_normals":

   Enables or disables the usage of scene normals for the pose refinement. If this parameter is enabled, and if the scene contains vertex normals, then those normals are used to increase the accuracy of the pose refinement. For this, the influence of scene points whose normal points in a different direction than the model normal is decreased. Note that the scene must contain vertex normals. Otherwise, this parameter is ignored.

   Value list: 'true'"true""true""true""true""true", 'false'"false""false""false""false""false"

   Default value: 'false'"false""false""false""false""false"

3. Dense pose refinement: Accurately refines the poses found in the previous steps. This step works similar to the sparse pose refinement and minimizes the distances between the scene points and the planes of the closest model points. The difference is that

   1. only the 'num_matches'"num_matches""num_matches""num_matches""num_matches""num_matches" poses with the best scores from the previous step are refined;

   2. all points from the scene passed in ObjectModel3DObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3D are used for the refinement.

   Taking all points from the scene increases the accuracy of the refinement but is slower than refining on the subsampled scene points. The dense pose refinement is enabled by default, but can be disabled with the generic parameter 'dense_pose_refinement'"dense_pose_refinement""dense_pose_refinement""dense_pose_refinement""dense_pose_refinement""dense_pose_refinement".

   After the dense pose refinement, the score of each match is recomputed. The threshold for considering a point to be 'on' the object is set with the generic parameter '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_rel" or '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_abs" (see below).

   The accuracy of the dense pose refinement is limited to around 0.1% of the model's size due to numerical reasons. The accuracy further depends on the noise of the scene points, the number of scene points and the shape of the model.

   The following generic parameters influence the accuracy and speed of the dense pose refinement and can be set with GenParamNameGenParamNameGenParamNameGenParamNameGenParamNamegenParamName and GenParamValueGenParamValueGenParamValueGenParamValueGenParamValuegenParamValue:

   'dense_pose_refinement'"dense_pose_refinement""dense_pose_refinement""dense_pose_refinement""dense_pose_refinement""dense_pose_refinement":

   Enables or disables the dense pose refinement.

   Value list: 'true'"true""true""true""true""true", 'false'"false""false""false""false""false"

   Default value: 'true'"true""true""true""true""true"

   'pose_ref_num_steps'"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 dense pose refinement. Increasing the number of iteration leads to a more accurate pose 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. Note that this parameter is ignored if the dense pose refinement is disabled.

   Suggested values: 1, 3, 5, 20

   Default value: 5

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

   'pose_ref_sub_sampling'"pose_ref_sub_sampling""pose_ref_sub_sampling""pose_ref_sub_sampling""pose_ref_sub_sampling""pose_ref_sub_sampling":

   Set the rate of scene points to be used for the dense pose refinement. For example, if this value is set to 5, every 5th point from the scene is used for pose refinement. This parameter allows an easy tradeoff between speed and accuracy of the pose refinement: Increasing the value leads to less points being used and in turn to a faster but less accurate pose refinement. Decreasing the value has the inverse effect. Note that this parameter is ignored if the dense pose refinement is disabled.

   Suggested values: 1, 2, 5, 10

   Default value: 2

   Assertion: 'pose_ref_sub_sampling'"pose_ref_sub_sampling""pose_ref_sub_sampling""pose_ref_sub_sampling""pose_ref_sub_sampling""pose_ref_sub_sampling" > 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_rel":

   Set the distance threshold for dense pose 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. Note that this parameter is ignored if the dense pose refinement is disabled.

   Suggested values: 0.03, 0.05, 0.1, 0.2

   Default value: 0.1

   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_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_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""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""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""pose_ref_scoring_dist_abs" can be set. If both are set, only the value of the last parameter is used. Note that this parameter is ignored if the dense pose refinement is disabled.

   Suggested values: 0.2, 0.01, 0.005, 0.0001

   Default value: 0.005

   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_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""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 pose 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. Note that this parameter is ignored if the dense pose refinement is disabled. 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""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""pose_ref_scoring_dist_abs" can be set. If both are set, only the value of the last parameter is used.

   'score_type'"score_type""score_type""score_type""score_type""score_type":

   Set the type of the score that is returned. Several different scores can be computed and returned after the pose refinement. This parameter has no effect if both the sparse and the dense pose refinement are disabled.

   For all score types, '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_rel" or '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_abs" controls how close a scene point needs to be to a model point in order to classify it as being on the model.

   Note that for the computation of the score after the sparse pose refinement, the sampled scene points are used (see above). For the computation of the score after the dense pose refinement, all scene points are used (see below). The score value after the dense pose refinement does therefore not depend on the sampling distance of the scene.

   The following score types are supported:

   'num_scene_points'"num_scene_points""num_scene_points""num_scene_points""num_scene_points""num_scene_points":

   Compute a weighted count of the number of scene points that lie on the surface of the found object. Each point is weighted based on the distance to the found object. The returned score will be between zero and the number of points in the scene.

   'num_model_points'"num_model_points""num_model_points""num_model_points""num_model_points""num_model_points":

   Count the number of sampled model points that were detected in the scene. A model point is defined to be 'detected' if there is a scene point close to it. The returned score will be between zero and the number of points in the sampled model.

   'model_point_fraction'"model_point_fraction""model_point_fraction""model_point_fraction""model_point_fraction""model_point_fraction":

   Compute the fraction of visible model points by dividing the score value from 'num_model_points'"num_model_points""num_model_points""num_model_points""num_model_points""num_model_points" by the number of model points. The returned score will be between zero and one, and is approximately the fraction of the model surface that is visible in the scene. This is the default score type.

   Value list: 'model_point_fraction'"model_point_fraction""model_point_fraction""model_point_fraction""model_point_fraction""model_point_fraction", 'num_scene_points'"num_scene_points""num_scene_points""num_scene_points""num_scene_points""num_scene_points", 'num_model_points'"num_model_points""num_model_points""num_model_points""num_model_points""num_model_points"

   Default value: 'model_point_fraction'"model_point_fraction""model_point_fraction""model_point_fraction""model_point_fraction""model_point_fraction"

   'pose_ref_use_scene_normals'"pose_ref_use_scene_normals""pose_ref_use_scene_normals""pose_ref_use_scene_normals""pose_ref_use_scene_normals""pose_ref_use_scene_normals":

   Enables or disables the usage of scene normals for the pose refinement. If this parameter is enabled, and if the scene contains vertex normals, then those normals are used to increase the accuracy of the pose refinement. For this, the influence of scene points whose normal points in a different direction than the model normal is decreased. Note that the scene must contain vertex normals. Otherwise, this parameter is ignored.

   Value list: 'true'"true""true""true""true""true", 'false'"false""false""false""false""false"

   Default value: 'false'"false""false""false""false""false"

Parallelization

• Multithreading type: reentrant (runs in parallel with non-exclusive operators).
• Multithreading scope: global (may be called from any thread).
• Automatically parallelized on internal data level.

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.

Parameters

Result

find_surface_modelfind_surface_modelFindSurfaceModelfind_surface_modelFindSurfaceModelFindSurfaceModel 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, read_surface_modelread_surface_modelReadSurfaceModelread_surface_modelReadSurfaceModelReadSurfaceModel, create_surface_modelcreate_surface_modelCreateSurfaceModelcreate_surface_modelCreateSurfaceModelCreateSurfaceModel, get_surface_model_paramget_surface_model_paramGetSurfaceModelParamget_surface_model_paramGetSurfaceModelParamGetSurfaceModelParam

Possible Successors

refine_surface_model_poserefine_surface_model_poseRefineSurfaceModelPoserefine_surface_model_poseRefineSurfaceModelPoseRefineSurfaceModelPose, get_surface_matching_resultget_surface_matching_resultGetSurfaceMatchingResultget_surface_matching_resultGetSurfaceMatchingResultGetSurfaceMatchingResult, clear_surface_matching_resultclear_surface_matching_resultClearSurfaceMatchingResultclear_surface_matching_resultClearSurfaceMatchingResultClearSurfaceMatchingResult, clear_object_model_3dclear_object_model_3dClearObjectModel3dclear_object_model_3dClearObjectModel3dClearObjectModel3d

Alternatives

refine_surface_model_poserefine_surface_model_poseRefineSurfaceModelPoserefine_surface_model_poseRefineSurfaceModelPoseRefineSurfaceModelPose

See also

refine_surface_model_poserefine_surface_model_poseRefineSurfaceModelPoserefine_surface_model_poseRefineSurfaceModelPoseRefineSurfaceModelPose

Module

3D Metrology