"""Protocol surface for the VIO component (ARCH-05).

Phase 1: defines the Protocol that concrete adapters in this directory
implement. Method signatures mirror ``ISequentialVisualOdometry`` from
``core/vo.py``. Adapters are NOT moved here yet — see Plan 04 (VIO).
"""
from __future__ import annotations

from typing import Protocol, runtime_checkable

import numpy as np

from gps_denied.schemas import CameraParameters
from gps_denied.schemas.vo import Features, Matches, Motion, RelativePose


@runtime_checkable
class VisualOdometry(Protocol):
    """Sequential visual odometry surface (mirrors ISequentialVisualOdometry)."""

    def compute_relative_pose(
        self, prev_image: np.ndarray, curr_image: np.ndarray, camera_params: CameraParameters
    ) -> RelativePose | None: ...

    def extract_features(self, image: np.ndarray) -> Features: ...

    def match_features(self, features1: Features, features2: Features) -> Matches: ...

    def estimate_motion(
        self, matches: Matches, camera_params: CameraParameters
    ) -> Motion | None: ...


# Backwards-compat alias — Phase 2 will deprecate the I-prefix.
ISequentialVisualOdometry = VisualOdometry