feat(pose): add pluggable pose backends

README.md

@@ -25,8 +25,25 @@ The pipeline runs in mock mode by default. To be explicit in scripts, call
 POZIFY_MOCK_MODE=1 uv run python app.py
 ```
 
-Setting `POZIFY_MOCK_MODE=0` currently raises `NotImplementedError` until real model-backed
-steps are added.
+Setting `POZIFY_MOCK_MODE=0` enables real video QC and MediaPipe-backed pose extraction while later
+analysis steps remain mocked. On current Python versions the pose step uses MediaPipe Tasks and
+downloads `pose_landmarker_lite.task` into `/tmp/pozify-models` on first use. To use a pre-downloaded
+model, set:
+
+```bash
+POZIFY_MEDIAPIPE_POSE_MODEL=/path/to/pose_landmarker_lite.task POZIFY_MOCK_MODE=0 uv run python app.py
+```
+
+The pose extractor is selected through a backend interface. MediaPipe is the default real backend:
+
+```bash
+POZIFY_POSE_BACKEND=mediapipe POZIFY_MOCK_MODE=0 uv run python app.py
+```
+
+Backend implementations live in `src/pozify/steps/pose_backends/` and return the same
+`PoseDetection` shape, so downstream steps do not depend on a specific model library. A reserved
+`mmpose` backend class is included as the integration point for OpenMMLab MMPose; implementing it
+requires installing MMPose/MMCV and mapping model keypoints into the shared landmark dictionary.
 
 ## Pipeline
 
@@ -117,7 +134,7 @@ Each step lives in `src/pozify/steps/` and exposes a `run(...)` function.
 Recommended replacement order:
 
 1. `video_qc.py`: read real video metadata with OpenCV.
-2. `pose_landmarker.py`: integrate MediaPipe Pose Landmarker.
+2. `pose_backends/`: add or refine pose model adapters such as MediaPipe or MMPose.
 3. `exercise_classifier.py`: load the exercise router model.
 4. `rep_counter.py`: implement exercise-specific state machines.
 5. `rep_analysis.py` and `issue_marker.py`: compute real metrics and issue scores.
@@ -134,3 +151,9 @@ uv run python -c "import app; from pozify.pipeline import run_pipeline; print('o
 
 The unit tests run the full mocked pipeline with no video input and with a small fixture path, then
 assert deterministic top-level keys for each JSON artifact.
+
+To run the real MediaPipe smoke test against `tests/fixtures/sample.MOV`, opt in explicitly:
+
+```bash
+POZIFY_RUN_REAL_POSE_TESTS=1 uv run python -m unittest tests.test_pose_steps.PoseStepTests.test_real_sample_mov_extracts_pose_landmarks
+```

pyproject.toml

@@ -6,6 +6,7 @@ readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
     "gradio>=4.44.0",
+    "mediapipe>=0.10.35",
     "numpy>=1.26.0",
     "opencv-python-headless>=4.10.0",
 ]

src/pozify/pipeline.py

@@ -38,8 +38,6 @@ def run_pipeline(
     mock: bool | None = None,
 ) -> dict[str, Any]:
     mock_mode = _env_mock_mode() if mock is None else mock
-    if not mock_mode:
-        raise NotImplementedError("Only mock pipeline implementations are available right now.")
 
     run_id = f"{datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%SZ')}-{uuid4().hex[:8]}"
     run_dir = RUNS_DIR / run_id
@@ -68,7 +66,7 @@ def run_pipeline(
     manifest = video_qc.run(video_path)
     write_artifact("video_manifest.json", manifest)
 
-    pose_sequence = pose_landmarker.run(manifest)
+    pose_sequence = pose_landmarker.run(manifest, mock=mock_mode)
     cleaned_pose_sequence = pose_cleaning.run(pose_sequence)
     write_artifact("pose_sequence.json", cleaned_pose_sequence)
 

src/pozify/steps/pose_backends/__init__.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from pozify.steps.pose_backends.base import PoseBackend, PoseDetection
+from pozify.steps.pose_backends.landmarks import LANDMARK_NAMES, landmark_list_to_dict, landmark_to_dict
+from pozify.steps.pose_backends.mediapipe import MediaPipePoseBackend
+from pozify.steps.pose_backends.mmpose import MMPoseBackend
+from pozify.steps.pose_backends.mock import MockPoseBackend
+from pozify.steps.pose_backends.registry import create_pose_backend
+
+
+__all__ = [
+    "LANDMARK_NAMES",
+    "MMPoseBackend",
+    "MediaPipePoseBackend",
+    "MockPoseBackend",
+    "PoseBackend",
+    "PoseDetection",
+    "create_pose_backend",
+    "landmark_list_to_dict",
+    "landmark_to_dict",
+]

src/pozify/steps/pose_backends/base.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+@dataclass(frozen=True)
+class PoseDetection:
+    landmarks: dict[str, dict[str, float]]
+    world_landmarks: dict[str, dict[str, float]]
+    source: str
+
+
+class PoseBackend(Protocol):
+    source: str
+
+    def __enter__(self) -> "PoseBackend":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        return None
+
+    def detect(self, rgb_frame: Any | None, *, frame_index: int) -> PoseDetection:
+        raise NotImplementedError

src/pozify/steps/pose_backends/landmarks.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+LANDMARK_NAMES = [
+    "nose",
+    "left_eye_inner",
+    "left_eye",
+    "left_eye_outer",
+    "right_eye_inner",
+    "right_eye",
+    "right_eye_outer",
+    "left_ear",
+    "right_ear",
+    "mouth_left",
+    "mouth_right",
+    "left_shoulder",
+    "right_shoulder",
+    "left_elbow",
+    "right_elbow",
+    "left_wrist",
+    "right_wrist",
+    "left_pinky",
+    "right_pinky",
+    "left_index",
+    "right_index",
+    "left_thumb",
+    "right_thumb",
+    "left_hip",
+    "right_hip",
+    "left_knee",
+    "right_knee",
+    "left_ankle",
+    "right_ankle",
+    "left_heel",
+    "right_heel",
+    "left_foot_index",
+    "right_foot_index",
+]
+
+
+def landmark_to_dict(landmark: Any) -> dict[str, float]:
+    payload = {
+        "x": round(float(landmark.x), 6),
+        "y": round(float(landmark.y), 6),
+        "z": round(float(landmark.z), 6),
+        "visibility": round(float(getattr(landmark, "visibility", 0.0)), 6),
+    }
+    presence = getattr(landmark, "presence", None)
+    if presence is not None:
+        payload["presence"] = round(float(presence), 6)
+    return payload
+
+
+def landmark_list_to_dict(landmarks: Any | None) -> dict[str, dict[str, float]]:
+    if landmarks is None:
+        return {}
+    landmark_values = landmarks.landmark if hasattr(landmarks, "landmark") else landmarks
+    return {
+        name: landmark_to_dict(landmark)
+        for name, landmark in zip(LANDMARK_NAMES, landmark_values, strict=False)
+    }

src/pozify/steps/pose_backends/mediapipe.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+from urllib.request import urlretrieve
+
+from pozify.steps.pose_backends.base import PoseDetection
+from pozify.steps.pose_backends.landmarks import landmark_list_to_dict
+
+
+POSE_TASK_MODEL_URL = (
+    "https://storage.googleapis.com/mediapipe-models/pose_landmarker/"
+    "pose_landmarker_lite/float16/latest/pose_landmarker_lite.task"
+)
+
+
+class MediaPipePoseBackend:
+    source = "mediapipe_pose"
+
+    def __init__(self) -> None:
+        self._pose = self._create_pose()
+
+    def __enter__(self) -> "MediaPipePoseBackend":
+        enter = getattr(self._pose, "__enter__", None)
+        if enter is not None:
+            enter()
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        exit_method = getattr(self._pose, "__exit__", None)
+        if exit_method is not None:
+            exit_method(*args)
+            return
+        close = getattr(self._pose, "close", None)
+        if close is not None:
+            close()
+
+    def detect(self, rgb_frame: Any | None, *, frame_index: int) -> PoseDetection:
+        if rgb_frame is None:
+            return PoseDetection(landmarks={}, world_landmarks={}, source=self.source)
+        results = self._pose.process(rgb_frame)
+        return PoseDetection(
+            landmarks=landmark_list_to_dict(getattr(results, "pose_landmarks", None)),
+            world_landmarks=landmark_list_to_dict(getattr(results, "pose_world_landmarks", None)),
+            source=self.source,
+        )
+
+    def _create_pose(self) -> Any:
+        try:
+            import mediapipe as mp
+        except ImportError as exc:
+            raise RuntimeError(
+                "MediaPipe is required for the mediapipe pose backend. Install dependencies with uv sync."
+            ) from exc
+
+        if hasattr(mp, "solutions"):
+            return mp.solutions.pose.Pose(
+                static_image_mode=False,
+                model_complexity=1,
+                smooth_landmarks=False,
+                enable_segmentation=False,
+                min_detection_confidence=0.5,
+                min_tracking_confidence=0.5,
+            )
+
+        return _MediaPipeTasksPoseAdapter(mp, _ensure_pose_task_model())
+
+
+class _MediaPipeTasksPoseAdapter:
+    def __init__(self, mediapipe_module: Any, model_path: Path) -> None:
+        self._mp = mediapipe_module
+        self._landmarker = self._create_landmarker(model_path)
+
+    def _create_landmarker(self, model_path: Path) -> Any:
+        base_options = self._mp.tasks.BaseOptions(model_asset_path=str(model_path))
+        options = self._mp.tasks.vision.PoseLandmarkerOptions(
+            base_options=base_options,
+            running_mode=self._mp.tasks.vision.RunningMode.IMAGE,
+            num_poses=1,
+            min_pose_detection_confidence=0.5,
+            min_pose_presence_confidence=0.5,
+            min_tracking_confidence=0.5,
+        )
+        return self._mp.tasks.vision.PoseLandmarker.create_from_options(options)
+
+    def process(self, rgb_frame: Any) -> Any:
+        image = self._mp.Image(image_format=self._mp.ImageFormat.SRGB, data=rgb_frame)
+        result = self._landmarker.detect(image)
+        pose_landmarks = result.pose_landmarks[0] if result.pose_landmarks else None
+        pose_world_landmarks = (
+            result.pose_world_landmarks[0] if result.pose_world_landmarks else None
+        )
+        return type(
+            "PoseResult",
+            (),
+            {
+                "pose_landmarks": pose_landmarks,
+                "pose_world_landmarks": pose_world_landmarks,
+            },
+        )()
+
+    def close(self) -> None:
+        close = getattr(self._landmarker, "close", None)
+        if close is not None:
+            close()
+
+
+def _pose_task_model_path() -> Path:
+    configured_path = os.getenv("POZIFY_MEDIAPIPE_POSE_MODEL")
+    if configured_path:
+        return Path(configured_path).expanduser()
+
+    cache_path = Path(os.getenv("POZIFY_MODEL_CACHE", "/tmp/pozify-models"))
+    return cache_path / "pose_landmarker_lite.task"
+
+
+def _ensure_pose_task_model() -> Path:
+    model_path = _pose_task_model_path()
+    if model_path.exists():
+        return model_path
+
+    model_path.parent.mkdir(parents=True, exist_ok=True)
+    urlretrieve(POSE_TASK_MODEL_URL, model_path)
+    return model_path

src/pozify/steps/pose_backends/mmpose.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+
+class MMPoseBackend:
+    source = "mmpose"
+
+    def __init__(self) -> None:
+        raise NotImplementedError(
+            "The mmpose backend is reserved behind the PoseBackend interface. "
+            "Install MMPose/MMCV and implement MMPoseBackend.detect() to map model keypoints "
+            "into the shared landmark dictionary."
+        )

src/pozify/steps/pose_backends/mock.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pozify.steps.pose_backends.base import PoseDetection
+from pozify.steps.pose_backends.landmarks import LANDMARK_NAMES
+
+
+def _mock_landmarks(frame_index: int) -> dict[str, dict[str, float]]:
+    phase = (frame_index % 90) / 90
+    vertical_offset = 0.08 if phase < 0.5 else 0.0
+    landmarks: dict[str, dict[str, float]] = {}
+    for idx, name in enumerate(LANDMARK_NAMES):
+        side_offset = -0.06 if "left" in name else 0.06 if "right" in name else 0.0
+        base_y = 0.2 + min(idx, 11) * 0.045
+        landmarks[name] = {
+            "x": round(0.5 + side_offset, 4),
+            "y": round(base_y + vertical_offset, 4),
+            "z": round(-0.02 * side_offset, 4),
+            "visibility": 0.95,
+        }
+    return landmarks
+
+
+class MockPoseBackend:
+    source = "mock_pose"
+
+    def __enter__(self) -> "MockPoseBackend":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        return None
+
+    def detect(self, rgb_frame: Any | None, *, frame_index: int) -> PoseDetection:
+        return PoseDetection(
+            landmarks=_mock_landmarks(frame_index),
+            world_landmarks={},
+            source=self.source,
+        )

src/pozify/steps/pose_backends/registry.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from pozify.steps.pose_backends.base import PoseBackend
+from pozify.steps.pose_backends.mediapipe import MediaPipePoseBackend
+from pozify.steps.pose_backends.mmpose import MMPoseBackend
+from pozify.steps.pose_backends.mock import MockPoseBackend
+
+
+def create_pose_backend(name: str) -> PoseBackend:
+    normalized_name = name.strip().lower().replace("-", "_")
+    if normalized_name == "mock":
+        return MockPoseBackend()
+    if normalized_name == "mediapipe":
+        return MediaPipePoseBackend()
+    if normalized_name == "mmpose":
+        return MMPoseBackend()
+    raise ValueError(f"Unknown pose backend: {name!r}")

src/pozify/steps/pose_cleaning.py

@@ -3,28 +3,188 @@ from __future__ import annotations
 from pozify.contracts import PoseFrame, PoseSequence
 
 
-def run(sequence: PoseSequence) -> PoseSequence:
-    cleaned_frames: list[PoseFrame] = []
-    for frame in sequence.frames:
-        cleaned_frames.append(
+MAX_INTERPOLATION_GAP = 3
+SMOOTHING_ALPHA = 0.45
+SMOOTHED_FIELDS = ("x", "y", "z")
+
+
+def _copy_landmarks(
+    landmarks: dict[str, dict[str, float]],
+) -> dict[str, dict[str, float]]:
+    return {name: dict(values) for name, values in landmarks.items()}
+
+
+def _copy_frame(frame: PoseFrame, landmarks: dict[str, dict[str, float]] | None = None) -> PoseFrame:
+    return PoseFrame(
+        frame_index=frame.frame_index,
+        timestamp_sec=frame.timestamp_sec,
+        landmarks=_copy_landmarks(landmarks if landmarks is not None else frame.landmarks),
+        world_landmarks=_copy_landmarks(frame.world_landmarks),
+        pose_quality=dict(frame.pose_quality),
+    )
+
+
+def _interpolate_landmarks(
+    start: dict[str, dict[str, float]],
+    end: dict[str, dict[str, float]],
+    fraction: float,
+) -> dict[str, dict[str, float]]:
+    interpolated: dict[str, dict[str, float]] = {}
+    for name in sorted(start.keys() & end.keys()):
+        start_values = start[name]
+        end_values = end[name]
+        values: dict[str, float] = {}
+        for field in ("x", "y", "z", "visibility", "presence"):
+            if field in start_values and field in end_values:
+                values[field] = round(
+                    float(start_values[field])
+                    + (float(end_values[field]) - float(start_values[field])) * fraction,
+                    6,
+                )
+        if values:
+            interpolated[name] = values
+    return interpolated
+
+
+def _interpolate_short_gaps(frames: list[PoseFrame]) -> list[PoseFrame]:
+    cleaned = [_copy_frame(frame) for frame in frames]
+    index = 0
+    while index < len(cleaned):
+        if cleaned[index].landmarks:
+            index += 1
+            continue
+
+        gap_start = index
+        while index < len(cleaned) and not cleaned[index].landmarks:
+            index += 1
+        gap_end = index - 1
+        previous_index = gap_start - 1
+        next_index = index
+        gap_size = gap_end - gap_start + 1
+
+        if (
+            previous_index < 0
+            or next_index >= len(cleaned)
+            or gap_size > MAX_INTERPOLATION_GAP
+            or not cleaned[previous_index].landmarks
+            or not cleaned[next_index].landmarks
+        ):
+            continue
+
+        for offset, frame_index in enumerate(range(gap_start, gap_end + 1), start=1):
+            fraction = offset / (gap_size + 1)
+            landmarks = _interpolate_landmarks(
+                cleaned[previous_index].landmarks,
+                cleaned[next_index].landmarks,
+                fraction,
+            )
+            cleaned[frame_index] = PoseFrame(
+                frame_index=cleaned[frame_index].frame_index,
+                timestamp_sec=cleaned[frame_index].timestamp_sec,
+                landmarks=landmarks,
+                world_landmarks=cleaned[frame_index].world_landmarks,
+                pose_quality={
+                    **cleaned[frame_index].pose_quality,
+                    "interpolated": bool(landmarks),
+                    "interpolation_gap_frames": gap_size,
+                },
+            )
+    return cleaned
+
+
+def _add_smoothed_fields(frames: list[PoseFrame]) -> list[PoseFrame]:
+    previous: dict[str, dict[str, float]] = {}
+    smoothed_frames: list[PoseFrame] = []
+
+    for frame in frames:
+        landmarks = _copy_landmarks(frame.landmarks)
+        for name, values in landmarks.items():
+            previous_values = previous.get(name, {})
+            current_smoothed: dict[str, float] = {}
+            for field in SMOOTHED_FIELDS:
+                if field not in values:
+                    continue
+                previous_value = previous_values.get(f"smoothed_{field}", values[field])
+                smoothed = previous_value * (1.0 - SMOOTHING_ALPHA) + values[field] * SMOOTHING_ALPHA
+                values[f"smoothed_{field}"] = round(smoothed, 6)
+                current_smoothed[f"smoothed_{field}"] = values[f"smoothed_{field}"]
+            previous[name] = current_smoothed
+
+        smoothed_frames.append(
+            PoseFrame(
+                frame_index=frame.frame_index,
+                timestamp_sec=frame.timestamp_sec,
+                landmarks=landmarks,
+                world_landmarks=frame.world_landmarks,
+                pose_quality=frame.pose_quality,
+            )
+        )
+    return smoothed_frames
+
+
+def _normalization_origin_and_scale(
+    landmarks: dict[str, dict[str, float]],
+) -> tuple[float, float, float, bool]:
+    required = ("left_hip", "right_hip", "left_shoulder", "right_shoulder")
+    if not all(name in landmarks for name in required):
+        return 0.0, 0.0, 1.0, False
+
+    left_hip = landmarks["left_hip"]
+    right_hip = landmarks["right_hip"]
+    left_shoulder = landmarks["left_shoulder"]
+    right_shoulder = landmarks["right_shoulder"]
+    origin_x = (left_hip["x"] + right_hip["x"]) / 2.0
+    origin_y = (left_hip["y"] + right_hip["y"]) / 2.0
+    mid_shoulder_x = (left_shoulder["x"] + right_shoulder["x"]) / 2.0
+    mid_shoulder_y = (left_shoulder["y"] + right_shoulder["y"]) / 2.0
+    torso_length = ((mid_shoulder_x - origin_x) ** 2 + (mid_shoulder_y - origin_y) ** 2) ** 0.5
+    if torso_length <= 1e-6:
+        return origin_x, origin_y, 1.0, False
+    return origin_x, origin_y, torso_length, True
+
+
+def _add_normalized_fields(frames: list[PoseFrame]) -> list[PoseFrame]:
+    normalized_frames: list[PoseFrame] = []
+    for frame in frames:
+        landmarks = _copy_landmarks(frame.landmarks)
+        origin_x, origin_y, scale, normalized = _normalization_origin_and_scale(landmarks)
+        for values in landmarks.values():
+            source_x = values.get("smoothed_x", values.get("x"))
+            source_y = values.get("smoothed_y", values.get("y"))
+            source_z = values.get("smoothed_z", values.get("z"))
+            if source_x is None or source_y is None or source_z is None:
+                continue
+            values["normalized_x"] = round((source_x - origin_x) / scale, 6)
+            values["normalized_y"] = round((source_y - origin_y) / scale, 6)
+            values["normalized_z"] = round(source_z / scale, 6)
+
+        normalized_frames.append(
             PoseFrame(
                 frame_index=frame.frame_index,
                 timestamp_sec=frame.timestamp_sec,
-                landmarks=frame.landmarks,
+                landmarks=landmarks,
                 world_landmarks=frame.world_landmarks,
                 pose_quality={
                     **frame.pose_quality,
                     "cleaned": True,
-                    "normalization_origin": "mid_hip_mock",
-                    "normalization_scale": "torso_length_mock",
+                    "normalized": normalized,
+                    "normalization_origin": "mid_hip",
+                    "normalization_scale": "mid_shoulder_to_mid_hip",
                 },
             )
         )
+    return normalized_frames
+
+
+def run(sequence: PoseSequence) -> PoseSequence:
+    interpolated_frames = _interpolate_short_gaps(sequence.frames)
+    smoothed_frames = _add_smoothed_fields(interpolated_frames)
+    cleaned_frames = _add_normalized_fields(smoothed_frames)
+    valid_frames = sum(1 for frame in cleaned_frames if frame.landmarks)
 
     return PoseSequence(
         frames=cleaned_frames,
         normalized=True,
-        smoothing_method="mock_exponential_smoothing",
-        pose_valid_ratio=sequence.pose_valid_ratio,
+        smoothing_method="exponential_smoothing",
+        pose_valid_ratio=round(valid_frames / len(cleaned_frames), 4) if cleaned_frames else 0.0,
     )
-

src/pozify/steps/pose_landmarker.py

@@ -1,54 +1,144 @@
 from __future__ import annotations
 
+from collections.abc import Iterator
+import os
+from typing import Any
+
+import cv2
+
 from pozify.contracts import PoseFrame, PoseSequence, VideoManifest
+from pozify.steps.pose_backends import (
+    MockPoseBackend,
+    PoseBackend,
+    create_pose_backend,
+)
 from pozify.steps.video_qc import sample_frame_indices
 
 
-LANDMARK_NAMES = [
-    "nose",
+CRITICAL_LANDMARKS = {
     "left_shoulder",
     "right_shoulder",
-    "left_elbow",
-    "right_elbow",
-    "left_wrist",
-    "right_wrist",
     "left_hip",
     "right_hip",
     "left_knee",
     "right_knee",
     "left_ankle",
     "right_ankle",
-]
-
-
-def _mock_landmarks(frame_index: int) -> dict[str, dict[str, float]]:
-    phase = (frame_index % 90) / 90
-    vertical_offset = 0.08 if phase < 0.5 else 0.0
-    landmarks: dict[str, dict[str, float]] = {}
-    for idx, name in enumerate(LANDMARK_NAMES):
-        side_offset = -0.06 if "left" in name else 0.06 if "right" in name else 0.0
-        base_y = 0.2 + min(idx, 11) * 0.045
-        landmarks[name] = {
-            "x": round(0.5 + side_offset, 4),
-            "y": round(base_y + vertical_offset, 4),
-            "z": round(-0.02 * side_offset, 4),
-            "visibility": 0.95,
+}
+FULL_BODY_LANDMARKS = CRITICAL_LANDMARKS | {"left_wrist", "right_wrist"}
+DEFAULT_POSE_SAMPLE_COUNT = 120
+
+
+def _env_pose_backend() -> str:
+    return os.getenv("POZIFY_POSE_BACKEND", "mediapipe")
+
+
+def _iter_video_frames(manifest: VideoManifest) -> Iterator[tuple[int, Any]]:
+    if not manifest.video_path or manifest.total_frames <= 0:
+        return
+
+    capture = cv2.VideoCapture(manifest.video_path)
+    try:
+        if not capture.isOpened():
+            return
+        sample_count = min(DEFAULT_POSE_SAMPLE_COUNT, manifest.total_frames)
+        for frame_index in sample_frame_indices(manifest.total_frames, sample_count):
+            capture.set(cv2.CAP_PROP_POS_FRAMES, frame_index)
+            ok, frame = capture.read()
+            if ok and frame is not None:
+                yield frame_index, frame
+    finally:
+        capture.release()
+
+
+def _pose_quality(landmarks: dict[str, dict[str, float]]) -> dict[str, Any]:
+    if not landmarks:
+        return {
+            "mean_visibility": 0.0,
+            "critical_landmarks_visible": False,
+            "full_body_visibility_proxy": 0.0,
+            "landmark_count": 0,
+            "pose_warning": "pose_not_detected",
         }
-    return landmarks
 
+    visibility_values = [landmark.get("visibility", 0.0) for landmark in landmarks.values()]
+    critical_values = [
+        landmarks[name].get("visibility", 0.0)
+        for name in CRITICAL_LANDMARKS
+        if name in landmarks
+    ]
+    full_body_values = [
+        landmarks[name].get("visibility", 0.0)
+        for name in FULL_BODY_LANDMARKS
+        if name in landmarks
+    ]
+    critical_visible = (
+        len(critical_values) == len(CRITICAL_LANDMARKS)
+        and min(critical_values, default=0.0) >= 0.5
+    )
+    return {
+        "mean_visibility": round(sum(visibility_values) / len(visibility_values), 4),
+        "critical_landmarks_visible": critical_visible,
+        "full_body_visibility_proxy": round(sum(full_body_values) / len(full_body_values), 4)
+        if full_body_values
+        else 0.0,
+        "landmark_count": len(landmarks),
+    }
+
+
+def _empty_sequence() -> PoseSequence:
+    return PoseSequence(frames=[], normalized=False, smoothing_method="none", pose_valid_ratio=0.0)
+
+
+def _run_with_backend(manifest: VideoManifest, backend: PoseBackend) -> PoseSequence:
+    if not manifest.analysis_allowed or not manifest.video_path:
+        return _empty_sequence()
 
-def run(manifest: VideoManifest) -> PoseSequence:
     frames: list[PoseFrame] = []
+    valid_frames = 0
+
+    with backend as extractor:
+        for frame_index, frame in _iter_video_frames(manifest):
+            rgb_frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+            detection = extractor.detect(rgb_frame, frame_index=frame_index)
+            if detection.landmarks:
+                valid_frames += 1
+            frames.append(
+                PoseFrame(
+                    frame_index=frame_index,
+                    timestamp_sec=round(frame_index / manifest.fps, 3) if manifest.fps else 0.0,
+                    landmarks=detection.landmarks,
+                    world_landmarks=detection.world_landmarks,
+                    pose_quality={
+                        **_pose_quality(detection.landmarks),
+                        "source": detection.source,
+                    },
+                )
+            )
+
+    pose_valid_ratio = round(valid_frames / len(frames), 4) if frames else 0.0
+    return PoseSequence(
+        frames=frames,
+        normalized=False,
+        smoothing_method="none",
+        pose_valid_ratio=pose_valid_ratio,
+    )
+
+
+def _run_mock(manifest: VideoManifest) -> PoseSequence:
+    frames: list[PoseFrame] = []
+    backend = MockPoseBackend()
     for frame_index in sample_frame_indices(manifest.total_frames):
+        detection = backend.detect(None, frame_index=frame_index)
         frames.append(
             PoseFrame(
                 frame_index=frame_index,
-                timestamp_sec=round(frame_index / manifest.fps, 3),
-                landmarks=_mock_landmarks(frame_index),
-                world_landmarks={},
+                timestamp_sec=round(frame_index / manifest.fps, 3) if manifest.fps else 0.0,
+                landmarks=detection.landmarks,
+                world_landmarks=detection.world_landmarks,
                 pose_quality={
-                    "mean_visibility": 0.95,
-                    "critical_landmarks_visible": True,
+                    **_pose_quality(detection.landmarks),
+                    "source": detection.source,
                     "mock": True,
                 },
             )
@@ -58,5 +148,20 @@ def run(manifest: VideoManifest) -> PoseSequence:
         frames=frames,
         normalized=False,
         smoothing_method="none",
-        pose_valid_ratio=1.0,
+        pose_valid_ratio=1.0 if frames else 0.0,
     )
+
+
+def run(
+    manifest: VideoManifest,
+    *,
+    mock: bool = False,
+    backend_name: str | None = None,
+    backend: PoseBackend | None = None,
+) -> PoseSequence:
+    if mock:
+        return _run_mock(manifest)
+    if backend is not None:
+        return _run_with_backend(manifest, backend)
+    selected_backend = create_pose_backend(backend_name or _env_pose_backend())
+    return _run_with_backend(manifest, selected_backend)

tests/test_pose_steps.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from types import SimpleNamespace
+import sys
+import tempfile
+import unittest
+
+import cv2
+import numpy as np
+
+FIXTURES_DIR = Path(__file__).resolve().parent / "fixtures"
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from pozify.contracts import PoseFrame, PoseSequence, VideoManifest
+from pozify.steps import pose_cleaning, pose_landmarker
+from pozify.steps.pose_backends import PoseDetection, landmark_list_to_dict
+
+
+def _landmark(x: float, y: float, z: float = 0.0, visibility: float = 0.9) -> SimpleNamespace:
+    return SimpleNamespace(x=x, y=y, z=z, visibility=visibility)
+
+
+def _landmark_result(offset: float = 0.0) -> SimpleNamespace:
+    landmarks = [
+        _landmark(0.2 + offset + index * 0.001, 0.1 + index * 0.01, -0.01, 0.91)
+        for index in range(33)
+    ]
+    return SimpleNamespace(
+        pose_landmarks=SimpleNamespace(landmark=landmarks),
+        pose_world_landmarks=SimpleNamespace(landmark=landmarks),
+    )
+
+
+class _FakePose:
+    source = "fake_pose"
+
+    def __init__(self) -> None:
+        self.calls = 0
+
+    def __enter__(self) -> "_FakePose":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        return None
+
+    def detect(self, _frame: object, *, frame_index: int) -> PoseDetection:
+        self.calls += 1
+        result = _landmark_result(offset=self.calls * 0.01)
+        return PoseDetection(
+            landmarks=landmark_list_to_dict(result.pose_landmarks),
+            world_landmarks=landmark_list_to_dict(result.pose_world_landmarks),
+            source=self.source,
+        )
+
+
+class PoseStepTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.temp_dir = tempfile.TemporaryDirectory()
+
+    def tearDown(self) -> None:
+        self.temp_dir.cleanup()
+
+    def _write_video(self, frame_count: int = 4) -> Path:
+        path = Path(self.temp_dir.name) / "pose.mp4"
+        writer = cv2.VideoWriter(str(path), cv2.VideoWriter_fourcc(*"mp4v"), 30.0, (640, 480))
+        self.assertTrue(writer.isOpened())
+        for frame_index in range(frame_count):
+            frame = np.full((480, 640, 3), 120 + frame_index, dtype=np.uint8)
+            writer.write(frame)
+        writer.release()
+        return path
+
+    def test_pose_landmarker_keeps_all_33_landmarks_and_quality(self) -> None:
+        path = self._write_video()
+        manifest = VideoManifest(
+            video_path=str(path),
+            fps=30.0,
+            duration_sec=0.133,
+            total_frames=4,
+            sampled_frames=4,
+            width=640,
+            height=480,
+            codec="mp4v",
+            container="mp4",
+            brightness_mean=120.0,
+            blur_laplacian_var=100.0,
+            quality_warnings=[],
+            analysis_allowed=True,
+        )
+        sequence = pose_landmarker.run(manifest, backend=_FakePose())
+
+        self.assertEqual(len(sequence.frames), 4)
+        self.assertEqual(len(sequence.frames[0].landmarks), 33)
+        self.assertIn("left_foot_index", sequence.frames[0].landmarks)
+        self.assertEqual(len(sequence.frames[0].world_landmarks), 33)
+        self.assertEqual(sequence.frames[0].pose_quality["source"], "fake_pose")
+        self.assertGreater(sequence.frames[0].pose_quality["mean_visibility"], 0.9)
+        self.assertTrue(sequence.frames[0].pose_quality["critical_landmarks_visible"])
+        self.assertEqual(sequence.pose_valid_ratio, 1.0)
+
+    def test_pose_cleaning_interpolates_smooths_and_adds_normalized_fields(self) -> None:
+        first_landmarks = _landmark_result(offset=0.0).pose_landmarks
+        last_landmarks = _landmark_result(offset=0.2).pose_landmarks
+        first = landmark_list_to_dict(first_landmarks)
+        last = landmark_list_to_dict(last_landmarks)
+        sequence = PoseSequence(
+            frames=[
+                PoseFrame(0, 0.0, first, {}, {"mean_visibility": 0.9}),
+                PoseFrame(1, 0.033, {}, {}, {"mean_visibility": 0.0}),
+                PoseFrame(2, 0.067, last, {}, {"mean_visibility": 0.9}),
+            ],
+            normalized=False,
+            smoothing_method="none",
+            pose_valid_ratio=0.667,
+        )
+
+        cleaned = pose_cleaning.run(sequence)
+
+        self.assertTrue(cleaned.normalized)
+        self.assertEqual(cleaned.smoothing_method, "exponential_smoothing")
+        self.assertEqual(cleaned.pose_valid_ratio, 1.0)
+        self.assertTrue(cleaned.frames[1].pose_quality["interpolated"])
+        shoulder = cleaned.frames[1].landmarks["left_shoulder"]
+        self.assertIn("x", shoulder)
+        self.assertIn("smoothed_x", shoulder)
+        self.assertIn("normalized_x", shoulder)
+        self.assertTrue(cleaned.frames[1].pose_quality["normalized"])
+
+    @unittest.skipUnless(
+        os.getenv("POZIFY_RUN_REAL_POSE_TESTS") == "1",
+        "set POZIFY_RUN_REAL_POSE_TESTS=1 to run the real MediaPipe fixture smoke test",
+    )
+    def test_real_sample_mov_extracts_pose_landmarks(self) -> None:
+        path = FIXTURES_DIR / "sample.MOV"
+        self.assertTrue(path.exists(), path)
+
+        from pozify.steps import video_qc
+
+        manifest = video_qc.run(str(path))
+        sequence = pose_landmarker.run(manifest, mock=False, backend_name="mediapipe")
+        cleaned = pose_cleaning.run(sequence)
+
+        self.assertTrue(manifest.analysis_allowed)
+        self.assertGreater(len(sequence.frames), 0)
+        self.assertGreater(sequence.pose_valid_ratio, 0.0)
+        self.assertEqual(len(sequence.frames[0].landmarks), 33)
+        self.assertEqual(sequence.frames[0].pose_quality["source"], "mediapipe_pose")
+        self.assertTrue(cleaned.normalized)
+
+
+if __name__ == "__main__":
+    unittest.main()