Struct CocoDataset 

pub struct CocoDataset { /* private fields */ }

COCO ground-truth dataset.

Storage is a single Arc<Vec<CocoAnnotation>> plus per-image and per-category index vectors. The Arc makes the dataset cheaply shareable across worker threads (the BackgroundEvaluator from a future ADR depends on this); the index vectors are owned by the CocoDataset because they’re cheap to rebuild and rebuild needs to happen exactly when the annotation set changes.

LVIS federated metadata (ADR-0026)

federated is Some exactly when the dataset was loaded via CocoDataset::from_lvis_json_bytes. The orchestrator’s federated branches gate on federated.is_some(); absence is the COCO default, where the matching engine runs unchanged.

Implementations

impl CocoDataset

pub fn from_json_bytes(bytes: &[u8]) -> Result<Self, EvalError>

Loads a dataset from a JSON byte slice.

Validates that every annotation references a known image and a known category; missing references raise EvalError::InvalidAnnotation rather than producing a silently-empty dataset.

pub fn from_parts( images: Vec<ImageMeta>, annotations: Vec<CocoAnnotation>, categories: Vec<CategoryMeta>, ) -> Result<Self, EvalError>

Loads a dataset from already-typed parts.

pub fn from_lvis_json_bytes(bytes: &[u8]) -> Result<Self, EvalError>

Loads an LVIS v1 ground-truth dataset from a JSON byte slice.

LVIS JSON is structurally COCO JSON plus per-image neg_category_ids / not_exhaustive_category_ids and per-category frequency (quirk AG1). This loader reads the extras into the federated metadata fields on the returned dataset; the underlying images / annotations / categories projections match what Self::from_json_bytes would produce on the same JSON.

Validation

• AA1. pos_category_ids[I] is derived from GT annotations: pos[I] = {ann.category_id for ann in annotations[I]}. Not a JSON field. A category with zero annotations on I is not in pos[I].

• AA7 (corrected). Disjointness invariants are enforced at load:

  • pos[I] ∩ neg[I] = ∅ — a category with GT on an image cannot also be in neg[I].
  • not_exhaustive[I] ⊆ pos[I] — by spec, not_exhaustive is a subset of pos.
  • not_exhaustive[I] ∩ neg[I] = ∅ — equivalent restatement given the prior two.

  The first violation surfaces as EvalError::LvisFederatedConflict with the offending (image_id, category_id).

• AB6 (corrected). Every category must carry a frequency tag. Missing tags are collected across the full categories list and surfaced once via EvalError::MissingFrequency with a sorted id list — more debuggable than lvis-api’s mid-eval KeyError on the first miss.

Per-image neg_category_ids and not_exhaustive_category_ids are optional in the JSON: an absent field is treated as an empty set, which matches the LVIS v1 semantic (“no negatives / nothing flagged non-exhaustive on this image”).

pub fn federated(&self) -> Option<&FederatedMetadata>

LVIS federated metadata bundle. Some only when the dataset was built by Self::from_lvis_json_bytes; the orchestrator’s AA3/AA4 branches gate on this.

pub fn pos_category_ids(&self) -> Option<&HashMap<ImageId, HashSet<CategoryId>>>

Per-image positive-category set, derived from GTs at load time (quirk AA1). Some only when the dataset is federated.

pub fn neg_category_ids(&self) -> Option<&HashMap<ImageId, HashSet<CategoryId>>>

Per-image negative-category set, read verbatim from the LVIS JSON (quirk AA2). Some only when the dataset is federated.

pub fn not_exhaustive_category_ids( &self, ) -> Option<&HashMap<ImageId, HashSet<CategoryId>>>

Per-image not-exhaustive-category set, read verbatim from the LVIS JSON (quirk AA3). Some only when the dataset is federated.

pub fn category_frequency(&self) -> Option<&HashMap<CategoryId, Frequency>>

Per-category frequency tag, read verbatim from the LVIS JSON (quirk AB1). Some only when the dataset is federated; missing-on-some-categories inputs are rejected at load (quirk AB6).

pub fn is_federated(&self) -> bool

true when the dataset carries LVIS federated metadata. Cheap shortcut for orchestration code that gates behaviour on the federated flag.

pub fn to_json_value(&self) -> CocoJson

Round-trips the dataset to the on-disk JSON shape, preserving every field vernier carries. Useful for fixture authoring and for debugging serde mismatches.

LVIS federated metadata is not included in the output — the round trip targets the COCO schema only. Callers needing to round-trip LVIS JSON must use the source bytes directly.

impl CocoDataset

pub fn ann_indices_for(&self, image: ImageId, cat: CategoryId) -> &[usize]

Indices into Self::annotations for a given (image, category) cell. Empty when no GT of that category exists on that image.

impl CocoDataset

pub fn dataset_hash(&self) -> [u8; 32]

32-byte BLAKE3 fingerprint of this dataset’s canonical form. Stable across input orderings: images, categories, annotations are sorted by id before hashing. Lazily cached on first call; shared across Clones via the underlying Arc<OnceLock>.

Carried in distributed-eval partial headers (ADR-0031); a receiving rank refuses to merge partials whose dataset_hash disagrees with its live dataset’s.

Trait Implementations

impl Clone for CocoDataset

fn clone(&self) -> CocoDataset

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CocoDataset

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl EvalDataset for CocoDataset

type Annotation = CocoAnnotation

Concrete annotation type. For CocoDataset this is CocoAnnotation; future datasets may use their own type with extra metadata.

fn images(&self) -> &[ImageMeta]

All images in the dataset, in input order.

fn categories(&self) -> &[CategoryMeta]

All categories in the dataset, in input order.

fn annotations(&self) -> &[CocoAnnotation]

Flat slice of every annotation in the dataset, in input order.

fn ann_indices_for_image(&self, image_id: ImageId) -> &[usize]

Indices into Self::annotations for a given image. Returns an empty slice when the image is unknown.

fn ann_indices_for_category(&self, cat_id: CategoryId) -> &[usize]

Indices into Self::annotations for a given category. Returns an empty slice when the category is unknown.

fn ann_iter_for_image( &self, image_id: ImageId, ) -> AnnotationIter<'_, Self::Annotation>

Convenience iterator over annotations for a given image.

fn ann_iter_for_category( &self, cat_id: CategoryId, ) -> AnnotationIter<'_, Self::Annotation>

Convenience iterator over annotations for a given category.