Event-Camera Weight Mirrors

Three upstream checkpoints flow through the srb event-camera fetch-weights CLI; SRB redistributes none in-repo:

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

The E2VID checkpoint comes from the original rpg_e2vid release, but SRB’s runtime adapter uses the MIT e2vid package from uzh-rpg/e2calib through the srb[event-reconstruction] extra. Do not vendor GPL model code into SRB. The private E2VID and V2CE mirrors are exercised by the opt-in Phase-B smoke at tests/integration/test_event_camera_phase_b_smoke.py.

All three artifacts now have maintainer-pinned Hugging Face mirrors. The repository is private until the release is ready; collaborators need access plus either HF_TOKEN or a local hf auth login.

Original upstream sources:

• SuperSloMo: https://drive.google.com/file/d/1ETID_4xqLpRBrRo1aOT7Yphs3QqWR_fx
• E2VID: http://rpg.ifi.uzh.ch/data/E2VID/models/E2VID_lightweight.pth.tar
• V2CE: https://drive.google.com/file/d/1-aC6CTGZgAZk3snANZ46FAGNkPzu_Scw

Bundling any of them in-repo would blow past the LFS budget and conflict with upstream redistribution terms.

The CLI still defaults to a placeholder artifact per kind when no --mirror / --url is supplied, so unverified downloads remain blocked:

$ srb event-camera fetch-weights                       # supersloMo (default)
WeightPlaceholderError: WeightArtifact 'SuperSloMo39.ckpt' is an unpinned
placeholder (url='srb-placeholder://...', sha256='000...'). Mirror the
checkpoint to an HTTP-fetchable host and pass --url + --sha256 ...

$ srb event-camera fetch-weights --artifact e2vid
WeightPlaceholderError: WeightArtifact 'E2VID_lightweight.pth.tar' is an
unpinned placeholder ...

$ srb event-camera fetch-weights --artifact v2ce
WeightPlaceholderError: WeightArtifact 'v2ce_3d.pt' is an unpinned
placeholder ...

This document is the publishing contract for adding a mirror for any of the three artifacts.

How users fetch weights today

Three paths work today; the first two scale to any of the three artifacts:

# 1. Explicit URL + SHA256 (one-off, e.g. private mirror)
srb event-camera fetch-weights --artifact supersloMo \
  --url https://example.com/path/to/SuperSloMo39.ckpt \
  --sha256 <hex digest> \
  --name SuperSloMo39.ckpt

srb event-camera fetch-weights --artifact e2vid \
  --url https://example.com/path/to/E2VID_lightweight.pth.tar \
  --sha256 <hex digest>

srb event-camera fetch-weights --artifact v2ce \
  --url https://example.com/path/to/v2ce_3d.pt \
  --sha256 <hex digest>

# 2. Short-name mirror (recommended for collaborators with HF access)
srb event-camera list-mirrors          # discover what's registered
srb event-camera fetch-weights --mirror hf-andrejorsula-supersloMo
srb event-camera fetch-weights --mirror hf-andrejorsula-e2vid
srb event-camera fetch-weights --mirror hf-andrejorsula-v2ce

The short-name path is the recommended one for end users: it carries the maintainer-verified SHA256 so users don’t need to copy-paste a hex digest. A mirror’s artifact.name identifies which kind it serves; the --mirror flag wins over --artifact when both are supplied. Private Hugging Face mirrors are fetched with a bearer token from HF_TOKEN, HUGGING_FACE_HUB_TOKEN, or the standard Hugging Face CLI token cache.

Mirror requirements

To register a mirror by appending to KNOWN_MIRRORS in srb/core/sensor/event_camera/weights.py, the URL must:

1. Be HTTP-fetchable via urllib.request — no Google Drive consent interstitials, no auth tokens, no rate-limited redirects. Confirm with:

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

2. Serve the exact upstream checkpoint:

   • For SuperSloMo: the v3.9 checkpoint shipped with v2e (filename SuperSloMo39.ckpt).
   • For E2VID: the lightweight checkpoint from the rpg_e2vid release (filename E2VID_lightweight.pth.tar).
   • For V2CE: the pretrained model from ucsd-hdsi-dvs/V2CE-Toolbox (filename v2ce_3d.pt).

   Mirrors of modified or re-trained checkpoints must use a different short_name and a clearly distinct artifact.name.

3. Carry a stable URL — mirrors that hot-link to ephemeral storage (cloud function URLs, signed-URL tokens) MUST NOT be registered.

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

5. Honour the upstream license — record license/attribution in WeightMirror.license_note so downstream consumers can audit redistribution.

PR template for adding a mirror

Open a PR that:

1. Appends one tuple to KNOWN_MIRRORS in srb/core/sensor/event_camera/weights.py. SuperSloMo, E2VID, and V2CE mirrors coexist in the same registry — the artifact.name field identifies which kind each entry serves:

   # SuperSloMo example
   KNOWN_MIRRORS = (
       WeightMirror(
           short_name="huggingface-<owner>-supersloMo",  # include artifact kind
           artifact=WeightArtifact(
               name="SuperSloMo39.ckpt",
               url="https://huggingface.co/<owner>/<repo>/resolve/main/SuperSloMo39.ckpt",
               sha256="<hex digest>",
               size_bytes=<file size>,
           ),
           license_note="MIT, © 2018 ...",
           notes="Mirrored 2026-MM-DD from v2e release X.Y.Z.",
       ),
       # E2VID example
       WeightMirror(
           short_name="huggingface-<owner>-e2vid",
           artifact=WeightArtifact(
               name="E2VID_lightweight.pth.tar",
               url="https://huggingface.co/<owner>/<repo>/resolve/main/E2VID_lightweight.pth.tar",
               sha256="<hex digest>",
               size_bytes=<file size>,
           ),
           license_note="GPL-3.0, © 2019 Rebecq et al.",
           notes="Mirrored 2026-MM-DD from rpg_e2vid release X.Y.Z.",
       ),
       # V2CE example
       WeightMirror(
           short_name="huggingface-<owner>-v2ce",
           artifact=WeightArtifact(
               name="v2ce_3d.pt",
               url="https://huggingface.co/<owner>/<repo>/resolve/main/v2ce_3d.pt",
               sha256="<hex digest>",
               size_bytes=<file size>,
           ),
           license_note="MIT, © 2024 Zhongyang Zhang.",
           notes="Mirrored 2026-MM-DD from ucsd-hdsi-dvs/V2CE-Toolbox.",
       ),
   )
   

   Use the artifact kind as a short_name suffix (-supersloMo, -e2vid, or -v2ce) so srb event-camera list-mirrors is self-documenting and typo-resistant when multiple mirrors come from the same host.

2. Updates the tripwire test (tests/unit/test_event_camera_weight_mirrors.py ::test_known_mirrors_pin_private_huggingface_weights and ::test_known_mirror_artifact_hashes_are_pinned) to assert the new non-empty 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 WeightArtifact.url / sha256 round-trip through get_known_mirror.

4. Includes evidence in the PR description that an end-to-end srb event-camera fetch-weights --mirror <short_name> succeeded against the mirror (paste the CLI JSON output).

5. Records the upstream license in the PR body and confirms the maintainer has authority to redistribute. Known upstream licenses: SuperSloMo / v2e is MIT, the E2VID checkpoint was published with rpg_e2vid under GPL-3.0, the E2VID Python provider used by SRB is MIT via uzh-rpg/e2calib, and V2CE-Toolbox is MIT.

Removing a mirror

If a registered mirror goes offline or serves a corrupted file, open a PR that:

1. Removes the entry from KNOWN_MIRRORS.
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 mirror” for any of the three artifacts. SRB does not own the upstream checkpoints and does not want to be the single point of failure for the event-camera pipeline. The registry pattern lets community mirrors live side-by-side with private institutional mirrors without one bucket having to scale to every SRB user.