refine_surface_model_pose_imageRefineSurfaceModelPoseImageRefineSurfaceModelPoseImagerefine_surface_model_pose_imageT_refine_surface_model_pose_image🔗

Short description🔗

refine_surface_model_pose_imageRefineSurfaceModelPoseImageRefineSurfaceModelPoseImagerefine_surface_model_pose_imageT_refine_surface_model_pose_image — Refine the pose of a surface model in a 3D scene and in images.

Signature🔗

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

Description🔗

The operator refine_surface_model_pose_imageRefineSurfaceModelPoseImage refines the approximate pose InitialPoseinitialPoseinitial_pose of the surface model SurfaceModelIDsurfaceModelIDsurface_model_id in the 3D scene 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 refinement simultaneously optimizes the alignment of the model with the 3D scene as well as the alignment of the reprojected edges with edges in the passed images. The domain of the images is ignored.

In addition to the parameters documented in refine_surface_model_poseRefineSurfaceModelPose, refine_surface_model_pose_imageRefineSurfaceModelPoseImage also supports the generic parameters 'min_contrast'"min_contrast" and 'max_deformation'"max_deformation", documented in find_surface_model_imageFindSurfaceModelImage.

Execution information🔗

Execution information

Multithreading type: reentrant (runs in parallel with non-exclusive operators).
Multithreading scope: global (may be called from any thread).
Processed without parallelization.

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.

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

Initial pose of the surface model in the scene.

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"
List of values: 'false', 'true'"false", "true"

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', 'max_deformation', 'min_contrast', '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', '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

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 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🔗

refine_surface_model_pose_imageRefineSurfaceModelPoseImage 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, find_surface_modelFindSurfaceModel, edges_object_model_3dEdgesObjectModel3d

Possible successors

get_surface_matching_resultGetSurfaceMatchingResult, clear_surface_matching_resultClearSurfaceMatchingResult, clear_object_model_3dClearObjectModel3d

Alternatives

find_surface_modelFindSurfaceModel, refine_surface_model_poseRefineSurfaceModelPose, find_surface_model_imageFindSurfaceModelImage

Module🔗

3D Metrology