Struct StreamingEvaluator 

pub struct StreamingEvaluator<K: EvalKernel> { /* private fields */ }

Streaming COCO evaluator, ADR-0013.

Holds a CocoDataset plus a sparse store of PerImageEval cells produced by per-batch match_image calls. Self::snapshot runs accumulate + summarize over the current store at any time; Self::finalize consumes the evaluator and returns the same Summary. Bit-identical to a batch run over the union of all update() batches submitted in order.

When params.retain_iou is true, the evaluator additionally retains a crate::tables::RetainedIous store keyed by (k, i), populated incrementally as each batch’s evaluate_with returns its per-batch retentions. Consumed by the per_pair / per_detection table builders.

Implementations

impl<K: EvalKernel> StreamingEvaluator<K>

pub fn new( dataset: CocoDataset, kernel: K, params: OwnedEvaluateParams, parity_mode: ParityMode, budget: MemoryBudget, ) -> Result<Self, EvalError>

Construct a new streaming evaluator.

Errors

Returns EvalError::InvalidConfig if params.area_ranges is empty (the batch path tolerates this; the streaming evaluator rejects it because the (K, A, I) grid would be degenerate).

pub fn with_rank(self, rank_id: RankId) -> Result<Self, EvalError>

Set this evaluator’s rank identifier for distributed-eval merge (ADR-0031). Builder shape: returns Self. Calling this after the first Self::update is a programming error and returns EvalError::InvalidConfig — rank identity is a construction-time property, not a mid-run mutable parameter.

Errors

EvalError::InvalidConfig when n_detections > 0.

pub fn rank_id(&self) -> Option<RankId>

The rank id this evaluator was tagged with, if any.

pub fn images_seen(&self) -> usize

Number of distinct images with at least one accepted detection.

pub fn detections_seen(&self) -> usize

Number of detections accepted across all update() calls.

pub fn images_pending(&self) -> usize

Number of GT images that have not yet received any detection.

pub fn memory_used_bytes(&self) -> usize

Total bytes the evaluator currently holds (sum of the three breakdown components).

pub fn budget(&self) -> MemoryBudget

View of the configured budget.

pub fn grid_meta(&self) -> &EvalGridMeta

Read-only access to the static grid metadata.

pub fn retained_ious(&self) -> Option<&RetainedIous>

Read-only access to the per-(category, image) IoU matrices retained when params.retain_iou was set at construction. None on the default no-retention path.

pub fn update(&mut self, json_bytes: &[u8]) -> Result<UpdateReport, EvalError>

Update with a new batch of detections, parsed from loadRes-shaped JSON bytes.

Errors

Propagates EvalError from the parse path, the underlying evaluate_with call, and the budget check (EvalError::OutOfBudget). On any error the evaluator state is unchanged and remains usable.

pub fn update_parsed( &mut self, parsed: ParsedDetections<K>, ) -> Result<UpdateReport, EvalError>

Update with a pre-parsed batch.

Errors

• EvalError::InvalidAnnotation if any detection’s image_id has already been processed in a prior update() call (no silent merge — submit duplicates as a single batch instead).
• EvalError::OutOfBudget if the projected post-insert total crosses MemoryBudget::bytes. State is unchanged on error.
• Any EvalError from the underlying evaluate_with call.

pub fn snapshot(&mut self) -> Result<Summary, EvalError>

Compute a Summary over the current store. Cheap to call repeatedly. Bit-identical to a batch run over the union of all detections submitted via update() so far (modulo stream-order ULP wobble in corrected mode — see ADR-0013 §Determinism).

Takes &mut self because the first call materializes a cached GT-only (K, A, I) grid for images that haven’t received any detection yet; subsequent snapshots reuse the cache.

Errors

Propagates EvalError from the underlying accumulate or summarize call.

pub fn finalize(self) -> Result<Summary, EvalError>

Consume the evaluator and return its final Summary.

Errors

Propagates EvalError from the underlying accumulate or summarize call.

pub fn snapshot_with_cells(&mut self) -> Result<SnapshotWithCells, EvalError>

Snapshot the current state, returning both the canonical Summary and a deep copy of the per-image cell store needed by the ADR-0018 calibration summarizer.

The Summary is bit-identical to what Self::snapshot would have produced for the same evaluator state — this method only adds the cell-store retention; the kernel maths are unchanged. Callers that don’t need calibration should prefer Self::snapshot / Self::finalize: this variant pays for an extra densification of the sparse (k, a, i) store, with GT-only overlay applied so the cells are immediately consumable by crate::calibration::summarize_calibration (which folds over dt_scores / dt_matched / dt_ignore and ignores GT-only slots anyway, but the consistency keeps the streaming and batch surfaces interchangeable).

Takes &mut self for the same reason as Self::snapshot: the first call materializes the cached GT-only (K, A, I) grid.

Errors

Propagates EvalError from the underlying accumulate or summarize call.

pub fn finalize_with_tables( self, request: TablesRequest, config: &TablesConfig, ) -> Result<(Summary, Tables), EvalError>

Consume the evaluator and return both its final Summary and the requested result tables.

v0.5 supports the cheap tables (crate::tables::TablesRequest::per_image, crate::tables::TablesRequest::per_class) on the streaming path — neither needs the per-cell EvalImageMeta the cells store would have to also retain. per_detection / per_pair on streaming returns EvalError::NotImplemented; callers who need those today should run the same workload via crate::evaluate_with in batch mode.

Errors

• EvalError::NotImplemented when request.per_detection or request.per_pair is set.
• Any error from the underlying accumulate / summarize / crate::tables::build_per_image / crate::tables::build_per_class calls.

pub fn snapshot_with_tables( &mut self, request: TablesRequest, config: &TablesConfig, ) -> Result<(Summary, Tables), EvalError>

Mid-stream version of Self::finalize_with_tables. See Self::snapshot for the determinism caveat.

Errors

Same conditions as Self::finalize_with_tables.

pub fn snapshot_to_partial(&self) -> Result<Vec<u8>, EvalError>

Serialize the current evaluator state to an opaque byte blob (ADR-0031 partial wire format). Non-consuming variant — the evaluator stays usable for further update calls.

Errors

EvalError::PartialFormatMismatch if rkyv archiving fails; EvalError::InvalidConfig if params hashing fails.

pub fn finalize_to_partial(self) -> Result<Vec<u8>, EvalError>

Consuming variant of Self::snapshot_to_partial. The evaluator is dropped after the partial is produced — the expected shape for the rank-local final state in a distributed-eval gather (ADR-0031).

Errors

Same as Self::snapshot_to_partial.

pub fn from_partials( dataset: CocoDataset, kernel: K, params: OwnedEvaluateParams, parity_mode: ParityMode, budget: MemoryBudget, partials: &[&[u8]], ) -> Result<Self, EvalError>

Construct an evaluator equivalent to a batch run over the union of all partials’ submitted detections (ADR-0031).

All partials must share dataset_hash, params_hash, parity_mode, kernel kind, retain_iou, and grid dimensions. In strict mode, every partial must declare a distinct rank_id. Image-id sets across partials must be disjoint.

Errors

• EvalError::PartialFormatMismatch on framing or rkyv validation failures (magic, version, CRC, kernel kind, grid dims, parity, retain_iou).
• EvalError::PartialDatasetMismatch on dataset_hash divergence.
• EvalError::PartialParamsMismatch on params_hash divergence.
• EvalError::PartialPartitionOverlap when two partials cover the same image_id.
• EvalError::PartialRankCollision when two strict-mode partials share a rank_id.

Trait Implementations

impl<K: Debug + EvalKernel> Debug for StreamingEvaluator<K>

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

Formats the value using the given formatter.