Halcon算子學習：find_surface_model

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
  場景中表面模型的三維姿態。
• 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姿勢 。它描述了場景座標系中曲面模型的位姿。 位姿是指相對於傳遞給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）近似匹配:搜索場景中表面模型實例的近似姿態
首先，從ObjectModel3D中傳遞的場景中均勻採樣點。採樣距離由參數RelSamplingDistance控制，並與表面模型的直徑有關。減小RelSamplingDistance會產生更多的採樣點，進而產生更穩定但更慢的匹配。增加RelSamplingDistance會減少採樣場景點的數量，從而導致不穩定但更快的匹配。要查看RelSamplingDistance的不同值，請參考操作符create_surface_model。操作符get_surface_matching_result可用於檢索採樣的場景點以進行視覺檢查。爲了進行魯棒匹配，建議每個對象實例至少採樣50-100個場景點。

從採樣的場景點中選擇一組關鍵點。所選關鍵點的數量由參數KeyPointFraction控制。例如，如果將值設置爲0.1，則使用10%的採樣場景點作爲關鍵點。對於穩定的結果，重要的是對象的每個實例都由幾個關鍵點覆蓋。增加KeyPointFraction意味着從場景中選擇更多的關鍵點，這會導致一個更慢但更穩定的匹配。減少關鍵點分數會產生相反的效果，導致更快但更不穩定的匹配。操作符get_surface_matching_result可用於檢索選定的關鍵點，以便進行可視化檢查。

對於每個選定的關鍵點，在關鍵點位於物體表面的假設下，計算出表面模型的最優姿態。這是通過將關鍵點與所有其他採樣的場景點配對，並在表面模型中找到距離和相對方向相似的點對來實現的。相似度由create_surface_model中的參數’feat_step_size_rel’和’feat_angle_resolution’定義。採樣場景中點的最大個數位於目標上的姿態被認爲是該關鍵點的最佳姿態。在目標上採樣的場景點的數量被認爲是姿態的得分。
如果對模型進行邊緣支持的基於表面的匹配訓練，則從3D場景中提取邊緣(類似於操作符edges_object_model_3d)並採樣。除了採樣的三維曲面外，參考點還與所有采樣的邊緣點配對，在曲面模型上找到相似的點-邊組合。然後將匹配採樣的邊緣點的數量與匹配採樣的場景點的數量相乘，重新計算得分，並提取如上所述的最佳姿態。

從所有關鍵點中選出得分最高的姿勢作爲近似姿勢。返回姿態的最大數量由通用參數「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」:
  該參數控制採樣場景的正常計算。在默認模式「快速」下，法線是基於一個小的點鄰域來計算的。在模式「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）稀疏位姿細化:
在第二步中，進一步細化前一步中得到的近似姿態。這增加了姿勢的準確性和分數值的重要性。
稀疏位姿細化使用了從近似匹配中採樣的場景點。通過優化姿態，使得采樣的場景點到最近模型點平面的距離最小。每個模型點的平面被定義爲垂直於其法線的平面。

此外，如果對模型進行邊緣支持的基於表面的匹配訓練，則對姿態進行優化，使場景中採樣的邊緣點與表面模型的邊緣對齊。

默認情況下啓用了稀疏姿態細化。可以通過將通用參數‘sparse_pose_細分’設置爲‘false’來禁用它。由於每個關鍵點產生一個位姿候選，因此需要優化的位姿候選的總數與關鍵點的數量成正比。對於有很多雜亂的大場景，即，場景中不屬於感興趣對象的部分，可以更快地禁用稀疏位姿細化。

通過計算具有相對應場景點的模型點的數量，再除以模型上的總點數量，對每個姿態的得分進行稀疏姿態細化後重新計算。這將得到一個介於0和1之間的值，該值大約是場景中可見的模型表面的分數(參見下面)。這個分數比近似匹配的分數更準確、更穩定。它仍然依賴於RelSamplingDistance中場景設置的採樣距離。如果對模型進行了邊緣支持的基於表面的匹配訓練，則該分數再乘以匹配採樣的邊緣點的數量，然後再乘以從單個視點可能可見的最大邊緣點的數量。注意，如果從多個視點提取邊緣，這可能導致得分大於1。

以下通用參數控制稀疏位姿細化，可以用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）密集姿態細化:精確細化的姿態發現在前面的步驟。這一步的工作原理類似於稀疏姿態細化，最小化場景點與最近模型點平面之間的距離。區別在於

• 只有前一步中得分最高的「num_matches」姿勢纔會被修改;
• ObjectModel3D中傳遞的場景中的所有點都用於細化。
• 如果模型是爲邊緣支持的基於表面的匹配而創建的，那麼所有提取的場景邊緣點都將被用於細化，而不僅僅是採樣的邊緣點。

從場景中提取所有的點可以提高細化的準確性，但是要比在次採樣的場景點上細化的速度慢。默認情況下啓用了密集型位姿細分，但可以通過通用參數「dense_pose_細分」禁用它。
在密集姿態細化之後，重新計算每個匹配的分數。將一個點設置爲「on」對象的閾值是通過通用參數「pose_ref_scoring_dist_rel」或「pose_ref_scoring_dist_abs」設置的(參見下面)。
由於數值原因，密集姿態細化的精度限制在模型尺寸的0.1%左右。精度進一步取決於場景點的噪聲、場景點的數量和模型的形狀。

以下通用參數影響稠密位姿細化的精度和速度，可以使用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」: 啓用或禁用使用場景法線進行姿態細化。如果啓用了該參數，並且場景中包含點法線，那麼這些法線將用於提高姿態細化的準確性。因此，降低了場景點法線方向與模型法線方向不同的場景點的影響。注意場景必須包含點法線。否則，此參數將被忽略。 Value list:‘true’，‘false’ 默認值:‘false’