find_shape_model_3dT_find_shape_model_3dFindShapeModel3dFindShapeModel3d (Operator)


find_shape_model_3dT_find_shape_model_3dFindShapeModel3dFindShapeModel3d — Find the best matches of a 3D shape model in an image.


find_shape_model_3d(Image : : ShapeModel3DID, MinScore, Greediness, NumLevels, GenParamName, GenParamValue : Pose, CovPose, Score)

Herror T_find_shape_model_3d(const Hobject Image, const Htuple ShapeModel3DID, const Htuple MinScore, const Htuple Greediness, const Htuple NumLevels, const Htuple GenParamName, const Htuple GenParamValue, Htuple* Pose, Htuple* CovPose, Htuple* Score)

void FindShapeModel3d(const HObject& Image, const HTuple& ShapeModel3DID, const HTuple& MinScore, const HTuple& Greediness, const HTuple& NumLevels, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* Pose, HTuple* CovPose, HTuple* Score)

HPoseArray HShapeModel3D::FindShapeModel3d(const HImage& Image, double MinScore, double Greediness, const HTuple& NumLevels, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* CovPose, HTuple* Score) const

HPoseArray HImage::FindShapeModel3d(const HShapeModel3D& ShapeModel3DID, double MinScore, double Greediness, const HTuple& NumLevels, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* CovPose, HTuple* Score) const

static void HOperatorSet.FindShapeModel3d(HObject image, HTuple shapeModel3DID, HTuple minScore, HTuple greediness, HTuple numLevels, HTuple genParamName, HTuple genParamValue, out HTuple pose, out HTuple covPose, out HTuple score)

HPose[] HShapeModel3D.FindShapeModel3d(HImage image, double minScore, double greediness, HTuple numLevels, HTuple genParamName, HTuple genParamValue, out HTuple covPose, out HTuple score)

HPose[] HImage.FindShapeModel3d(HShapeModel3D shapeModel3DID, double minScore, double greediness, HTuple numLevels, HTuple genParamName, HTuple genParamValue, out HTuple covPose, out HTuple score)


The operator find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3d finds the best matches of the 3D shape model ShapeModel3DIDShapeModel3DIDShapeModel3DIDShapeModel3DIDshapeModel3DID in the input ImageImageImageImageimage. The 3D shape model must have been created previously by calling create_shape_model_3dcreate_shape_model_3dCreateShapeModel3dCreateShapeModel3dCreateShapeModel3d or read_shape_model_3dread_shape_model_3dReadShapeModel3dReadShapeModel3dReadShapeModel3d.

The 3D pose of the found instances of the model is returned in PosePosePosePosepose. The pose is in the form , where ccs denotes the camera coordinate system and mcs the model coordinate system (which is a 3D world coordinate system), see Transformations / Poses and “Solution Guide III-C - 3D Vision”. Hence, it describes the pose of the 3D object model in camera coordinates. It should be noted that the resulting PosePosePosePosepose does not refer to reference coordinate system that is introduced in create_shape_model_3dcreate_shape_model_3dCreateShapeModel3dCreateShapeModel3dCreateShapeModel3d but to the original 3D object model coordinate system used in the CAD file. If a pose refinement was applied (see below), additionally the accuracy of the six pose parameters are returned in CovPoseCovPoseCovPoseCovPosecovPose. By default, CovPoseCovPoseCovPoseCovPosecovPose contains the 6 standard deviations of the pose parameters for each match. In contrast, if the generic parameter 'cov_pose_mode'"cov_pose_mode""cov_pose_mode""cov_pose_mode""cov_pose_mode" (see below) was set to 'covariances'"covariances""covariances""covariances""covariances", CovPoseCovPoseCovPoseCovPosecovPose contains the 36 values of the complete 6×6 covariance matrix of the 6 pose parameters. Note that this reflects only an inner accuracy from which the real accuracy of the pose may differ. Finally, the score of each found instance is returned in ScoreScoreScoreScorescore. The score is a number between 0 and 1, which is an approximate measure of how much of the model is visible in the image. If, for example, half of the model is occluded, the score cannot exceed 0.5.

Input parameters in detail

The image and its domain:

The domain of the image ImageImageImageImageimage determines the search space for the reference point of the 3D object model.


The parameter MinScoreMinScoreMinScoreMinScoreminScore determines what score a potential match must at least have to be regarded as an instance of the model in the image. The larger MinScoreMinScoreMinScoreMinScoreminScore is chosen, the faster the search is. If the model can be expected never to be occluded in the images, MinScoreMinScoreMinScoreMinScoreminScore may be set as high as 0.8 or even 0.9. Note that in images with a high degree of clutter or strong background texture, MinScoreMinScoreMinScoreMinScoreminScore should be set to a value not much lower than 0.7 since otherwise false matches could be found.


The parameter GreedinessGreedinessGreedinessGreedinessgreediness determines how “greedily” the search should be carried out. If GreedinessGreedinessGreedinessGreedinessgreediness=0, a safe search heuristic is used, which always finds the model if it is visible in the image. However, the search will be relatively time consuming in this case. If GreedinessGreedinessGreedinessGreedinessgreediness=1, an unsafe search heuristic is used, which may cause the model not to be found in rare cases, even though it is visible in the image. For GreedinessGreedinessGreedinessGreedinessgreediness=1, the maximum search speed is achieved. In almost all cases, the 3D shape model will always be found for GreedinessGreedinessGreedinessGreedinessgreediness=0.9.


The number of pyramid levels used during the search is determined with NumLevelsNumLevelsNumLevelsNumLevelsnumLevels. If necessary, the number of levels is clipped to the range given when the 3D shape model was created with create_shape_model_3dcreate_shape_model_3dCreateShapeModel3dCreateShapeModel3dCreateShapeModel3d. If NumLevelsNumLevelsNumLevelsNumLevelsnumLevels is set to 0, the number of pyramid levels specified in create_shape_model_3dcreate_shape_model_3dCreateShapeModel3dCreateShapeModel3dCreateShapeModel3d is used. Optionally, NumLevelsNumLevelsNumLevelsNumLevelsnumLevels can contain a second value that determines the lowest pyramid level to which the found matches are tracked. Hence, a value of [4,2] for NumLevelsNumLevelsNumLevelsNumLevelsnumLevels means that the matching starts at the fourth pyramid level and tracks the matches to the second lowest pyramid level (the lowest pyramid level is denoted by a value of 1). This mechanism can be used to decrease the runtime of the matching. If the lowest pyramid level to use is chosen too large, it may happen that the desired accuracy cannot be achieved, or that wrong instances of the model are found because the model is not specific enough on the higher pyramid levels to facilitate a reliable selection of the correct instance of the model. In this case, the lowest pyramid level to use must be set to a smaller value.

GenParamName and GenParamValue:

In addition to the parameters described above, there are some generic parameters that can optionally be used to influence the matching. For most applications these parameters need not to be specified but can be left at their default values. If desired, these parameters and their corresponding values can be specified by using GenParamNameGenParamNameGenParamNameGenParamNamegenParamName and GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue, respectively. The following values for GenParamNameGenParamNameGenParamNameGenParamNamegenParamName are possible:

Execution Information


ImageImageImageImageimage (input_object)  (multichannel-)image objectHImageHImageHobject (byte / uint2)

Input image in which the model should be found.

ShapeModel3DIDShapeModel3DIDShapeModel3DIDShapeModel3DIDshapeModel3DID (input_control)  shape_model_3d HShapeModel3D, HTupleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the 3D shape model.

MinScoreMinScoreMinScoreMinScoreminScore (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

Minimum score of the instances of the model to be found.

Default value: 0.7

Suggested values: 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0

Typical range of values: 0 ≤ MinScore MinScore MinScore MinScore minScore ≤ 1

Minimum increment: 0.01

Recommended increment: 0.05

GreedinessGreedinessGreedinessGreedinessgreediness (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

“Greediness” of the search heuristic (0: safe but slow; 1: fast but matches may be missed).

Default value: 0.9

Suggested values: 0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0

Typical range of values: 0 ≤ Greediness Greediness Greediness Greediness greediness ≤ 1

Minimum increment: 0.01

Recommended increment: 0.05

NumLevelsNumLevelsNumLevelsNumLevelsnumLevels (input_control)  integer-array HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Number of pyramid levels used in the matching (and lowest pyramid level to use if |NumLevelsNumLevelsNumLevelsNumLevelsnumLevels| = 2).

Default value: 0

List of values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10

GenParamNameGenParamNameGenParamNameGenParamNamegenParamName (input_control) HTupleHTupleHtuple (string) (string) (HString) (char*)

Names of (optional) parameters for controlling the behavior of the operator.

Default value: []

List of values: 'border_model'"border_model""border_model""border_model""border_model", 'cam_roll_max'"cam_roll_max""cam_roll_max""cam_roll_max""cam_roll_max", 'cam_roll_min'"cam_roll_min""cam_roll_min""cam_roll_min""cam_roll_min", 'cov_pose_mode'"cov_pose_mode""cov_pose_mode""cov_pose_mode""cov_pose_mode", 'dist_max'"dist_max""dist_max""dist_max""dist_max", 'dist_min'"dist_min""dist_min""dist_min""dist_min", 'latitude_max'"latitude_max""latitude_max""latitude_max""latitude_max", 'latitude_min'"latitude_min""latitude_min""latitude_min""latitude_min", 'longitude_max'"longitude_max""longitude_max""longitude_max""longitude_max", 'longitude_min'"longitude_min""longitude_min""longitude_min""longitude_min", 'max_overlap'"max_overlap""max_overlap""max_overlap""max_overlap", 'num_matches'"num_matches""num_matches""num_matches""num_matches", 'outlier_suppression'"outlier_suppression""outlier_suppression""outlier_suppression""outlier_suppression", 'pose_refinement'"pose_refinement""pose_refinement""pose_refinement""pose_refinement", 'recompute_score'"recompute_score""recompute_score""recompute_score""recompute_score"

GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue (input_control) HTupleHTupleHtuple (integer / real / string) (int / long / double / string) (Hlong / double / HString) (Hlong / double / char*)

Values of the optional generic parameters.

Default value: []

Suggested values: -0.78, -0.35, -0.17, 0.0, 0.17, 0.35, 0.78, 0.1, 0.2, 0.5, 'none'"none""none""none""none", 'false'"false""false""false""false", 'true'"true""true""true""true", 'least_squares'"least_squares""least_squares""least_squares""least_squares", 'least_squares_high'"least_squares_high""least_squares_high""least_squares_high""least_squares_high", 'least_squares_very_high'"least_squares_very_high""least_squares_very_high""least_squares_very_high""least_squares_very_high", 'standard_deviations'"standard_deviations""standard_deviations""standard_deviations""standard_deviations", 'covariances'"covariances""covariances""covariances""covariances", 'medium'"medium""medium""medium""medium", 'high'"high""high""high""high"

PosePosePosePosepose (output_control)  pose(-array) HPose, HTupleHTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)

3D pose of the 3D shape model.

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

6 standard deviations or 36 covariances of the pose parameters.

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

Score of the found instances of the 3D shape model.

Example (HDevelop)

read_object_model_3d (DXFModelFileName, 'm', [], [], ObjectModel3D, \
CamParam := ['area_scan_division',0.01221,2791,7.3958e-6,7.4e-6,\
create_shape_model_3d (ObjectModel3D, CamParam, 0, 0, 0, 'gba', \
                       -rad(20), rad(20), -rad(20), rad(20), 0, \
                       rad(360), 0.15, 0.2, 10, [], [], ShapeModel3DID)
grab_image_async (Image, AcqHandle, -1)
find_shape_model_3d (Image, ShapeModel3DID, 0.6, 0.9, 0, [], [], \
                     Pose, CovPose, Score)
project_shape_model_3d (ModelContours, ShapeModel3DID, CamParam, \
                        Pose, 'true', rad(30))


If the parameter values are correct, the operator find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3d returns the value 2 (H_MSG_TRUE). If the input is empty (no input images are available) the behavior can be set via set_system('no_object_result',<Result>)set_system("no_object_result",<Result>)SetSystem("no_object_result",<Result>)SetSystem("no_object_result",<Result>)SetSystem("no_object_result",<Result>). If necessary, an exception is raised. If the model was created with find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3d by setting 'metric'"metric""metric""metric""metric" to 'ignore_part_polarity'"ignore_part_polarity""ignore_part_polarity""ignore_part_polarity""ignore_part_polarity" and a multi-channel input image is passed in ImageImageImageImageimage, the error 3359 is raised.

Possible Predecessors

create_shape_model_3dcreate_shape_model_3dCreateShapeModel3dCreateShapeModel3dCreateShapeModel3d, read_shape_model_3dread_shape_model_3dReadShapeModel3dReadShapeModel3dReadShapeModel3d

Possible Successors


See also

convert_point_3d_cart_to_spherconvert_point_3d_cart_to_spherConvertPoint3dCartToSpherConvertPoint3dCartToSpherConvertPoint3dCartToSpher, convert_point_3d_spher_to_cartconvert_point_3d_spher_to_cartConvertPoint3dSpherToCartConvertPoint3dSpherToCartConvertPoint3dSpherToCart, create_cam_pose_look_at_pointcreate_cam_pose_look_at_pointCreateCamPoseLookAtPointCreateCamPoseLookAtPointCreateCamPoseLookAtPoint, trans_pose_shape_model_3dtrans_pose_shape_model_3dTransPoseShapeModel3dTransPoseShapeModel3dTransPoseShapeModel3d


3D Metrology