annotate3d op• Data kinds: image2d → image2d
• Call: import fullseye as fs; fs.ledger.annotate3d_scale_bar(img, origin, direction, length, pose, K, unit='', depth=None, color='neutral', width=2.0, tick=8.0, font_size=12, label_fmt='{:g}', box_alpha=0.55, text_color=None, occlusion_tol=0.01, scheme='okabe_ito', font_path=None) (to call the implementation directly, import annotate3d; annotate3d.annotate3d_scale_bar(img, origin, direction, length, pose, K, unit='', depth=None, color='neutral', width=2.0, tick=8.0, font_size=12, label_fmt='{:g}', box_alpha=0.55, text_color=None, occlusion_tol=0.01, scheme='okabe_ito', font_path=None); from the registry, ops3d.get("annotate3d_scale_bar"))
Returns an image (image2d): a bar of length in mesh units, laid on the surface and projected.
The bar is a 3-D line segment going length from origin along direction (normalised), and its pixel length after projection shrinks with its tilt relative to the line of sight (showing perspective and foreshortening honestly). Parallel to the image plane, the pixel length is f * length / z -- the tests check this.
ValueError
direction is zero, length is non-positive, an endpoint is behind the camera / outside the image.
Procedure: build p1 = origin + direction / |direction| * length and project origin and p1 (same convention as annotate3d_project). Draw the line joining the two end pixels and, at both ends, perpendicular ticks of length tick [px] (_bar_with_ticks), and from the midpoint of the line, at a position tick/2 + 4 px away toward the top of the screen (the side where row is smaller), place a text box with label_fmt.format(length) + " " + unit.
Arguments:
• origin (3,), direction (3,) (only the direction is used; its length is ignored, zero is rejected), length: length in mesh units (> 0, at least 1e-300).
• unit: a string (if empty, only the number). label_fmt: a str.format format (default "{:g}").
• width [px] >= 0.5, tick [px] >= 0 (0 means no ticks), font_size / box_alpha / text_color / font_path: appearance of the text box.
• depth: forward-distance image. If both ends are hidden, the line is drawn dashed.
• color: default "neutral" (a role name). occlusion_tol: [0, 1).
Return value: a new drawn image (float64 [0, 1]).
Error conditions: the norm of direction is under 1e-12 / length <= 0 / either endpoint has z <= 1e-9 / either endpoint is outside the image (this op requires in_image at both ends -- unlike the arrow, out-of-frame is rejected) / invalid pose, K or depth / the text box does not fit.
Note: the length in pixels is foreshortened by the tilt relative to the line of sight (parallel to the image plane it is f * length / z px). Placed along the depth direction it looks short, but that is the honest projection. To show the measured value between 2 points, use annotate3d_measure.
• Sample-data catalog (download URLs / licences) — 2-D uses skimage.data (BSD/public domain) plus synthetic images; 3-D lists download URLs for real data sources (Stanford, PDS, …).
• Operator provenance and references — the sources of the research/methods this op family came from.
• annotate3d_figure — py -3.11 examples_3d/annotate3d_figure.py
image2d as input)fuse_to_voxel · fit_poly_surface · eval_poly_surface · surface_form_error · background_flatten · polar_unwrap · fit_zernike · matcap_shade
annotate3d)annotate3d_project · annotate3d_arrow · annotate3d_label · annotate3d_axes · annotate3d_bbox · annotate3d_measure
*Provenance: annotate3d.py — 3D operator registry. This per-op note is generated by tools/opdocs.py md (do not hand-edit).*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.