Skip to content

VISUS model prediction intake

GazeForge provides an audited intake layer for frame-indexed dynamic-AOI predictions generated by an external detector or tracker on VISUS stimuli. This layer connects model output to the exact audited VISUS video snapshot before model-human evaluation.

Why prediction intake is separate from evaluation

Model output should not silently define the evaluation protocol. In particular, the frames at which a detector emits boxes are not an appropriate basis for choosing the timestamps at which model and human tracks are compared. GazeForge therefore keeps three concerns separate:

  1. the VISUS source audit establishes the exact dataset/video identity and reviewed coordinate/time basis;
  2. prediction intake validates and fingerprints the model output against that audited source;
  3. model-human validation evaluates canonical model and human tracks on an externally supplied timestamp grid.

This separation prevents a sparse or model-dependent emission schedule from becoming the benchmark grid by accident.

Required prediction fields

Each prediction row must contain:

  • stimulus_id;
  • frame_index;
  • aoi_id;
  • label;
  • xmin, ymin, xmax, ymax.

confidence is optional. If it is absent, the canonical intake records a default confidence of 1.0; this does not imply calibrated probability.

Required provenance

prepare_visus_dynamic_aoi_predictions() requires explicit:

  • model name and version;
  • a description of how predictions were generated;
  • prediction coordinate unit;
  • 0- or 1-based frame convention;
  • optionally, the SHA-256 of the exact model artifact.

The source-audit report, source-audit specification, and exact manifest fingerprints are revalidated before prediction rows are accepted. Every audited VISUS stimulus must have exactly one audited video identity, and the resulting prediction report records each video's relative path, SHA-256, and byte size.

Geometry and identity gates

By default, predictions must cover every audited VISUS stimulus and may not introduce unknown stimuli. GazeForge rejects non-finite or fractional frame positions, duplicate stimulus/AOI/frame identities, invalid rectangles, confidence values outside [0, 1], and semantic-label changes within one predicted AOI track.

Prediction coordinates must use the same verified coordinate unit as the audited human-reference source. When this basis is pixels, predicted boxes must remain inside the audited VISUS video resolution.

Frame-to-time conversion

The prediction intake uses the audited VISUS video rate and an explicit frame-index convention:

timestamp_ms = (frame_index - frame_index_base) * 1000 / video_frame_rate_hz

It does not infer cadence from detector emissions and does not create an evaluation timestamp grid.

Minimal use

from gazeforge import prepare_visus_dynamic_aoi_predictions

predictions = prepare_visus_dynamic_aoi_predictions(
    audit,
    prediction_table,
    model_name="example-detector",
    model_version="1.0.0",
    prediction_basis="Reviewed detector output on each exact audited VISUS video.",
    prediction_coordinate_unit="pixels",
    frame_index_base=1,
    model_artifact_sha256=model_sha256,
)

The returned by_stimulus mapping contains canonical DynamicAOIKeyframe objects carrying the explicit model name/version. It can be supplied to run_visus_dynamic_aoi_model_validation() together with a canonical human-reference stream and an external evaluation timestamp grid.

Fingerprinted output

The prediction-intake report records the original and canonical table fingerprints, exact source-audit/spec/manifest identities, explicit model provenance, frame conversion convention, coordinate basis, audited video ledger, and whether complete stimulus coverage was required.

The report also records evaluation_timestamp_grid_generated=false as an explicit scientific guardrail.

Claim boundary

Prediction intake is provenance and schema infrastructure. It does not establish model accuracy, tracking quality, semantic validity, human agreement, or any VISUS empirical performance result. Empirical claims require an authoritative audited source, reviewed prediction provenance, a canonical human reference, a separately fixed evaluation grid, and the model-human validation workflow.