distance_segment_segment — 3D geometry op

• 資料種類:primitive → measurement

• 呼叫: import fullseye as fs; fs.ledger.distance_segment_segment(p0, p1, q0, q1)(要直接呼叫實作,import match3d; match3d.distance_segment_segment(p0, p1, q0, q1);從台帳取用則 ops3d.get("distance_segment_segment"))

• 經台帳呼叫的回傳值: fullseye.ledger.distance_segment_segment(...) 只回傳宣告的 out 型別 measurement 的值(底層函式還會回傳輔助資訊)。需要被捨棄的部分時,請用 fullseye.ledger.distance_segment_segment.raw(...),或直接呼叫 match3d.distance_segment_segment。

用法

有限線段之間的最短距離及其最近點對。→ (distance, cp, cq)。

distance_line_line 是無限直線之間的距離,因此對分離的 2 條線段也可能回傳 0(實測: 對 (0,0,0)-(1,0,0) 與 (5,0,0)-(6,0,0) 為 0.0,真值為 4.0)。手腳、機器人連桿、管線、工具都是有限的,因此在安全距離或干涉判定中使用無限直線版會低估危險(在 poc_safety_clearance 的實測中, 對同樣 2 條線段低估了 87.6 %)。

Args:

p0, p1: 線段 1 的端點 (3,)。若 p0 == p1 則視為點。

q0, q1: 線段 2 的端點 (3,)。

Returns:

(distance, cp, cq): 最短距離 float,以及線段 1 側、線段 2 側的最近點

(3,)。distance == 0 表示 2 條線段相交(或接觸)。

★經由台帳(fullseye.ledger.distance_segment_segment)只回傳宣告的 out 型別

distance。也需要最近點時請用

fullseye.ledger.distance_segment_segment.raw(...)。

Raises:

ValueError: 端點無法轉換為 (3,),或非有限時。

平行、退化(塌縮為點的線段)的情況也透過分支正確處理(Ericson, *Real-Time Collision Detection*, §5.1.9 的 clamped closest-point 法)。膠囊體(芯線 + 半徑) 之間的距離為 distance - r1 - r2,干涉即其為負。

Reference (public): C. Ericson, *Real-Time Collision Detection*, Morgan Kaufmann 2005, §5.1.9 "Closest Points of Two Line Segments".

參考(範例資料、文獻)

• 範例資料目錄(下載 URL / 授權) —— 2-D 用 skimage.data(BSD/公有領域)加合成圖,3-D 給出真實資料源(Stanford/PDS 等)的下載 URL。

• 運算子來歷與參考文獻 —— 該運算子族所依據的研究/方法出處。

可執行的範例(實際呼叫該運算子並已驗證的樣例)

• geometry_metrology — py -3.11 examples_3d/geometry_metrology.py

型別可銜接的下一個運算子(可接受 measurement 作為輸入)

vol_gaussian_psf · fuse_to_voxel · fresnel_reflectance · snell_angle

同類別(geometry)

line_from_2points · plane_from_3points · angle_3points · angle_between_lines · angle_between_planes · angle_line_plane · distance_point_plane · distance_point_line

*Provenance: match3d.py — 3D 運算子登記表。本條目由 tools/opdocs.py md 自動產生(請勿手動編輯)。*

© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.