find_surface_model_imageFindSurfaceModelImageFindSurfaceModelImagefind_surface_model_imageT_find_surface_model_image🔗

Short description🔗

find_surface_model_imageFindSurfaceModelImageFindSurfaceModelImagefind_surface_model_imageT_find_surface_model_image — Find the best matches of a surface model in a 3D scene and images.

Signature🔗

find_surface_model_image( image Image, surface_model SurfaceModelID, object_model_3d ObjectModel3D, real RelSamplingDistance, real KeyPointFraction, real MinScore, string ReturnResultHandle, attribute.name GenParamName, attribute.value GenParamValue, out pose Pose, out real Score, out surface_matching_result SurfaceMatchingResultID )

Description🔗

The operator find_surface_model_imageFindSurfaceModelImage finds the best matches of the surface model SurfaceModelIDsurfaceModelIDsurface_model_id in the scene that is comprised of the 3D surface in ObjectModel3DobjectModel3Dobject_model_3d and the images of the scene in Imageimageimage. Note that the number of images passed in Imageimageimage must correspond to the number of cameras set with set_surface_model_paramSetSurfaceModelParam. Note also that the surface model must have been created by create_surface_modelCreateSurfaceModel with the parameter 'train_3d_edges'"train_3d_edges" enabled.

The images are used only in the sparse and dense refinement step. For this, the refinement simultaneously optimizes the alignment of the model with the 3D scene as well as the alignment of the reprojected edges of the model silhouette with edges in the passed images. The domain of the images is ignored.

In addition to the parameters documented in find_surface_modelFindSurfaceModel, find_surface_model_imageFindSurfaceModelImage also supports the following generic parameters:

'min_contrast'"min_contrast": Sets the minimum contrast of the object in the search images. Edges with a contrast below this threshold are ignored in the refinement.

Suggested values: 55, 1010, 2020

Default: 1010

Restriction: 'min_contrast'"min_contrast" >= 00
'max_deformation'"max_deformation": Sets the search range in pixels for corresponding edges in the image. This parameter can be used if the shape of the object is slightly deformed compared to the original 3D model used in create_surface_modelCreateSurfaceModel. Note that increasing this parameter can have a significant impact on the runtime of the refinement.

Suggested values: 00, 11, 55

Default: 11

Restriction: 'max_deformation'"max_deformation" >= 00

Execution information🔗

Execution information

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.

This operator supports canceling timeouts and interrupts.

Parameters🔗

Imageimageimage (input_object) (multichannel-)image(-array) → object (byte / uint2)HObject (byte / uint2)HImage (byte / uint2)HObject (byte / uint2)Hobject (byte / uint2)

Images of the scene.

SurfaceModelIDsurfaceModelIDsurface_model_id (input_control) surface_model → (handle)HTuple (HHandle)HSurfaceModel, HTuple (IntPtr)HHandleHtuple (handle)

Handle of the surface model.

ObjectModel3DobjectModel3Dobject_model_3d (input_control) object_model_3d → (handle)HTuple (HHandle)HObjectModel3D, HTuple (IntPtr)HHandleHtuple (handle)

Handle of the 3D object model containing the scene.

RelSamplingDistancerelSamplingDistancerel_sampling_distance (input_control) real → (real)HTuple (double)HTuple (double)floatHtuple (double)

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

Default: 0.050.05
Suggested values: 0.1, 0.07, 0.05, 0.04, 0.030.1, 0.07, 0.05, 0.04, 0.03
Restriction: 0 < RelSamplingDistance < 1

KeyPointFractionkeyPointFractionkey_point_fraction (input_control) real → (real)HTuple (double)HTuple (double)floatHtuple (double)

Fraction of sampled scene points used as key points.

Default: 0.20.2
Suggested values: 0.3, 0.2, 0.1, 0.050.3, 0.2, 0.1, 0.05
Restriction: 0 < KeyPointFraction <= 1

MinScoreminScoremin_score (input_control) real(-array) → (real / integer)HTuple (double / Hlong)HTuple (double / int / long)MaybeSequence[Union[float, int]]Htuple (double / Hlong)

Minimum score of the returned poses.

Default: 00
Restriction: MinScore >= 0

ReturnResultHandlereturnResultHandlereturn_result_handle (input_control) string → (string)HTuple (HString)HTuple (string)strHtuple (char*)

Enable returning a result handle in SurfaceMatchingResultIDsurfaceMatchingResultIDsurface_matching_result_id.

Default: 'false'"false"
Suggested values: 'true', 'false'"true", "false"

GenParamNamegenParamNamegen_param_name (input_control) attribute.name-array → (string)HTuple (HString)HTuple (string)Sequence[str]Htuple (char*)

Names of the generic parameters.

Default: [][]
List of values: '3d_edge_min_amplitude_abs', '3d_edge_min_amplitude_rel', '3d_edges', 'dense_pose_refinement', 'max_deformation', 'max_gap', 'max_overlap_dist_abs', 'max_overlap_dist_rel', 'min_contrast', 'num_matches', 'pose_ref_dist_threshold_abs', 'pose_ref_dist_threshold_rel', 'pose_ref_num_steps', 'pose_ref_scoring_dist_abs', 'pose_ref_scoring_dist_rel', 'pose_ref_sub_sampling', 'pose_ref_use_scene_normals', 'scene_invert_normals', 'scene_normal_computation', 'sparse_pose_refinement', 'use_3d_edges', 'use_self_similar_poses', 'use_view_based', 'viewpoint'

GenParamValuegenParamValuegen_param_value (input_control) attribute.value-array → (string / real / integer)HTuple (HString / double / Hlong)HTuple (string / double / int / long)Sequence[Union[str, float, int]]Htuple (char* / double / Hlong)

Values of the generic parameters.

Default: [][]
Suggested values: 0, 1, 'true', 'false', 0.005, 0.01, 0.03, 0.05, 0.1, 'num_scene_points', 'model_point_fraction', 'num_model_points', 'fast', 'mls'

Poseposepose (output_control) pose(-array) → (real / integer)HTuple (double / Hlong)HPose, HTuple (double / int / long)Sequence[Union[float, int]]Htuple (double / Hlong)

3D pose of the surface model in the scene.

Scorescorescore (output_control) real-array → (real)HTuple (double)HTuple (double)Sequence[float]Htuple (double)

Score of the found instances of the surface model.

SurfaceMatchingResultIDsurfaceMatchingResultIDsurface_matching_result_id (output_control) surface_matching_result(-array) → (handle)HTuple (HHandle)HSurfaceMatchingResult, HTuple (IntPtr)Sequence[HHandle]Htuple (handle)

Handle of the matching result, if enabled in ReturnResultHandlereturnResultHandlereturn_result_handle.

Result🔗

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

Combinations with other operators🔗

Combinations

Possible predecessors

read_object_model_3dReadObjectModel3d, xyz_to_object_model_3dXyzToObjectModel3d, get_object_model_3d_paramsGetObjectModel3dParams, read_surface_modelReadSurfaceModel, create_surface_modelCreateSurfaceModel, get_surface_model_paramGetSurfaceModelParam, edges_object_model_3dEdgesObjectModel3d

Possible successors

refine_surface_model_poseRefineSurfaceModelPose, get_surface_matching_resultGetSurfaceMatchingResult, clear_surface_matching_resultClearSurfaceMatchingResult, clear_object_model_3dClearObjectModel3d

Alternatives

refine_surface_model_poseRefineSurfaceModelPose, find_surface_modelFindSurfaceModel, refine_surface_model_pose_imageRefineSurfaceModelPoseImage

Module🔗

3D Metrology