Source code for rigconductor.labels.rules

# ╔══════════════════════════════════════════════════════════════════╗
# ║  Rig Conductor — labels.rules                                    ║
# ║  « is this labelled frame good enough to train on? »             ║
# ╠══════════════════════════════════════════════════════════════════╣
# ║  Pure numpy checks on one frame; the SLEAP-side worker feeds it. ║
# ╚══════════════════════════════════════════════════════════════════╝
"""Checks for labelled frames coming back from a labeller.

A frame is *rejected* when training on it would teach the model something
wrong (half-corrected, wrong fly count, no thorax, points off the image,
duplicates). It gets a *warning* when it breaks a labelling convention that a
person should look at (the decapitated female's hidden head points).
"""

from __future__ import annotations

from dataclasses import dataclass, field

import numpy as np

from rigconductor.constants import LABEL_ANCHOR, LABEL_FEMALE_HIDDEN

DUPLICATE_PX = 2.0  # every shared point this close = the same fly labelled twice


[docs] @dataclass class Inst: """One instance: ``xy`` (n_nodes, 2) with NaN where not visible.""" xy: np.ndarray user: bool = True
[docs] @dataclass class Verdict: status: str # accepted | rejected | unlabelled reasons: list[str] = field(default_factory=list) warnings: list[str] = field(default_factory=list)
[docs] def same_fly(a: np.ndarray, b: np.ndarray, tol: float = DUPLICATE_PX) -> bool: """True when two instances are copies: every point visible in both coincides. Flies that overlap (courtship, mounting, copulation) share at most some points, so they are not flagged; at least two shared points are needed. """ both = ~np.isnan(a).any(axis=1) & ~np.isnan(b).any(axis=1) if both.sum() < 2: return False return bool((np.linalg.norm(a[both] - b[both], axis=1) < tol).all())
def _female_like(inst: Inst, nodes: list[str]) -> bool: idx = [nodes.index(n) for n in LABEL_FEMALE_HIDDEN if n in nodes] return bool(idx) and bool(np.isnan(inst.xy[idx]).any(axis=1).all())
[docs] def check_frame( instances: list[Inst], nodes: list[str], shape_hw: tuple[int, int], allowed_counts: tuple[int, ...] = (3,), n_females: int | None = 1, ) -> Verdict: """Judge one labelled frame. Args: instances: All instances on the frame (user and predicted). nodes: Skeleton node names, in order. shape_hw: Image height and width. allowed_counts: Valid numbers of user instances (3 for triads). n_females: Instances expected with hidden head points, None to skip. """ users = [i for i in instances if i.user] if not users: return Verdict("unlabelled") reasons: list[str] = [] if len(users) != len(instances): reasons.append("half-corrected: predicted and labelled flies mixed") if len(users) not in allowed_counts: want = " or ".join(str(c) for c in allowed_counts) flies = "fly" if len(users) == 1 else "flies" reasons.append(f"{len(users)} {flies} labelled, expected {want}") a = nodes.index(LABEL_ANCHOR) if LABEL_ANCHOR in nodes else None h, w = shape_hw for k, inst in enumerate(users, 1): if a is not None and np.isnan(inst.xy[a]).any(): reasons.append(f"fly {k}: no {LABEL_ANCHOR}") pts = inst.xy[~np.isnan(inst.xy).any(axis=1)] if len(pts) and ((pts < 0).any() or (pts[:, 0] >= w).any() or (pts[:, 1] >= h).any()): reasons.append(f"fly {k}: points outside the image") for i in range(len(users)): for j in range(i + 1, len(users)): if same_fly(users[i].xy, users[j].xy): reasons.append(f"flies {i + 1} and {j + 1} are the same fly (labelled twice)") warnings: list[str] = [] if n_females is not None and len(users) == max(allowed_counts): n = sum(_female_like(u, nodes) for u in users) if n != n_females: warnings.append(f"{n} flies with hidden head points, expected {n_females} (female)") return Verdict("rejected" if reasons else "accepted", reasons, warnings)
[docs] def skeleton_problem(nodes: list[str], expected: list[str]) -> str | None: """Text describing a skeleton mismatch, or None when identical.""" if list(nodes) == list(expected): return None if set(nodes) == set(expected): return "skeleton nodes are in a different order" missing = [n for n in expected if n not in nodes] extra = [n for n in nodes if n not in expected] return f"skeleton differs (missing {missing}, extra {extra})"