find_surface_model

( : : SurfaceModelID, ObjectModel3D, RelSamplingDistance, KeyPointFraction, MinScore, ReturnResultHandle, GenParamName, GenParamValue : Pose, Score, SurfaceMatchingResultID)
在3D场景中找到一个表面模型的最佳匹配。

输入：

• SurfaceModelID
  表面模型的句柄。
• ObjectModel3D
  包含场景的3D对象模型句柄。
• RelSamplingDistance
  场景采样距离相对于表面模型的直径。
  默认值:0.05
  建议值:0.1、0.07、0.05、0.04、0.03
  限制:0 < RelSamplingDistance < 1
• KeyPointFraction
  作为关键点的采样场景点部分（大小）。
  默认值:0.2
  建议值:0.3、0.2、0.1、0.05
  限制:0 < KeyPointFraction <= 1
• MinScore
  返回姿势的最低得分。
  默认值:0
  限制:MinScore >= 0
• ReturnResultHandle
  在SurfaceMatchingResultID中启用返回结果句柄。
  默认值:“假”
  建议值:“true”、“false”
• GenParamName
  通用参数的名称
  默认值:[]
  的值列表:‘3 d_edge_min_amplitude_abs’,‘3 d_edge_min_amplitude_rel’,‘3 d_edges’,‘dense_pose_refinement’,‘max_overlap_dist_abs’,‘max_overlap_dist_rel’,‘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_normal_computation’,‘score_type’,‘sparse_pose_refinement’,‘观点’
• GenParamValue
  通用参数的值
  默认值:[]
  建议值:0、1、‘真’、‘假’、0.005、0.01、0.03、0.05、0.1、‘num_scene_points’、‘model_point_fraction’、‘num_model_points’、‘fast’、‘mls’

输出：

• Pose
  场景中表面模型的三维姿态（3D场景坐标系中SFM的位姿）。
• Score
  surface模型找到的实例的得分。
• SurfaceMatchingResultID
  匹配结果的句柄，如果在ReturnResultHandle中启用。

算子说明

1、操作符find_surface_model在3D场景ObjectModel3D中找到表面模型SurfaceModelID的最佳匹配。surface模型SurfaceModelID必须在之前使用create_surface_model或read_surface_model创建。
曲面模型的匹配要求三维对象模型包含点和法线。下列组合是可能的:

• 点和点法线;
• 点和2d映射，例如用xyz_to_object_model_3d三倍转换的XYZ图像。

2、如果对模型进行边缘支持的基于表面的匹配训练，则只有第二种组合是可能的，即，场景必须包含2D映射。注意，经过的场景中的三角形或多边形将被忽略。相反，只使用顶点进行匹配。因此，通常不建议在网格化的场景(如CAD数据)上使用此操作符。相反，必须使用sample_object_model_3d预先采样这样的场景，以创建点和法线。当使用有噪声的点云时，例如在飞行时间摄像机中，一般参数‘scene_normal_computation’应该设置为‘mls’，以获得更稳定的结果(见下文)。

在Pose中返回 找到的对象实例的3D姿势 。它描述了场景坐标系中表面模型的位姿。 位姿"Pose"是指相对于传递给create_surface_model的3D对象模型的原始坐标系的。

3、此外，每一场匹配都会返回一个分数。在以下情况下，得分的值和解释是不同的:

• 1） 不带位姿细化 Without pose refinement

  • 不带边缘支持
    分数是在被发现的对象上的来自次采样的场景的点的近似数目。
    Score >= 0

  • 带边缘支持
    分数是来自被发现对象上的次采样场景的点的近似数量乘以来自与模型边缘对齐的采样场景边缘的点的数量。
    Score > = 0

• 2）带位姿细化 With pose refinement

  • 不带边缘支持
    分数是表面分数，即物体表面在场景中可见的近似分数。
    0 <=Score <= 1

  • 带边缘支持
    分数是表面分数和边缘分数的几何平均值。边缘分数是采样的模型边缘与场景边缘对齐的点的数量，除以模型上潜在可见边缘的最大数量。
    0 <= Score <= 1(如果场景是从一个视角获取的)
    0 <= Score <= N(从N个不同视点获取的场景中合并场景)

4、参数MinScore可用于过滤结果。只返回得分超过MinScore值的匹配。如果MinScore设置为0，则返回所有匹配项。如果ReturnResultHandle被设置为‘true’，那么在SurfaceMatchingResultID中会返回一个表面匹配结果句柄。可以使用操作符 get_surface_matching_result 查询匹配过程的其他细节。必须使用clear_surface_matching_result 释放返回的句柄，以避免内存泄漏。
参数GenParamName和GenParamValue用于设置通用参数。两者都得到一个长度相等的元组，其中传递给GenParamName的元组包含要设置的参数的名称，传递给GenParamValue的元组包含相应的值。可能的参数名和值如下所述。

匹配分为三个步骤:

1）近似匹配 Approximate matching：搜索场景中表面模型实例的近似姿态

• 1.首先，从ObjectModel3D中传递的场景中均匀采样点。采样距离由参数RelSamplingDistance控制，并与表面模型的直径有关。减小RelSamplingDistance会产生更多的采样点，进而产生更稳定但更慢的匹配。增加RelSamplingDistance会减少采样场景点的数量，从而导致不稳定但更快的匹配。要查看RelSamplingDistance的不同值，请参考操作符create_surface_model。操作符get_surface_matching_result可用于检索采样的场景点以进行视觉检查。为了进行鲁棒匹配，建议每个对象实例至少采样50-100个场景点。

• 2.从采样的场景点中选择一组关键点。所选关键点的数量由参数KeyPointFraction控制。例如，如果将值设置为0.1，则使用10%的采样场景点作为关键点。对于稳定的结果，重要的是对象的每个实例都由几个关键点覆盖。增加KeyPointFraction意味着从场景中选择更多的关键点，这会导致一个更慢但更稳定的匹配。减少关键点分数会产生相反的效果，导致更快但更不稳定的匹配。操作符get_surface_matching_result可用于检索选定的关键点，以便进行可视化检查。

• 3.对于每个选定的关键点，在关键点位于物体表面的假设下，计算出表面模型的最优姿态。这是通过将关键点与所有其他采样的场景点配对，并在表面模型中找到距离和相对方向相似的点对来实现的。相似度由create_surface_model中的参数’feat_step_size_rel’和’feat_angle_resolution’定义。采样场景中点的最大个数位于目标上的姿态被认为是该关键点的最佳姿态。在目标上采样的场景点的数量被认为是姿态的得分。
  如果对模型进行边缘支持的基于表面的匹配训练，则从3D场景中提取边缘(类似于操作符edges_object_model_3d)并采样。除了采样的三维曲面外，参考点还与所有采样的边缘点配对，在曲面模型上找到相似的点-边组合。然后将匹配采样的边缘点的数量与匹配采样的场景点的数量相乘，重新计算得分，并提取如上所述的最佳姿态。

• 4.从所有关键点中选出得分最高的姿势作为近似姿势。返回姿态的最大数量由通用参数“num_matches”设置。如果禁用了姿态细分，则为score中的每个姿态返回上面描述的得分。分数的值取决于场景中可见的实例表面的数量和场景的采样率。只有得分超过最低分的姿势才会被返回。为了确定一个好的MinScore阈值，建议在几个场景中测试匹配。

  注意，这一步的结果只是近似的。姿态的误差与create_surface_model中给定的表面模型的采样率成正比，通常小于物体直径的5%。

  以下通用参数控制近似匹配，可以用GenParamName和GenParamValue设置:

  • “num_matches”:
    设置返回的最大匹配数。
    建议值:1、2、5
    默认值:1
    声明:‘num_matches’ > 0

  • “max_overlap_dist_rel”:
    由于效率的原因，无法在3D中定义最大重叠。相反，可以使用max_overlap_dist_rel’指定两个匹配项的轴向对齐的边界框的中心之间的最小距离。该值是相对于对象的直径设置的。一旦找到一个得分高的对象，如果其边界框的中心太靠近第一个对象的中心，那么所有其他匹配项都将被取消。如果结果匹配必须不重叠，则’max_overlap_dist_rel’的值应设置为1.0。注意，只应该设置参数’max_overlap_dist_rel’和’max_overlap_dist_abs’中的一个。如果同时设置了这两个参数，则只使用最后一个参数的值。
    建议值:0.1、0.5、1
    默认值:0.5
    声明:‘max_overlap_dist_rel’ >= 0

  • “max_overlap_dist_abs”:
    此参数与参数’max_overlap_dist_rel’具有相同的效果。注意，与‘max_overlap_dist_rel’不同，‘max_overlap_dist_abs’的值被设置为绝对值。参见上面的“max_overlap_dist_rel”，以了解该参数的效果。注意，只应该设置参数’max_overlap_dist_rel’和’max_overlap_dist_abs’中的一个。如果同时设置了这两个参数，则只使用最后一个参数的值。
    建议值:1、2、3
    声明:‘max_overlap_dist_abs’ >= 0

  • “scene_normal_computation”:
    该参数控制采样场景的法线计算。在默认模式“fast”下，法线是基于一个小的点邻域来计算的。在模式“mls”中，法线的计算基于更大的邻域，并使用更复杂但更精确的“mls”方法。有关“mls”方法的更详细描述可以在操作符surface_normals_object_model_3d的描述中找到。“mls”模式针对的是噪声数据，比如飞行时间照相机拍摄的图像。
    值列表:‘fast’， ‘mls’
    默认值:“快”

  • “3 d_edges”:
    允许手动设置3D场景的边缘来支持基于表面的匹配，也就是说，如果表面模型是在启用了‘train_3d_edges’的情况下创建的。参数必须是3D对象模型句柄。边缘通常是操作符edges_object_model_3d的结果，但是可以进一步过滤以删除异常值。如果没有给出这个参数，find_surface_model将在内部提取与操作符edges_object_model_3d类似的边。

  • “3 d_edge_min_amplitude_rel”:
    设置提取三维边缘进行基于边缘支持的表面匹配时的阈值，即在启用‘train_3d_edges’的情况下创建表面模型。阈值是相对于对象的直径设置的。注意，如果使用通用参数“3d_edges”手动传递边缘，则忽略该参数。否则，它的行为将与操作符edges_object_model_3d的参数“MinAmplitude”相同。
    建议值:0.05,0.1,0.5
    默认值:0.05
    声明:‘3d_edge_min_amplitude_rel’ >= 0

  • “3 d_edge_min_amplitude_abs”:
    与“3d_edge_min_amplitude_rel”类似，但是，该值是作为绝对距离给出的，而不是相对于对象直径。
    声明:‘3d_edge_min_amplitude_abs’ >= 0

2）稀疏位姿细化:

1.在第二步中，进一步细化前一步中得到的近似姿态。这增加了姿势的准确性和分数值的重要性。

稀疏位姿细化使用了从近似匹配中采样的场景点。通过优化姿态，使得采样的场景点到最近模型点平面的距离最小。每个模型点的平面被定义为垂直于其法线的平面。

此外，如果对模型进行边缘支持的基于表面的匹配训练，则对姿态进行优化，使场景中采样的边缘点与表面模型的边缘对齐。

2.默认情况下启用了稀疏姿态细化。可以通过将通用参数‘sparse_pose_refinement ’设置为‘false’来禁用它。由于每个关键点产生一个位姿候选，因此需要优化的位姿候选的总数与关键点的数量成正比。对于有很多杂乱的大场景，即场景中不属于感兴趣对象的部分，可以更快地禁用稀疏位姿细化。

3.通过计算具有相对应场景点的模型点的数量，再除以模型上的总点数量，对每个姿态的得分进行稀疏姿态细化后重新计算。这将得到一个介于0和1之间的值，该值大约是场景中可见的模型表面的分数(参见下面)。这个分数比近似匹配的分数更准确、更稳定。它仍然依赖于RelSamplingDistance中场景设置的采样距离。如果对模型进行了边缘支持的基于表面的匹配训练，则该分数再乘以匹配采样的边缘点的数量，然后再乘以从单个视点可能可见的最大边缘点的数量。注意，如果从多个视点提取边缘，这可能导致得分大于1。

4.以下通用参数控制稀疏位姿细化，可以用GenParamName和GenParamValue设置:

• “sparse_pose_refinement”:
  启用或禁用稀疏位姿细化。
  Value list:‘true’，‘false’
  默认值:‘true’

• “score_type”:
  设置返回的分数的类型。几个不同的分数可以计算和返回后的姿态细化。如果同时禁用稀疏和稠密位姿细分，则此参数无效。
  注意，对于稀疏姿态细化后的分数计算，使用了采样的场景点。为了计算密集姿态细化后的分数，使用了所有的场景点(如下图所示)。因此，稀疏姿态细化后的评分值取决于场景的采样距离。
  支持以下分数类型:

• “num_scene_points”:
  计算位于目标表面的采样场景点的加权计数。每个点都根据到找到的物体的距离加权。这个分数比近似匹配的分数更准确、更稳定。它取决于场景在RelSamplingDistance中设置的采样距离。返回的分数将在0和采样场景中的点数之间。

• “num_model_points”:
  计算场景中检测到的采样模型点的数量。一个模型点被定义为“检测”，如果附近有一个场景点。返回的分数将介于0和采样模型中的点数之间。

• “model_point_fraction”:
  在没有边缘支持的情况下，计算表面分数，即物体表面在场景中可见的近似分数。它的计算方法是将“num_model_points”的分数值除以模型点的数量。
  在边缘支撑下，计算表面分数和边缘分数的几何平均值。边缘分数是采样的模型边缘与场景边缘对齐的点的数量，除以模型上潜在可见边缘的最大数量。
  以上是两种情况下的可能得分范围。这是默认的分数类型。
  值列表:model_point_fraction， num_scene_points， num_model_points
  默认值:“model_point_fraction”

• “pose_ref_use_scene_normals”:
  启用或禁用使用场景法线进行姿态细化。如果启用了该参数，并且场景中包含点法线，那么这些法线将用于提高姿态细化的准确性。因此，降低了场景点法线方向与模型法线方向不同的场景点的影响。注意场景必须包含点法线。否则，此参数将被忽略。
  Value list:‘true’，‘false’
  默认值:‘false’

3）密集姿态细化：

1.精确细化的姿态发现在前面的步骤。这一步的工作原理类似于稀疏姿态细化，最小化场景点与最近模型点平面之间的距离。区别在于

• 1.只有前一步中得分最高的“num_matches”姿势才会被修改;
• 2.ObjectModel3D中传递的场景中的所有点都用于细化。
• 3.如果模型是为边缘支持的基于表面的匹配而创建的，那么所有提取的场景边缘点都将被用于细化，而不仅仅是采样的边缘点。

2.从场景中提取所有的点可以提高细化的准确性，但是要比在次采样的场景点上细化的速度慢。默认情况下启用了密集型位姿细分，但可以通过通用参数“dense_pose_refinement”禁用它。
在密集姿态细化之后，重新计算每个匹配的分数。将一个点设置为“on”对象的阈值是通过通用参数“pose_ref_scoring_dist_rel”或“pose_ref_scoring_dist_abs”设置的(参见下面)。
由于数值原因，密集姿态细化的精度限制在模型尺寸的0.1%左右。精度进一步取决于场景点的噪声、场景点的数量和模型的形状。

3.以下通用参数影响密集位姿细化的精度和速度，可以使用GenParamName和GenParamValue设置:

• “dense_pose_refinement”:
  启用或禁用密集姿态细化。
  Value list:‘true’，‘false’
  默认值:‘true’

• “pose_ref_num_steps”:
  密集姿态细化的迭代次数。增加迭代次数会导致以运行时为代价的更精确的布局。然而，一旦达到收敛，即使增加步数，精度也无法再提高。请注意，如果禁用密集姿态细化，则忽略此参数。
  建议值:1、3、5、20
  默认值:5
  声明:‘pose_ref_num_steps’ > 0

• “pose_ref_sub_sampling”:
  设置用于密集姿态细化的场景点的速率。例如，如果该值设置为5，则场景中的每5个点都用于姿态细化。该参数允许在姿态细化的速度和精度之间进行简单的权衡:增加该值会导致使用更少的点，从而导致更快但更不精确的姿态细化。降低该值具有相反的效果。请注意，如果禁用密集姿态细化，则忽略此参数。
  建议值:1、2、5、10
  默认值:2
  声明:‘pose_ref_sub_sampling’ > 0

• “pose_ref_dist_threshold_rel”:
  设置相对于表面模型直径的密集位姿细化距离阈值。只有比这个距离更接近目标的场景点才会被用于优化。更远的场景点被忽略。只能设置参数‘pose_ref_dist_threshold_rel’和‘pose_ref_dist_threshold_abs’中的一个。如果同时设置了这两个参数，则只使用最后一个参数的值。请注意，如果禁用密集姿态细化，则忽略此参数。
  建议值:0.03、0.05、0.1、0.2
  默认值:0.1
  声明:0 < ‘pose_ref_dist_threshold_rel’

• “pose_ref_dist_threshold_abs”:
  将密集姿态细化的距离阈值设置为绝对值。详细描述请参见“pose_ref_dist_threshold_rel”。只能设置参数‘pose_ref_dist_threshold_rel’和‘pose_ref_dist_threshold_abs’中的一个。如果同时设置了这两个参数，则只使用最后一个参数的值。
  声明:0 < ‘pose_ref_dist_threshold_abs’

• “pose_ref_scoring_dist_rel”:
  设置距离阈值，根据表面模型的直径进行评分。详细描述请参见下面的“pose_ref_scoring_dist_abs”。只能设置参数‘pose_ref_scoring_dist_rel’和‘pose_ref_scoring_dist_abs’中的一个。如果同时设置了这两个参数，则只使用最后一个参数的值。请注意，如果禁用密集姿态细化，则忽略此参数。
  建议值:0.2,0.01,0.005,0.0001
  默认值:0.005
  声明:0 < ‘pose_ref_scoring_dist_rel’

• “pose_ref_scoring_dist_abs”:
  设置距离阈值进行评分。只有比这个距离更接近物体的场景点才被认为是“在模型上”。所有其他的场景点都被认为不在模型上。该值应与场景点坐标上的噪声量相对应。请注意，如果禁用密集姿态细化，则忽略此参数。只能设置参数‘pose_ref_scoring_dist_rel’和‘pose_ref_scoring_dist_abs’中的一个。如果同时设置了这两个参数，则只使用最后一个参数的值。

• “score_type”:
  设置返回的分数的类型。几个不同的分数可以计算和返回后的姿态细化。如果同时禁用稀疏和稠密位姿细分，则此参数无效。
  对于所有的分数类型，‘pose_ref_scoring_dist_rel’或‘pose_ref_scoring_dist_abs’控制场景点与模型点的距离，以便将其划分为模型点。
  注意，为了计算稀疏姿态细化后的分数，使用了采样的场景点(见上文)。为了计算密集姿态细化后的分数，使用了所有的场景点。因此，密集姿态细化后的评分值不依赖于场景的采样距离。
  关于不同分数类型的更多细节可以在上面的稀疏姿态细化描述中找到。
  值列表:model_point_fraction， num_scene_points， num_model_points
  默认值:model_point_fraction

• “pose_ref_use_scene_normals”:
  启用或禁用使用场景法线进行姿态细化。如果启用了该参数，并且场景中包含点法线，那么这些法线将用于提高姿态细化的准确性。因此，降低了场景点法线方向与模型法线方向不同的场景点的影响。注意场景必须包含点法线。否则，此参数将被忽略。
  值列表: ‘true’，‘false’
  默认值: ‘false’