Start Here

Goal: choose the right StereoComplex workflow without reading the whole research documentation first.

StereoComplex has a deliberately layered design:

Layer	Use it for	Status
Ray2D / planar ray-field	improve ChArUco observations before OpenCV calibration	stable practical preprocessing
Central 3D ray-field	ray-based stereo calibration/reconstruction without a pinhole matrix	research prototype
Non-central Zernike rayfield	diagnose and model systems where each pixel maps to a 3D line	research-grade, validated on synthetic oracles and one real CMO case study

Ray2D is a 2D correction of board-plane observations. It is not itself a 3D non-central camera model.

Recommended first step

Start with notebook 00 — open it directly in Google Colab, or follow the step-by-step tutorial (text-only, faster to scan). or run it locally (see the Notebook walkthroughs section below):

examples/notebooks/00_getting_started.ipynb
examples/notebooks/00_getting_started.py

This is the shortest path for users who already know OpenCV:

define a ChArUco board;
compare raw OpenCV calibration against Ray2D-refined calibration;
call assess_calibration;
export the refined result back to OpenCV format.

Companion page:

:doc:FROM_OPENCV_TO_STEREOCOMPLEX

Installation

Editable install:

.venv/bin/python -m pip install -e .

For notebooks:

.venv/bin/python -m pip install -e '.[notebooks]'

If you do not install the package, most commands can still be run with PYTHONPATH=src.

Which path should I use?

Situation	Recommended path
I know OpenCV and want a quick start	`examples/notebooks/00_getting_started.ipynb`
I just want better OpenCV calibration	`sc.compare_opencv_stereo_calibration(...)` or `sc.calibrate_opencv(..., method2d="rayfield_tps_robust")`
My OpenCV calibration plateaus on blur/noise/compression	:doc:`FIX_MY_CALIBRATION`
I have my own left/right folders	:doc:`BRING_YOUR_OWN_DATA`
I want to understand Ray2D	`examples/notebooks/01_ray2d_vs_opencv.ipynb` and :doc:`RAYFIELD_WORKED_EXAMPLE`
I want a central ray-based 3D model	`sc.calibrate_central(...)` and :doc:`RAYFIELD3D_RECONSTRUCTION`
I suspect non-central optics	`sc.calibrate_noncentral(...)` and :doc:`NONCENTRAL_FROM_IMAGES`
I want to identify a physical optical family	`sc.identify_optics(...)` and :doc:`IDENTIFY_MY_OPTICS`
I want the real CMO validation	:doc:`REAL_CMO_PYCASO_RAYFIELD` and `examples/notebooks/09_pycaso_real_data.ipynb`

What StereoComplex does today

StereoComplex currently provides:

a CPU synthetic stereo dataset generator with ChArUco targets;
ChArUco detection and Ray2D refinement tools;
OpenCV-compatible calibration wrappers and diagnostics;
central 3D ray-field calibration and triangulation prototypes;
non-central Zernike rayfield calibration from image folders;
physical optical model identification from measured rayfields;
a real-data Pycaso CMO microscope case study.

Main validated results

OpenCV-compatible calibration improvement

Ray2D can improve ChArUco localization before feeding points into OpenCV calibration. Start with:

examples/notebooks/00_getting_started.ipynb
examples/notebooks/01_ray2d_vs_opencv.ipynb
:doc:FROM_OPENCV_TO_STEREOCOMPLEX
:doc:FIX_MY_CALIBRATION

Non-central rendered-image benchmark

On the inclined-plate benchmark, the non-central bundle adjustment benefits strongly from Ray2D-refined observations and reaches sub-millimetric reconstruction accuracy. Read:

:doc:PARALLEL_PLATE_ORIGIN_FIELD
examples/notebooks/04_parallel_plate_origin_field.ipynb

Real CMO microscope case study

The Pycaso CMO case study is the main real-data validation of the non-central workflow. The final documented comparison is:

Model / method	Role	RMS
Standard OpenCV stereo on the tested setup	central baseline	>300 px
Perspective CMO physical model	wrong optical family	~86 px
Telecentric CMO 14p	correct family but not usable	~14.6 px
Telecentric CMO + per-arm SE(3), 26p	compact usable physical model	1.06 px
Zernike O(0)+d(2), 57p	flexible rayfield reference	0.47 px

Read:

:doc:REAL_CMO_PYCASO_RAYFIELD
:doc:CMO_PHYSICAL_MODEL
examples/notebooks/09_pycaso_real_data.ipynb

Notebook walkthroughs

The ten numbered notebooks are the guided teaching sequence; see :doc:NOTEBOOKS for the detailed overview.

Run them locally — install the notebook extras, then launch JupyterLab. Each notebook’s first cell moves to the repository root on its own, so the relative dataset/ paths resolve wherever JupyterLab is started:

.venv/bin/python -m pip install -e '.[notebooks]'
.venv/bin/jupyter lab examples/notebooks

Run them on Google Colab — click a link below. The first cell installs StereoComplex automatically; no local setup is needed.

Recommended order:

00_getting_started.ipynb — OpenCV-to-StereoComplex onboarding.
01_ray2d_vs_opencv.ipynb — why Ray2D improves ChArUco observations.
02_ray3d.ipynb — central 3D ray-field reconstruction prototype.
03_rayfield_virtual_rectification.ipynb — bridge back to dense stereo.
04_parallel_plate_origin_field.ipynb — non-central synthetic oracle.
05_noncentral_calibration_from_images.ipynb — practical non-central image-folder path.
06_cmo_model_selection.ipynb — physical model selection on CMO-like optics.
07_model_selection_matrix.ipynb — 6-oracle classification matrix.
08_direct_vs_rayfield_inversion.ipynb — direct vs rayfield-mediated inversion.
09_pycaso_real_data.ipynb — real Pycaso CMO case study.

Quickstart for your own stereo folders

from pathlib import Path
import stereocomplex as sc

board = sc.CharucoBoardSpec(
    squares_x=11,
    squares_y=7,
    square_size_mm=39.0713,
    marker_size_mm=27.3499,
    aruco_dictionary="DICT_4X4_1000",
)

report = sc.compare_opencv_stereo_calibration(
    left_dir=Path("my_data/left"),
    right_dir=Path("my_data/right"),
    board=board,
)

assessment = sc.assess_calibration(report["refined_result"])
K1, d1, K2, d2, R, T = report["refined_result"].to_opencv()

For the detailed version:

:doc:BRING_YOUR_OWN_DATA

Quickstart for the versioned synthetic dataset

Generate and validate a minimal dataset:

.venv/bin/python -m stereocomplex.cli generate-cpu-dataset --out dataset/charuco --pattern charuco --frames-per-scene 16
.venv/bin/python -m stereocomplex.cli validate-dataset dataset/charuco

Evaluate Ray2D ChArUco identification against synthetic ground truth:

.venv/bin/python -m stereocomplex.cli eval-charuco-detection dataset/charuco --method rayfield_tps_robust

Documentation map

First use: :doc:FROM_OPENCV_TO_STEREOCOMPLEX, :doc:BRING_YOUR_OWN_DATA, :doc:NOTEBOOKS.
ChArUco and Ray2D: :doc:CHARUCO_IDENTIFICATION, :doc:RAYFIELD_WORKED_EXAMPLE.
Ray-based calibration and reconstruction: :doc:STEREO_RECONSTRUCTION, :doc:RECONSTRUCTION_API, :doc:RAYFIELD3D_RECONSTRUCTION, :doc:RAYFIELD_VIRTUAL_RECTIFY.
Non-central and optical model identification: :doc:NONCENTRAL_FROM_IMAGES, :doc:IDENTIFY_MY_OPTICS, :doc:PARALLEL_PLATE_ORIGIN_FIELD, :doc:CMO_MODEL_SELECTION.
Real-data CMO: :doc:REAL_CMO_PYCASO_RAYFIELD, :doc:CMO_PHYSICAL_MODEL.
Project status and reference: :doc:VALIDATION_STATUS, :doc:ROADMAP, :doc:PUBLIC_API, :doc:ARCHITECTURE, :doc:CONVENTIONS.

Next steps

Start with examples/notebooks/00_getting_started.ipynb.
Use :doc:FROM_OPENCV_TO_STEREOCOMPLEX if you want the OpenCV migration path.
Use :doc:REAL_CMO_PYCASO_RAYFIELD if you want the advanced scientific validation.
Add more real datasets before claiming deployment-grade generality for non-central optics.