Architecture

Goal: iterate quickly on dataset → geometry → metrics, from practical OpenCV-compatible ChArUco workflows to experimental central and non-central ray-based stereo models, without being blocked by OptiX.

Modules

  • src/stereocomplex/meta.py: metadata schema + validation (pixel pitch is mandatory, crop/resize/binning).

  • src/stereocomplex/core/geometry.py: pixel↔sensor (µm) conversions, minimal pinhole model, triangulation.

  • src/stereocomplex/sim/cpu/: CPU generator (textured board plane + GT correspondences).

  • src/stereocomplex/synthetic/parallel_plate.py: inclined parallel-plate oracle for physically plausible non-central synthetic rayfields.

  • src/stereocomplex/synthetic/parallel_plate_images.py: rendered ChArUco images with vignetting, blur, noise, and detection-front-end stressors for the non-central benchmark.

  • src/stereocomplex/eval/: metrics/evaluations (oracle, ChArUco detection vs GT, compression sweeps).

  • src/stereocomplex/ray3d/: central 3D ray-field (Zernike) and point↔ray bundle adjustment (mono/stereo).

  • src/stereocomplex/rayfields/zernike_origin_field.py: non-central Zernike origin-field model O(u,v) and direction-field extensions for pixel-to-line rayfields.

  • src/stereocomplex/calibration/fit_zernike_origin_field.py: experimental non-central origin-field calibration and staged/complete point-to-ray BA.

  • src/stereocomplex/physics/parallel_plate_fit.py: second-stage physical interpretation of a measured rayfield as a compact pinhole + inclined parallel-plate model.

  • src/stereocomplex/benchmarks/parallel_plate_origin_field.py: controlled non-central benchmark, oracle floors, rendered-image evaluation, and Ray2D front-end comparison.

  • paper/experiments/: reproducible scripts used to generate tables/figures in the docs/paper.

  • docs/examples/: end-to-end runnable examples (used in the documentation).

  • examples/notebooks/04_parallel_plate_origin_field.ipynb: scientific inclined-plate oracle and non-central BA walkthrough.

  • examples/notebooks/05_noncentral_calibration_from_images.ipynb: practical non-central calibration path from image folders.

Model layers

  • Ray2D / planar ray-field: a homography plus smooth residual field on the board plane. This is a 2D observation refinement step, not a 3D camera model.

  • Central 3D ray-field: each pixel maps to a unit direction and all rays share one center.

  • Non-central 3D rayfield: each pixel maps to a 3D line (O(u,v), d(u,v)); the origin field is gauge-fixed by the transverse condition O(u,v) · d(u,v) = 0.

Non-central paths

  • Use docs/PARALLEL_PLATE_ORIGIN_FIELD.md / notebook 04 for the controlled validation: the inclined plate is only a synthetic oracle; its physical parameters are not fitted.

  • Use docs/NONCENTRAL_FROM_IMAGES.md / notebook 05 for the practical workflow: two image folders plus a CharucoBoardSpec feed fit_stereo_zernike_origin_field_from_image_dirs(...).

Planned evolution

  • sim/optix/ will replace the data source without changing the dataset format.

  • ml/ will consume dataset v0 and output a latent z + a compact decoder.