griip-sdk-dev 0.4.0.dev24238__py3-none-any.whl

griip_sdk/calibration/app.py

@@ -0,0 +1,638 @@
+"""High-level recipe for assembling a calibration app from a cell YAML.
+
+Parallel to :mod:`griip_sdk.cell.recipes`: ``build_calibration_app`` wires a
+calibration workflow the way ``build_pick_only_manager`` wires picking. The
+returned :class:`CalibrationApp` drives hand-eye calibration and the
+operator-driven environment scan. See the README for the consumer walkthrough.
+
+Protos: requests use ``griip_core.generated.griip_pb2``; the mmai-griip-api
+server serves the schema-identical ``griip.proto``. The two are kept in
+lockstep -- if they diverge, gRPC calls silently misbehave.
+"""
+
+from __future__ import annotations
+
+import logging
+from contextlib import contextmanager
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Callable, Iterator, cast
+
+import grpc
+import numpy as np
+import numpy.typing as npt
+from spatialmath import SE3, SO3
+from vention.vision.v1.vision_service_abc import ImageServiceBackend
+
+from griip_sdk.calibration.camera_factory import build_calibration_camera
+from griip_sdk.calibration.config_store import (
+    DEFAULT_CALIBRATION_DATA_PATH,
+    CalibrationConfigStore,
+    utc_ts,
+)
+from griip_sdk.calibration.hand_eye_calib import (
+    CalibrationCancelledError,
+    HandEyeCalibrationService,
+)
+from griip_sdk.calibration.hand_eye_calib.planning import (
+    build_and_configure_hand_eye_planning_service,
+    resolve_hand_eye_planner_params,
+)
+from griip_sdk.calibration.hand_eye_calib.transforms import (
+    compute_camera_to_tcp_transform,
+    load_camera_to_flange_transform,
+)
+from griip_sdk.calibration.mqtt_publisher import MqttProgressPublisher, compose_on_progress
+from griip_sdk.calibration.mqtt_topics import ENVIRONMENT_PROGRESS_TOPIC, HAND_EYE_PROGRESS_TOPIC
+from griip_sdk.calibration.routines import DEFAULT_ENCIRCLE_ROUTINE
+from griip_sdk.calibration.scanning import EnvironmentScanningService
+from griip_sdk.calibration.types import PerceptionStub, PlanningStub
+from griip_sdk.cell import load_cell_config
+from griip_sdk.cell.builders import resolve_camera_calibration
+from griip_sdk.cell.config import PrototypeCellConfig
+from griip_sdk.cell.initialize import build_robot_initialize_request, send_initialize
+from griip_sdk.errors import ConfigError
+from griip_core.generated import griip_pb2 as pb
+from griip_core.generated import griip_pb2_grpc
+from griip_sdk.grpc_adapters.servicer_as_stub import ServicerAsStub
+from griip_sdk.hardware.robot_client import VrmcsRobotClient, build_vrmcs_client
+
+logger = logging.getLogger(__name__)
+
+
+class CalibrationApp:
+    """Returned by :func:`build_calibration_app`; exposes the calibration verbs.
+
+    Owns shared infrastructure (robot client, started camera client, planning +
+    perception stubs, calibration store) so repeated verb calls don't re-pay
+    setup. Per-verb services are built on demand.
+    """
+
+    def __init__(
+        self,
+        *,
+        cell: PrototypeCellConfig,
+        config_path: Path,
+        robot_client: VrmcsRobotClient,
+        vision_backend: ImageServiceBackend,
+        cam_name: str,
+        camera_mxid: str,
+        sensor: str,
+        store: CalibrationConfigStore,
+        calib_data_root: Path | str,
+        planning_stub: PlanningStub,
+        perception_stub: PerceptionStub,
+        secondary_source_id: str = "right",
+        mqtt_publisher: MqttProgressPublisher | None = None,
+        strict_intrinsics: bool = True,
+    ) -> None:
+        self._cell = cell
+        self._config_path = config_path
+        self._robot_client = robot_client
+        self._vision_backend = vision_backend
+        self._cam_name = cam_name
+        self._camera_mxid = camera_mxid
+        self._sensor = sensor
+        self._secondary_source_id = secondary_source_id
+        self._store = store
+        self._calib_data_root = calib_data_root
+        self._planning_stub = planning_stub
+        self._perception_stub = perception_stub
+        self._mqtt_publisher = mqtt_publisher
+        self._strict_intrinsics = strict_intrinsics
+
+        self._env_session_service: EnvironmentScanningService | None = None
+        self._env_session_sequence_dir: Path | None = None
+        self._env_session_next_index: int = 0
+        self._env_session_previous_tcp_offset: SE3 | None = None
+        self._reset_env_session_state()
+
+    # ----- Hand-eye calibration --------------------------------------
+
+    def run_hand_eye_calibration(
+        self,
+        *,
+        on_progress: Callable[[int, str, str], None] | None = None,
+        is_cancelled: Callable[[], bool] | None = None,
+        save_dir: Path | None = None,
+        routine: dict[str, Any] | None = None,
+        bootstrap_path: Path | None = None,
+    ) -> SE3:
+        """Plan to ``cell.positions.calibration_joints``, run the sphere routine, then return there.
+
+        Raises :class:`ConfigError` if ``calibration_joints`` is unset. Persists
+        the result under ``X_cam_flg__{cam_name}__{mxid}__{sensor}``. Emits exactly
+        one terminal ``on_progress`` tick (``success`` 100 / ``error`` 0 /
+        ``cancelled`` 0), even on early failures, so consumers needn't wrap the call.
+
+        Args:
+            on_progress: ``(percent, status, message)`` callback.
+            is_cancelled: predicate polled between waypoints to stop cooperatively.
+            save_dir: output dir for artifacts; defaults to a timestamped ``/tmp`` dir.
+            routine: sphere-routine dict overriding
+                :data:`~griip_sdk.calibration.routines.DEFAULT_ENCIRCLE_ROUTINE`.
+            bootstrap_path: pre-computed bootstrap result to skip the bootstrap leg.
+        """
+        # Compose the consumer's callback with the SDK's own MQTT publisher (if a
+        # broker was configured) so the terminal ticks below also reach the UI.
+        mqtt_progress = self._mqtt_publisher.make_on_progress(HAND_EYE_PROGRESS_TOPIC) if self._mqtt_publisher else None
+        effective_on_progress = compose_on_progress(on_progress, mqtt_progress)
+        try:
+            service = self._build_hand_eye_service(
+                save_dir=save_dir,
+                routine=routine,
+                bootstrap_path=bootstrap_path,
+            )
+            x_cam_flg: SE3 = service.calibrate(on_progress=effective_on_progress, is_cancelled=is_cancelled)
+            config_name = self._hand_eye_name()
+            self._store.add_new_version(config_name, {"X_cam_flg": x_cam_flg.A.tolist()})
+            logger.info("Saved %s under %s", config_name, self._store.root)
+        except CalibrationCancelledError:
+            self._emit_terminal(effective_on_progress, 0, "cancelled", "Hand-eye calibration cancelled")
+            raise
+        except Exception as exc:
+            self._emit_terminal(effective_on_progress, 0, "error", f"Hand-eye calibration failed: {exc}")
+            raise
+        else:
+            self._emit_terminal(effective_on_progress, 100, "success", "Hand-eye calibration complete")
+            return x_cam_flg
+
+    @staticmethod
+    def _emit_terminal(
+        on_progress: Callable[[int, str, str], None] | None,
+        percent: int,
+        status: str,
+        message: str,
+    ) -> None:
+        """Emit one guarded terminal ``on_progress`` tick (no-op if unset)."""
+        if on_progress is not None:
+            on_progress(percent, status, message)
+
+    def last_hand_eye_calibration_timestamp(self) -> datetime | None:
+        return self._store.timestamp_of(self._hand_eye_name())
+
+    # ----- Environment-scan session ----------------------------------
+
+    def start_environment_session(self, save_dir: Path | None = None) -> Path:
+        """Open a new operator-driven environment-scan session.
+
+        Builds the :class:`EnvironmentScanningService`, creates the sequence
+        directory, persists post-crop intrinsics, and switches the robot into
+        freedrive. Raises ``RuntimeError`` if a session is already open; returns
+        the sequence directory.
+        """
+        if self._env_session_service is not None:
+            raise RuntimeError(
+                "An environment-scan session is already open; call end_environment_session() first.",
+            )
+
+        x_tcp_flg = self._env_scan_tcp_offset_transform()
+        previous_tcp_offset = self._robot_client.X_tcp_flg
+        self._robot_client.set_tcp_offset(x_tcp_flg)
+
+        try:
+            service = self._build_env_scan_service(save_dir=save_dir, x_tcp_flg=x_tcp_flg)
+            sequence_dir = service.start_session()
+            next_index = service.resume_index(sequence_dir)
+        except Exception:
+            # Restore the frame mutated above so a failed start can't strand the
+            # robot on the env-scan offset -- and so a retry doesn't capture the
+            # mutated offset as its "previous" and later restore to the wrong frame.
+            self._robot_client.set_tcp_offset(previous_tcp_offset)
+            raise
+
+        # Commit session state only once the start fully succeeded.
+        self._env_session_previous_tcp_offset = previous_tcp_offset
+        self._env_session_service = service
+        self._env_session_sequence_dir = sequence_dir
+        self._env_session_next_index = next_index
+        self._publish_env_progress(
+            "in_progress",
+            f"Session started: {sequence_dir.name}",
+            extra={"sessionName": sequence_dir.name, "photoCount": self._env_session_next_index},
+        )
+        return sequence_dir
+
+    def take_environment_image(self) -> int:
+        """Capture one frame in the current session and return its index.
+
+        Reads the TCP pose, grabs stereo + depth, and writes the per-frame files
+        under the active sequence directory (robot stays in freedrive between
+        captures). Raises ``RuntimeError`` if no session is open.
+        """
+        service, sequence_dir = self._require_open_session()
+        frame_index = self._env_session_next_index
+        service.capture_frame(sequence_dir, frame_index)
+        self._env_session_next_index += 1
+        self._publish_env_progress(
+            "in_progress",
+            f"Captured photo {self._env_session_next_index}",
+            extra={
+                "sessionName": sequence_dir.name,
+                "photoCount": self._env_session_next_index,
+            },
+        )
+        return frame_index
+
+    def end_environment_session(self) -> Path:
+        """Close the active session, restore the robot, and persist a store entry
+        pointing at the sequence directory.
+
+        Returns the sequence directory. Raises ``RuntimeError`` if no session is open.
+        """
+        service, sequence_dir = self._require_open_session()
+        photo_count = self._env_session_next_index
+        try:
+            service.end_session()
+        finally:
+            # Restore the TCP offset mutated at session start (so a later
+            # hand-eye run plans from the same frame), then clear session state.
+            # Both must run even if end_session() raises, or a failed close
+            # leaves a zombie service the next end_environment_session() would
+            # re-close. Restore before reset: the reset clears the saved offset.
+            if self._env_session_previous_tcp_offset is not None:
+                self._robot_client.set_tcp_offset(self._env_session_previous_tcp_offset)
+            self._reset_env_session_state()
+        config_name = self._env_scan_name()
+        self._store.add_new_version(config_name, {"sequence_dir": str(sequence_dir)})
+        logger.info("Saved %s under %s", config_name, self._store.root)
+        self._publish_env_progress(
+            "success",
+            f"Session ended: {photo_count} photo(s) saved",
+            extra={"sessionName": None, "photoCount": photo_count},
+        )
+        return sequence_dir
+
+    def _publish_env_progress(self, status: str, message: str, *, extra: dict[str, Any]) -> None:
+        """Publish an environment-scan progress event to MQTT (no-op if unconfigured)."""
+        if self._mqtt_publisher is None:
+            return
+        payload = {"status": status, "message": message, **extra}
+        self._mqtt_publisher.publish(ENVIRONMENT_PROGRESS_TOPIC, payload)
+
+    def last_environment_scan_timestamp(self) -> datetime | None:
+        return self._store.timestamp_of(self._env_scan_name())
+
+    def _reset_env_session_state(self) -> None:
+        """Clear the operator-driven environment-scan session state."""
+        self._env_session_service = None
+        self._env_session_sequence_dir = None
+        self._env_session_next_index = 0
+        self._env_session_previous_tcp_offset = None
+
+    def _require_open_session(self) -> tuple[EnvironmentScanningService, Path]:
+        """Return the open session's ``(service, sequence_dir)`` or raise ``RuntimeError``."""
+        if self._env_session_service is None or self._env_session_sequence_dir is None:
+            raise RuntimeError(
+                "No environment-scan session open; call start_environment_session() first.",
+            )
+        return self._env_session_service, self._env_session_sequence_dir
+
+    # ----- Name builders ----------------------------------------------
+
+    def _hand_eye_name(self) -> str:
+        return CalibrationConfigStore.format_config_name(
+            "X_cam_flg",
+            self._cam_name,
+            self._camera_mxid,
+            self._sensor,
+        )
+
+    def _env_scan_name(self) -> str:
+        return CalibrationConfigStore.format_config_name("env_scan", self._cam_name, self._camera_mxid)
+
+    # ----- Service builders -------------------------------------------
+
+    def _resolve_calibration(self) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64], int, int, float]:
+        """Resolve intrinsics/distortion/baseline for ``self._sensor`` via the vision ABC.
+
+        If the store has no calibio entry: ``strict_intrinsics=True`` (default)
+        raises :class:`FileNotFoundError` naming the missing config;
+        ``strict_intrinsics=False`` logs a warning and proceeds with whatever
+        calibration ``vision_backend`` currently reports -- the camera-swap
+        escape hatch for a fresh camera with no calibio data yet. Either way,
+        the backend itself owns applying calibio (see
+        :class:`~griip_sdk.hardware.mmai_vision_backend.MmaiVisionServiceBackend`);
+        this only gates the strict check and reads the result.
+
+        The calibio store gate only applies to the legacy ``mmai`` camera
+        backend; native gRPC vision services own their calibration, so their
+        reported intrinsics are authoritative as-is.
+
+        Returns ``(cam_intr, dist_coeffs, im_width, im_height, stereo_baseline)``.
+        """
+        if self._cell.camera.backend == "mmai":
+            intr_config_name = CalibrationConfigStore.format_config_name(
+                "calibio",
+                self._cam_name,
+                self._camera_mxid,
+            )
+            if not self._store.list_versions(intr_config_name):
+                if self._strict_intrinsics:
+                    raise FileNotFoundError(
+                        f"No intrinsic calibration found in store for '{intr_config_name}'. "
+                        f"Upload calibio intrinsics under {self._store.root / intr_config_name}, or "
+                        "construct the app with `strict_intrinsics=False` to fall back to live "
+                        "camera defaults.",
+                    )
+                logger.warning(
+                    "No calibio intrinsics for '%s' in store; falling back to live camera defaults (strict_intrinsics=False).",
+                    intr_config_name,
+                )
+        cam_intr, dist_coeffs, im_width, im_height, stereo_baseline, _, _ = resolve_camera_calibration(
+            self._vision_backend, self._sensor, self._secondary_source_id
+        )
+        return cam_intr, dist_coeffs, im_width, im_height, stereo_baseline
+
+    def _resolve_calibration_joints(self) -> list[float]:
+        """Return ``cell.positions.calibration_joints`` or raise :class:`ConfigError`.
+
+        The cell YAML is the single source of truth for the starting pose -- no
+        runtime fallback. A missing field is an operator-actionable config problem.
+        """
+        joints = self._cell.positions.calibration_joints
+        if joints is None:
+            raise ConfigError(
+                f"cell.positions.calibration_joints is not set in {self._config_path}. "
+                "Commissioning needs to author the starting pose in the cell YAML before "
+                "calibration can run.",
+            )
+        return list(joints)
+
+    def _resolve_save_dir(self, save_dir: Path | None, default: str) -> Path:
+        """Return ``save_dir`` (or a timestamped ``default``), created on disk."""
+        resolved = Path(save_dir) if save_dir is not None else Path(default)
+        resolved.mkdir(parents=True, exist_ok=True)
+        return resolved
+
+    def _build_hand_eye_service(
+        self,
+        *,
+        save_dir: Path | None,
+        routine: dict[str, Any] | None,
+        bootstrap_path: Path | None,
+    ) -> HandEyeCalibrationService:
+        cam_intr, dist_coeffs, im_width, im_height, _stereo_baseline = self._resolve_calibration()
+
+        # Bundled routine wins by default; consumers override with `routine=`.
+        # The legacy hand_eye_routine.yaml-next-to-cell-yaml lookup is gone.
+        calibration_routine = routine if routine is not None else DEFAULT_ENCIRCLE_ROUTINE
+
+        resolved_save_dir = self._resolve_save_dir(save_dir, f"/tmp/hand_eye_calibration_{utc_ts()}")
+
+        return HandEyeCalibrationService(
+            robo=self._robot_client,
+            vision_backend=self._vision_backend,
+            store=self._store,
+            planning_stub=cast(griip_pb2_grpc.PlanningServiceStub, self._planning_stub),
+            config=calibration_routine,
+            cam_intr=cam_intr,
+            dist_coeffs=dist_coeffs,
+            im_width=im_width,
+            im_height=im_height,
+            sensor_name=self._sensor,
+            save_dir=str(resolved_save_dir),
+            calibration_joint_angles=self._resolve_calibration_joints(),
+            bootstrap_path=str(bootstrap_path) if bootstrap_path is not None else None,
+            velocity_scaling=self._cell.motion.calibration.velocity_scaling,
+            acceleration_scaling=self._cell.motion.calibration.acceleration_scaling,
+        )
+
+    def _env_scan_tcp_offset_transform(self) -> SE3:
+        """Build the flange-to-TCP offset transform from ``cell.tool``."""
+        if self._cell.tool is None:
+            logger.warning(
+                "cell.tool is unset; defaulting tcp_offset to [0,0,0]. Env-scan output will be miscalibrated "
+                "for cells with a physically-mounted tool.",
+            )
+            tcp_offset = [0.0, 0.0, 0.0]
+        else:
+            tcp_offset = list(self._cell.tool.tcp_offset)
+        return SE3.Rt(R=SO3(), t=np.array(tcp_offset, dtype=np.float64))
+
+    def _build_env_scan_service(self, *, save_dir: Path | None, x_tcp_flg: SE3) -> EnvironmentScanningService:
+        cam_intr, _dist_coeffs, image_width, image_height, stereo_baseline = self._resolve_calibration()
+
+        x_cam_flg = load_camera_to_flange_transform(
+            camera_vendor=self._cam_name,
+            camera_mx_id=self._camera_mxid,
+            sensor=self._sensor,
+            calibration_data_path=self._calib_data_root,
+        )
+        x_cam_tcp = compute_camera_to_tcp_transform(x_cam_flg, x_tcp_flg)
+
+        resolved_save_dir = self._resolve_save_dir(save_dir, f"/data/vention/scene_scanning_dataset_{utc_ts()}")
+
+        return EnvironmentScanningService(
+            robot_client=self._robot_client,
+            vision_backend=self._vision_backend,
+            left_source_id=self._sensor,
+            right_source_id=self._secondary_source_id,
+            perception_stub=self._perception_stub,
+            camera_intrinsics=cam_intr,
+            x_cam_tcp=x_cam_tcp,
+            stereo_baseline=stereo_baseline,
+            save_dir=resolved_save_dir,
+            image_width=image_width,
+            image_height=image_height,
+        )
+
+
+def _build_in_process_planning_stub(
+    robot_client: VrmcsRobotClient,
+    cell: PrototypeCellConfig,
+    cell_config_directory: Path,
+    *,
+    cuboids_path_override: str | None = None,
+) -> PlanningStub:
+    # Lazy import: pulls mmai_griip_api transitively (dev-only dep; see
+    # pyproject.toml). Importing it at module top-level would break wheel installs.
+    from mmai_griip_api.api.planning_api import PlanningApi
+    from mmai_griip_api.api.service_registry import ServiceRegistry
+
+    planning_service = build_and_configure_hand_eye_planning_service(
+        robot_client,
+        cell,
+        cell_config_directory,
+        cuboids_path_override=cuboids_path_override,
+    )
+    registry = ServiceRegistry()
+    registry.planning_service = planning_service
+    return ServicerAsStub(PlanningApi(registry))
+
+
+def _build_in_process_perception_stub(cell: PrototypeCellConfig) -> PerceptionStub:
+    # Lazy import: same reasoning as _build_in_process_planning_stub.
+    from mmai_griip_api.api.perception_api import PerceptionApi
+    from mmai_griip_api.api.service_registry import ServiceRegistry
+    from mmai_griip_api.services.perception.foundation_stereo_client import FoundationStereoClient
+    from mmai_griip_api.services.perception.perception_service import PerceptionService
+
+    foundation_stereo_client = FoundationStereoClient(host=cell.perception.services.foundation_stereo)
+    perception_service = PerceptionService(
+        sam_client=None,
+        foundation_pose_client=None,
+        foundation_stereo_client=foundation_stereo_client,
+    )
+    registry = ServiceRegistry()
+    registry.perception_service = perception_service
+    return ServicerAsStub(PerceptionApi(registry))
+
+
+def _build_grpc_calibration_stubs(griip_api_url: str) -> tuple[grpc.Channel, PlanningStub, PerceptionStub]:
+    """Open a gRPC channel to ``griip_api_url``; return ``(channel, planning_stub, perception_stub)``.
+
+    Uses the SDK's own generated stubs so callers don't need the dev-only
+    ``mmai_griip_api`` package. The caller closes the channel.
+    """
+    channel = grpc.insecure_channel(griip_api_url)
+    planning_stub = griip_pb2_grpc.PlanningServiceStub(channel)
+    perception_stub = griip_pb2_grpc.PerceptionServiceStub(channel)
+    return channel, planning_stub, perception_stub
+
+
+def _initialize_remote_api(channel: grpc.Channel, cell: PrototypeCellConfig) -> None:
+    """Register the remote planning subsystem before ``ConfigurePlanner``.
+
+    A fresh server holds no ``PlanningService`` until ``GriipApiAdmin.Initialize``
+    runs; until then ``ConfigurePlanner``/``PlanPath`` abort with ``UNAVAILABLE``.
+    Sends a part-free, perception-mocked Initialize that builds the planner and
+    registers the robot with VRMCS.
+
+    Idempotent. Initialize replaces the server's service registry, so calibration
+    and picking sessions must not share one server concurrently.
+    """
+    admin_stub = griip_pb2_grpc.GriipApiAdminStub(channel)
+    send_initialize(admin_stub, build_robot_initialize_request(cell.model_dump(mode="python")))
+    logger.info("Remote mmai-griip-api initialized for hand-eye (robot registered; server-side perception mocked)")
+
+
+def _configure_remote_planner(
+    planning_stub: PlanningStub,
+    cell: PrototypeCellConfig,
+    cell_config_directory: Path,
+    *,
+    cuboids_path_override: str | None = None,
+) -> None:
+    """Send the hand-eye :class:`pb.ConfigurePlannerRequest` over a gRPC stub.
+
+    Shares :func:`resolve_hand_eye_planner_params` with the in-process path so
+    both transports resolve gripper spheres (via the
+    :class:`~griip_sdk.cell.end_effector_collision_model.EndEffectorCollisionModel`)
+    and cuboids identically. The spheres are always sent inline.
+    """
+    request_kwargs = resolve_hand_eye_planner_params(cell, cell_config_directory, cuboids_path_override=cuboids_path_override)
+    inline_spheres = request_kwargs.pop("gripper_collision_spheres")
+    request_kwargs["gripper_collision_spheres"] = [
+        pb.CollisionSpheres(center=pb.Vector3(x=sphere[0], y=sphere[1], z=sphere[2]), radius=sphere[3]) for sphere in inline_spheres
+    ]
+
+    response = planning_stub.ConfigurePlanner(pb.ConfigurePlannerRequest(**request_kwargs))
+    logger.info(
+        "Hand-eye PlanningService configured over gRPC: environment_id=%s robot_dof=%s cuboids=%d",
+        response.environment_id,
+        response.robot_dof,
+        response.num_cuboids_loaded,
+    )
+
+
+@contextmanager
+def build_calibration_app(
+    cell_yaml: Path | str,
+    *,
+    calib_data: Path | str | None = None,
+    cuboids_path: Path | str | None = None,
+    mqtt_host: str | None = "localhost",
+    mqtt_port: int = 1883,
+    strict_intrinsics: bool = True,
+) -> Iterator[CalibrationApp]:
+    """Yield a wired :class:`CalibrationApp` for the cell at ``cell_yaml``.
+
+    Loads the config, builds the robot + camera clients, wires planning +
+    perception stubs (in-process for ``griip_api.mode: direct``; gRPC for
+    ``grpc``), and builds the store. In gRPC mode it first issues a part-free
+    Initialize then ``ConfigurePlanner`` (without Initialize the latter aborts
+    with ``UNAVAILABLE``). On exit, releases the robot registration if this client
+    created it (failures logged) and
+    closes the channel. To inject custom stubs, construct :class:`CalibrationApp`
+    directly -- its ``__init__`` is keyword-only.
+
+    Args:
+        cell_yaml: path to the cell YAML.
+        calib_data: store root; defaults to :data:`DEFAULT_CALIBRATION_DATA_PATH`.
+        cuboids_path: override for the VAMP collision cuboids; defaults to
+            ``cell.environment.cuboids_path``.
+        mqtt_host: broker host for live progress events; defaults to
+            ``"localhost"``. Pass ``None`` to disable publishing. Hand-eye ticks
+            land on ``griip/calibration/hand_eye/progress``, environment ticks on
+            ``griip/calibration/environment/progress``; the React components in
+            ``@vention/machine-apps-components`` subscribe to both.
+        mqtt_port: broker port; defaults to ``1883``.
+        strict_intrinsics: when ``True`` (default), missing calibio intrinsics
+            raise :class:`FileNotFoundError`; ``False`` falls back to live
+            ``camera_info`` (camera-swap escape hatch).
+    """
+    resolved_path = Path(cell_yaml).expanduser().resolve()
+    cell = load_cell_config(resolved_path)
+
+    effective_cuboids_path = cell.environment.cuboids_path
+    if cuboids_path is not None:
+        effective_cuboids_path = str(Path(cuboids_path).expanduser().resolve())
+        logger.info("Using cuboids_path override: %s -> %s", cell.environment.cuboids_path, effective_cuboids_path)
+
+    logger.info("=== build_calibration_app ===")
+    logger.info("Config: %s     griip_api.mode: %s", resolved_path, cell.griip_api.mode)
+
+    robot_client = build_vrmcs_client(resolved_path, cell)
+    grpc_channel: grpc.Channel | None = None
+    mqtt_publisher: MqttProgressPublisher | None = None
+    if mqtt_host is not None:
+        mqtt_publisher = MqttProgressPublisher(host=mqtt_host, port=mqtt_port)
+    try:
+        robot_client.reset_to_normal()
+
+        sensor = cell.camera.sensor
+        secondary_source_id = cell.camera.right_source_id
+        calib_root: Path | str = calib_data if calib_data is not None else DEFAULT_CALIBRATION_DATA_PATH
+        store = CalibrationConfigStore(root=calib_root)
+
+        # require_calibio=False: the app gates calibio per-verb via
+        # strict_intrinsics (see _resolve_calibration) instead of at build time.
+        camera = build_calibration_camera(cell.camera, store=store, require_calibio=False)
+
+        if cell.griip_api.mode == "grpc":
+            grpc_channel, planning_stub, perception_stub = _build_grpc_calibration_stubs(cell.griip_api.url)
+            logger.info("Connected to mmai-griip-api over gRPC at %s", cell.griip_api.url)
+            _initialize_remote_api(grpc_channel, cell)
+            _configure_remote_planner(planning_stub, cell, resolved_path.parent, cuboids_path_override=effective_cuboids_path)
+        else:
+            planning_stub = _build_in_process_planning_stub(
+                robot_client, cell, resolved_path.parent, cuboids_path_override=effective_cuboids_path
+            )
+            perception_stub = _build_in_process_perception_stub(cell)
+
+        yield CalibrationApp(
+            cell=cell,
+            config_path=resolved_path,
+            robot_client=robot_client,
+            vision_backend=camera.vision_backend,
+            cam_name=camera.camera_vendor,
+            camera_mxid=camera.camera_mx_id,
+            sensor=sensor,
+            secondary_source_id=secondary_source_id,
+            store=store,
+            calib_data_root=calib_root,
+            planning_stub=planning_stub,
+            perception_stub=perception_stub,
+            mqtt_publisher=mqtt_publisher,
+            strict_intrinsics=strict_intrinsics,
+        )
+    finally:
+        try:
+            robot_client.release_registration()
+        except Exception as exc:
+            logger.warning("release_registration: %s", exc)
+        if grpc_channel is not None:
+            grpc_channel.close()
+        if mqtt_publisher is not None:
+            mqtt_publisher.close()