Operator Reference

HALCON Operator Reference / 3D Matching / Surface-Based
ClassesClasses | | Operators

find_surface_model_imageT_find_surface_model_imageFindSurfaceModelImageFindSurfaceModelImagefind_surface_model_image (Operator)

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

Signature

Herror T_find_surface_model_image(const Hobject Image, const Htuple SurfaceModelID, const Htuple ObjectModel3D, const Htuple RelSamplingDistance, const Htuple KeyPointFraction, const Htuple MinScore, const Htuple ReturnResultHandle, const Htuple GenParamName, const Htuple GenParamValue, Htuple* Pose, Htuple* Score, Htuple* SurfaceMatchingResultID)

void FindSurfaceModelImage(const HObject& Image, const HTuple& SurfaceModelID, const HTuple& ObjectModel3D, const HTuple& RelSamplingDistance, const HTuple& KeyPointFraction, const HTuple& MinScore, const HTuple& ReturnResultHandle, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* Pose, HTuple* Score, HTuple* SurfaceMatchingResultID)

HPoseArray HObjectModel3D::FindSurfaceModelImage(const HImage& Image, const HSurfaceModel& SurfaceModelID, double RelSamplingDistance, double KeyPointFraction, const HTuple& MinScore, const HString& ReturnResultHandle, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* Score, HSurfaceMatchingResultArray* SurfaceMatchingResultID) const

HPose HObjectModel3D::FindSurfaceModelImage(const HImage& Image, const HSurfaceModel& SurfaceModelID, double RelSamplingDistance, double KeyPointFraction, double MinScore, const HString& ReturnResultHandle, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* Score, HSurfaceMatchingResult* SurfaceMatchingResultID) const

HPose HObjectModel3D::FindSurfaceModelImage(const HImage& Image, const HSurfaceModel& SurfaceModelID, double RelSamplingDistance, double KeyPointFraction, double MinScore, const char* ReturnResultHandle, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* Score, HSurfaceMatchingResult* SurfaceMatchingResultID) const

HPose HObjectModel3D::FindSurfaceModelImage(const HImage& Image, const HSurfaceModel& SurfaceModelID, double RelSamplingDistance, double KeyPointFraction, double MinScore, const wchar_t* ReturnResultHandle, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* Score, HSurfaceMatchingResult* SurfaceMatchingResultID) const   ( Windows only)

HPoseArray HSurfaceModel::FindSurfaceModelImage(const HImage& Image, const HObjectModel3D& ObjectModel3D, double RelSamplingDistance, double KeyPointFraction, const HTuple& MinScore, const HString& ReturnResultHandle, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* Score, HSurfaceMatchingResultArray* SurfaceMatchingResultID) const

HPose HSurfaceModel::FindSurfaceModelImage(const HImage& Image, const HObjectModel3D& ObjectModel3D, double RelSamplingDistance, double KeyPointFraction, double MinScore, const HString& ReturnResultHandle, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* Score, HSurfaceMatchingResult* SurfaceMatchingResultID) const

HPose HSurfaceModel::FindSurfaceModelImage(const HImage& Image, const HObjectModel3D& ObjectModel3D, double RelSamplingDistance, double KeyPointFraction, double MinScore, const char* ReturnResultHandle, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* Score, HSurfaceMatchingResult* SurfaceMatchingResultID) const

HPose HSurfaceModel::FindSurfaceModelImage(const HImage& Image, const HObjectModel3D& ObjectModel3D, double RelSamplingDistance, double KeyPointFraction, double MinScore, const wchar_t* ReturnResultHandle, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* Score, HSurfaceMatchingResult* SurfaceMatchingResultID) const   ( Windows only)

static HPoseArray HSurfaceMatchingResult::FindSurfaceModelImage(const HImage& Image, const HSurfaceModel& SurfaceModelID, const HObjectModel3D& ObjectModel3D, double RelSamplingDistance, double KeyPointFraction, const HTuple& MinScore, const HString& ReturnResultHandle, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* Score, HSurfaceMatchingResultArray* SurfaceMatchingResultID)

HPose HSurfaceMatchingResult::FindSurfaceModelImage(const HImage& Image, const HSurfaceModel& SurfaceModelID, const HObjectModel3D& ObjectModel3D, double RelSamplingDistance, double KeyPointFraction, double MinScore, const HString& ReturnResultHandle, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* Score)

HPose HSurfaceMatchingResult::FindSurfaceModelImage(const HImage& Image, const HSurfaceModel& SurfaceModelID, const HObjectModel3D& ObjectModel3D, double RelSamplingDistance, double KeyPointFraction, double MinScore, const char* ReturnResultHandle, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* Score)

HPose HSurfaceMatchingResult::FindSurfaceModelImage(const HImage& Image, const HSurfaceModel& SurfaceModelID, const HObjectModel3D& ObjectModel3D, double RelSamplingDistance, double KeyPointFraction, double MinScore, const wchar_t* ReturnResultHandle, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* Score)   ( Windows only)

static void HOperatorSet.FindSurfaceModelImage(HObject image, HTuple surfaceModelID, HTuple objectModel3D, HTuple relSamplingDistance, HTuple keyPointFraction, HTuple minScore, HTuple returnResultHandle, HTuple genParamName, HTuple genParamValue, out HTuple pose, out HTuple score, out HTuple surfaceMatchingResultID)

HPose[] HObjectModel3D.FindSurfaceModelImage(HImage image, HSurfaceModel surfaceModelID, double relSamplingDistance, double keyPointFraction, HTuple minScore, string returnResultHandle, HTuple genParamName, HTuple genParamValue, out HTuple score, out HSurfaceMatchingResult[] surfaceMatchingResultID)

HPose HObjectModel3D.FindSurfaceModelImage(HImage image, HSurfaceModel surfaceModelID, double relSamplingDistance, double keyPointFraction, double minScore, string returnResultHandle, HTuple genParamName, HTuple genParamValue, out HTuple score, out HSurfaceMatchingResult surfaceMatchingResultID)

HPose[] HSurfaceModel.FindSurfaceModelImage(HImage image, HObjectModel3D objectModel3D, double relSamplingDistance, double keyPointFraction, HTuple minScore, string returnResultHandle, HTuple genParamName, HTuple genParamValue, out HTuple score, out HSurfaceMatchingResult[] surfaceMatchingResultID)

HPose HSurfaceModel.FindSurfaceModelImage(HImage image, HObjectModel3D objectModel3D, double relSamplingDistance, double keyPointFraction, double minScore, string returnResultHandle, HTuple genParamName, HTuple genParamValue, out HTuple score, out HSurfaceMatchingResult surfaceMatchingResultID)

static HPose[] HSurfaceMatchingResult.FindSurfaceModelImage(HImage image, HSurfaceModel surfaceModelID, HObjectModel3D objectModel3D, double relSamplingDistance, double keyPointFraction, HTuple minScore, string returnResultHandle, HTuple genParamName, HTuple genParamValue, out HTuple score, out HSurfaceMatchingResult[] surfaceMatchingResultID)

HPose HSurfaceMatchingResult.FindSurfaceModelImage(HImage image, HSurfaceModel surfaceModelID, HObjectModel3D objectModel3D, double relSamplingDistance, double keyPointFraction, double minScore, string returnResultHandle, HTuple genParamName, HTuple genParamValue, out HTuple score)

def find_surface_model_image(image: HObject, surface_model_id: HHandle, object_model_3d: HHandle, rel_sampling_distance: float, key_point_fraction: float, min_score: MaybeSequence[Union[float, int]], return_result_handle: str, gen_param_name: Sequence[str], gen_param_value: Sequence[Union[str, float, int]]) -> Tuple[Sequence[Union[float, int]], Sequence[float], Sequence[HHandle]]

def find_surface_model_image_s(image: HObject, surface_model_id: HHandle, object_model_3d: HHandle, rel_sampling_distance: float, key_point_fraction: float, min_score: MaybeSequence[Union[float, int]], return_result_handle: str, gen_param_name: Sequence[str], gen_param_value: Sequence[Union[str, float, int]]) -> Tuple[Sequence[Union[float, int]], Sequence[float], HHandle]

Description

The operator find_surface_model_imagefind_surface_model_imageFindSurfaceModelImageFindSurfaceModelImagefind_surface_model_image finds the best matches of the surface model SurfaceModelIDSurfaceModelIDSurfaceModelIDsurfaceModelIDsurface_model_id in the scene that is comprised of the 3D surface in ObjectModel3DObjectModel3DObjectModel3DobjectModel3Dobject_model_3d and the images of the scene in ImageImageImageimageimage. Note that the number of images passed in ImageImageImageimageimage must correspond to the number of cameras set with set_surface_model_paramset_surface_model_paramSetSurfaceModelParamSetSurfaceModelParamset_surface_model_param. Note also that the surface model must have been created by create_surface_modelcreate_surface_modelCreateSurfaceModelCreateSurfaceModelcreate_surface_model with the parameter 'train_3d_edges'"train_3d_edges""train_3d_edges""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_modelfind_surface_modelFindSurfaceModelFindSurfaceModelfind_surface_model, find_surface_model_imagefind_surface_model_imageFindSurfaceModelImageFindSurfaceModelImagefind_surface_model_image also supports the following generic parameters:

'min_contrast'"min_contrast""min_contrast""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: 5, 10, 20

Default: 10

Restriction: 'min_contrast'"min_contrast""min_contrast""min_contrast""min_contrast" >= 0

'max_deformation'"max_deformation""max_deformation""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_modelcreate_surface_modelCreateSurfaceModelCreateSurfaceModelcreate_surface_model. Note that increasing this parameter can have a significant impact on the runtime of the refinement.

Suggested values: 0, 1, 5

Default: 1

Restriction: 'max_deformation'"max_deformation""max_deformation""max_deformation""max_deformation" >= 0

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

ImageImageImageimageimage (input_object)  (multichannel-)image(-array) → objectHImageHObjectHObjectHobject (byte / uint2)

Images of the scene.

SurfaceModelIDSurfaceModelIDSurfaceModelIDsurfaceModelIDsurface_model_id (input_control)  surface_model → HSurfaceModel, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the surface model.

ObjectModel3DObjectModel3DObjectModel3DobjectModel3Dobject_model_3d (input_control)  object_model_3d → HObjectModel3D, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the 3D object model containing the scene.

RelSamplingDistanceRelSamplingDistanceRelSamplingDistancerelSamplingDistancerel_sampling_distance (input_control)  real → HTuplefloatHTupleHtuple (real) (double) (double) (double)

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

Default: 0.05

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

Restriction: 0 < RelSamplingDistance < 1

KeyPointFractionKeyPointFractionKeyPointFractionkeyPointFractionkey_point_fraction (input_control)  real → HTuplefloatHTupleHtuple (real) (double) (double) (double)

Fraction of sampled scene points used as key points.

Default: 0.2

Suggested values: 0.3, 0.2, 0.1, 0.05

Restriction: 0 < KeyPointFraction <= 1

MinScoreMinScoreMinScoreminScoremin_score (input_control)  real(-array) → HTupleMaybeSequence[Union[float, int]]HTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)

Minimum score of the returned poses.

Default: 0

Restriction: MinScore >= 0

ReturnResultHandleReturnResultHandleReturnResultHandlereturnResultHandlereturn_result_handle (input_control)  string → HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Enable returning a result handle in SurfaceMatchingResultIDSurfaceMatchingResultIDSurfaceMatchingResultIDsurfaceMatchingResultIDsurface_matching_result_id.

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

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

GenParamNameGenParamNameGenParamNamegenParamNamegen_param_name (input_control)  attribute.name-array → HTupleSequence[str]HTupleHtuple (string) (string) (HString) (char*)

Names of the generic parameters.

Default: []

List of values: '3d_edge_min_amplitude_abs'"3d_edge_min_amplitude_abs""3d_edge_min_amplitude_abs""3d_edge_min_amplitude_abs""3d_edge_min_amplitude_abs", '3d_edge_min_amplitude_rel'"3d_edge_min_amplitude_rel""3d_edge_min_amplitude_rel""3d_edge_min_amplitude_rel""3d_edge_min_amplitude_rel", '3d_edges'"3d_edges""3d_edges""3d_edges""3d_edges", 'dense_pose_refinement'"dense_pose_refinement""dense_pose_refinement""dense_pose_refinement""dense_pose_refinement", 'max_deformation'"max_deformation""max_deformation""max_deformation""max_deformation", 'max_gap'"max_gap""max_gap""max_gap""max_gap", 'max_overlap_dist_abs'"max_overlap_dist_abs""max_overlap_dist_abs""max_overlap_dist_abs""max_overlap_dist_abs", 'max_overlap_dist_rel'"max_overlap_dist_rel""max_overlap_dist_rel""max_overlap_dist_rel""max_overlap_dist_rel", 'min_contrast'"min_contrast""min_contrast""min_contrast""min_contrast", 'num_matches'"num_matches""num_matches""num_matches""num_matches", '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", 'pose_ref_sub_sampling'"pose_ref_sub_sampling""pose_ref_sub_sampling""pose_ref_sub_sampling""pose_ref_sub_sampling", '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", 'scene_invert_normals'"scene_invert_normals""scene_invert_normals""scene_invert_normals""scene_invert_normals", 'scene_normal_computation'"scene_normal_computation""scene_normal_computation""scene_normal_computation""scene_normal_computation", 'sparse_pose_refinement'"sparse_pose_refinement""sparse_pose_refinement""sparse_pose_refinement""sparse_pose_refinement", 'use_3d_edges'"use_3d_edges""use_3d_edges""use_3d_edges""use_3d_edges", 'use_self_similar_poses'"use_self_similar_poses""use_self_similar_poses""use_self_similar_poses""use_self_similar_poses", 'use_view_based'"use_view_based""use_view_based""use_view_based""use_view_based", 'viewpoint'"viewpoint""viewpoint""viewpoint""viewpoint"

GenParamValueGenParamValueGenParamValuegenParamValuegen_param_value (input_control)  attribute.value-array → HTupleSequence[Union[str, float, int]]HTupleHtuple (string / real / integer) (string / double / int / long) (HString / double / Hlong) (char* / double / Hlong)

Values of the generic parameters.

Default: []

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

PosePosePoseposepose (output_control)  pose(-array) → HPose, HTupleSequence[Union[float, int]]HTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)

3D pose of the surface model in the scene.

ScoreScoreScorescorescore (output_control)  real-array → HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

Score of the found instances of the surface model.

SurfaceMatchingResultIDSurfaceMatchingResultIDSurfaceMatchingResultIDsurfaceMatchingResultIDsurface_matching_result_id (output_control)  surface_matching_result(-array) → HSurfaceMatchingResult, HTupleSequence[HHandle]HTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the matching result, if enabled in ReturnResultHandleReturnResultHandleReturnResultHandlereturnResultHandlereturn_result_handle.

Result

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

Possible Predecessors

read_object_model_3dread_object_model_3dReadObjectModel3dReadObjectModel3dread_object_model_3d, xyz_to_object_model_3dxyz_to_object_model_3dXyzToObjectModel3dXyzToObjectModel3dxyz_to_object_model_3d, get_object_model_3d_paramsget_object_model_3d_paramsGetObjectModel3dParamsGetObjectModel3dParamsget_object_model_3d_params, read_surface_modelread_surface_modelReadSurfaceModelReadSurfaceModelread_surface_model, create_surface_modelcreate_surface_modelCreateSurfaceModelCreateSurfaceModelcreate_surface_model, get_surface_model_paramget_surface_model_paramGetSurfaceModelParamGetSurfaceModelParamget_surface_model_param, edges_object_model_3dedges_object_model_3dEdgesObjectModel3dEdgesObjectModel3dedges_object_model_3d

Possible Successors

refine_surface_model_poserefine_surface_model_poseRefineSurfaceModelPoseRefineSurfaceModelPoserefine_surface_model_pose, get_surface_matching_resultget_surface_matching_resultGetSurfaceMatchingResultGetSurfaceMatchingResultget_surface_matching_result, clear_surface_matching_resultclear_surface_matching_resultClearSurfaceMatchingResultClearSurfaceMatchingResultclear_surface_matching_result, clear_object_model_3dclear_object_model_3dClearObjectModel3dClearObjectModel3dclear_object_model_3d

Alternatives

refine_surface_model_poserefine_surface_model_poseRefineSurfaceModelPoseRefineSurfaceModelPoserefine_surface_model_pose, find_surface_modelfind_surface_modelFindSurfaceModelFindSurfaceModelfind_surface_model, refine_surface_model_pose_imagerefine_surface_model_pose_imageRefineSurfaceModelPoseImageRefineSurfaceModelPoseImagerefine_surface_model_pose_image

See also

refine_surface_model_poserefine_surface_model_poseRefineSurfaceModelPoseRefineSurfaceModelPoserefine_surface_model_pose, find_surface_modelfind_surface_modelFindSurfaceModelFindSurfaceModelfind_surface_model

Module

3D Metrology

ClassesClasses | | Operators