create_shape_model_3dT_create_shape_model_3dCreateShapeModel3dCreateShapeModel3dcreate_shape_model_3d创建形状模型三维（算子）

名称

create_shape_model_3dT_create_shape_model_3dCreateShapeModel3dCreateShapeModel3dcreate_shape_model_3d — 准备一个三维对象模型进行匹配。

签名

create_shape_model_3d( : : ObjectModel3D, CamParam, RefRotX, RefRotY, RefRotZ, OrderOfRotation, LongitudeMin, LongitudeMax, LatitudeMin, LatitudeMax, CamRollMin, CamRollMax, DistMin, DistMax, MinContrast, GenParamName, GenParamValue : ShapeModel3DID)

描述

算子 create_shape_model_3dcreate_shape_model_3dCreateShapeModel3dCreateShapeModel3dCreateShapeModel3dcreate_shape_model_3d 会将传递给 ObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3Dobject_model_3d 的三维对象模型准备为用于匹配的三维形状模型。必须先使用 read_object_model_3dread_object_model_3dReadObjectModel3dReadObjectModel3dReadObjectModel3dread_object_model_3d 从文件中读取三维对象模型。

三维形状模型是通过计算三维对象模型在用户指定的姿态范围内的不同视图生成的。这些视图是通过在三维对象模型周围放置虚拟相机，并将三维对象模型投影到每个虚拟相机位置的图像平面上而自动生成的。对于每个获得的视图，都会计算出相应的二维形状表示。因此，在生成三维形状模型时，并不使用对象的图像，而仅使用作为参数传递给 ObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3Dobject_model_3d 的三维对象模型。所有视图的形状表示都存储在三维形状模型中，该模型通过 ShapeModel3DIDShapeModel3DIDShapeModel3DIDShapeModel3DIDshapeModel3DIDshape_model_3did 返回。在使用 find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3dfind_shape_model_3d 进行匹配的过程中，将利用这些形状表示来确定最佳匹配视图，随后据此精化姿态并返回结果。

为了正确创建模型视图，必须将用于匹配的相机的相机参数传递给 CamParamCamParamCamParamCamParamcamParamcam_param。相机参数是必要的，例如，通过使用相机的实际焦距来确定投影的比例。此外，它们还用于正确处理镜头的径向畸变。因此，在创建三维形状模型之前，必须使用 calibrate_camerascalibrate_camerasCalibrateCamerasCalibrateCamerasCalibrateCamerascalibrate_cameras 对相机进行校准。一方面，这是为了从 find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3dfind_shape_model_3d 获取准确的姿态信息。另一方面，这使得即使在使用具有显著径向畸变的镜头时，三维匹配也能正常进行。

可以通过参数 RefRotXRefRotXRefRotXRefRotXrefRotXref_rot_x、RefRotYRefRotYRefRotYRefRotYrefRotYref_rot_y、RefRotZRefRotZRefRotZRefRotZrefRotZref_rot_z、OrderOfRotationOrderOfRotationOrderOfRotationOrderOfRotationorderOfRotationorder_of_rotation、LongitudeMinLongitudeMinLongitudeMinLongitudeMinlongitudeMinlongitude_min、LongitudeMaxLongitudeMaxLongitudeMaxLongitudeMaxlongitudeMaxlongitude_max、LatitudeMinLatitudeMinLatitudeMinLatitudeMinlatitudeMinlatitude_min、LatitudeMaxLatitudeMaxLatitudeMaxLatitudeMaxlatitudeMaxlatitude_max、CamRollMinCamRollMinCamRollMinCamRollMincamRollMincam_roll_min、CamRollMaxCamRollMaxCamRollMaxCamRollMaxcamRollMaxcam_roll_max、DistMinDistMinDistMinDistMindistMindist_min 和 DistMaxDistMaxDistMaxDistMaxdistMaxdist_max 来指定生成模型视图的姿态范围。请注意，只有当模型出现在指定的姿态范围内时，才会被匹配识别。这些参数的说明如下：

在计算视图之前，需将三维对象模型的坐标系原点移动到该三维对象模型的参考点，该参考点即为最小包围轴平行长方体的中心，可通过调用 get_object_model_3d_paramsget_object_model_3d_paramsGetObjectModel3dParamsGetObjectModel3dParamsGetObjectModel3dParamsget_object_model_3d_params 进行查询。用于创建视图的虚拟相机围绕三维对象模型排列，使得它们均朝向坐标系的原点，即相机的 z 轴穿过原点。随后，可以通过将视图限制在原点周围球体上的某个四边形内来指定姿态范围。这自然导致了球坐标系中经度、纬度和半径的使用。球坐标系的定义方式是：赤道面对应于笛卡尔坐标系的 xz 平面，其中 y 轴指向南极（负纬度），负 z 轴指向零经线方向（有关笛卡尔坐标与球坐标之间转换的更多细节，请参阅 convert_point_3d_spher_to_cartconvert_point_3d_spher_to_cartConvertPoint3dSpherToCartConvertPoint3dSpherToCartConvertPoint3dSpherToCartconvert_point_3d_spher_to_cart 或 convert_point_3d_cart_to_spherconvert_point_3d_cart_to_spherConvertPoint3dCartToSpherConvertPoint3dCartToSpherConvertPoint3dCartToSpherconvert_point_3d_cart_to_spher）。此定义的优势在于：姿态为 [0,0,z,0,0,0,0] 的相机，其光心位于经度longitude=0、纬度latitude=0、半径radius=z 处。在此情况下，半径代表相机光心到三维对象模型参考点的距离。

要生成视图的经度范围可通过 LongitudeMinLongitudeMinLongitudeMinLongitudeMinlongitudeMinlongitude_min 和 LongitudeMaxLongitudeMaxLongitudeMaxLongitudeMaxlongitudeMaxlongitude_max 指定，两者均以弧度为单位。相应地，纬度范围可通过 LatitudeMinLatitudeMinLatitudeMinLatitudeMinlatitudeMinlatitude_min 和 LatitudeMaxLatitudeMaxLatitudeMaxLatitudeMaxlatitudeMaxlatitude_max 指定，同样以弧度为单位。LongitudeMinLongitudeMinLongitudeMinLongitudeMinlongitudeMinlongitude_min 和 LongitudeMaxLongitudeMaxLongitudeMaxLongitudeMaxlongitudeMaxlongitude_max 会进行调整，以确保范围保持在 360° 之内。如果可以进行调整，则会保留 LongitudeMinLongitudeMinLongitudeMinLongitudeMinlongitudeMinlongitude_min 和范围。相机中心与模型参考点之间的最小和最大距离由 DistMinDistMinDistMinDistMindistMindist_min 和 DistMaxDistMaxDistMaxDistMaxdistMaxdist_max 指定。因此，模型原点位于最小包围长方体的中心，并不一定与 CAD 坐标系的原点重合。请注意，距离的单位必须为米（假设在使用 read_object_model_3dread_object_model_3dReadObjectModel3dReadObjectModel3dReadObjectModel3dread_object_model_3d 读取 CAD 文件时，ScaleScaleScaleScalescalescale 参数已正确设置）。最后，可以通过 CamRollMinCamRollMinCamRollMinCamRollMincamRollMincam_roll_min 和 CamRollMaxCamRollMaxCamRollMaxCamRollMaxcamRollMaxcam_roll_max 指定相机的最小和最大横滚角。该区间指定了相机相对于三维对象模型在 z 轴上的允许旋转范围。如果图像平面与对象所在的平面平行，且已知对象在此平面上的旋转仅限于特定范围，则在 CamRollMinCamRollMinCamRollMinCamRollMincamRollMincam_roll_min 和 CamRollMaxCamRollMaxCamRollMaxCamRollMaxcamRollMaxcam_roll_max 中指定该范围是合理的。在所有其他情况下，相机横滚角的解释较为困难，因此建议将该区间设置为。请注意，指定的姿态范围越大，模型消耗的内存就越多（相机横滚角范围除外），且匹配速度也会越慢。

三维对象模型的坐标系方向由通过 read_object_model_3dread_object_model_3dReadObjectModel3dReadObjectModel3dReadObjectModel3dread_object_model_3d 读取的 CAD 文件中的坐标定义。因此，建议先将三维对象模型旋转至参考方向，使得对应经度 longitude=0 和纬度 latitude=0 的视图大致位于姿态范围的中心。这可以通过在 RefRotXRefRotXRefRotXRefRotXrefRotXref_rot_x、RefRotYRefRotYRefRotYRefRotYrefRotYref_rot_y、RefRotZRefRotZRefRotZRefRotZrefRotZref_rot_z 和 OrderOfRotationOrderOfRotationOrderOfRotationOrderOfRotationorderOfRotationorder_of_rotation 中传入适当的参考方向值来实现。旋转操作围绕三维对象模型的轴进行，其原点被设置为参考点。随后，经度和纬度范围即可被解释为三维对象模型相对于参考方向的姿态变化。指定参考姿态有两种可能的方式。第一种是在 RefRotXRefRotXRefRotXRefRotXrefRotXref_rot_x、RefRotYRefRotYRefRotYRefRotYrefRotYref_rot_y 和 RefRotZRefRotZRefRotZRefRotZrefRotZref_rot_z 中指定三个旋转角度，并在 OrderOfRotationOrderOfRotationOrderOfRotationOrderOfRotationorderOfRotationorder_of_rotation 中指定应用这三个旋转的顺序，该顺序可以是 'gba'"gba""gba""gba""gba""gba" 或 'abg'"abg""abg""abg""abg""abg"。第二种方法是在 RefRotXRefRotXRefRotXRefRotXrefRotXref_rot_x、RefRotYRefRotYRefRotYRefRotYrefRotYref_rot_y 和 RefRotZRefRotZRefRotZRefRotZrefRotZref_rot_z 中指定罗德里格斯（Rodriguez）旋转向量的三个分量。在此情况下，OrderOfRotationOrderOfRotationOrderOfRotationOrderOfRotationorderOfRotationorder_of_rotation 必须设置为 'rodriguez'"rodriguez""rodriguez""rodriguez""rodriguez""rodriguez"（有关旋转顺序和罗德里格斯向量定义的详细信息，请参阅 create_posecreate_poseCreatePoseCreatePoseCreatePosecreate_pose）。

因此，在计算姿态范围内的模型视图之前，需对三维对象模型应用两次变换。第一次变换是将坐标系原点平移至参考点。第二次变换是将三维对象模型绕参考坐标系的轴线旋转，使其达到所需的参考方向。通过组合这两个变换，即可得到三维形状模型的参考姿态。因此，三维形状模型的参考姿态描述了参考坐标系相对于CAD文件定义的三维对象模型坐标系的姿态。设 t = (x,y,z)' 为三维对象模型的参考点坐标，R 为包含参考方向的旋转矩阵。则三维对象模型坐标系中给定的点可通过应用以下公式转换为三维形状模型参考坐标系中的点：

该变换可以用齐次三维变换矩阵表示，或者用三维姿态来描述。后者可通过在 get_shape_model_3d_paramsget_shape_model_3d_paramsGetShapeModel3dParamsGetShapeModel3dParamsGetShapeModel3dParamsget_shape_model_3d_params 算子的 GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name 参数中传入 'reference_pose'"reference_pose""reference_pose""reference_pose""reference_pose""reference_pose" 来查询。上述公式最好理解为姿态类型为 8、10 或 12 的姿态，具体取决于 OrderOfRotationOrderOfRotationOrderOfRotationOrderOfRotationorderOfRotationorder_of_rotation 的取值（有关不同姿态类型的详细信息，请参阅 create_posecreate_poseCreatePoseCreatePoseCreatePosecreate_pose）。但请注意，get_shape_model_3d_paramsget_shape_model_3d_paramsGetShapeModel3dParamsGetShapeModel3dParamsGetShapeModel3dParamsget_shape_model_3d_params 算子始终以姿态类型 0 返回姿态。最后，使用 trans_pose_shape_model_3dtrans_pose_shape_model_3dTransPoseShapeModel3dTransPoseShapeModel3dTransPoseShapeModel3dtrans_pose_shape_model_3d 可以将给定于其中一个坐标系的姿态转换为另一个坐标系。

此外，需要注意的是，引入参考坐标系仅是为了更方便地指定姿态范围。通过 find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3dfind_shape_model_3d 执行的三维匹配所得到的姿态，始终以 CAD 文件中使用的原始三维对象模型坐标系为基准。

通过 MinContrastMinContrastMinContrastMinContrastminContrastmin_contrast，可以确定模型在 find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3dfind_shape_model_3d 执行的识别过程中至少需要具备多少边缘对比度。换言之，该参数用于将模型与图像中的噪声分离。因此，理想设置应为图像噪声引发的灰度值变化范围。例如，若灰度值波动范围在 10 个灰度级内，则应将 MinContrastMinContrastMinContrastMinContrastminContrastmin_contrast 设为 10。如果使用多通道图像作为搜索图像，则必须将一个通道中的噪声乘以通道数的平方根，以确定 MinContrastMinContrastMinContrastMinContrastminContrastmin_contrast。例如，如果单个通道的灰度值在 10 个灰度级范围内波动，且图像为三通道图像，则应将 MinContrastMinContrastMinContrastMinContrastminContrastmin_contrast 设置为 17。若需在极低对比度图像中识别模型，则需将 MinContrastMinContrastMinContrastMinContrastminContrastmin_contrast 设置为相应较小的数值。如果需要即使在模型严重被遮挡的情况下也能识别，MinContrastMinContrastMinContrastMinContrastminContrastmin_contrast 应略大于噪声产生的灰度值波动范围，以确保 find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3dfind_shape_model_3d 能稳健、准确地提取模型的姿态。

上述参数取决于具体应用，在创建三维形状模型时必须始终指定。此外，还有一些泛型参数可用于影响模型的创建，但使用与否可选。对于大多数应用，这些参数无需指定，可保留其默认值。如需指定，可分别使用 GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name 和 GenParamValueGenParamValueGenParamValueGenParamValuegenParamValuegen_param_value 参数来设定这些参数及其对应值。GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name 的可能取值如下：

'num_levels'"num_levels""num_levels""num_levels""num_levels""num_levels"：

出于效率考虑，模型视图是在多个金字塔层上生成的。较高层生成的视图数量少于较低层。通过 'num_levels'"num_levels""num_levels""num_levels""num_levels""num_levels" 参数，可以指定生成模型视图的金字塔层数。该数值应尽可能大，因为这样可以显著缩短查找模型所需的时间。另一方面，层数的选择必须确保最高金字塔层上的视图形状仍可识别，且包含足够数量的点（至少四个）。如果某个视图生成的模型点不足，该视图将从模型中删除，并由较低金字塔层上的视图替代。如果金字塔层上的所有视图生成的模型点都不够，则系统会内部减少层数，直到在最高金字塔层上至少有一个视图能找到足够的模型点为止。如果此过程会导致模型没有金字塔层，即如果所有视图在最低金字塔层上的模型点数都太少，create_shape_model_3dcreate_shape_model_3dCreateShapeModel3dCreateShapeModel3dCreateShapeModel3dcreate_shape_model_3d 返回一条错误消息。如果 'num_levels'"num_levels""num_levels""num_levels""num_levels""num_levels" 设置为 'auto'"auto""auto""auto""auto""auto"（默认值），create_shape_model_3dcreate_shape_model_3dCreateShapeModel3dCreateShapeModel3dCreateShapeModel3dcreate_shape_model_3d 将自动确定金字塔层数。在这种情况下，系统会自动检查所有金字塔层级上的模型视图，确认其形状表示是否仍可识别。如果发现某个视图的形状表示无法识别，该视图将从模型中删除，并由较低金字塔层级上的视图替代。请注意，如果将 'num_levels'"num_levels""num_levels""num_levels""num_levels""num_levels" 设置为 'auto'"auto""auto""auto""auto""auto"，不同视图的金字塔层级数量可能会有所不同。在极少数情况下，create_shape_model_3dcreate_shape_model_3dCreateShapeModel3dCreateShapeModel3dCreateShapeModel3dcreate_shape_model_3d确定的金字塔层数可能过大或过小。如果金字塔层数设置过大，模型可能无法在图像中被识别，或者可能需要在 find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3dfind_shape_model_3d 中为 MinScoreMinScoreMinScoreMinScoreminScoremin_score 或 GreedinessGreedinessGreedinessGreedinessgreedinessgreediness 选择非常低的参数才能找到模型。如果金字塔层数设置过小，find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3dfind_shape_model_3d 中查找模型所需的时间可能会增加。在这些情况下，应使用 get_shape_model_3d_contoursget_shape_model_3d_contoursGetShapeModel3dContoursGetShapeModel3dContoursGetShapeModel3dContoursget_shape_model_3d_contours 的输出结果检查各金字塔层上的视图。

建议值： 'auto'"auto""auto""auto""auto""auto", 3, 4, 5, 6

默认值： 'auto'"auto""auto""auto""auto""auto"

'fast_pose_refinement'"fast_pose_refinement""fast_pose_refinement""fast_pose_refinement""fast_pose_refinement""fast_pose_refinement"：

该参数用于指定在使用 find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3dfind_shape_model_3d 进行搜索时，是否加快姿态精化速度。如果将 'fast_pose_refinement'"fast_pose_refinement""fast_pose_refinement""fast_pose_refinement""fast_pose_refinement""fast_pose_refinement" 设置为 'false'"false""false""false""false""false"，对于具有大量面的复杂模型，姿态精化步骤可能会占用整体计算时间中的很大一部分。若将 'fast_pose_refinement'"fast_pose_refinement""fast_pose_refinement""fast_pose_refinement""fast_pose_refinement""fast_pose_refinement" 设置为 'true'"true""true""true""true""true"，姿态精化过程中所需的部分计算将在模型生成阶段提前完成并存储于模型中。因此，搜索过程中的姿态精化速度将得到提升。但请注意，在此情况下模型的内存占用可能会显著增加（通常不超过 30%）。此外，由于当该参数设置为 'true'"true""true""true""true""true" 时，内部会采用近似方式进行姿态精化，因此 find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3dfind_shape_model_3d 返回的最终姿态可能会因 'fast_pose_refinement'"fast_pose_refinement""fast_pose_refinement""fast_pose_refinement""fast_pose_refinement""fast_pose_refinement" 的取值而略有差异。

值列表： 'true'"true""true""true""true""true", 'false'"false""false""false""false""false"

默认值： 'true'"true""true""true""true""true"

'lowest_model_level'"lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level"：

在某些情况下，模型生成过程可能非常耗时，且模型的内存占用可能非常高。原因在于，这些情况下必须计算并存储在模型中的视图数量非常多。选择的姿态范围越大，以及图像中对象的尺寸（以像素为单位）越大，所需的视图数量就越多。因此，特别是使用大尺寸图像（例如超过 640×480 像素的图像）时，可能会生成非常庞大的模型。由于较低金字塔层级的视图数量最多，因此可以使用 'lowest_model_level'"lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level" 参数将较低金字塔层级排除在视图生成之外。传递给 'lowest_model_level'"lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level" 的值决定了视图生成并存储在三维形状模型中的最低金字塔层级。例如，如果为大型模型传递值 2，则模型生成时间以及生成的模型大小将减少到原始值的大约三分之一。若未传入 'lowest_model_level'"lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level" 参数，则将为所有金字塔层生成视图，这相当于将 'lowest_model_level'"lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level" 设为 1 时的行为。若传入的 'lowest_model_level'"lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level" 值大于 1，则在 find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3dfind_shape_model_3d 中，通过金字塔的匹配追踪将在该层停止。然而，若在 find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3dfind_shape_model_3d 中选择最小二乘法进行姿态精化，则匹配结果将在最低金字塔层级通过最小二乘法进行精化。请注意，根据 'lowest_model_level'"lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level" 的不同值，搜索过程中可能找到不同的匹配结果。此外，匹配的分数取决于所选的姿态精化方法。另请注意，'lowest_model_level'"lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level" 值越高，在 find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3dfind_shape_model_3d 的总运行时间中，精化步骤所占的比例就越大。因此，对于较高的 'lowest_model_level'"lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level" 值，泛型参数 'fast_pose_refinement'"fast_pose_refinement""fast_pose_refinement""fast_pose_refinement""fast_pose_refinement""fast_pose_refinement"（见上文）对运行时间的影响将随之增加。一方面，如果 'fast_pose_refinement'"fast_pose_refinement""fast_pose_refinement""fast_pose_refinement""fast_pose_refinement""fast_pose_refinement" 被关闭（'false'"false""false""false""false""false"），过大的 'lowest_model_level'"lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level" 值可能会导致 find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3dfind_shape_model_3d 的计算时间过长。另一方面，如果 'fast_pose_refinement'"fast_pose_refinement""fast_pose_refinement""fast_pose_refinement""fast_pose_refinement""fast_pose_refinement" 被开启（'true'"true""true""true""true""true"），可能会导致精度下降，因为在此模式下，姿态精化仅为近似处理。因此，应尽可能选择较小的 'lowest_model_level'"lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level"值。此外，'lowest_model_level'"lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level" 应足够小，以确保在此级别下仍能观察到三维对象模型的边界。

建议值： 1, 2, 3

默认值： 1

'optimization'"optimization""optimization""optimization""optimization""optimization"：

对于模型视图特别大的模型，将优化 'optimization'"optimization""optimization""optimization""optimization""optimization" 设置为 'none'"none""none""none""none""none" 以外的值以减少模型点数量可能会很有帮助。如果 'optimization'"optimization""optimization""optimization""optimization""optimization" = 'none'"none""none""none""none""none"，则会存储所有模型点。在所有其他情况下，点数将根据 'optimization'"optimization""optimization""optimization""optimization""optimization" 的值进行减少。如果点数减少，则可能需要在 find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3dfind_shape_model_3d 中将贪婪度 GreedinessGreedinessGreedinessGreedinessgreedinessgreediness 参数设置为较小的值，例如 0.7 或 0.8。对于模型视图较少的模型，减少模型点数并不会加快搜索速度，因为在此情况下通常需要检查的模型潜在实例数量会显著增加。如果将 'optimization'"optimization""optimization""optimization""optimization""optimization" 设置为 'auto'"auto""auto""auto""auto""auto"，create_shape_model_3dcreate_shape_model_3dCreateShapeModel3dCreateShapeModel3dCreateShapeModel3dcreate_shape_model_3d 会自动为每个模型视图确定模型点数的减少量。

值列表： 'auto'"auto""auto""auto""auto""auto", 'none'"none""none""none""none""none", 'point_reduction_low'"point_reduction_low""point_reduction_low""point_reduction_low""point_reduction_low""point_reduction_low", 'point_reduction_medium'"point_reduction_medium""point_reduction_medium""point_reduction_medium""point_reduction_medium""point_reduction_medium", 'point_reduction_high'"point_reduction_high""point_reduction_high""point_reduction_high""point_reduction_high""point_reduction_high"

默认值： 'auto'"auto""auto""auto""auto""auto"

'metric'"metric""metric""metric""metric""metric"：

此参数决定了在何种条件下可在图像中识别出模型。如果 'metric'"metric""metric""metric""metric""metric" = 'ignore_part_polarity'"ignore_part_polarity""ignore_part_polarity""ignore_part_polarity""ignore_part_polarity""ignore_part_polarity"，则仅允许模型不同部分之间的对比度极性发生变化，而同一模型部分内的模型点极性不得改变。请注意，'ignore_part_polarity'"ignore_part_polarity""ignore_part_polarity""ignore_part_polarity""ignore_part_polarity""ignore_part_polarity" 这一术语容易引起误解。其含义是，相邻模型部分之间的极性变化不会影响评分，因此会被忽略。合适的模型部分会自动确定。部分的大小可以通过泛型参数 'part_size'"part_size""part_size""part_size""part_size""part_size" 进行控制，该参数将在下文描述。请注意，此度量仅适用于单通道图像。因此，如果使用此度量创建模型，然后使用 find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3dfind_shape_model_3d 在多通道图像中进行搜索，将会返回错误。若 'metric'"metric""metric""metric""metric""metric" = 'ignore_local_polarity'"ignore_local_polarity""ignore_local_polarity""ignore_local_polarity""ignore_local_polarity""ignore_local_polarity"，即使每个模型点的对比度极性发生变化，仍能找到模型。该度量适用于单通道图像和多通道图像。若图像包含纹理强烈的背景或杂乱对象，可能导致错误匹配，此时应使用 'ignore_part_polarity'"ignore_part_polarity""ignore_part_polarity""ignore_part_polarity""ignore_part_polarity""ignore_part_polarity" 度量。请注意，通常情况下，find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3dfind_shape_model_3d 返回的匹配分数在 'ignore_part_polarity'"ignore_part_polarity""ignore_part_polarity""ignore_part_polarity""ignore_part_polarity""ignore_part_polarity" 模式下会低于 'ignore_local_polarity'"ignore_local_polarity""ignore_local_polarity""ignore_local_polarity""ignore_local_polarity""ignore_local_polarity" 模式。在为 find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3dfind_shape_model_3d 的 MinScoreMinScoreMinScoreMinScoreminScoremin_score参数选择合适值时，应将此点纳入考量。

值列表： 'ignore_local_polarity'"ignore_local_polarity""ignore_local_polarity""ignore_local_polarity""ignore_local_polarity""ignore_local_polarity", 'ignore_part_polarity'"ignore_part_polarity""ignore_part_polarity""ignore_part_polarity""ignore_part_polarity""ignore_part_polarity"

默认值： 'ignore_local_polarity'"ignore_local_polarity""ignore_local_polarity""ignore_local_polarity""ignore_local_polarity""ignore_local_polarity"

'part_size'"part_size""part_size""part_size""part_size""part_size"：

当 'metric'"metric""metric""metric""metric""metric" 设置为 'ignore_part_polarity'"ignore_part_polarity""ignore_part_polarity""ignore_part_polarity""ignore_part_polarity""ignore_part_polarity" （参见上文）时，此参数用于确定模型部分的大小。该尺寸必须以像素为单位指定，且应约为图像中背景纹理尺寸的两倍。例如，若需在由 5×5 像素黑白方格组成的棋盘前方寻找对象，则应将 'part_size'"part_size""part_size""part_size""part_size""part_size" 设置为 10。请注意，'part_size'"part_size""part_size""part_size""part_size""part_size" 值过高可能会降低正确实例的评分，尤其是在搜索具有光泽或反射表面的对象时。因此，若将 'part_size'"part_size""part_size""part_size""part_size""part_size" 设为较大数值，遗漏正确实例的风险可能会增加。若 'metric'"metric""metric""metric""metric""metric" 设为 'ignore_local_polarity'"ignore_local_polarity""ignore_local_polarity""ignore_local_polarity""ignore_local_polarity""ignore_local_polarity"，则 'part_size'"part_size""part_size""part_size""part_size""part_size" 的数值将被忽略。

建议值： 2, 3, 4, 6, 8, 10

默认值： 4

'min_face_angle'"min_face_angle""min_face_angle""min_face_angle""min_face_angle""min_face_angle"：

只有当与三维对象模型边缘相交的两个三维面之间的夹角不小于 'min_face_angle'"min_face_angle""min_face_angle""min_face_angle""min_face_angle""min_face_angle" 时，这些三维边缘才会被包含在视图的形状表示中。若将 'min_face_angle'"min_face_angle""min_face_angle""min_face_angle""min_face_angle""min_face_angle" 设为 0.0，则包含所有边。若将 'min_face_angle'"min_face_angle""min_face_angle""min_face_angle""min_face_angle""min_face_angle" 设为（即 180 度），则仅包含三维对象模型的轮廓。此参数可用于抑制曲面内的边，例如圆柱体或圆锥体的表面。曲面由多个平面表面近似表示。此类相邻平面表面之间的边不应包含在形状表示中，因为它们在模型的真实图像中也不会出现。因此，应将 'min_face_angle'"min_face_angle""min_face_angle""min_face_angle""min_face_angle""min_face_angle" 设置得足够高以抑制这些边。在调用 create_shape_model_3dcreate_shape_model_3dCreateShapeModel3dCreateShapeModel3dCreateShapeModel3dcreate_shape_model_3d 之前，可通过 project_object_model_3dproject_object_model_3dProjectObjectModel3dProjectObjectModel3dProjectObjectModel3dproject_object_model_3d 检查不同 'min_face_angle'"min_face_angle""min_face_angle""min_face_angle""min_face_angle""min_face_angle" 值的效果。请注意，如果形状表示中包含了在搜索图像中不可见的边缘，匹配的性能（稳健性和速度）可能会显著下降。

建议值： 'rad(10)'"rad(10)""rad(10)""rad(10)""rad(10)""rad(10)", 'rad(20)'"rad(20)""rad(20)""rad(20)""rad(20)""rad(20)", 'rad(30)'"rad(30)""rad(30)""rad(30)""rad(30)""rad(30)", 'rad(45)'"rad(45)""rad(45)""rad(45)""rad(45)""rad(45)"

默认值： 'rad(30)'"rad(30)""rad(30)""rad(30)""rad(30)""rad(30)"

'min_size'"min_size""min_size""min_size""min_size""min_size"：

该值根据组件的大小确定了选择显著模型组件的阈值，即，连接组件中的点数少于指定最小大小的，将被屏蔽。该最小尺寸阈值在金字塔各层级中均按二分法递减。

建议值： 'auto'"auto""auto""auto""auto""auto", 0, 3, 5, 10, 20

默认值： 'auto'"auto""auto""auto""auto""auto"

'model_tolerance'"model_tolerance""model_tolerance""model_tolerance""model_tolerance""model_tolerance"：

该参数指定了图像中投影的三维对象模型边缘的公差，单位为像素。选择的数值越高，需要生成的视图就越少。因此，较高的数值会生成占用内存更少且使用 find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3dfind_shape_model_3d 查找速度更快的模型。另一方面，如果数值设置过高，匹配的稳健性将会降低。因此，修改此参数时应谨慎。对于大多数应用而言，将 'model_tolerance'"model_tolerance""model_tolerance""model_tolerance""model_tolerance""model_tolerance" 设置为 1 可在速度与稳健性之间取得良好的平衡。

建议值： 0, 1, 2

默认值： 1

'union_adjacent_contours'"union_adjacent_contours""union_adjacent_contours""union_adjacent_contours""union_adjacent_contours""union_adjacent_contours"：

此参数用于指定算子 project_shape_model_3dproject_shape_model_3dProjectShapeModel3dProjectShapeModel3dProjectShapeModel3dproject_shape_model_3d 是否应将相邻的投影轮廓连接起来。启用此选项相当于随后调用 union_adjacent_contours_xldunion_adjacent_contours_xldUnionAdjacentContoursXldUnionAdjacentContoursXldUnionAdjacentContoursXldunion_adjacent_contours_xld，但速度要快得多。

值列表： 'true'"true""true""true""true""true", 'false'"false""false""false""false""false"

默认值： 'false'"false""false""false""false""false"

如果系统变量（参见 set_systemset_systemSetSystemSetSystemSetSystemset_system）'opengl_hidden_surface_removal_enable'"opengl_hidden_surface_removal_enable""opengl_hidden_surface_removal_enable""opengl_hidden_surface_removal_enable""opengl_hidden_surface_removal_enable""opengl_hidden_surface_removal_enable" 设置为 'true'"true""true""true""true""true"（如果可用，则为默认值），则会利用显卡来加速模型视图中可见面的计算。根据显卡性能的不同，这比解析可见性计算要快得多。请注意，OpenGL 投影的结果与解析投影相比会略有不同。

执行信息

多线程类型：可重入（与非独占算子并行运行）。
多线程作用域：全局（可从任何线程调用）。
在内部数据级别上自动并行化。

此算子返回一个句柄。请注意，即使该句柄被用作特定算子的输入参数，这些算子仍可能改变此句柄类型的实例状态。

参数

ObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3Dobject_model_3d (输入控制) object_model_3d → (handle)

3D 对象模型的句柄。

CamParamCamParamCamParamCamParamcamParamcam_param (输入控制) campar → (real / integer / string)

内部相机参数。

RefRotXRefRotXRefRotXRefRotXrefRotXref_rot_x (输入控制) angle.rad → (real)

参考坐标系：绕 x 轴或罗德里格斯向量 x 分量旋转（以弧度为单位或不带单位）。

默认值： 0

建议值： -1.57, -0.78, -0.17, 0., 0.17, 0.78, 1.57

RefRotYRefRotYRefRotYRefRotYrefRotYref_rot_y (输入控制) angle.rad → (real)

参考方向：绕 y 轴或罗德里格斯向量的 y 分量旋转（以弧度为单位或不带单位）。

默认值： 0

建议值： -1.57, -0.78, -0.17, 0., 0.17, 0.78, 1.57

RefRotZRefRotZRefRotZRefRotZrefRotZref_rot_z (输入控制) angle.rad → (real)

参考方向：绕 z 轴或罗德里格斯向量的 z 分量旋转（以弧度为单位或不带单位）。

默认值： 0

建议值： -1.57, -0.78, -0.17, 0., 0.17, 0.78, 1.57

OrderOfRotationOrderOfRotationOrderOfRotationOrderOfRotationorderOfRotationorder_of_rotation (输入控制) string → (string)

参考方向旋转值的含义。

默认值： 'gba' "gba" "gba" "gba" "gba" "gba"

值列表： 'abg'"abg""abg""abg""abg""abg", 'gba'"gba""gba""gba""gba""gba", 'rodriguez'"rodriguez""rodriguez""rodriguez""rodriguez""rodriguez"

LongitudeMinLongitudeMinLongitudeMinLongitudeMinlongitudeMinlongitude_min (输入控制) angle.rad → (real)

模型视图的最小经度。

默认值： -0.35

建议值： -0.78, -0.35, -0.17

LongitudeMaxLongitudeMaxLongitudeMaxLongitudeMaxlongitudeMaxlongitude_max (输入控制) angle.rad → (real)

模型视图的最大经度。

默认值： 0.35

建议值： 0.17, 0.35, 0.78

限制： LongitudeMax >= LongitudeMin

LatitudeMinLatitudeMinLatitudeMinLatitudeMinlatitudeMinlatitude_min (输入控制) angle.rad → (real)

模型视图的最小纬度。

默认值： -0.35

建议值： -0.78, -0.35, -0.17

限制： - pi / 2 <= LatitudeMin && LatitudeMin <= pi / 2

LatitudeMaxLatitudeMaxLatitudeMaxLatitudeMaxlatitudeMaxlatitude_max (输入控制) angle.rad → (real)

模型视图的最大纬度。

默认值： 0.35

建议值： 0.17, 0.35, 0.78

限制： - pi / 2 <= LatitudeMax && LatitudeMax <= pi / 2 && LatitudeMax >= LatitudeMin

CamRollMinCamRollMinCamRollMinCamRollMincamRollMincam_roll_min (输入控制) angle.rad → (real)

模型视图的最小相机横滚角度。

默认值： -3.1416

建议值： -3.14, -1.57, -0.39, 0.0, 0.39, 1.57, 3.14

CamRollMaxCamRollMaxCamRollMaxCamRollMaxcamRollMaxcam_roll_max (输入控制) angle.rad → (real)

模型视图的最大相机横滚角度。

默认值： 3.1416

建议值： -3.14, -1.57, -0.39, 0.0, 0.39, 1.57, 3.14

限制： CamRollMax >= CamRollMin

DistMinDistMinDistMinDistMindistMindist_min (输入控制) number → (real)

模型视图的最小相机-对象距离。

默认值： 0.3

建议值： 0.05, 0.1, 0.2, 0.5

限制： DistMin > 0

DistMaxDistMaxDistMaxDistMaxdistMaxdist_max (输入控制) number → (real)

模型视图的最大相机-对象距离。

默认值： 0.4

建议值： 0.1, 0.2, 0.5, 1.0

限制： DistMax >= DistMin

MinContrastMinContrastMinContrastMinContrastminContrastmin_contrast (输入控制) number → (integer)

搜索图像中对象的最小对比度。

默认值： 10

建议值： 1, 2, 3, 5, 7, 10, 20, 30, 1000, 2000, 5000

GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name (输入控制) attribute.name(-array) → (string)

用于控制算子行为的（可选）参数名称。

默认值： []

值列表： 'fast_pose_refinement'"fast_pose_refinement""fast_pose_refinement""fast_pose_refinement""fast_pose_refinement""fast_pose_refinement", 'lowest_model_level'"lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level""lowest_model_level", 'metric'"metric""metric""metric""metric""metric", 'min_face_angle'"min_face_angle""min_face_angle""min_face_angle""min_face_angle""min_face_angle", 'min_size'"min_size""min_size""min_size""min_size""min_size", 'model_tolerance'"model_tolerance""model_tolerance""model_tolerance""model_tolerance""model_tolerance", 'num_levels'"num_levels""num_levels""num_levels""num_levels""num_levels", 'optimization'"optimization""optimization""optimization""optimization""optimization", 'part_size'"part_size""part_size""part_size""part_size""part_size", 'union_adjacent_contours'"union_adjacent_contours""union_adjacent_contours""union_adjacent_contours""union_adjacent_contours""union_adjacent_contours"

GenParamValueGenParamValueGenParamValueGenParamValuegenParamValuegen_param_value (输入控制) attribute.name(-array) → (integer / real / string)

可选泛型参数的值。

默认值： []

建议值： 0, 1, 2, 3, 4, 6, 8, 10, 'auto'"auto""auto""auto""auto""auto", 'none'"none""none""none""none""none", 'point_reduction_low'"point_reduction_low""point_reduction_low""point_reduction_low""point_reduction_low""point_reduction_low", 'point_reduction_medium'"point_reduction_medium""point_reduction_medium""point_reduction_medium""point_reduction_medium""point_reduction_medium", 'point_reduction_high'"point_reduction_high""point_reduction_high""point_reduction_high""point_reduction_high""point_reduction_high", 0.1, 0.2, 0.3, 'ignore_local_polarity'"ignore_local_polarity""ignore_local_polarity""ignore_local_polarity""ignore_local_polarity""ignore_local_polarity", 'ignore_part_polarity'"ignore_part_polarity""ignore_part_polarity""ignore_part_polarity""ignore_part_polarity""ignore_part_polarity", 'true'"true""true""true""true""true", 'false'"false""false""false""false""false"

ShapeModel3DIDShapeModel3DIDShapeModel3DIDShapeModel3DIDshapeModel3DIDshape_model_3did (输出控制) shape_model_3d → (handle)

3D 形状模型的句柄。

结果

如果参数有效，算子 create_shape_model_3dcreate_shape_model_3dCreateShapeModel3dCreateShapeModel3dCreateShapeModel3dcreate_shape_model_3d 返回值 2 (H_MSG_TRUE)。如有必要，则抛出异常。如果参数设置不当，导致所有模型视图中的点数过少，则会触发错误 8510。如果投影模型在至少一个模型视图中的尺寸超过图像尺寸的两倍，则会触发错误 8910。

可能的前趋

read_object_model_3dread_object_model_3dReadObjectModel3dReadObjectModel3dReadObjectModel3dread_object_model_3d, project_object_model_3dproject_object_model_3dProjectObjectModel3dProjectObjectModel3dProjectObjectModel3dproject_object_model_3d, get_object_model_3d_paramsget_object_model_3d_paramsGetObjectModel3dParamsGetObjectModel3dParamsGetObjectModel3dParamsget_object_model_3d_params

可能的后继

find_shape_model_3dfind_shape_model_3dFindShapeModel3dFindShapeModel3dFindShapeModel3dfind_shape_model_3d, write_shape_model_3dwrite_shape_model_3dWriteShapeModel3dWriteShapeModel3dWriteShapeModel3dwrite_shape_model_3d, project_shape_model_3dproject_shape_model_3dProjectShapeModel3dProjectShapeModel3dProjectShapeModel3dproject_shape_model_3d, get_shape_model_3d_paramsget_shape_model_3d_paramsGetShapeModel3dParamsGetShapeModel3dParamsGetShapeModel3dParamsget_shape_model_3d_params, get_shape_model_3d_contoursget_shape_model_3d_contoursGetShapeModel3dContoursGetShapeModel3dContoursGetShapeModel3dContoursget_shape_model_3d_contours

另见

convert_point_3d_cart_to_spherconvert_point_3d_cart_to_spherConvertPoint3dCartToSpherConvertPoint3dCartToSpherConvertPoint3dCartToSpherconvert_point_3d_cart_to_spher, convert_point_3d_spher_to_cartconvert_point_3d_spher_to_cartConvertPoint3dSpherToCartConvertPoint3dSpherToCartConvertPoint3dSpherToCartconvert_point_3d_spher_to_cart, create_cam_pose_look_at_pointcreate_cam_pose_look_at_pointCreateCamPoseLookAtPointCreateCamPoseLookAtPointCreateCamPoseLookAtPointcreate_cam_pose_look_at_point, trans_pose_shape_model_3dtrans_pose_shape_model_3dTransPoseShapeModel3dTransPoseShapeModel3dTransPoseShapeModel3dtrans_pose_shape_model_3d

参考文献

Markus Ulrich, Christian Wiedemann, Carsten Steger, “Combining Scale-Space and Similarity-Based Aspect Graphs for Fast 3D Object Recognition,” IEEE Transactions on Pattern Analysis and Machine Intelligence, pp. 1902-1914, Oct., 2012.

模块

三维计量

算子