src/fpgm/depth/base.py

"""Abstract interface for depth sources."""

from __future__ import annotations

from abc import ABC, abstractmethod

from fpgm.types import DepthQuery, DepthResult


class DepthSource(ABC):
    """Provides metric depth at arbitrary 2D image locations for a given frame.

    Implementations must never raise for individual bad points -- those are
    reported via :attr:`DepthResult.valid` and :attr:`DepthResult.method`. Raising
    is reserved for whole-frame failures (see
    :class:`~fpgm.types.NoValidDepthAnnotationsError`).
    """

    @abstractmethod
    def query(self, q: DepthQuery) -> DepthResult:
        """Return metric depth (metres) at ``q.uv`` for frame ``q.frame_idx``."""