overlay op• Data kinds: image2d × mask → image2d
• Call: import fullseye as fs; fs.ledger.annotate_invert(img, mask, draw='fill', width=1.5, mode='complement', alpha=1.0, bits=128, min_contrast=1.5, on_invisible='warn') (to call the implementation directly, import annotate; annotate.annotate_invert(img, mask, draw='fill', width=1.5, mode='complement', alpha=1.0, bits=128, min_contrast=1.5, on_invisible='warn'); from the registry, opsannotate.get("annotate_invert"))
Fills / outlines a region in inverted color.
The classic trick for when "you do not know whether the ground is light or dark, so you want to draw in a colour visible on either". It spares you choosing a fill colour, but in exchange it vanishes in mid-tones, so the measurement of annotate_invert_visibility is always run internally.
★If the ground is monochrome (grey), first consider a saturated colour. Grey has no saturation, so a saturated colour is distinguishable from every level by hue -- more reliable than inverted colour, and moreover you can tell at a glance "this is an overlaid line" (pass a role colour to annotate_outline / overlay_mask). Inverted colour comes into its own when the ground is in colour and any colour you pick could clash. Note that what annotate_invert_visibility measures is the WCAG luminance ratio, so it cannot evaluate looks like "same luminance but different hue" -- if you draw with colour, do not rely on this op's numbers.
mask : (H,W)
Region. Boolean or weights in [0,1]. A shape different from the image is an exception.
draw : {"fill", "margin"}
Same word as HALCON's set_draw. "fill" inverts including the interior, "margin"
inverts only the contour. The contour is a band width pixels thick (rounded to an integer)
that extends half inward and half outward from the region.
width : float
Band thickness (pixels) when draw="margin".
mode : str
INVERT_MODES. "complement" keeps the ground's pattern, "xor"
keeps the pattern while guaranteeing it does not vanish, and "contrast" falls back to black and white and
guarantees visibility.
bits : int
Bit mask for mode="xor" (1..255). The default 0x80 inverts only the most significant bit
-- it always jumps 128 levels, so it never vanishes. 0xFF is
the same as complement (cliff and all), and a mask of only low bits like 0x0F
is invisible at every level (measured: ratio below 1.5 at all 256 levels).
alpha : float
Strength of the inversion. 1.0 inverts fully, 0.5 is midway between ground and inverted colour
(mode="complement" at 0.5 always yields a mid-tone -- halving the inverted colour
naturally makes it vanish, and the warning catches that).
min_contrast, on_invisible :
What to do when it turns out invisible. "warn" (default) / "raise" (fail-closed)
/ "ignore".
(H,W[,C]) float64
A copy with the inversion applied. The input is not modified.
ValueError
shape mismatch / out of value range / unknown draw mode on_invisible /
invisible with on_invisible="raise".
>>> import numpy as np, annotate
>>> img = np.zeros((16, 16)); img[4:12, 4:12] = 1.0
>>> m = np.zeros((16, 16), bool); m[6:10, 6:10] = True
>>> out = annotate.annotate_invert(img, m)
>>> float(out[7, 7]), float(out[1, 1])
(0.0, 0.0)
>>> ring = annotate.annotate_invert(img, m, draw="margin", width=1)
>>> float(ring[7, 7]) # interior is untouched
1.0
• figure_annotation family guide
• dataset_conventions — Training-dataset conventions — COCO / YOLO / VOC and pitfalls in visual inspection
• 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.
• The canonical algorithm (author, year) and its uses are named in the family usage guide above.
• annotate_paper_tour — py -3.11 examples/annotate_paper_tour.py
image2d as input)text_box · arrow · leader_line · label_points · crosshair · legend_box · color_bar · scale_bar
overlay)overlay_mask · overlay_labels · annotate_invert_visibility · annotate_invert_path
*Provenance: annotate.py — ANNOTATE 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.