MR-Cal Guide

Multiple Robot Calibration Guide — interactive reference.

🚀 Open the live site → cal.valpatel.com

A free, public, plain-English reference for camera, LiDAR, and IMU calibration — what the techniques are, when each one wins, what research it comes from, and which permissively-licensed software implements it. Designed to demystify a topic that's currently spread across hundreds of papers and dozens of single-purpose repos.

🔗 Quick links

📚 Browse all 16 topics	papers · open-source software (license-badged) · real hardware part numbers
🧪 19 technique deep-dives	Zhang's method · ICP · AX = XB · Kalibr · bundle adjustment · Allan variance · …
🖼 Animation gallery (137 beats)	every interactive scene, every beat, with captions
📖 Glossary	68 plain-English term definitions
🏗 Architecture	how the site itself is built (no build step, no framework)
✍️ Contributing	adding a paper / a software / a topic / an animation
☁️ Deploy	Cloudflare Pages step-by-step
🚀 Onboarding	first-week path for a new contributor
📒 Project glossary	codebase-internal terms (anim-host, beat, slug, lazy-mount, …) — not the calibration jargon
🗺 System map	bird's-eye diagrams: surface area · data flow · asset relationships · test pipeline
📋 Requirements	inviolable contracts (R-01 … R-NN) — read before merging
📝 Changelog	curated rollup by ship-date

Gallery

Six picks from the 21 interactive animations. Click any tile for the topic doc (papers, software, hardware); see the full screenshot index → for every beat of every animation.

Levinson LiDAR refinement per-beam offsets converging on flat ground	Multi-LiDAR ICP two scans converging into a single cloud	Hand-eye AX = XB two LiDARs on a moving robot
LiDAR-IMU time offset aligning gyro rate vs LiDAR pose rate	Fisheye projection models pinhole vs Kannala-Brandt vs double-sphere	Asymmetric stepped block why symmetric targets fail (4 pose ghosts)

What's in here

• Topic pages for every common calibration relationship — mono camera, wide-FoV / fisheye, stereo, multi-camera, LiDAR intrinsics, multi-LiDAR extrinsics, IMU, camera-LiDAR, camera-IMU, LiDAR-IMU, calibration targets, hand-eye / robot-sensor.
• Real research citations — papers with arXiv / IEEE / venue links, year, authors.
• Permissive software index — every tool we cite is verified MIT / BSD / Apache-2.0 / MPL-2.0. GPL/LGPL/AGPL projects are flagged so readers can avoid accidental contamination.
• Real hardware part numbers — Ouster OS-series, Hesai Pandar, Velodyne VLP/HDL, Livox, AprilTag boards, etc., with datasheet links.
• 21 interactive Three.js animations — pinhole projection, ICP convergence, Allan variance, hand-eye AX=XB, fisheye ray-bending, Zhang's method walkthrough, six-position IMU cal, Levinson-Thrun refinement, asymmetric stepped block, the works. Every animation has its own dedicated title bar, canvas, and narration panel with captions + opt-in TTS narration that follows the scene beat-by-beat.
• Portrait + landscape variants for every animation, with a state-preserving orientation remount controller (rotate your phone mid-narration; you don't lose the beat).
• Narration-driven cinematography — each animation ships a per-beat camera script that re-frames the scene to focus on whatever the narration is currently discussing.
• Tradeoffs, glossary, and a beginner-friendly tone throughout.

Why this exists

Robotics calibration is critical, copyleft-heavy, and woefully under-explained for newcomers. MR-Cal Guide is a deliberate counter-program: free, plain-English, permissively-licensed references, and interactive explanations of the math.

The guide stands on its own — read it, fork it, share it, mirror it. It's published by Valpatel Software.

Run locally

# Any static server. The guide ships zero build step.
npx serve .                      # http://localhost:3000
# or
python3 -m http.server 8080      # http://localhost:8080

Stack

Vanilla HTML + ES modules + Three.js (loaded via importmap from unpkg). No build step. Drops onto any static host. Ships fast, stays maintainable, no framework treadmill.

mr-cal-guide/
├── index.html        ← landing page
├── glossary.html
├── about.html
├── topics/           ← one HTML page per topic (16 topics)
├── styles/
│   ├── theme.css     ← shared dark cyberpunk theme
│   └── guide.css     ← guide-specific layout (titles, panels, citations)
├── js/
│   ├── nav.js        ← injects header + side rail + section collapsing
│   ├── citations.js  ← renders paper / software / part chips
│   ├── narration.js  ← captions + word-sync; plays pre-rendered Piper audio
│   ├── viewer.js     ← mountAnim + orientation remount controller
│   ├── common/       ← shared library (sensors, targets, minimap, hud-controls,
│   │                   hud-panel, narration-sync, orientation, state-bus,
│   │                   reduced-motion, trail, camera-script) — see
│   │                   docs/architecture/stack.md "Framework vs project boundary"
│   └── animations/   ← one folder per animation:
│                       <slug>/{index,landscape,portrait,shared}.js
├── data/
│   ├── topics.json         ← list of topics + slugs + categories
│   ├── schema.md           ← citation JSON schema
│   ├── by-topic/           ← per-topic citations — 14 files (ros + isaac-sim
│   │                         are orientation pages without citations)
│   ├── narration/          ← per-animation narration scripts — 21 JSON files
│   └── camera-scripts/     ← per-animation camera plans — 21 JSON files
├── audio/narration/  ← pre-rendered Piper voice clips, one folder per slug
├── scripts/render-narration.py  ← regenerate the audio above
├── images/targets/   ← 9 printable SVG calibration targets
├── tests/            ← pytest + Playwright + (opt-in) VLM suite
│   ├── conftest.py
│   ├── test_pages_load.py / test_animations.py / test_narration.py / …
│   ├── test_chaos_fuzz.py / test_external_links.py
│   ├── visual/        ← OpenCV + VLM + OCR + caption-stability + wheel-zoom
│   └── README.md      ← how to run + what each file does
├── scripts/
│   ├── render-narration.py      ← regenerate audio
│   ├── build-docs.py            ← regenerate docs/topics + docs/gallery
│   ├── build-test-reports.py    ← aggregate probe reports → data/testing/summary.json
│   ├── refresh-dashboard.sh     ← run every probe + rebuild the dashboard
│   ├── scan-*.py                ← individual probes (web-vitals, heap-growth, …)
│   ├── naive-user-review.py     ← overnight VLM "first-time visitor" loop
│   ├── review-test-reports.py   ← LLM reviewer that annotates each suite card
│   ├── llm-server-setup.sh      ← manage remote Ollama / llama-server CUDA backend
│   ├── setup-visual-tests.sh    ← one-time pip install for OpenCV layer
│   └── setup-vlm.sh             ← one-time remote Ollama install for VLM layer
├── .env.example      ← visual-test config template (copy to .env)
├── _headers          ← Cloudflare Pages security headers
└── DEPLOY.md         ← Cloudflare Pages step-by-step

Testing infrastructure

A 21-suite dashboard at /about/test-reports.html aggregates every probe on the repo into one live status page. The explainer page at /about/testing.html walks through every suite in plain English (philosophy, what it catches, where the report lives) — that's the place to read if you want the full picture.

To run the whole thing locally:

# Prereq: http.server on :8000 (the probes drive a headless Chromium
# against localhost:8000 — they never hit the production site).
python3 -m http.server 8000 &

# Full refresh (~45 min):
scripts/refresh-dashboard.sh            # incremental
scripts/refresh-dashboard.sh --clean    # wipe previous artefacts first
scripts/refresh-dashboard.sh --quick    # skip chaos-fuzz (saves ~20 min)
scripts/refresh-dashboard.sh --only vitals   # run a single stage

Opt-in pytest gates (each gated on a MRCAL_GATE_* env var so they stay out of CI by default):

Var	Gate
MRCAL_GATE_FRAMING=1	per-(anim × viewport) beat-0 framing check
MRCAL_GATE_FRAMING_PER_BEAT=1	every camera-script beat × viewport
MRCAL_GATE_WHEEL_ZOOM=1	wheel-zoom doesn't fall through / blank / break clamp
MRCAL_VLM_ENABLED=1	semantic scene check against a local VLM
MRCAL_LINK_CHECK_EXTERNAL=1	every external URL reachable

Full probe-by-probe + pytest tables, env vars, and an LLM reviewer loop are documented in tests/README.md and on /about/testing.html.

Deploy

See DEPLOY.md for Cloudflare Pages instructions (literally: connect the repo, set build = none, output = /).

Contributing

Each topic is one HTML page in topics/<slug>.html plus one JSON file in data/by-topic/<slug>.json. The HTML follows topics/_template.html. Citations follow data/schema.md.

To add a topic:

1. Copy topics/_template.html → topics/<your-slug>.html.
2. Fill in the placeholders (search for {{ }} markers).
3. Add citations to data/by-topic/<your-slug>.json.
4. Append your slug to data/topics.json.
5. Optionally: add a Three.js animation in js/animations/<your-slug>.js.

Next steps for contributors

• docs/ONBOARDING.md — the first-week path; what to read in what order.
• docs/REQUIREMENTS.md — the contracts every change has to respect.

License

MIT — see LICENSE. © 2026 Valpatel Software · Created by Matthew Valancy. Use it however you like.