Buckets:
AnonymousSpottedToad/candidate_bucket / codebase /python /ruvnet_RuView /scripts /calibrate-camera-room.py
| #!/usr/bin/env python3 | |
| """Two-checkerboard camera-room calibration for WiFi pose training (ADR-152 S2.1.3). | |
| Aligns the ADR-079 ground-truth camera and the ESP32 WiFi transceivers in | |
| one shared 3D room frame -- the PerceptAlign (arXiv 2601.12252) defense | |
| against "coordinate overfitting", where CSI-to-camera-coordinate regression | |
| memorizes the deployment layout and collapses cross-layout. | |
| Procedure (<5 minutes): | |
| 1. Print a checkerboard (default 9x6 inner corners, 25 mm squares). | |
| 2. Tape one board flat on the ORIGIN WALL, tape-measure its top-left inner | |
| corner position in room coordinates (+x along wall, +y into room, +z up). | |
| 3. Lay the second board flat on the FLOOR, measure its near-left inner corner. | |
| 4. With the collection camera in its final position, photograph each board. | |
| 5. Run this script; tape-measure each ESP32 node position when prompted | |
| (or pass --geometry nodes.json). | |
| Output: a calibration bundle JSON consumed by | |
| scripts/collect-ground-truth.py --calibration <bundle.json> | |
| Usage: | |
| python scripts/calibrate-camera-room.py \\ | |
| --wall-image photos/wall.jpg --wall-origin 0.50,0.0,1.60 \\ | |
| --floor-image photos/floor.jpg --floor-origin 1.00,1.00,0.0 \\ | |
| --calib-images "photos/intrinsics/*.jpg" \\ | |
| --geometry config/transceivers.json \\ | |
| --output data/calibration/camera-room.json | |
| """ | |
| from __future__ import annotations | |
| import argparse | |
| import glob | |
| import json | |
| import sys | |
| from datetime import datetime | |
| from pathlib import Path | |
| import cv2 | |
| import numpy as np | |
| sys.path.insert(0, str(Path(__file__).resolve().parent)) | |
| import calibration_lib as cal # noqa: E402 | |
| INTRINSICS_CACHE = Path("data") / ".cache" / "camera_intrinsics.json" | |
| def parse_vec3(text: str) -> np.ndarray: | |
| parts = [float(p) for p in text.replace(",", " ").split()] | |
| if len(parts) != 3: | |
| raise argparse.ArgumentTypeError(f"Expected 3 comma-separated numbers, got {text!r}") | |
| return np.array(parts, dtype=np.float64) | |
| def detect_corners(image_path: Path, cols: int, rows: int) -> tuple[np.ndarray, tuple[int, int]]: | |
| image = cv2.imread(str(image_path)) | |
| if image is None: | |
| print(f"ERROR: Cannot read image {image_path}", file=sys.stderr) | |
| sys.exit(1) | |
| corners = cal.find_board_corners(image, cols, rows) | |
| if corners is None: | |
| print( | |
| f"ERROR: No {cols}x{rows} checkerboard found in {image_path}. " | |
| "Check lighting, focus, and the --board-cols/--board-rows flags.", | |
| file=sys.stderr, | |
| ) | |
| sys.exit(1) | |
| h, w = image.shape[:2] | |
| return corners, (w, h) | |
| def resolve_intrinsics(args, repo_root: Path, board_args: tuple[int, int, float]) -> dict: | |
| """Pre-computed file > cached > computed from --calib-images > | |
| last-resort 2-view estimate from the wall+floor photos themselves.""" | |
| cols, rows, square_m = board_args | |
| if args.intrinsics: | |
| print(f"Intrinsics: loading {args.intrinsics}") | |
| return cal.load_intrinsics(Path(args.intrinsics)) | |
| cache_path = repo_root / INTRINSICS_CACHE | |
| if cache_path.exists() and not args.recalibrate_intrinsics: | |
| print(f"Intrinsics: using cached {cache_path} (pass --recalibrate-intrinsics to redo)") | |
| intr = cal.load_intrinsics(cache_path) | |
| intr["source"] = "cached" | |
| return intr | |
| if args.calib_images: | |
| paths = sorted(glob.glob(args.calib_images)) | |
| if len(paths) < 3: | |
| print( | |
| f"ERROR: --calib-images matched only {len(paths)} file(s); " | |
| "need >= 3 checkerboard views for stable intrinsics.", | |
| file=sys.stderr, | |
| ) | |
| sys.exit(1) | |
| corner_sets, image_size = [], None | |
| for p in paths: | |
| corners, size = detect_corners(Path(p), cols, rows) | |
| if image_size is None: | |
| image_size = size | |
| elif size != image_size: | |
| print(f"ERROR: {p} has size {size}, expected {image_size}.", file=sys.stderr) | |
| sys.exit(1) | |
| corner_sets.append(corners) | |
| print(f" corners found: {p}") | |
| intr = cal.compute_intrinsics(corner_sets, image_size, cols, rows, square_m) | |
| print(f"Intrinsics: computed from {len(paths)} views, " | |
| f"reprojection RMS {intr['reprojection_error_px']:.3f} px") | |
| cal.save_bundle(intr, cache_path) # plain JSON write; reused on next run | |
| print(f" cached to {cache_path}") | |
| return intr | |
| # Last resort: 2-view calibration from the extrinsic photos. Workable but | |
| # weak -- warn loudly and recommend a proper multi-view pass. | |
| print( | |
| "WARNING: no --intrinsics / cache / --calib-images; estimating intrinsics " | |
| "from the wall+floor photos alone (2 views, low quality). Prefer " | |
| "--calib-images with 5-10 varied board views.", | |
| file=sys.stderr, | |
| ) | |
| corner_sets, image_size = [], None | |
| for p in (args.wall_image, args.floor_image): | |
| corners, size = detect_corners(Path(p), cols, rows) | |
| image_size = image_size or size | |
| corner_sets.append(corners) | |
| intr = cal.compute_intrinsics(corner_sets, image_size, cols, rows, square_m) | |
| intr["source"] = "two-view-fallback" | |
| return intr | |
| def prompt_transceiver_geometry() -> dict: | |
| """Tape-measure entry of ESP32 node positions in room coordinates.""" | |
| print() | |
| print("Transceiver geometry -- enter one node per line:") | |
| print(" <node-id> <x> <y> <z> [yaw_deg] (meters, room frame; blank line to finish)") | |
| print(" example: esp32-s3-a 0.10 2.40 1.10 180") | |
| nodes = [] | |
| while True: | |
| try: | |
| line = input("node> ").strip() | |
| except EOFError: | |
| break | |
| if not line: | |
| break | |
| parts = line.split() | |
| if len(parts) not in (4, 5): | |
| print(" expected: <node-id> <x> <y> <z> [yaw_deg]", file=sys.stderr) | |
| continue | |
| try: | |
| node = {"id": parts[0], "position_m": [float(parts[1]), float(parts[2]), float(parts[3])]} | |
| if len(parts) == 5: | |
| node["antenna_yaw_deg"] = float(parts[4]) | |
| except ValueError: | |
| print(" positions must be numeric", file=sys.stderr) | |
| continue | |
| nodes.append(node) | |
| if not nodes: | |
| print("WARNING: no transceiver nodes entered; bundle will carry empty geometry.", | |
| file=sys.stderr) | |
| return {"nodes": nodes, "units": "meters", "source": "tape-measure-prompt"} | |
| def load_geometry_file(path: Path) -> dict: | |
| with open(path, "r", encoding="utf-8") as f: | |
| data = json.load(f) | |
| nodes = data.get("nodes", data if isinstance(data, list) else None) | |
| if nodes is None: | |
| raise ValueError(f"{path}: expected {{'nodes': [...]}} or a top-level list") | |
| for node in nodes: | |
| if "id" not in node or "position_m" not in node: | |
| raise ValueError(f"{path}: each node needs 'id' and 'position_m' [x,y,z]") | |
| return {"nodes": nodes, "units": "meters", "source": "file"} | |
| def main(): | |
| parser = argparse.ArgumentParser( | |
| description="Two-checkerboard camera-room calibration (ADR-152 S2.1.3 / ADR-079)." | |
| ) | |
| parser.add_argument("--wall-image", required=True, | |
| help="Photo of the checkerboard on the origin wall") | |
| parser.add_argument("--floor-image", required=True, | |
| help="Photo of the checkerboard on the floor (camera NOT moved)") | |
| parser.add_argument("--wall-origin", type=parse_vec3, default="0.5,0.0,1.6", | |
| help="Room xyz (m) of the wall board's first inner corner " | |
| "(default: 0.5,0.0,1.6)") | |
| parser.add_argument("--floor-origin", type=parse_vec3, default="1.0,1.0,0.0", | |
| help="Room xyz (m) of the floor board's first inner corner " | |
| "(default: 1.0,1.0,0.0)") | |
| parser.add_argument("--wall-axes", default="+x,-z", | |
| help="Wall board column,row directions in room frame (default: +x,-z)") | |
| parser.add_argument("--floor-axes", default="+x,+y", | |
| help="Floor board column,row directions in room frame (default: +x,+y)") | |
| parser.add_argument("--board-cols", type=int, default=cal.DEFAULT_BOARD_COLS, | |
| help=f"Inner corners per row (default: {cal.DEFAULT_BOARD_COLS})") | |
| parser.add_argument("--board-rows", type=int, default=cal.DEFAULT_BOARD_ROWS, | |
| help=f"Inner corners per column (default: {cal.DEFAULT_BOARD_ROWS})") | |
| parser.add_argument("--square-size-mm", type=float, default=cal.DEFAULT_SQUARE_SIZE_MM, | |
| help=f"Checkerboard square size in mm (default: {cal.DEFAULT_SQUARE_SIZE_MM})") | |
| parser.add_argument("--intrinsics", help="Pre-computed intrinsics JSON (skips computation)") | |
| parser.add_argument("--calib-images", | |
| help="Glob of >=3 checkerboard photos for intrinsics computation") | |
| parser.add_argument("--recalibrate-intrinsics", action="store_true", | |
| help="Ignore the cached intrinsics and recompute") | |
| parser.add_argument("--geometry", | |
| help="Transceiver geometry JSON ({nodes:[{id,position_m,[antenna_yaw_deg]}]}); " | |
| "omit to be prompted for tape-measure entry") | |
| parser.add_argument("--output", default=None, | |
| help="Bundle output path (default: data/calibration/camera-room-<ts>.json)") | |
| args = parser.parse_args() | |
| if isinstance(args.wall_origin, str): | |
| args.wall_origin = parse_vec3(args.wall_origin) | |
| if isinstance(args.floor_origin, str): | |
| args.floor_origin = parse_vec3(args.floor_origin) | |
| repo_root = Path(__file__).resolve().parent.parent | |
| cols, rows = args.board_cols, args.board_rows | |
| square_m = args.square_size_mm / 1000.0 | |
| # --- Intrinsics --- | |
| intrinsics = resolve_intrinsics(args, repo_root, (cols, rows, square_m)) | |
| camera_matrix = np.asarray(intrinsics["camera_matrix"], dtype=np.float64) | |
| dist_coeffs = np.asarray(intrinsics["dist_coeffs"], dtype=np.float64) | |
| # --- Corner detection on the two placed boards --- | |
| wall_corners, wall_size = detect_corners(Path(args.wall_image), cols, rows) | |
| floor_corners, floor_size = detect_corners(Path(args.floor_image), cols, rows) | |
| if wall_size != floor_size: | |
| print(f"ERROR: wall image {wall_size} and floor image {floor_size} differ in size; " | |
| "both must come from the fixed collection camera.", file=sys.stderr) | |
| sys.exit(1) | |
| print(f"Corners detected: wall + floor boards ({cols}x{rows}, {args.square_size_mm} mm)") | |
| # Re-scale intrinsics if they were computed at a different resolution | |
| # than the extrinsic photos (the bundle always stores K at wall_size). | |
| intr_size = tuple(intrinsics["image_size"]) | |
| if intr_size != wall_size: | |
| sx, sy = wall_size[0] / intr_size[0], wall_size[1] / intr_size[1] | |
| camera_matrix[0, 0] *= sx | |
| camera_matrix[0, 2] *= sx | |
| camera_matrix[1, 1] *= sy | |
| camera_matrix[1, 2] *= sy | |
| print(f" intrinsics scaled {intr_size} -> {wall_size}") | |
| intrinsics = {**intrinsics, "camera_matrix": camera_matrix.tolist(), | |
| "image_size": list(wall_size)} | |
| # --- Room-frame corner positions from the measured placements --- | |
| wall_u, wall_v = (cal.parse_axis(t) for t in args.wall_axes.split(",")) | |
| floor_u, floor_v = (cal.parse_axis(t) for t in args.floor_axes.split(",")) | |
| wall_room = cal.board_room_points(cols, rows, square_m, args.wall_origin, wall_u, wall_v) | |
| floor_room = cal.board_room_points(cols, rows, square_m, args.floor_origin, floor_u, floor_v) | |
| # --- Extrinsics: joint two-board solve (resolves per-board corner-order | |
| # ambiguity -- a single planar board is centrosymmetric; the pair is not) --- | |
| extrinsics = cal.solve_two_board_extrinsics( | |
| wall_room, wall_corners, floor_room, floor_corners, camera_matrix, dist_coeffs | |
| ) | |
| wall_rmse = extrinsics["per_board"]["wall"]["rmse_px"] | |
| floor_rmse = extrinsics["per_board"]["floor"]["rmse_px"] | |
| print(f" joint solve: RMSE {extrinsics['rmse_px']:.3f} px " | |
| f"(wall {wall_rmse:.3f} / floor {floor_rmse:.3f})") | |
| print(f" camera at room {np.round(extrinsics['translation_m'], 3).tolist()} m") | |
| if max(wall_rmse, floor_rmse) > 3.0: | |
| print( | |
| "WARNING: high per-board reprojection error -- re-check the measured " | |
| "board origins/axes and that the camera did not move between photos.", | |
| file=sys.stderr, | |
| ) | |
| # --- Transceiver geometry --- | |
| if args.geometry: | |
| geometry = load_geometry_file(Path(args.geometry)) | |
| print(f"Transceiver geometry: {len(geometry['nodes'])} node(s) from {args.geometry}") | |
| else: | |
| geometry = prompt_transceiver_geometry() | |
| # --- Bundle --- | |
| bundle = cal.make_bundle( | |
| camera_intrinsics=intrinsics, | |
| camera_to_room_extrinsics=extrinsics, | |
| checkerboard_spec={"cols": cols, "rows": rows, "square_size_mm": args.square_size_mm}, | |
| transceiver_geometry=geometry, | |
| ) | |
| if args.output: | |
| out_path = Path(args.output) | |
| else: | |
| ts = datetime.now().strftime("%Y%m%d_%H%M%S") | |
| out_path = repo_root / "data" / "calibration" / f"camera-room-{ts}.json" | |
| cal.save_bundle(bundle, out_path) | |
| print() | |
| print("=== Calibration bundle written ===") | |
| print(f" path: {out_path}") | |
| print(f" calibration_id: {cal.calibration_id(bundle)}") | |
| print(f" next: python scripts/collect-ground-truth.py --calibration {out_path}") | |
| if __name__ == "__main__": | |
| main() | |
Xet Storage Details
- Size:
- 13.7 kB
- Xet hash:
- 7728ff504fa6dc848ea78375f12ffa3f57d7b0c895343055f37b11db17108259
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.