From 12231e43debdd59da74d02432fdfd13805f673d6 Mon Sep 17 00:00:00 2001
From: ravindu somawansa <ravindu.somawansa@gmail.com>
Date: Mon, 12 Oct 2026 15:10:43 +0200
Subject: [PATCH] feat(cameras): ghost overlay of a saved reference frame to
 realign the rig

---
 .../control/BrowserCameraPreview.test.tsx     | 10 +++
 .../control/BrowserCameraPreview.tsx          | 16 ++++
 .../src/components/landing/RecordingModal.tsx |  5 +-
 .../recording/CameraConfiguration.test.tsx    | 16 ++++
 .../recording/CameraConfiguration.tsx         | 32 ++++++-
 .../recording/CameraReferenceControls.tsx     | 67 ++++++++++++++
 frontend/src/hooks/useCameraReference.ts      | 68 ++++++++++++++
 frontend/src/lib/cameraReferenceApi.test.ts   | 25 ++++++
 frontend/src/lib/cameraReferenceApi.ts        | 57 ++++++++++++
 lelab/camera_reference.py                     | 70 +++++++++++++++
 lelab/server.py                               | 36 +++++++-
 lelab/utils/config.py                         |  3 +
 tests/test_camera_reference.py                | 89 +++++++++++++++++++
 13 files changed, 491 insertions(+), 3 deletions(-)
 create mode 100644 frontend/src/components/recording/CameraReferenceControls.tsx
 create mode 100644 frontend/src/hooks/useCameraReference.ts
 create mode 100644 frontend/src/lib/cameraReferenceApi.test.ts
 create mode 100644 frontend/src/lib/cameraReferenceApi.ts
 create mode 100644 lelab/camera_reference.py
 create mode 100644 tests/test_camera_reference.py

diff --git a/frontend/src/components/control/BrowserCameraPreview.test.tsx b/frontend/src/components/control/BrowserCameraPreview.test.tsx
index 818c762a7..c6bca6f70 100644
--- a/frontend/src/components/control/BrowserCameraPreview.test.tsx
+++ b/frontend/src/components/control/BrowserCameraPreview.test.tsx
@@ -39,3 +39,13 @@ test("a stream at another size keeps the recorded aspect ratio", () => {
   expect(video.style.width).toBe("100%");
   expect(video.style.objectFit).toBe("cover");
 });
+test("the reference ghost sits over the video with its rotation and opacity", () => {
+  act(() => root.render(<BrowserCameraPreview deviceId="wrist" rotation={90} ghostSrc="blob:ref" ghostOpacity={0.3} />));
+  const video = container.querySelector("video")!, ghost = container.querySelector("img")!;
+  expect(ghost.getAttribute("src")).toBe("blob:ref");
+  expect(ghost.style.opacity).toBe("0.3");
+  expect(ghost.style.transform).toBe(video.style.transform);
+  expect(ghost.style.width).toBe(video.style.width);
+  act(() => root.render(<BrowserCameraPreview deviceId="wrist" />));
+  expect(container.querySelector("img")).toBeNull();
+});
diff --git a/frontend/src/components/control/BrowserCameraPreview.tsx b/frontend/src/components/control/BrowserCameraPreview.tsx
index de6107d99..b2b693345 100644
--- a/frontend/src/components/control/BrowserCameraPreview.tsx
+++ b/frontend/src/components/control/BrowserCameraPreview.tsx
@@ -11,6 +11,9 @@ interface Props {
   height?: number;
   className?: string;
   fallback?: string;
+  /** Saved reference frame, drawn over the live video as a translucent ghost. */
+  ghostSrc?: string;
+  ghostOpacity?: number;
 }
 
 /**
@@ -26,6 +29,8 @@ export default function BrowserCameraPreview({
   height = 480,
   className = "",
   fallback,
+  ghostSrc,
+  ghostOpacity = 0.5,
 }: Props) {
   const rotationError = cameraRotationError({ rotation });
   const { videoRef, hasError } = useCameraStream(deviceId, paused || !!rotationError, { width, height });
@@ -39,6 +44,7 @@ export default function BrowserCameraPreview({
       style={{ aspectRatio: geometry.aspectRatio }}
     >
       {showVideo ? (
+        <>
         <video
           ref={videoRef}
           autoPlay
@@ -46,6 +52,16 @@ export default function BrowserCameraPreview({
           playsInline
           style={geometry.videoStyle}
         />
+        {ghostSrc && (
+          <img
+            src={ghostSrc}
+            alt=""
+            aria-hidden
+            className="pointer-events-none"
+            style={{ ...geometry.videoStyle, opacity: ghostOpacity }}
+          />
+        )}
+        </>
       ) : (
         <div className="absolute inset-0 flex flex-col items-center justify-center">
           <VideoOff className="w-5 h-5 text-gray-500 mb-1" />
diff --git a/frontend/src/components/landing/RecordingModal.tsx b/frontend/src/components/landing/RecordingModal.tsx
index 4c45e0195..0cff4ee1a 100644
--- a/frontend/src/components/landing/RecordingModal.tsx
+++ b/frontend/src/components/landing/RecordingModal.tsx
@@ -282,10 +282,13 @@ const RecordingModal: React.FC<RecordingModalProps> = ({
                   onCamerasChange={setCameras}
                   releaseStreamsRef={releaseStreamsRef}
                   readOnly
+                  robotName={robot?.name}
                 />
                 <p className="text-xs text-gray-500">
                   These are the cameras set up for this robot. To add or change a
-                  camera, configure it on the Calibration page.
+                  camera, configure it on the Calibration page. Save a reference
+                  frame to see it as a ghost over the live preview and realign
+                  the rig next session.
                 </p>
               </div>
             )}
diff --git a/frontend/src/components/recording/CameraConfiguration.test.tsx b/frontend/src/components/recording/CameraConfiguration.test.tsx
index cf33c3a18..571552e9c 100644
--- a/frontend/src/components/recording/CameraConfiguration.test.tsx
+++ b/frontend/src/components/recording/CameraConfiguration.test.tsx
@@ -6,6 +6,8 @@ import CameraConfiguration from "./CameraConfiguration";
 import { CameraConfig, normalizeCameraConfig, serializeCameras } from "@/lib/cameraConfig";
 vi.mock("@/hooks/useAvailableCameras", () => ({ useAvailableCameras: () => ({ cameras: [], isLoading: false, refresh: vi.fn() }) }));
 vi.mock("@/hooks/use-toast", () => ({ useToast: () => ({ toast: vi.fn() }) }));
+const reference = { url: null as string | null, error: null, save: vi.fn(), clear: vi.fn() };
+vi.mock("@/hooks/useCameraReference", () => ({ useCameraReference: () => reference }));
 vi.mock("@/hooks/useCameraStream", () => ({ useCameraStream: () => ({ videoRef: React.createRef<HTMLVideoElement>(), hasError: false }) }));
 let root: Root;
 let container: HTMLDivElement;
@@ -43,3 +45,17 @@ test("an invalid stored rotation stays visible until the user selects a valid va
   act(() => { select.value = "180"; select.dispatchEvent(new Event("change", { bubbles: true })); });
   expect(change).toHaveBeenCalledWith([{ ...camera, rotation: 180 }]);
 });
+test("reference controls appear only for a named robot in read-only mode", () => {
+  act(() => root.render(<CameraConfiguration cameras={[camera]} onCamerasChange={vi.fn()} readOnly />));
+  expect(container.textContent).not.toContain("Set reference");
+  act(() => root.render(<CameraConfiguration cameras={[camera]} onCamerasChange={vi.fn()} readOnly robotName="arm" />));
+  expect(container.textContent).toContain("Set reference");
+  expect(container.querySelector('input[type="range"]')).toBeNull();
+  reference.url = "blob:ref";
+  act(() => root.render(<CameraConfiguration cameras={[camera]} onCamerasChange={vi.fn()} readOnly robotName="arm" />));
+  expect(container.textContent).toContain("Replace reference");
+  expect(container.querySelector("img")!.getAttribute("src")).toBe("blob:ref");
+  const slider = container.querySelector<HTMLInputElement>('input[type="range"]')!;
+  expect(slider).not.toBeNull();
+  reference.url = null;
+});
diff --git a/frontend/src/components/recording/CameraConfiguration.tsx b/frontend/src/components/recording/CameraConfiguration.tsx
index aef2d80b9..60c6b6907 100644
--- a/frontend/src/components/recording/CameraConfiguration.tsx
+++ b/frontend/src/components/recording/CameraConfiguration.tsx
@@ -1,4 +1,4 @@
-import React, { useState, useEffect, useCallback } from "react";
+import React, { useState, useEffect, useCallback, useRef } from "react";
 import { Button } from "@/components/ui/button";
 import { Label } from "@/components/ui/label";
 import {
@@ -18,8 +18,10 @@ import {
 } from "@/components/ui/collapsible";
 import { useToast } from "@/hooks/use-toast";
 import { useAvailableCameras } from "@/hooks/useAvailableCameras";
+import { useCameraReference } from "@/hooks/useCameraReference";
 import BrowserCameraPreview from "@/components/control/BrowserCameraPreview";
 import CameraRotationSelect from "@/components/control/CameraRotationSelect";
+import CameraReferenceControls from "@/components/recording/CameraReferenceControls";
 import {
   CameraConfig,
   cameraRotation,
@@ -54,6 +56,9 @@ interface CameraConfigurationProps {
   // cameras as read-only live previews. Used in the recording dialog, where
   // cameras are managed on the Calibration page rather than added ad hoc.
   readOnly?: boolean;
+  // Robot the cameras belong to. In read-only mode this enables the reference
+  // frame controls, which are stored per robot and camera.
+  robotName?: string;
 }
 
 const CameraConfiguration: React.FC<CameraConfigurationProps> = ({
@@ -61,6 +66,7 @@ const CameraConfiguration: React.FC<CameraConfigurationProps> = ({
   onCamerasChange,
   releaseStreamsRef,
   readOnly = false,
+  robotName,
 }) => {
   const { toast } = useToast();
 
@@ -307,6 +313,7 @@ const CameraConfiguration: React.FC<CameraConfigurationProps> = ({
                 deviceId={previewDeviceId(camera, availableCameras)}
                 paused={streamsPaused}
                 readOnly={readOnly}
+                robotName={robotName}
                 onRemove={() => removeCamera(camera.id)}
                 onUpdate={(updates) => updateCamera(camera.id, updates)}
               />
@@ -334,6 +341,7 @@ interface CameraPreviewProps {
   deviceId: string;
   paused: boolean;
   readOnly: boolean;
+  robotName?: string;
   onRemove: () => void;
   onUpdate: (updates: Partial<CameraConfig>) => void;
 }
@@ -343,22 +351,30 @@ const CameraPreview: React.FC<CameraPreviewProps> = ({
   deviceId,
   paused,
   readOnly,
+  robotName,
   onRemove,
   onUpdate,
 }) => {
+  const previewRef = useRef<HTMLDivElement>(null);
+  const [ghostOpacity, setGhostOpacity] = useState(0.5);
+  const reference = useCameraReference(readOnly ? robotName : undefined, camera.name);
   const rotationError = cameraRotationError(camera);
   const rotation = rotationError ? null : cameraRotation(camera.rotation);
   const output = rotation === null ? null : rotatedDimensions(camera.width, camera.height, rotation);
   return (
     <div className="bg-gray-900 rounded-lg border border-gray-700 overflow-hidden">
+      <div ref={previewRef}>
       <BrowserCameraPreview
         deviceId={deviceId}
         paused={paused}
+        ghostSrc={reference.url ?? undefined}
+        ghostOpacity={ghostOpacity}
         rotation={camera.rotation}
         width={camera.width}
         height={camera.height}
         fallback={paused ? "Preview paused" : deviceId ? undefined : "No browser match"}
       />
+      </div>
 
       {/* Camera Info */}
       <div className="p-3 space-y-2">
@@ -376,6 +392,20 @@ const CameraPreview: React.FC<CameraPreviewProps> = ({
           )}
         </div>
 
+        {readOnly && robotName && (
+          <CameraReferenceControls
+            hasReference={!!reference.url}
+            opacity={ghostOpacity}
+            onOpacityChange={setGhostOpacity}
+            onSave={() => {
+              const video = previewRef.current?.querySelector("video");
+              if (video) void reference.save(video);
+            }}
+            onClear={() => void reference.clear()}
+            disabled={paused || !!rotationError}
+            error={reference.error}
+          />
+        )}
         {rotationError && <p role="alert" className="text-xs text-red-400">{rotationError} Select a valid rotation.</p>}
         {readOnly ? (
           <p className="text-xs text-gray-400">
diff --git a/frontend/src/components/recording/CameraReferenceControls.tsx b/frontend/src/components/recording/CameraReferenceControls.tsx
new file mode 100644
index 000000000..c23e97acc
--- /dev/null
+++ b/frontend/src/components/recording/CameraReferenceControls.tsx
@@ -0,0 +1,67 @@
+import React from "react";
+import { Button } from "@/components/ui/button";
+
+interface Props {
+  hasReference: boolean;
+  opacity: number;
+  onOpacityChange: (opacity: number) => void;
+  onSave: () => void;
+  onClear: () => void;
+  disabled: boolean;
+  error: string | null;
+}
+
+/** Save the current frame as the reference, then slide the ghost overlay over the live preview. */
+const CameraReferenceControls: React.FC<Props> = ({
+  hasReference,
+  opacity,
+  onOpacityChange,
+  onSave,
+  onClear,
+  disabled,
+  error,
+}) => (
+  <div className="space-y-1.5">
+    <div className="flex items-center gap-2">
+      <Button
+        type="button"
+        size="sm"
+        variant="outline"
+        onClick={onSave}
+        disabled={disabled}
+        className="h-7 px-2 text-xs bg-gray-800 border-gray-700 text-white hover:bg-gray-700"
+      >
+        {hasReference ? "Replace reference" : "Set reference"}
+      </Button>
+      {hasReference && (
+        <Button
+          type="button"
+          size="sm"
+          variant="ghost"
+          onClick={onClear}
+          className="h-7 px-2 text-xs text-gray-400 hover:text-white"
+        >
+          Clear
+        </Button>
+      )}
+    </div>
+    {hasReference && (
+      <label className="flex items-center gap-2 text-xs text-gray-400">
+        Ghost
+        <input
+          type="range"
+          min={0}
+          max={1}
+          step={0.05}
+          value={opacity}
+          onChange={(e) => onOpacityChange(Number(e.target.value))}
+          className="flex-1"
+          aria-label="Reference overlay opacity"
+        />
+      </label>
+    )}
+    {error && <p role="alert" className="text-xs text-red-400">{error}</p>}
+  </div>
+);
+
+export default CameraReferenceControls;
diff --git a/frontend/src/hooks/useCameraReference.ts b/frontend/src/hooks/useCameraReference.ts
new file mode 100644
index 000000000..8dea95a37
--- /dev/null
+++ b/frontend/src/hooks/useCameraReference.ts
@@ -0,0 +1,68 @@
+import { useCallback, useEffect, useState } from "react";
+import { useApi } from "@/contexts/ApiContext";
+import {
+  captureVideoFrame,
+  deleteCameraReference,
+  getCameraReference,
+  saveCameraReference,
+} from "@/lib/cameraReferenceApi";
+
+/**
+ * The saved reference frame for one robot camera, as an object URL ready to use
+ * as an `<img src>`. Pass `robot = undefined` to disable it.
+ */
+export function useCameraReference(robot: string | undefined, camera: string) {
+  const { baseUrl, fetchWithHeaders } = useApi();
+  const [url, setUrl] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const show = useCallback((blob: Blob | null) => {
+    setUrl((prev) => {
+      if (prev) URL.revokeObjectURL(prev);
+      return blob ? URL.createObjectURL(blob) : null;
+    });
+  }, []);
+
+  useEffect(() => {
+    if (!robot) return;
+    const controller = new AbortController();
+    getCameraReference(baseUrl, fetchWithHeaders, robot, camera, controller.signal)
+      .then(show)
+      .catch((e) => {
+        if (!controller.signal.aborted) setError(String(e.message ?? e));
+      });
+    return () => {
+      controller.abort();
+      show(null);
+    };
+  }, [robot, camera, baseUrl, fetchWithHeaders, show]);
+
+  const save = useCallback(
+    async (video: HTMLVideoElement) => {
+      if (!robot) return;
+      setError(null);
+      try {
+        const png = await captureVideoFrame(video);
+        if (!png) throw new Error("No frame to capture yet");
+        await saveCameraReference(baseUrl, fetchWithHeaders, robot, camera, png);
+        show(png);
+      } catch (e) {
+        setError(e instanceof Error ? e.message : String(e));
+      }
+    },
+    [robot, camera, baseUrl, fetchWithHeaders, show],
+  );
+
+  const clear = useCallback(async () => {
+    if (!robot) return;
+    setError(null);
+    try {
+      await deleteCameraReference(baseUrl, fetchWithHeaders, robot, camera);
+      show(null);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e));
+    }
+  }, [robot, camera, baseUrl, fetchWithHeaders, show]);
+
+  return { url, error, save, clear };
+}
diff --git a/frontend/src/lib/cameraReferenceApi.test.ts b/frontend/src/lib/cameraReferenceApi.test.ts
new file mode 100644
index 000000000..74028bc02
--- /dev/null
+++ b/frontend/src/lib/cameraReferenceApi.test.ts
@@ -0,0 +1,25 @@
+import { expect, test, vi } from "vitest";
+
+import { getCameraReference, saveCameraReference } from "./cameraReferenceApi";
+
+const BASE = "http://localhost:8000";
+
+test("a missing reference reads as null rather than an error", async () => {
+  const fetcher = vi.fn().mockResolvedValue(new Response("{}", { status: 404 }));
+  await expect(getCameraReference(BASE, fetcher, "my arm", "front")).resolves.toBeNull();
+  expect(fetcher.mock.calls[0][0]).toBe(`${BASE}/robots/my%20arm/camera-reference/front`);
+});
+
+test("saving puts the PNG bytes and surfaces a rejection", async () => {
+  const png = new Blob(["png"], { type: "image/png" });
+  const fetcher = vi.fn().mockResolvedValueOnce(new Response("{}", { status: 200 }));
+  await saveCameraReference(BASE, fetcher, "arm", "front", png);
+  expect(fetcher).toHaveBeenCalledWith(`${BASE}/robots/arm/camera-reference/front`, {
+    method: "PUT",
+    headers: { "Content-Type": "image/png" },
+    body: png,
+  });
+
+  fetcher.mockResolvedValueOnce(new Response("{}", { status: 400 }));
+  await expect(saveCameraReference(BASE, fetcher, "arm", "front", png)).rejects.toThrow("Save reference failed: 400");
+});
diff --git a/frontend/src/lib/cameraReferenceApi.ts b/frontend/src/lib/cameraReferenceApi.ts
new file mode 100644
index 000000000..94143cd32
--- /dev/null
+++ b/frontend/src/lib/cameraReferenceApi.ts
@@ -0,0 +1,57 @@
+import { ApiError, Fetcher, apiRequest } from "./apiClient";
+
+export function cameraReferenceUrl(baseUrl: string, robot: string, camera: string): string {
+  return `${baseUrl}/robots/${encodeURIComponent(robot)}/camera-reference/${encodeURIComponent(camera)}`;
+}
+
+/** The saved reference frame as a PNG blob, or null when none has been saved yet. */
+export async function getCameraReference(
+  baseUrl: string,
+  fetcher: Fetcher,
+  robot: string,
+  camera: string,
+  signal?: AbortSignal,
+): Promise<Blob | null> {
+  const r = await fetcher(cameraReferenceUrl(baseUrl, robot, camera), { signal });
+  if (r.status === 404) return null;
+  if (!r.ok) throw new ApiError(`Load reference failed: ${r.status}`, r.status, null);
+  return r.blob();
+}
+
+export async function saveCameraReference(
+  baseUrl: string,
+  fetcher: Fetcher,
+  robot: string,
+  camera: string,
+  png: Blob,
+): Promise<void> {
+  const r = await fetcher(cameraReferenceUrl(baseUrl, robot, camera), {
+    method: "PUT",
+    headers: { "Content-Type": "image/png" },
+    body: png,
+  });
+  if (!r.ok) throw new ApiError(`Save reference failed: ${r.status}`, r.status, null);
+}
+
+export async function deleteCameraReference(
+  baseUrl: string,
+  fetcher: Fetcher,
+  robot: string,
+  camera: string,
+): Promise<void> {
+  await apiRequest(baseUrl, fetcher, `/robots/${encodeURIComponent(robot)}/camera-reference/${encodeURIComponent(camera)}`, {
+    method: "DELETE",
+    action: "Delete reference",
+  });
+}
+
+/** Snapshot of the frame the preview is showing, unrotated like the stream itself. */
+export function captureVideoFrame(video: HTMLVideoElement): Promise<Blob | null> {
+  const canvas = document.createElement("canvas");
+  canvas.width = video.videoWidth;
+  canvas.height = video.videoHeight;
+  const ctx = canvas.getContext("2d");
+  if (!ctx || !canvas.width || !canvas.height) return Promise.resolve(null);
+  ctx.drawImage(video, 0, 0);
+  return new Promise((resolve) => canvas.toBlob(resolve, "image/png"));
+}
diff --git a/lelab/camera_reference.py b/lelab/camera_reference.py
new file mode 100644
index 000000000..5d5e910b9
--- /dev/null
+++ b/lelab/camera_reference.py
@@ -0,0 +1,70 @@
+# Copyright 2025 The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Reference frames for realigning a stashed rig.
+
+The frontend grabs one frame per camera from its live preview and saves it here,
+then overlays it as a ghost on later previews. The backend only stores the PNG
+and never opens a camera, so it can't compete with the browser or the recorder
+for the device.
+"""
+
+from __future__ import annotations
+
+import os
+
+from .utils import config
+
+_PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+MAX_REFERENCE_BYTES = 10 * 1024 * 1024
+
+
+class InvalidReferenceError(ValueError):
+    """The robot/camera name or the image payload is unusable."""
+
+
+def _reference_path(robot: str, camera: str) -> str:
+    # Reuses the robot-name check: neither part may contain path separators or "..".
+    if not config.is_valid_robot_name(robot) or not config.is_valid_robot_name(camera):
+        raise InvalidReferenceError("Invalid robot or camera name")
+    return os.path.join(config.CAMERA_REFERENCES_PATH, robot, f"{camera}.png")
+
+
+def load_reference(robot: str, camera: str) -> bytes | None:
+    path = _reference_path(robot, camera)
+    if not os.path.isfile(path):
+        return None
+    with open(path, "rb") as f:
+        return f.read()
+
+
+def save_reference(robot: str, camera: str, png: bytes) -> None:
+    path = _reference_path(robot, camera)
+    if not png.startswith(_PNG_SIGNATURE):
+        raise InvalidReferenceError("Reference must be a PNG image")
+    if len(png) > MAX_REFERENCE_BYTES:
+        raise InvalidReferenceError("Reference image is too large")
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    tmp = f"{path}.tmp"
+    with open(tmp, "wb") as f:
+        f.write(png)
+    os.replace(tmp, path)
+
+
+def delete_reference(robot: str, camera: str) -> bool:
+    path = _reference_path(robot, camera)
+    if not os.path.isfile(path):
+        return False
+    os.remove(path)
+    return True
diff --git a/lelab/server.py b/lelab/server.py
index 57943acc7..b245a59ad 100644
--- a/lelab/server.py
+++ b/lelab/server.py
@@ -37,7 +37,7 @@
 from starlette.types import Scope
 
 # Import our custom recording functionality
-from . import datasets as dataset_browser, record as _record
+from . import camera_reference, datasets as dataset_browser, record as _record
 
 # Import our custom calibration functionality
 from .calibrate import CalibrationRequest, calibration_manager
@@ -1397,6 +1397,40 @@ def delete_robot(name: str):
     return JSONResponse(status_code=404, content={"status": "error", "message": "Robot not found"})
 
 
+@app.get("/robots/{name}/camera-reference/{camera}")
+def get_camera_reference(name: str, camera: str):
+    """The saved reference frame for one of a robot's cameras, as a PNG."""
+    try:
+        png = camera_reference.load_reference(name, camera)
+    except camera_reference.InvalidReferenceError as e:
+        return JSONResponse(status_code=400, content={"status": "error", "message": str(e)})
+    if png is None:
+        return JSONResponse(status_code=404, content={"status": "error", "message": "No reference saved"})
+    # The frame is replaced in place on re-save, so the browser must revalidate.
+    return Response(content=png, media_type="image/png", headers={"Cache-Control": "no-cache"})
+
+
+@app.put("/robots/{name}/camera-reference/{camera}")
+async def put_camera_reference(name: str, camera: str, request: Request):
+    """Save the request body (a PNG) as the reference frame for one camera."""
+    try:
+        camera_reference.save_reference(name, camera, await request.body())
+    except camera_reference.InvalidReferenceError as e:
+        return JSONResponse(status_code=400, content={"status": "error", "message": str(e)})
+    return {"status": "success"}
+
+
+@app.delete("/robots/{name}/camera-reference/{camera}")
+def delete_camera_reference(name: str, camera: str):
+    try:
+        deleted = camera_reference.delete_reference(name, camera)
+    except camera_reference.InvalidReferenceError as e:
+        return JSONResponse(status_code=400, content={"status": "error", "message": str(e)})
+    if not deleted:
+        return JSONResponse(status_code=404, content={"status": "error", "message": "No reference saved"})
+    return {"status": "success"}
+
+
 @app.on_event("startup")
 def startup_event():
     """One-time startup diagnostics surfaced in the server terminal."""
diff --git a/lelab/utils/config.py b/lelab/utils/config.py
index f5ae25da8..3d9eceac4 100644
--- a/lelab/utils/config.py
+++ b/lelab/utils/config.py
@@ -44,6 +44,9 @@
 # Robot config records (per-robot JSON metadata)
 ROBOTS_PATH = os.path.expanduser("~/.cache/huggingface/lerobot/robots")
 
+# Saved camera reference frames, one PNG per robot/camera (see lelab/camera_reference.py)
+CAMERA_REFERENCES_PATH = os.path.expanduser("~/.cache/huggingface/lerobot/camera_references")
+
 # Tag stamped on every dataset pushed to the Hub from LeLab, so we can later
 # query the Hub for LeLab-produced datasets and compute usage metrics.
 LELAB_TAG = "LeLab"
diff --git a/tests/test_camera_reference.py b/tests/test_camera_reference.py
new file mode 100644
index 000000000..f2f4a6d46
--- /dev/null
+++ b/tests/test_camera_reference.py
@@ -0,0 +1,89 @@
+# Copyright 2025 The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Tests for lelab.camera_reference and its /robots/{name}/camera-reference endpoints."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from fastapi.testclient import TestClient
+
+from lelab import camera_reference
+from lelab.server import app
+
+PNG = b"\x89PNG\r\n\x1a\n" + b"\x00" * 16
+
+
+@pytest.fixture
+def references_dir(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    path = tmp_path / "camera_references"
+    monkeypatch.setattr("lelab.utils.config.CAMERA_REFERENCES_PATH", str(path))
+    return path
+
+
+@pytest.fixture
+def client() -> TestClient:
+    return TestClient(app)
+
+
+def test_save_then_load_round_trips_and_overwrites(references_dir: Path) -> None:
+    assert camera_reference.load_reference("arm", "front") is None
+    camera_reference.save_reference("arm", "front", PNG)
+    assert camera_reference.load_reference("arm", "front") == PNG
+    newer = PNG + b"\x01"
+    camera_reference.save_reference("arm", "front", newer)
+    assert camera_reference.load_reference("arm", "front") == newer
+    assert not list(references_dir.rglob("*.tmp"))
+
+
+def test_save_rejects_non_png_and_oversized(references_dir: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    with pytest.raises(camera_reference.InvalidReferenceError):
+        camera_reference.save_reference("arm", "front", b"not a png")
+    monkeypatch.setattr(camera_reference, "MAX_REFERENCE_BYTES", 10)
+    with pytest.raises(camera_reference.InvalidReferenceError):
+        camera_reference.save_reference("arm", "front", PNG)
+    assert not references_dir.exists()
+
+
+@pytest.mark.parametrize(
+    "robot,camera", [("..", "front"), ("arm", "../front"), ("a/b", "front"), ("arm", "")]
+)
+def test_names_cannot_escape_the_references_dir(references_dir: Path, robot: str, camera: str) -> None:
+    with pytest.raises(camera_reference.InvalidReferenceError):
+        camera_reference.save_reference(robot, camera, PNG)
+
+
+def test_delete_reports_whether_anything_was_removed(references_dir: Path) -> None:
+    assert camera_reference.delete_reference("arm", "front") is False
+    camera_reference.save_reference("arm", "front", PNG)
+    assert camera_reference.delete_reference("arm", "front") is True
+    assert camera_reference.load_reference("arm", "front") is None
+
+
+def test_endpoints_put_get_delete(references_dir: Path, client: TestClient) -> None:
+    url = "/robots/arm/camera-reference/front"
+    assert client.get(url).status_code == 404
+    assert client.put(url, content=PNG).status_code == 200
+    got = client.get(url)
+    assert got.status_code == 200
+    assert got.headers["content-type"] == "image/png"
+    assert got.content == PNG
+    assert client.delete(url).status_code == 200
+    assert client.delete(url).status_code == 404
+
+
+def test_endpoint_rejects_non_png(references_dir: Path, client: TestClient) -> None:
+    assert client.put("/robots/arm/camera-reference/front", content=b"nope").status_code == 400