ref-metro

Scientific image-based metrology — measure real-world distances from two photographs using a known-size reference object and stereo triangulation.

---

Overview

ref-metro uses a stereo pair of photographs (two photos from slightly different positions) and a credit-card-sized reference object to triangulate true 3D distances. Place the reference card in the scene, take two photos ~20–30 cm apart, and measure any distance in the scene by clicking pairs of points.

• No AI, no machine learning, no automatic edge detection
• True 3D triangulation — not a planar homography approximation
• Works with any camera that produces JPEG or PNG files
• Uncertainty reported at 95% confidence

---

Requirements

• Python 3.12+
• Node.js 20+

---

Installation

Backend

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Frontend

cd frontend
npm install

---

Running

Development (both servers)

./scripts/dev.sh

Or individually:

# Backend
cd backend
source .venv/bin/activate
uvicorn src.main:app --reload --port 8000

# Frontend
cd frontend
npm run dev

The frontend runs at http://localhost:5173. The backend API runs at http://localhost:8000. API documentation is available at http://localhost:8000/docs.

---

Workflow

1. Upload — Select Image A and Image B (same scene, ~20–30 cm lateral separation, same camera).
2. Locate card — Click the 4 corners of the reference ID card in Image A. The backend automatically detects the card in Image B.
3. Measure — Click a point in Image A; an epipolar line guides you to the corresponding point in Image B. Repeat for the second endpoint. The backend triangulates and returns the 3D distance.

Each project supports up to 10 measurements. Results are shown in mm and cm with a ±uncertainty at 95% confidence.

---

Tips for Good Results

• Move the camera sideways (not closer/further) between shots — a ~20–30 cm baseline is ideal
• Keep the reference card fully visible and flat in both images
• Use the same camera for both images (focal length must be consistent)
• Ensure good texture in the scene — smooth uniform surfaces reduce feature matching quality
• Check the calibration quality indicator after card location: "good" epipolar error < 1 px

---

Project Persistence

Stereo projects are saved as JSON files in backend/data/stereo_projects/. Open the ☰ Projects drawer from the upload or measurement screen to reopen a previous session.

From the measurement screen you can also:

• ⬇ Image (PNG) — download Image A annotated with all measurement lines and labels
• ⬇ JSON — download the full project state

---

Keyboard Shortcuts

Key	Action
Esc	Cancel current draft measurement
Space + drag	Pan canvas
Scroll wheel	Zoom in / out
Middle mouse + drag	Pan canvas

---

Testing

cd backend
source .venv/bin/activate
pytest

# With coverage
pytest --cov=src --cov-report=term-missing

70 unit tests covering all engine modules.

---

Linting and Formatting

./scripts/lint.sh

Or individually:

cd backend
ruff check src tests
ruff format src tests
mypy src

---

Architecture

See PROJECT.md for architecture details. See docs/decisions.md for architectural decisions. See CHANGELOG.md for completed work history.

---

License

Private — all rights reserved.