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.