annotate3d op• 資料種類:points → table
• 呼叫: import fullseye as fs; fs.ledger.annotate3d_project(points, pose, K, depth=None, shape=None, occlusion_tol=0.01)(要直接呼叫實作,import annotate3d; annotate3d.annotate3d_project(points, pose, K, depth=None, shape=None, occlusion_tol=0.01);從台帳取用則 ops3d.get("annotate3d_project"))
回傳表(dict):3-D 點的像素座標、前向距離,以及在畫面內/被遮蔽的判定(project_anchors)。
不伴隨繪製的「僅投影」op。把 annotate3d 的全部繪製 op 在內部使用的判定原樣作為表格回傳，用於自己的繪圖、數值驗證、「這個點是否可見」的分支。
投影（閉合式，與 render3d 相同的慣例）： X_c = R X + t（pose 是 4x4 的 object→camera，或 (R, t) 的 2-tuple）。相機朝 local -Z 看，因此前方距離為 z = -X_c[2]。像素為 u = fx X_c[0]/z + skew X_c[1]/z + cx、v = cy - fy X_c[1]/z（K 是 3x3，也使用 K[0,1] 的 skew。像素中心為整數座標，u = 行，v = 列）。
參數：
• points： (N, 3) 或 (3,)（object 座標，有限）。
• depth： (H, W) 的前方距離影像（render3d.render_mesh 的 depth，背景為 +inf）。傳入時 shape 從它取得，並判定遮擋。
• shape： (H, W)。沒有 depth 時用於影像內判定。
• occlusion_tol： [0, 1)。若像素的深度 d 滿足 d < z * (1 - tol) 則判為被遮擋（z-buffer 離散化的容許誤差）。
回傳值（dict，全部長度為 N）：
• uv (N, 2) float — (u, v) 像素座標。後方的點為 NaN。
• depth (N,) — 前方距離 z（後方為負）。
• in_front — z > 1e-9。
• in_image — 0 <= u <= W-1 且 0 <= v <= H-1（僅前方的點）。若 shape 與 depth 都沒有則全為 True（未判定）。
• hidden — 僅在有 depth 時判定（像素以最近鄰取整）。沒有則全為 False。
• visible = in_front & in_image & ~hidden。
驗證(ValueError)： pose 既不是 4x4 也不是 (R, t)、非有限、旋轉部分的行列式接近 0 / K 不是 3x3、非有限、fx 或 fy 為 0 / points 的形狀不正確、非有限 / depth 不是 2-D、與 shape 不一致、含 NaN / occlusion_tol 在 [0, 1) 之外。後方的點在這裡不報錯 （以 in_front=False 回傳。繪製 op 會在那時報 ValueError）。
注意： camera.project_points 是朝 +Z 看的另一種慣例（OpenCV 風格），因此若傳入其位姿，所有點都會被當作在後方。請把傳給 render3d.render_mesh 的 pose / intrinsics 原樣傳入。
• 範例資料目錄(下載 URL / 授權) —— 2-D 用 skimage.data(BSD/公有領域)加合成圖,3-D 給出真實資料源(Stanford/PDS 等)的下載 URL。
• 運算子來歷與參考文獻 —— 該運算子族所依據的研究/方法出處。
• annotate3d_figure — py -3.11 examples_3d/annotate3d_figure.py
table 作為輸入)fuse_to_voxel · mesh_select_lod
annotate3d)annotate3d_arrow · annotate3d_label · annotate3d_scale_bar · annotate3d_axes · annotate3d_bbox · annotate3d_measure
*Provenance: annotate3d.py — 3D 運算子登記表。本條目由 tools/opdocs.py md 自動產生(請勿手動編輯)。*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.