Monocular range estimation from a printed fiducial, for a six-legged robot. The printable targets, the collection protocol, the manifest, and the checks that catch a recording mistake in week two rather than in November.
Companion to hexapod-kinematics,
which holds the robot's constant table and kinematics. Neither repository
depends on the other.
MP2 is due 31 December 2026. Collection has not started and the protocol budgets September to November for it, so the schedule is the binding constraint and not the code.
| Printable marker set | done — print/ |
| Calibration board | done — print/ |
| Collection protocol | done — docs/ |
| Manifest template and checker | done — data/, tools/ |
| Capture tool | done — tools/capture.py. Fixed resolution checked on every frame, protocol filenames, never overwrites, saves the raw frame |
| Calibration tool | done — tools/calibrate_charuco.py. Writes the file vision/range.py reads; refuses mixed resolutions, fewer than 20 views, and a set that never reaches the image corners. 42 camera-free tests cover both tools, plus tools/selftest_calibrate_charuco.py against a synthetic camera of known focal length |
| Camera calibration | not started — needs the printed board and the photographs |
| Collection, 40 sessions x 50 frames | not started — September to November. 40 x 50 confirmed by the owner, 9 September |
| Range estimator and error analysis | working — vision/range.py, 27 tests |
Range geometry: what w_px means |
done — vision/geometry.py. Three estimators from the four detected corners: naive (mean of the four sides — +20 to +33 % at 60° of yaw, kept as the baseline), axis (harmonic mean of the least-foreshortened pair, lens distortion removed — exact for pure yaw or pitch at any offset), pose (planar homography — exact in theory, the most fragile far out and oblique) |
| Detection | done — tools/detect_frames.py. ArUco DICT_4X4_50, sub-pixel corner refinement on: without it every marker reads one pixel narrow, −2.2 % of range at 45 px. Writes raw corners only; everything after is re-derivable |
| Held-out evaluation against tape-measure ground truth | written, waits on frames — vision/evaluate.py, tools/evaluate.py. Split by session with a SHA-256 rule, committed before any result is read; the correction 1/Z = a/Z_est + b and the choice of estimator are both made on train sessions only |
| Stress test | tools/stress_detect.py → docs/stress_detect.md: rendered frames at 0.5–6 m under motion blur, defocus, dim light and JPEG. Motion blur of 9 px loses every marker beyond 1 m; the far limit is f_px · W / 20 (5.5 m at the planning figures). Planning figures, on a synthetic camera |
| EE4211 notebook | notebooks/ee4211_range_from_marker.ipynb — the course project's source (Colab or Jupyter). MODE = "demo" renders a synthetic collection and runs detection, the session split, the train-only correction, the report and the figures today; MODE = "real" reads tranche 1 from Drive. Every cell executed before release |
| Detection self-test | tools/selftest_detect.py — frames rendered at known range through a distorted camera, the real detector, the three estimators and the pipeline end to end. Run once on the collecting machine |
143 passing, 0 skipped. Standard library only, so CI needs no
pip install beyond pytest and cannot be broken by a wheel that does not exist
yet for a Python version in the matrix.
vision/range.py was written before any frame exists, deliberately. Every
input to Z = f_px * W_mm / w_px is a number, and apparent_width_px is its
exact algebraic inverse, so the geometry can be exercised against synthetic values
whose answer is known in advance. Writing it after collection would mean meeting
its refusal thresholds on real data, when a refused frame is one that has already
cost a session.
It reads f_px from a calibration file and will not invent one. Range is
linear in f_px; a spec-sheet focal length is a range estimate with a silent 20%
error, and laptop webcams are routinely 10-15 degrees from their quoted field of
view. A missing value raises rather than defaulting — a plausible number from an
uncalibrated camera is worse than an exception, because nothing downstream can
tell it apart from a real one.
Below 20 px of observed marker width it refuses; between 20 and 30 it returns
an estimate carrying a marginal label. Those thresholds are the protocol's, not
this module's.
| True distance | The image does not contain it. An unlabelled frame is a picture, not a data point |
| Session identity | Which frames share a camera setup, a room and a lighting condition. Lose it and the set cannot be split into train and test without leaking |
| Deliberately hard frames | A frame that was hard on purpose and one that failed by accident look identical afterwards |
Crops, resizes, re-detection and derived features can all be redone from the
file. These three cannot. tools/check_manifest.py treats a missing one as an
error; everything else is a warning.
| File | Job |
|---|---|
print/aruco_4x4_100mm.pdf |
4 range markers, DICT_4X4_50, IDs 0–3, 100 mm nominal |
print/charuco_a4_landscape.pdf |
ChArUco calibration board, DICT_5X5_100, 7×5 squares at 32 mm |
Different dictionaries on purpose. A ChArUco board built from 4X4_50
would carry IDs 0–16, and a frame containing both targets would report the
same ID twice with no way to say which target it came from.
Print at 100 %. No fit-to-page, matte paper, flat. Then measure the black square with calipers and write it down. Every range estimate divides by the measured width, not by 100 — a sheet that came out at 99.6 mm gives a clean 0.4 % bias on every frame in the set, which survives every sanity check because it moves nothing relative to anything else. The checker warns when a manifest records exactly 100.0.
Both PDFs are generated, committed, and checksummed. Generation is
byte-reproducible (reportlab invariant=1), so regenerating unchanged input
gives an identical file and the checksum means something.
python -m pytest tests/ -q
# regenerating the print set needs requirements-print.txt, CI does not
python -m tools.make_print_set --out print/
# collecting needs requirements-collect.txt (OpenCV with a window), CI does not
python -m tools.selftest_calibrate_charuco
python -m tools.capture --calibration --width 1280 --height 720
python -m tools.calibrate_charuco --images data/calibration/<folder> --square-mm <measured> --out data/calibration/intrinsics_<folder>.json
python -m tools.capture --session S001 --width 1280 --height 720 --detect
# after a session
python -m tools.check_manifest --manifest data/manifest.csv --frames data/frames
python -m tools.detect_frames --manifest data/manifest.csv --frames data/frames --out data/derived/detections.csv
# once, before any result is read: propose the split, check its strata, commit it
python -m tools.evaluate --manifest data/manifest.csv --propose-split data/split.json
# the held-out evaluation
python -m tools.evaluate --manifest data/manifest.csv --detections data/derived/detections.csv --camera data/calibration/intrinsics_<folder>.json --split data/split.json --out-md data/derived/evaluation.md
# once on the collecting machine, beside the calibration self-test
python -m tools.selftest_detect
# planning: detection and range under blur, defocus, dim light and JPEG, on rendered frames
python -m tools.stress_detect --out docs/stress_detect.mddata/manifest.csv is tracked. The 2000 JPEGs are not, and
.gitignore enforces it.
Git has no delete. A committed image stays in every clone forever, even after a later commit removes it. Several gigabytes of frames would make this repository permanently slow to clone, for data that is not the deliverable.
The manifest is the record: 2000 rows of text, diffable, reviewable, and
the thing that makes the images meaningful. A representative sample lives in
docs/samples/. The full set is held outside git with its own backup.
.gitattributes normalises text to LF and marks *.pdf and *.png binary.
Not a style preference — Git decides a file is binary by looking for a NUL
byte in its first 8000, and neither PDF here has one. Both were classified as
text and rewritten on a Windows checkout, which corrupts them. Anyone cloning
on Windows would have got a broken calibration target with no indication of it.
Found by the Windows half of the CI matrix; invisible on the machine that made
the files. tests/test_manifest.py fails if .gitattributes is removed.
The kit manufacturer's manuals, schematic and example source are referenced, never redistributed, and never copied into source. Nothing here is theirs. The ArUco and ChArUco markers are generated from OpenCV's public dictionaries.
MIT. See LICENSE.