Skip to content

About

Vision for a six-legged walking robot: camera calibration, marker-based range estimation with error bars and refusal thresholds, and a documented protocol for collecting a 2,000-frame labelled set. MP2 of a twelve-project series.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

hexapod-vision

CI Python Tests

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.


Status — 27 September 2026

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.


The three things no later processing can recover

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.


The print set

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.md

Frames are not in this repository

data/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.


Line endings are pinned

.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.


Third-party material

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.


Licence

MIT. See LICENSE.

About

Vision for a six-legged walking robot: camera calibration, marker-based range estimation with error bars and refusal thresholds, and a documented protocol for collecting a 2,000-frame labelled set. MP2 of a twelve-project series.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages