descriptron-core 2.6.0__tar.gz → 2.7.0__tar.gz

{descriptron_core-2.6.0 → descriptron_core-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: descriptron-core
-Version: 2.6.0
+Version: 2.7.0
 Summary: Evidence-tiered species descriptions, keys and audits from phenomic matrices
 Project-URL: Homepage, https://github.com/alexrvandam/Descriptron
 Project-URL: Repository, https://github.com/alexrvandam/Descriptron

{descriptron_core-2.6.0 → descriptron_core-2.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "descriptron-core"
-version = "2.6.0"
+version = "2.7.0"
 description = "Evidence-tiered species descriptions, keys and audits from phenomic matrices"
 readme = "README.md"
 requires-python = ">=3.9"

{descriptron_core-2.6.0 → descriptron_core-2.7.0}/src/descriptron_core/tools/biosyslit_rag_retrieval_v2.py

@@ -64,6 +64,48 @@ from biorag_llm_backend import load_prompt_library, make_llm_client  # noqa: E40
 
 V2_VERSION = "2.0"
 
+# ── retrieval log (opt-in): BIORAG_RETRIEVAL_LOG=<file.jsonl> records every literature search and every passage
+# returned (source, DOI, section, score), so a run can show WHERE in the literature the model was primed from.
+# BIORAG_RETRIEVAL_CONTEXT (e.g. the species code) is copied into each record. v1 is not modified: the two
+# functions are wrapped here.
+_RLOG = os.environ.get("BIORAG_RETRIEVAL_LOG")
+if _RLOG:
+    import datetime as _dt
+    import json as _json
+
+    def _rlog_write(rec):
+        rec = {"time": _dt.datetime.now().isoformat(timespec="seconds"),
+               "context": os.environ.get("BIORAG_RETRIEVAL_CONTEXT", ""), **rec}
+        with open(_RLOG, "a") as _f:
+            _f.write(_json.dumps(rec, ensure_ascii=False) + "\n")
+
+    _orig_retrieve = base.TreatmentIndex.retrieve
+
+    def _logged_retrieve(self, query, _orig=_orig_retrieve):
+        res = _orig(self, query)
+        _rlog_write({"kind": "index_retrieve",
+                     "query": {k: getattr(query, k, "") for k in ("taxon_name", "taxon_family", "body_region",
+                                                                    "description_mode", "free_text", "k")},
+                     "index_chunks": len(getattr(self, "chunks", []) or []),
+                     "results": [{"rank": i + 1, "score": round(float(r.score), 4), "chunk_id": r.chunk.chunk_id,
+                                  "source_type": r.chunk.source_type, "source_id": r.chunk.source_id,
+                                  "source_doi": r.chunk.source_doi, "source_title": r.chunk.source_title,
+                                  "section": r.chunk.description_section, "body_region": r.chunk.body_region,
+                                  "match_reasons": list(r.match_reasons or []),
+                                  "text_preview": (r.chunk.text or "")[:240]} for i, r in enumerate(res)]})
+        return res
+    base.TreatmentIndex.retrieve = _logged_retrieve
+
+    _orig_search = base.BioSysLitIngester.search
+
+    def _logged_search(self, query, *a, _orig=_orig_search, **kw):
+        recs = _orig(self, query, *a, **kw)
+        _rlog_write({"kind": "biosyslit_search", "query": query,
+                     "records": [{"id": r.get("id"), "doi": r.get("doi", ""),
+                                  "title": (r.get("metadata", {}) or {}).get("title", "")} for r in (recs or [])]})
+        return recs
+    base.BioSysLitIngester.search = _logged_search
+
 SUBCOMMAND_MODULES = {
     "build-key": "biorag_key_builder_v1",
     "refine-descriptions": "biorag_description_refiner_v1",

descriptron_core-2.7.0/src/descriptron_core/tools/descriptron_check_cross_image_copies_v1.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+"""
+descriptron_check_cross_image_copies_v1.py - find annotations copied onto images they do not belong to
+=======================================================================================================
+
+Before GUI v81, "Load Annotations" drew EVERY annotation of a COCO file on the image on screen and saved
+them under that image. A file that was loaded while another image was showing can therefore carry the
+same outline twice: once under its own image, once under an image it was never drawn on. A copy keeps
+the exact pixel position AND the outline points of the original, so it is found by comparing annotations
+filed under DIFFERENT images: a pair that overlaps almost completely (IoU >= --min_iou, default 0.95) and
+shares most of its outline vertices exactly (>= --min_shared, default 0.9) is a copy. Two people tracing
+similar structures on aligned images can overlap at 0.95 but share only a few percent of their points (1-5%
+on aligned ant heads), so overlap alone is not enough. Where either mask is RLE there are no vertices; such
+a pair is reported on overlap alone and marked "check". Pairs that share 20-90% of their points are listed
+as "partly shared" (an outline copied and then edited, e.g. a second photo of the same specimen).
+
+The program cannot tell which of a pair is the original (both may since have been re-labelled), so it
+reports both and changes nothing. To write a cleaned copy, name what to drop: --drop_ids <annotation ids>
+and/or --drop_image <image file name> (every annotation filed under that image). The input file is
+never modified; the cleaned file is written beside it as <name>_cleaned.json unless --output is given.
+
+  python descriptron_check_cross_image_copies_v1.py --coco annotations.json
+  python descriptron_check_cross_image_copies_v1.py --coco annotations.json --drop_image MJ_31308000000.tif
+
+Writes <name>_cross_image_copies.tsv beside the input (or --report) and prints a summary.
+"""
+import argparse
+import csv
+import json
+import os
+import sys
+from pathlib import Path
+
+import numpy as np
+
+STEP = 4                                   # masks compared at 1/4 resolution
+
+
+def _image_name(im):
+    return os.path.basename(str(im.get("file_name") or im.get("id")))
+
+
+def _mask(seg, shape, step=STEP):
+    """annotation mask at 1/step resolution on a canvas shared by both images (same pixel coordinates)"""
+    import cv2
+    H, W = shape
+    m = np.zeros((H // step + 1, W // step + 1), np.uint8)
+    if isinstance(seg, list):
+        for poly in seg:
+            p = (np.asarray(poly, float).reshape(-1, 2) / step).round().astype(np.int32)
+            if len(p) >= 3:
+                cv2.fillPoly(m, [p], 1)
+    elif isinstance(seg, dict) and "counts" in seg:
+        h, w = seg["size"]
+        counts = seg["counts"]
+        if isinstance(counts, str):
+            from pycocotools import mask as mu
+            full = mu.decode(seg)
+        else:
+            flat = np.zeros(h * w, np.uint8); i = 0; v = 0
+            for r in counts:
+                flat[i:i + r] = v; i += r; v = 1 - v
+            full = flat.reshape((w, h)).T
+        small = full[::step, ::step]
+        m[:small.shape[0], :small.shape[1]] = small[:m.shape[0], :m.shape[1]]
+    return m.astype(bool)
+
+
+def _bbox(a):
+    b = a.get("bbox")
+    if b and len(b) == 4:
+        return [float(x) for x in b]
+    seg = a.get("segmentation")
+    if isinstance(seg, list) and seg:
+        p = np.concatenate([np.asarray(s, float).reshape(-1, 2) for s in seg if len(s) >= 6])
+        return [p[:, 0].min(), p[:, 1].min(), np.ptp(p[:, 0]), np.ptp(p[:, 1])]
+    return None
+
+
+def _verts(a):
+    s = a.get("segmentation")
+    if not isinstance(s, list):
+        return None
+    v = set()
+    for poly in s:
+        q = np.round(np.asarray(poly, float).reshape(-1, 2)).astype(int)
+        v.update(map(tuple, q.tolist()))
+    return v
+
+
+def shared_vertices(a, b):
+    """fraction of the smaller outline's points found exactly in the other; None if either is RLE"""
+    va, vb = _verts(a), _verts(b)
+    if not va or not vb:
+        return None
+    return len(va & vb) / min(len(va), len(vb))
+
+
+def find_copies(d, min_iou=0.95, corner_tol=0.05, min_shared=0.9, partly=0.2):
+    """pairs (a, b, iou) of mask annotations under different images whose masks coincide"""
+    imgs = {im["id"]: im for im in d.get("images", [])}
+    cats = {c["id"]: c["name"] for c in d.get("categories", [])}
+    anns = [a for a in d.get("annotations", []) if a.get("segmentation") and _bbox(a)]
+    out = []
+    cache = {}
+    for i in range(len(anns)):
+        a = anns[i]; ba = _bbox(a)
+        for j in range(i + 1, len(anns)):
+            b = anns[j]
+            if a.get("image_id") == b.get("image_id"):
+                continue
+            bb = _bbox(b)
+            tol = corner_tol * max(ba[2], ba[3], bb[2], bb[3], 1.0)
+            if abs(ba[0] - bb[0]) > tol or abs(ba[1] - bb[1]) > tol:       # copies sit at the same corner
+                continue
+            H = int(max(ba[1] + ba[3], bb[1] + bb[3])) + 2
+            W = int(max(ba[0] + ba[2], bb[0] + bb[2])) + 2
+            for k, x in ((i, a), (j, b)):
+                if (k, H, W) not in cache:
+                    cache[(k, H, W)] = _mask(x["segmentation"], (H, W))
+            ma, mb = cache[(i, H, W)], cache[(j, H, W)]
+            inter = np.logical_and(ma, mb).sum(); union = np.logical_or(ma, mb).sum()
+            iou = inter / union if union else 0.0
+            if iou >= min_iou:
+                sh = shared_vertices(a, b)
+                if sh is None:
+                    verdict = "check (RLE: overlap only)"
+                elif sh >= min_shared:
+                    verdict = "copy"
+                elif sh >= partly:
+                    verdict = "partly shared"
+                else:
+                    continue                                  # similar shapes traced independently
+                out.append({"verdict": verdict, "iou": round(float(iou), 4),
+                            "shared_vertices": "" if sh is None else round(sh, 3),
+                            "annotation_id_1": a.get("id"), "image_1": _image_name(imgs.get(a.get("image_id"), {"id": a.get("image_id")})),
+                            "category_1": cats.get(a.get("category_id"), a.get("category_id")),
+                            "annotation_id_2": b.get("id"), "image_2": _image_name(imgs.get(b.get("image_id"), {"id": b.get("image_id")})),
+                            "category_2": cats.get(b.get("category_id"), b.get("category_id"))})
+    return out
+
+
+def drop(d, ids=(), image=None):
+    """a copy of the COCO dict without the named annotations / every annotation of the named image"""
+    ids = {str(x) for x in ids}
+    gone_imgs = set()
+    if image:
+        want = os.path.splitext(os.path.basename(image))[0].lower()
+        gone_imgs = {im["id"] for im in d.get("images", [])
+                     if os.path.splitext(_image_name(im))[0].lower() == want
+                     or os.path.basename(str(im["id"])).lower() == want}
+        if not gone_imgs:
+            sys.exit(f"--drop_image {image}: no such image in the file")
+    out = dict(d)
+    out["annotations"] = [a for a in d.get("annotations", [])
+                          if str(a.get("id")) not in ids and a.get("image_id") not in gone_imgs]
+    out["images"] = [im for im in d.get("images", []) if im["id"] not in gone_imgs]
+    return out
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--coco", required=True, help="COCO .json or .rlejson")
+    ap.add_argument("--min_iou", type=float, default=0.95)
+    ap.add_argument("--min_shared", type=float, default=0.9, help="share of identical outline points for a copy")
+    ap.add_argument("--report", default=None, help="TSV of the pairs found (default: beside the input)")
+    ap.add_argument("--drop_ids", nargs="*", default=[], help="annotation ids to leave out of the cleaned copy")
+    ap.add_argument("--drop_image", default=None, help="leave out this image and everything filed under it")
+    ap.add_argument("--output", default=None, help="cleaned copy (default: <name>_cleaned<ext> beside the input)")
+    a = ap.parse_args()
+    src = Path(a.coco)
+    d = json.load(open(src))
+    pairs = find_copies(d, a.min_iou, min_shared=a.min_shared)
+    rep = Path(a.report) if a.report else src.with_name(src.stem + "_cross_image_copies.tsv")
+    with open(rep, "w", newline="") as f:
+        cols = ["verdict", "iou", "shared_vertices", "annotation_id_1", "image_1", "category_1", "annotation_id_2", "image_2", "category_2"]
+        w = csv.DictWriter(f, fieldnames=cols, delimiter="\t"); w.writeheader(); w.writerows(pairs)
+    n_img = len(d.get("images", [])); n_ann = len(d.get("annotations", []))
+    n_copy = sum(p["verdict"] == "copy" for p in pairs)
+    print(f"{src.name}: {n_img} images, {n_ann} annotations; {n_copy} cross-image cop"
+          f"{'y' if n_copy == 1 else 'ies'}, {len(pairs) - n_copy} other pair(s) to look at")
+    for p in pairs:
+        sv = "" if p["shared_vertices"] == "" else f", {100 * p['shared_vertices']:.0f}% points shared"
+        print(f"  {p['verdict']:24s} IoU {p['iou']:.3f}{sv}  {p['image_1']} [{p['category_1']}, id {p['annotation_id_1']}]"
+              f"  ==  {p['image_2']} [{p['category_2']}, id {p['annotation_id_2']}]")
+    print(f"report -> {rep}")
+    if a.drop_ids or a.drop_image:
+        out = Path(a.output) if a.output else src.with_name(src.stem + "_cleaned" + src.suffix)
+        if out.resolve() == src.resolve():
+            sys.exit("--output must not be the input file")
+        cleaned = drop(d, a.drop_ids, a.drop_image)
+        tmp = out.with_suffix(out.suffix + ".tmp")
+        json.dump(cleaned, open(tmp, "w")); os.replace(tmp, out)
+        print(f"cleaned copy: {len(d['annotations'])} -> {len(cleaned['annotations'])} annotations -> {out}")
+    elif n_copy:
+        print("nothing changed; to write a cleaned copy add --drop_ids <id ...> or --drop_image <file name>")
+
+
+if __name__ == "__main__":
+    main()

descriptron_core-2.7.0/src/descriptron_core/tools/descriptron_labelled_plates_v1.py

@@ -0,0 +1,290 @@
+#!/usr/bin/env python3
+"""
+descriptron_labelled_plates_v1.py - species plates in the specimens' own colours, with every structure named
+=============================================================================================================
+
+The companion to generate_species_plates.py (which is left as it is): the same specimens, but with no mask
+overlay. Each annotated structure gets a thin leader line from the edge of the structure to its name, set in a
+column beside the image, the way a hand-labelled plate in a taxonomic paper looks.
+
+Where the line ends: it starts from the deepest point of the part of the structure that no smaller structure
+covers (for a structure with others inside it, such as the whole wing or whole head, from the deepest point of
+its whole outline, since its uncovered remainder may be an unannotated part such as the eyes), heads straight
+for the label, and the dot is put where it leaves the structure's outline. A wing cell's
+dot is therefore on that cell's own edge, facing its label, and the whole wing's dot is on the wing margin.
+With --anchor centre the line runs on to that deepest point instead, so the dot sits in the middle of the
+structure (the deepest point, not the centroid, which can fall outside a curved or U-shaped structure). A
+structure with smaller ones inside it (the whole wing around its cells, the whole head around the vertex) has
+no middle of its own, so its dot goes to the centroid of its whole outline (or its deepest point, if the
+centroid falls outside it).
+Labels sit on the side of the image the structure is on, at the height of the structure, pushed apart only as
+far as needed to stop them overlapping.
+
+For every species (from --group_labels) writes into --plates_dir/<species>/:
+  <image>_labelled.png              one labelled image per specimen photograph
+  <species>_labelled_plate.png/pdf  those images together (up to --max_images_per_species)
+
+  python descriptron_labelled_plates_v1.py --coco_json <coco.json> --image_dir <images> \\
+      --group_labels <group_labels.csv> --plates_dir <out> [--species sp1 sp4] [--outline] [--anchor centre]
+"""
+import argparse
+import os
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+import cv2
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.patheffects as pe
+import matplotlib.pyplot as plt
+import numpy as np
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import generate_species_plates as gsp          # noqa: E402  (COCO, mask and group-label readers)
+
+INK = "#1d2327"
+HALO = [pe.withStroke(linewidth=1.8, foreground="white")]
+
+
+def pretty(name):
+    return name.replace("_", " ")
+
+
+def structures_of(anns, id_to_cat, h, w, scale):
+    """(name, mask) at display scale for every annotation with a segmentation (keypoint-only ones skipped)"""
+    hs, ws = max(1, round(h * scale)), max(1, round(w * scale))
+    out = []
+    for a in anns:
+        seg = a.get("segmentation")
+        if not seg:
+            continue
+        name = id_to_cat.get(a["category_id"], "?")
+        if isinstance(seg, list):
+            m = np.zeros((hs, ws), np.uint8)
+            for poly in seg:
+                pts = (np.asarray(poly, float).reshape(-1, 2) * scale).round().astype(np.int32)
+                if len(pts) >= 3:
+                    cv2.fillPoly(m, [pts], 1)
+            m = m.astype(bool)
+        else:
+            m = cv2.resize(gsp.seg_to_mask(seg, h, w).astype(np.uint8), (ws, hs),
+                           interpolation=cv2.INTER_NEAREST).astype(bool)
+        if m.sum() >= 4:
+            out.append((name, m))
+    return out
+
+
+def own_regions(structs):
+    """each structure minus every SMALLER structure on top of it (falls back to the whole mask if nothing is
+    left), so a container such as the whole wing points at its margin, not at a cell inside it"""
+    areas = [m.sum() for _, m in structs]
+    own = []
+    for i, (n, m) in enumerate(structs):
+        cover = np.zeros_like(m)
+        for j, (_, o) in enumerate(structs):
+            if j != i and areas[j] < areas[i]:
+                cover |= o
+        r = m & ~cover
+        own.append(r if r.sum() > 0.03 * m.sum() else m)
+    return own
+
+
+def is_container(structs, i, inside=0.8):
+    """True when some smaller structure lies (mostly) inside structure i, e.g. the whole wing around its cells"""
+    m = structs[i][1]
+    a = m.sum()
+    return any(o.sum() < a and (o & m).sum() >= inside * o.sum() for j, (_, o) in enumerate(structs) if j != i)
+
+
+def centroid(mask):
+    """centroid of the whole outline; if it falls outside the structure (a curved one), its deepest point"""
+    ys, xs = np.nonzero(mask)
+    x, y = int(round(xs.mean())), int(round(ys.mean()))
+    if mask[y, x]:
+        return x, y
+    dt = cv2.distanceTransform(np.pad(mask, 1).astype(np.uint8), cv2.DIST_L2, 3)[1:-1, 1:-1]
+    y, x = np.unravel_index(np.argmax(dt), dt.shape)
+    return x, y
+
+
+def exit_point(mask, start, toward):
+    """walk from `start` (inside the structure) straight toward the label; the last pixel still inside the
+    structure is where the leader line meets its outline, on the side facing the label"""
+    H, W = mask.shape
+    x0, y0 = start
+    dx, dy = toward[0] - x0, toward[1] - y0
+    n = int(np.hypot(dx, dy)) + 1
+    last = (x0, y0)
+    for t in np.linspace(0, 1, n):
+        x, y = int(round(x0 + t * dx)), int(round(y0 + t * dy))
+        if not (0 <= x < W and 0 <= y < H) or not mask[y, x]:
+            break
+        last = (x, y)
+    return last
+
+
+def spread(targets, lo, hi, gap):
+    """label heights as close to their targets as possible, at least `gap` apart, inside [lo, hi]"""
+    if not targets:
+        return []
+    order = np.argsort(targets)
+    n = len(targets)
+    gap = min(gap, (hi - lo) / max(1, n - 1)) if n > 1 else gap
+    ys = np.clip(np.asarray(targets, float)[order], lo, hi)
+    for _ in range(200):                              # alternate push-down / push-up until stable
+        moved = False
+        for k in range(1, n):
+            if ys[k] - ys[k - 1] < gap - 1e-9:
+                ys[k] = ys[k - 1] + gap; moved = True
+        if ys[-1] > hi:
+            ys[-1] = hi
+            for k in range(n - 2, -1, -1):
+                if ys[k + 1] - ys[k] < gap - 1e-9:
+                    ys[k] = ys[k + 1] - gap; moved = True
+        if ys[0] < lo:
+            ys += lo - ys[0]; moved = True
+        if not moved:
+            break
+    out = np.empty(n)
+    out[order] = ys
+    return list(out)
+
+
+def draw_labelled(img_rgb, structs, out_path, title=None, img_width_in=5.0, fontsize=9, outline=False, dpi=200,
+                  anchor="edge"):
+    H, W = img_rgb.shape[:2]
+    own = own_regions(structs)
+    poles = []
+    for i, r in enumerate(own):
+        if is_container(structs, i):     # its uncovered remainder can be an unannotated part (a head's eyes),
+            r = structs[i][1]            # so start from the middle of the whole outline instead
+        dt = cv2.distanceTransform(np.pad(r, 1).astype(np.uint8), cv2.DIST_L2, 3)[1:-1, 1:-1]
+        y, x = np.unravel_index(np.argmax(dt), dt.shape)
+        poles.append((x, y))
+    names = [pretty(n) for n, _ in structs]
+    left = [i for i in range(len(structs)) if poles[i][0] < W / 2]
+    right = [i for i in range(len(structs)) if i not in left]
+    per_in = W / img_width_in                                  # data units per inch
+    char_in = fontsize * 0.62 / 72
+    margin_l = (max((len(names[i]) for i in left), default=0) * char_in + 0.45) * per_in
+    margin_r = (max((len(names[i]) for i in right), default=0) * char_in + 0.45) * per_in
+    gap = fontsize * 1.45 / 72 * per_in
+    fig_w = img_width_in + (margin_l + margin_r) / per_in
+    fig_h = H / per_in + (0.35 if title else 0.1)
+    fig, ax = plt.subplots(figsize=(fig_w, fig_h))
+    ax.imshow(img_rgb)
+    if outline:
+        for (_, m) in structs:
+            cs, _ = cv2.findContours(m.astype(np.uint8), cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+            for c in cs:
+                c = c[:, 0, :]
+                ax.plot(np.r_[c[:, 0], c[0, 0]], np.r_[c[:, 1], c[0, 1]], color="white", lw=0.5, alpha=0.8)
+    for side, idx in (("L", left), ("R", right)):
+        ys = spread([poles[i][1] for i in idx], 0.02 * H, 0.98 * H, gap)
+        tx = -0.25 * per_in if side == "L" else W + 0.25 * per_in
+        for i, ty in zip(idx, ys):
+            if anchor == "centre":
+                ax_, ay = centroid(structs[i][1]) if is_container(structs, i) else poles[i]
+            else:
+                ax_, ay = exit_point(structs[i][1], poles[i], (tx, ty))
+            ax.plot([tx, ax_], [ty, ay], color=INK, lw=0.6, path_effects=HALO, solid_capstyle="round", zorder=3)
+            ax.plot(ax_, ay, "o", ms=2.6, mfc=INK, mec="white", mew=0.6, zorder=4)
+            ax.text(tx + (-0.06 if side == "L" else 0.06) * per_in, ty, names[i], fontsize=fontsize, color=INK,
+                    ha="right" if side == "L" else "left", va="center", zorder=5)
+    ax.set_xlim(-margin_l, W + margin_r); ax.set_ylim(H, 0); ax.axis("off")
+    if title:
+        ax.set_title(title, fontsize=fontsize + 1, color=INK, pad=4)
+    fig.subplots_adjust(0, 0, 1, (fig_h - 0.35) / fig_h if title else 1)
+    fig.savefig(out_path, dpi=dpi, facecolor="white")
+    plt.close(fig)
+
+
+def make_plate(species, files, out_base, cols=2, dpi=200):
+    ims = [plt.imread(str(f)) for f in files]
+    rows = int(np.ceil(len(ims) / cols))
+    cell_w = 6.5
+    heights = [max(im.shape[0] / im.shape[1] * cell_w for im in ims[r * cols:(r + 1) * cols]) for r in range(rows)]
+    fig, axs = plt.subplots(rows, cols, figsize=(cell_w * cols, sum(heights) + 0.6),
+                            gridspec_kw={"height_ratios": heights}, squeeze=False)
+    for k, ax in enumerate(axs.ravel()):
+        ax.axis("off")
+        if k < len(ims):
+            ax.imshow(ims[k])
+            ax.text(0.0, 1.0, "abcdefghijklmnop"[k], transform=ax.transAxes, fontsize=13, weight="bold",
+                    va="bottom", ha="left", color=INK)
+    fig.suptitle(species, fontsize=15, style="italic" if not species[:2].lower() in ("sp", "cf") else "normal",
+                 x=0.01, ha="left", color=INK)
+    fig.tight_layout(rect=(0, 0, 1, 0.98))
+    for ext in ("png", "pdf"):
+        fig.savefig(f"{out_base}.{ext}", dpi=dpi, facecolor="white")
+    plt.close(fig)
+
+
+def round_robin(imgs):
+    """one image of each body part in turn (forewing, rostrum, metaleg, ...), so a plate capped at N images
+    shows every body part instead of the first N files"""
+    groups = defaultdict(list)
+    for im in imgs:
+        groups[gsp.extract_body_part(im["file_name"])].append(im)
+    order = sorted(groups)
+    out = []
+    while any(groups[g] for g in order):
+        for g in order:
+            if groups[g]:
+                out.append(groups[g].pop(0))
+    return out
+
+
+def main():
+    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--coco_json", required=True)
+    p.add_argument("--image_dir", required=True)
+    p.add_argument("--group_labels", required=True)
+    p.add_argument("--plates_dir", required=True)
+    p.add_argument("--species", nargs="*", default=None, help="only these species (default: all)")
+    p.add_argument("--max_images_per_species", type=int, default=8)
+    p.add_argument("--display_px", type=int, default=1400, help="longest image side as drawn")
+    p.add_argument("--outline", action="store_true", help="also draw each structure's outline, thin and white")
+    p.add_argument("--anchor", default="edge", choices=["edge", "centre", "center"],
+                   help="where each leader line ends: on the structure's outline, facing its label (default), or "
+                        "in the middle of the structure (its deepest point)")
+    p.add_argument("--dpi", type=int, default=200)
+    a = p.parse_args()
+
+    coco, id_to_img, id_to_cat, img_anns = gsp.load_coco(a.coco_json)
+    fn_to_species = gsp.load_group_labels(a.group_labels)
+    by_species = defaultdict(list)
+    for img in coco["images"]:
+        sp = fn_to_species.get(img["file_name"]) or fn_to_species.get(gsp._normalize_fn(img["file_name"]))
+        if sp and (not a.species or sp in a.species):
+            by_species[sp].append(img)
+    out = Path(a.plates_dir); out.mkdir(parents=True, exist_ok=True)
+    print(f"Labelled plates for {len(by_species)} species -> {out}")
+    for sp in sorted(by_species):
+        sd = out / sp; sd.mkdir(exist_ok=True)
+        done = []
+        for img in round_robin(by_species[sp])[:a.max_images_per_species]:
+            path = os.path.join(a.image_dir, img["file_name"])
+            bgr = cv2.imread(path) if os.path.exists(path) else None
+            if bgr is None:
+                continue
+            h, w = bgr.shape[:2]
+            s = min(1.0, a.display_px / max(h, w))
+            rgb = cv2.cvtColor(cv2.resize(bgr, (round(w * s), round(h * s)), interpolation=cv2.INTER_AREA),
+                               cv2.COLOR_BGR2RGB)
+            structs = structures_of(img_anns.get(img["id"], []), id_to_cat, h, w, s)
+            if not structs:
+                continue
+            stem = Path(img["file_name"]).stem
+            f = sd / f"{stem}_labelled.png"
+            draw_labelled(rgb, structs, f, title=gsp.extract_body_part(img["file_name"]), outline=a.outline,
+                          dpi=a.dpi, anchor="centre" if a.anchor in ("centre", "center") else "edge")
+            done.append(f)
+        if done:
+            make_plate(sp, done, sd / f"{sp}_labelled_plate", dpi=a.dpi)
+            print(f"  {sp}: {len(done)} images")
+
+
+if __name__ == "__main__":
+    main()