`vernier.panoptic`

Panoptic-quality (PQ) evaluation. Evaluator + evaluate(...) mirror the instance API; Predictions / Dataset carry the panoptic-specific payload (segment id maps + segment-info JSON).

Panoptic-quality (PQ) evaluation surface (ADR-0025).

Per ADR-0029, the panoptic-segmentation evaluation paradigm lives under vernier.panoptic. Sibling to :mod:vernier.instance and :mod:vernier.semantic. The Rust kernel ships in the vernier-panoptic crate; this module is a thin Python wrapper.

BackgroundEvaluator

BackgroundEvaluator(
    categories: bytes,
    parity_mode: str,
    *,
    things_stuff_split: bool = ...,
    retain_per_image_deltas: bool = ...,
    rank_id: int | None = ...,
    queue_capacity: int = ...,
    worker_affinity: int | None = ...,
    worker_nice: int = ...,
    shutdown_timeout_seconds: float = ...,
)

Background panoptic-quality evaluator (ADR-0014 + ADR-0032).

Wraps a single dedicated worker thread that owns the underlying [StreamingPanopticEvaluator]. submit(image_id, gt_label_map, gt_segments_info, dt_label_map, dt_segments_info) posts one image; snapshot / finalize block on a worker reply. Mirrors the instance and semantic background surfaces.

retain_per_image_deltas=True opts into the strict-mode bit- equality property at merge time (ADR-0032 §"Determinism") at the cost of ~2× streaming memory, same as the sibling streaming evaluator.

n_categories `property`

n_categories: int

Number of categories in the taxonomy.

n_images `property`

n_images: int

Mirror of the underlying evaluator's n_images. Advisory.

queue_depth `property`

queue_depth: int

Approximate count of Update messages waiting in the channel.

finalize `method descriptor`

finalize() -> PanopticSummary

Drain the queue, finalize the evaluator, and join the worker.

finalize_to_partial `method descriptor`

finalize_to_partial() -> bytes

ADR-0032 / ADR-0035: drain, serialize the final state, and shut the worker down.

submit `method descriptor`

submit(
    image_id: int,
    gt_label_map: NDArray[uint32],
    gt_segments_info: bytes,
    dt_label_map: NDArray[uint32],
    dt_segments_info: bytes,
    *,
    timeout: float | None = None,
) -> None

Submit one image's GT/DT pair to the worker. timeout mirrors the instance / semantic background surfaces.

submit_png `method descriptor`

submit_png(
    image_id: int,
    gt_png_bytes: bytes,
    gt_segments_info: bytes,
    dt_png_bytes: bytes,
    dt_segments_info: bytes,
    *,
    timeout: float | None = None,
) -> None

Variant of [Self::submit] that takes panoptic PNG byte blobs instead of pre-decoded uint32 ndarrays. Fuses libpng decode + RGB→id + (DT side) S3 area marginals + S1/S11 validation in one Rust pass; skips the Pillow → numpy → uint32 round-trip the Python wrapper would otherwise drive on the main thread. Strictly equivalent to submit(decode_label_map_png(p), ...) on the result; the diff is wall-time, not correctness.

Breakdown

Python wrapper around [Breakdown] / [ClassGroupBreakdown].

axis `property`

axis: str

Axis name (e.g., "area", "vehicle_taxonomy").

buckets `property`

buckets: list[tuple[str, float, float]]

Range buckets as a list of (label, lo, hi) triples in construction order.

Raises AttributeError if this Breakdown was built via from_class_groups. Use class_groups instead.

class_groups `property`

class_groups: list[tuple[str, list[int]]]

Class-id groups as a list of (label, class_ids) pairs in construction order.

Raises AttributeError if this Breakdown was built via from_ranges. Use buckets instead.

kind `property`

kind: Literal['range', 'class_groups']

Variant discriminator: "range" for from_ranges-constructed breakdowns, "class_groups" for from_class_groups-constructed ones. Use this to dispatch in validators that accept a Breakdown of a specific shape.

from_class_groups `builtin`

from_class_groups(
    axis: str, groups: Sequence[tuple[str, Sequence[int]]]
) -> Breakdown

Construct from class-id-keyed groups.

groups is a sequence of (label, class_ids) pairs, one per group. Group order on input determines the group axis index (first pair is index 0). Strict partition discipline is enforced — no class id may appear in two groups.

Raises ValueError on:

empty groups;
any group with empty class_ids;
duplicate group labels;
the same class id appearing in more than one group.

from_ranges `builtin`

from_ranges(
    axis: str, buckets: Sequence[tuple[str, float, float]]
) -> Breakdown

Construct from f64-keyed buckets.

buckets is a sequence of (label, lo, hi) triples, one per bucket. [lo, hi] is closed on both ends per ADR-0016 (quirk D6); an annotation whose key sits exactly on a boundary lands in both adjacent buckets.

Raises ValueError on:

empty buckets;
NaN or infinite lo / hi;
lo < 0;
lo > hi;
duplicate bucket labels.

ClassPanopticStats

Per-class PQ row exposed to Python (W8 strict-superset shape).

iou_sum `property`

iou_sum: float

n_fn `property`

n_fn: int

n_fp `property`

n_fp: int

n_tp `property`

n_tp: int

pq `property`

pq: float

rq `property`

rq: float