Event-Camera Fixture Mirrors

A Gen4 reference fixture is a small Prophesee Gen4-HD event-camera recording in the frozen EVENT_HDF5 schema v1 (see ADR-0002 §12). It is the held-out evaluation target consumed by:

Readiness across fixtures, weights, validation, and Phase A / Phase B gates is summarized in the Status Matrix.

SRB ships no captures in git. Gen4 recordings are institutionally owned and capture-licensed; the lab/team that ran the EVK4 owns the data and decides whether to publish it. Private staging mirrors can be registered while public redistribution terms are being confirmed. The CLI default remains a placeholder fixture that the fetcher refuses to download unless a mirror or explicit URL is supplied:

$ srb event-camera fetch-fixture
FixturePlaceholderError: FixtureArtifact 'gen4_reference.h5' is an
unpinned placeholder (url='srb-placeholder://...', sha256='000...').
Mirror the capture to an HTTP-fetchable host and pass --url + --sha256
on `srb event-camera fetch-fixture`, or construct
FixtureArtifact(... url=..., sha256=...) directly. ...

This document is the publishing contract for adding or changing a Gen4 fixture mirror in KNOWN_FIXTURES.

How users fetch fixtures today

Three paths work today:

# 1. Explicit URL + SHA256 (one-off, e.g. private institutional mirror)
srb event-camera fetch-fixture \
  --url https://your-host.example/gen4_reference.h5 \
  --sha256 <hex digest> \
  --name gen4_reference.h5

# 2. Short-name mirror (recommended for collaborators with HF access)
srb event-camera list-fixtures          # discover what's registered
srb event-camera fetch-fixture --mirror hf-andrejorsula-active-marker-gen4

The short-name path is the recommended one for end users: it carries the maintainer-verified SHA256 and the pinned schema version, so users don’t need to copy-paste either.

Candidate source: Prophesee Active Marker

Prophesee’s active_marker KDrive share is a useful source capture for fixture preparation and now has a private SRB staging mirror:

• Share page: https://kdrive.infomaniak.com/app/share/975517/d39fd010-8d56-4ce1-980d-224d5654b478
• Downloaded ZIP SHA256: 3a2aced3efee1b37b89e53bcb8b2882985ff6da9b556e7cfa1494e42e509098f
• Source payload: MV_SDK_5_x/active_marker_dataset/active_marker.raw
• RAW header: EVT3, generation 4.2, geometry 1280x720
• Private mirror: hf-andrejorsula-active-marker-gen4
• HF dataset repo: AndrejOrsula/srb-event-camera-fixtures
• HF path: prophesee/active_marker/active_marker.h5

It is registered only as a private staging mirror. Do not make the HF repo public until Prophesee redistribution terms are confirmed. Conversion evidence from srb dataset import-raw-evt3:

srb dataset import-raw-evt3 active_marker.raw \
  --output active_marker.h5 \
  --task active_marker \
  --policy-id prophesee_source

Verified converted HDF5:

• Event count: 22_316_758
• Resolution: 1280x720
• EVT3 24-bit time wraps: 1
• Invalid coordinates skipped: 0
• HDF5 size: 61_565_619 bytes
• HDF5 SHA256: 1e54f9853982ec0920a10aff3a5340322f435edd5ac29712bfd2db2eda47d6c0
• Local size: 58.7M with gzip fallback compression

Verified private HF upload:

srb event-camera fetch-fixture \
  --mirror hf-andrejorsula-active-marker-gen4 \
  --force

This fixture is useful for schema, importer, fetcher, and statistical smoke work, and for the opt-in Phase-B E2VID smoke. It does not by itself lift the downstream-fidelity NotImplementedError; that harness still needs a labelled/task-specific real Gen4 target and model adapter.

Fixture mirror requirements

To register a fixture by appending to KNOWN_FIXTURES in srb/core/sensor/event_camera/fixtures.py, the URL must:

1. Be HTTP-fetchable via urllib.request — no Google Drive consent interstitials, no auth tokens, no signed-URL tokens that expire. Confirm with:

   srb event-camera fetch-fixture --url <url> --sha256 <sha> --force
   

2. Serve an EVENT_HDF5 file with schema v1:

   • Datasets /events/t (int64 ns), /events/x (uint16), /events/y (uint16), /events/p (int8: −1/+1).
   • Group /metadata with schema_version=1, resolution, and the reproducibility attrs from EventEpisodeMetadata.
   • Optionally Blosc:zstd-3 or gzip-6 compressed (the SRB reader handles both).

   Mirrors of modified or resampled captures must use a different short_name and a clearly distinct artifact.name, and bump the schema_version only via an ADR amendment.

3. Pin the sensor model in FixtureArtifact.sensor_model — the downstream-fidelity probe consults this to pick the right resolution prior (currently "prophesee_gen4_hd"; the field accepts other strings if a future fixture targets DAVIS or EVK3).

4. Carry a stable URL — mirrors that hot-link to ephemeral storage (cloud-function URLs, signed-URL tokens, presigned S3) MUST NOT be registered. Zenodo, Hugging Face datasets, and institutional research data repositories with DOIs are the recommended hosts.

5. Be SHA256-verified — the maintainer adding the entry must have downloaded the file from the mirror and confirmed the digest matches the known-good reference.

6. Honour the capture license — record license/attribution in FixtureMirror.license_note (typically CC-BY-4.0 for academic captures; never a license stricter than the upstream redistribution terms permit). Note the distinction from the weight registry: captures are data not code, so the conventional license is CC-BY-4.0 rather than MIT.

PR template for adding a fixture mirror

Open a PR that:

1. Appends one tuple to KNOWN_FIXTURES in srb/core/sensor/event_camera/fixtures.py:

   KNOWN_FIXTURES = (
       FixtureMirror(
           short_name="zenodo-<owner>-gen4",  # include sensor kind suffix
           artifact=FixtureArtifact(
               name="gen4_reference.h5",
               url="https://zenodo.org/records/<id>/files/gen4_reference.h5",
               sha256="<hex digest>",
               size_bytes=<file size>,
               schema_version=1,
               sensor_model="prophesee_gen4_hd",
               num_episodes=<count>,
           ),
           license_note="CC-BY-4.0, © 2026 <owner/lab>",
           notes="Captured 2026-MM-DD on EVK4-HD, <scene summary>.",
       ),
   )
   

   Use the sensor kind as a short_name suffix (-gen4, -davis346, -evk3) so srb event-camera list-fixtures is self-documenting and typo-resistant when multiple sensor families coexist.

2. Updates the tripwire test (tests/unit/test_event_camera_fixture_mirrors.py ::test_known_fixtures_registry_is_pinned) to assert the registry shape. The tripwire is intentional — its failure forces a reviewer to read this document.

3. Adds a CLI smoke test that resolves the new short_name and confirms FixtureArtifact.url / sha256 / schema_version round-trip through get_known_fixture.

4. Includes evidence in the PR description that an end-to-end srb event-camera fetch-fixture --mirror <short_name> succeeded against the mirror (paste the CLI JSON output, including the schema_version and sensor_model fields).

5. Records the capture license in the PR body and confirms the maintainer has authority to redistribute (institutional sign-off where applicable; subject-consent for any human-visible content).

6. Lifts the NotImplementedError in srb/datasets/event_validation/downstream.py::run_downstream_evaluation ONLY if this PR also wires the real harness (train + eval). A mirror-only PR keeps the NotImplementedError in place — both PRs can be authored in parallel, but the lifting commit MUST NOT land without a real verified mirror present in KNOWN_FIXTURES.

Removing a fixture mirror

If a registered fixture goes offline, serves a corrupted file, or has its license retracted, open a PR that:

1. Removes the entry from KNOWN_FIXTURES.
2. Updates the tripwire test to reflect the new shape.
3. Documents the reason in the commit body so the same mirror is not re-added by accident later.

Why this is a registry and not a single canonical URL

There is intentionally no “the SRB Gen4 fixture.” SRB does not own capture data and cannot be the single point of failure for the downstream-fidelity probe. The registry pattern lets institutional mirrors (university research-data repos, Zenodo deposits with DOIs) live side-by-side with community mirrors without one bucket having to scale to every SRB user — and lets multiple labs publish their own Gen4 captures without a coordination handshake.

Parallel pattern to the SuperSloMo / E2VID weight registry — see event_camera_weight_mirrors.md for the precedent and the same rationale applied to ML checkpoints.