rpx_benchmark.adapters.depth

269class DepthAdapterSkeleton(BenchmarkModel):
270    """Base class for every depth-model adapter skeleton.
271
272    Subclasses set the class-level :attr:`MODEL_KEY` to the
273    ``DEPTH_MODEL_CARDS`` entry they wrap; everything else flows from
274    that card automatically. Override ``setup()`` and ``predict()``
275    with real implementations once the model is installed.
276
277    The default ``predict()`` raises a ``NotImplementedError`` whose
278    message includes the install hint, so any contributor who tries
279    to run an unimplemented adapter sees exactly what they need to do.
280    """
281
282    #: Key into :data:`DEPTH_MODEL_CARDS`. Must be set by subclasses.
283    MODEL_KEY: ClassVar[str] = ""
284
285    def __init_subclass__(cls, **kwargs: Any) -> None:
286        super().__init_subclass__(**kwargs)
287        if not cls.MODEL_KEY:
288            # The abstract scaffold itself doesn't have a key; subclasses
289            # without a key are an error.
290            if cls.__name__ != "DepthAdapterSkeleton":
291                raise ConfigError(
292                    f"{cls.__name__}: MODEL_KEY must be set on every DepthAdapterSkeleton subclass",
293                    hint="Set MODEL_KEY to the matching DEPTH_MODEL_CARDS key.",
294                )
295            return
296        if cls.MODEL_KEY not in DEPTH_MODEL_CARDS:
297            raise ConfigError(
298                f"{cls.__name__}: MODEL_KEY {cls.MODEL_KEY!r} is not in DEPTH_MODEL_CARDS",
299                hint=(
300                    f"Either add a card for {cls.MODEL_KEY!r} to "
301                    f"DEPTH_MODEL_CARDS, or fix the typo. Known keys: "
302                    f"{sorted(DEPTH_MODEL_CARDS)}"
303                ),
304            )
305        card = DEPTH_MODEL_CARDS[cls.MODEL_KEY]
306        # Inherit task + output kind from the card so adapter authors
307        # can't accidentally diverge from the canonical roster.
308        cls.task = card.task
309        cls.depth_output_kind = card.depth_output_kind
310        cls.name = card.name
311        cls.install_hint = card.install_hint
312
313    name: ClassVar[str] = ""
314    install_hint: ClassVar[str] = ""
315
316    def setup(self) -> None:
317        """Load weights, warm CUDA, etc. Skeleton: no-op.
318
319        Override in concrete subclasses. The runner calls this once
320        before iteration; the override should be idempotent so
321        repeated calls (e.g. when warming a multi-process pool) are
322        cheap.
323        """
324        return None
325
326    def predict(self, batch: Sequence[Sample]) -> Sequence[Any]:
327        """Skeleton ``predict`` — raises ``NotImplementedError`` with
328        the install hint baked in so a contributor sees exactly which
329        package to install / which forward call to wire up.
330        """
331        raise NotImplementedError(
332            f"Adapter for {self.name!r} ({self.MODEL_KEY}) is a skeleton. "
333            f"Install the model and implement `predict`: {self.install_hint}",
334        )

57@dataclass(frozen=True)
58class DepthModelCard:
59    """Static metadata about one depth model in the roster.
60
61    Used by tests to verify the adapter package covers every model
62    the paper claims to evaluate, and by tooling to render
63    "available models" tables.
64    """
65
66    name: str
67    """Display name used in result tables — matches the paper's
68    Table 2 / Table 3 spelling exactly (e.g. ``"DA3 Metric-L"``)."""
69
70    task: TaskType
71    """``MONOCULAR_DEPTH`` (Image Depth) or ``VIDEO_DEPTH`` (Video Depth)."""
72
73    depth_output_kind: Literal["metric", "relative"]
74    """Determines whether the runner applies per-scene-phase scale +
75    shift alignment before metrics. ``"metric"`` for models that
76    output meters directly; ``"relative"`` for affine-invariant
77    models (Lotus-2, FE2E and DA-V2 relative)."""
78
79    install_hint: str
80    """One-line `pip install ...` (or equivalent) the contributor
81    runs to make ``setup()`` work. Surfaced in the
82    ``NotImplementedError`` raised by skeleton ``predict()`` so the
83    next contributor doesn't have to grep."""
84
85    paper_ref: str = ""
86    """Optional citation key — matches an entry in
87    ``paper-submission/overleaf/root.bib`` so the model card can
88    cross-link to its primary source."""

342def available_depth_adapters() -> dict[str, type[DepthAdapterSkeleton]]:
343    """Return every DepthAdapterSkeleton subclass currently importable.
344
345    Walks the registered subclasses of :class:`DepthAdapterSkeleton`
346    and returns ``{MODEL_KEY: class}``. Useful for CLI tooling and
347    tests that want to enumerate "every model we've at least
348    skeletoned".
349    """
350    out: dict[str, type[DepthAdapterSkeleton]] = {}
351    for cls in DepthAdapterSkeleton.__subclasses__():
352        if cls.MODEL_KEY:
353            out[cls.MODEL_KEY] = cls
354    return out

357def lazy_import(module_name: str, *, install_hint: str) -> Any:
358    """Best-effort import with a friendly error.
359
360    Skeleton ``setup()`` overrides call this to defer heavy deps
361    until the adapter is actually run; if the dep is missing, the
362    contributor gets the install hint inline.
363    """
364    try:
365        import importlib
366
367        return importlib.import_module(module_name)
368    except ImportError as e:
369        raise ModelError(
370            f"failed to import {module_name!r}",
371            hint=install_hint,
372        ) from e