API reference

This page documents the public StereoComplex API, auto-generated from the docstrings. For conceptual guides and worked examples see the rest of the documentation; for the tiered overview and the stability contract see Public API contract.

The most common entry points are also re-exported at the top level for convenience — the calibration entry point is reachable both as stereocomplex.api.calibrate and as sc.calibrate. The stereocomplex.advanced namespace bundles additional composition and diagnostic helpers, which are re-exports of the symbols documented below.

Note

StereoComplex v0.x is explicitly unstable: public names may still change. Backward-compatible stability commitments start at v1.0 — see Public API contract.

Physical optical models — stereocomplex.physics

Physical optical models (pinhole, Brown-Conrady, inclined parallel plate, compact-mirror-objective) and ray-space model selection.

class stereocomplex.physics.BrownConrady(k1=0.0, k2=0.0, p1=0.0, p2=0.0, k3=0.0)

Bases: object

Brown-Conrady radial + tangential lens distortion in normalised coordinates.

Uses the same coefficient convention as OpenCV. Distortion acts on normalised (focal-length-relative) coordinates, not on pixels.

Parameters:

• k1 (float)

• k2 (float)

• p1 (float)

• p2 (float)

• k3 (float)

k1, k2, k3

Radial distortion coefficients.

Type:

float

p1, p2

Tangential (decentering) distortion coefficients.

Type:

float

distort(x, y)

Apply Brown-Conrady distortion to normalised image coordinates.

Parameters:

• x (ndarray) – Undistorted normalised coordinates (unitless).

• y (ndarray) – Undistorted normalised coordinates (unitless).

Returns:

xd, yd – Distorted normalised coordinates, same shape as the inputs.

Return type:

ndarray

References

D. C. Brown, “Decentering distortion of lenses”, Photogrammetric Engineering 32(3), 444-462, 1966.

undistort(xd, yd, iterations=10)

Remove Brown-Conrady distortion by fixed-point iteration.

The Brown-Conrady model has no closed-form inverse; the undistorted coordinate is recovered by iterating from (x, y) = (xd, yd) and subtracting the modelled distortion each step.

Parameters:

• xd (ndarray) – Distorted normalised coordinates (unitless).

• yd (ndarray) – Distorted normalised coordinates (unitless).

• iterations (int) – Number of fixed-point iterations; 5-10 suffices for typical lenses.

Returns:

x, y – Undistorted normalised coordinates, same shape as the inputs.

Return type:

ndarray

class stereocomplex.physics.CMOChannelRayField(channel, common_aberration=<factory>, name='cmo_channel')

Bases: object

Physical CMO channel exposed as a rayfield for ray-space tools.

Wraps a fixed CMOChannelSpec behind the rayfield interface (ray, parameter_vector, …). This wrapper exposes no free parameters — it is a forward model, not a fittable one.

Parameters:

• channel (CMOChannelSpec)

• common_aberration (PolynomialRayAberration)

• name (str)

channel

The channel whose optics define the rayfield.

Type:

CMOChannelSpec

common_aberration

Shared aberration added to the channel’s differential aberration.

Type:

PolynomialRayAberration

name

Model identifier used by model-selection reports.

Type:

str

classmethod from_parameter_vector(x, **kwargs)

Rebuild the rayfield from an (empty) parameter vector.

This model has no free parameters, so x must be empty; the channel itself is supplied through keyword arguments.

Parameters:

• x (ndarray) – Must be empty (size 0).

• **kwargs – Must include channel (CMOChannelSpec); may include common_aberration (PolynomialRayAberration).

Return type:

CMOChannelRayField

Raises:

ValueError – If x is non-empty.

property n_parameters: int

Total number of free parameters (0 for this minimal channel spec).

parameter_dict()

Empty parameter dict (this channel has no free params).

Return type:

dict[str, float]

parameter_vector()

Empty parameter vector (this channel has no free params).

Return type:

ndarray

ray(u, v)

Compute the 3D ray (origin, direction) for each pixel of this channel.

Pipeline: invert the sensor warp to recover ideal pixels, convert to normalised coordinates, undistort (Brown-Conrady), apply the combined common + differential polynomial aberration, lift to a camera-frame direction [x, y, 1] and normalise, then rotate into the world frame. Every ray shares the same sub-pupil origin (the channel is central).

Parameters:

• u (ndarray) – Pixel coordinates (broadcast against each other).

• v (ndarray) – Pixel coordinates (broadcast against each other).

Returns:

• origins (ndarray, shape (…, 3)) – Ray origin (the channel sub-pupil) in world millimetres — identical for every pixel.

• directions (ndarray, shape (…, 3)) – Unit ray directions in the world frame, same leading shape as the inputs.

Return type:

tuple[ndarray, ndarray]

class stereocomplex.physics.CMOChannelSpec(name, intrinsics, origin_world_mm, R_cam_to_world=<factory>, distortion=<factory>, differential_aberration=<factory>, sensor_warp=<factory>, vignetting=<factory>)

Bases: object

One effective CMO stereo channel: sub-pupil, intrinsics and per-channel optics.

“Effective” means the channel is described by a single sub-pupil (optical centre) plus image-formation terms — the per-camera view of a shared compact-mirror-objective (CMO) stereo head, not a literal lens model.

Parameters:

• name (Literal['left', 'right'])

• intrinsics (CMOIntrinsics)

• origin_world_mm (tuple[float, float, float])

• R_cam_to_world (ndarray)

• distortion (BrownConrady)

• differential_aberration (PolynomialRayAberration)

• sensor_warp (SensorWarp)

• vignetting (Vignetting)

name

Channel identifier.

Type:

{“left”, “right”}

intrinsics

Pixel intrinsics of this channel.

Type:

CMOIntrinsics

origin_world_mm

Sub-pupil (optical centre) position in the world frame, in millimetres.

Type:

tuple of 3 float

R_cam_to_world

Rotation from the channel camera frame to the world frame.

Type:

ndarray, shape (3, 3)

distortion

Per-channel radial/tangential distortion.

Type:

BrownConrady

differential_aberration

Per-channel polynomial ray perturbation, added on top of the shared one.

Type:

PolynomialRayAberration

sensor_warp

Per-channel image-plane deformation.

Type:

SensorWarp

vignetting

Per-channel radial shading.

Type:

Vignetting

property origin: ndarray

Sub-pupil (optical centre) position as a length-3 array, in millimetres.

class stereocomplex.physics.CMOIntrinsics(width, height, fx, fy, cx, cy)

Bases: object

Pinhole pixel intrinsics for a single CMO camera channel.

Parameters:

• width (int)

• height (int)

• fx (float)

• fy (float)

• cx (float)

• cy (float)

width, height

Image size in pixels.

Type:

int

fx, fy

Focal length along the u and v axes, in pixels.

Type:

float

cx, cy

Principal point, in pixels.

Type:

float

as_K()

Return the 3x3 pinhole camera matrix K = [[fx, 0, cx], [0, fy, cy], [0, 0, 1]].

Return type:

ndarray

classmethod from_focal_and_pitch(width, height, focal_mm, pitch_um)

Build intrinsics from a physical focal length and sensor pixel pitch.

The pixel focal length is f_px = focal_mm * 1000 / pitch_um (the factor 1000 converts millimetres to micrometres). The principal point is placed at the image centre ((width - 1) / 2, (height - 1) / 2).

Parameters:

• width (int) – Image size in pixels.

• height (int) – Image size in pixels.

• focal_mm (float) – Lens focal length, in millimetres.

• pitch_um (float) – Sensor pixel pitch, in micrometres.

Returns:

Intrinsics with square pixels (fx == fy) and a centred principal point.

Return type:

CMOIntrinsics

norm_to_pixel(x, y)

Convert normalised image coordinates back to pixel coordinates.

Applies the intrinsics u = fx * x + cx and v = fy * y + cy — the inverse of pixel_to_norm().

Parameters:

• x (ndarray) – Normalised (unitless) image coordinates.

• y (ndarray) – Normalised (unitless) image coordinates.

Returns:

Pixel coordinates stacked on the last axis.

Return type:

ndarray, shape (…, 2)

pixel_grid()

Return the full-image meshgrid of integer pixel-centre coordinates.

Returns:

u, v – Pixel column (u) and row (v) coordinates, built with indexing="xy"; pixel centres sit at integer coordinates.

Return type:

ndarray, shape (height, width)

pixel_to_norm(u, v)

Convert pixel coordinates to normalised image coordinates.

Applies the inverse intrinsics x = (u - cx) / fx and y = (v - cy) / fy. The result is dimensionless: for an ideal pinhole it equals the tangent of the ray angle.

Parameters:

• u (ndarray) – Pixel coordinates.

• v (ndarray) – Pixel coordinates.

Returns:

x, y – Normalised image coordinates (unitless), same shape as the inputs.

Return type:

ndarray

class stereocomplex.physics.CMOPhysicalChannelModel(rig, channel, name='cmo_physical_channel', is_stereo_shared=True)

Bases: object

Single-channel facade for a shared CMO physical rig.

Parameters:

• rig (CMOPhysicalStereoModel)

• channel (Literal['left', 'right'])

• name (str)

• is_stereo_shared (bool)

classmethod from_parameter_vector(x, **kwargs)

Reconstruct a channel model from a flat parameter vector.

Builds the shared CMOPhysicalStereoModel from x, then wraps it with the channel given by kwargs["channel"] (default "left").

Parameters:

• x (ndarray of float, shape (19,) or (21,)) – Flattened parameter vector (see CMOPhysicalStereoModel.from_parameter_vector()).

• **kwargs – Must include pixel_pitch_mm. May include image_size, share_principal_point, and channel ("left" or "right").

Return type:

CMOPhysicalChannelModel

property n_parameters: int

Number of free parameters, delegated to the shared rig.

See CMOPhysicalStereoModel.n_parameters.

parameter_dict()

Return free/fixed parameter groups, delegated to the shared rig.

See CMOPhysicalStereoModel.parameter_dict().

Return type:

dict[str, object]

parameter_vector()

Serialize to a flat parameter vector, delegated to the shared rig.

See CMOPhysicalStereoModel.parameter_vector().

Return type:

ndarray

project_point(X, max_iter=20)

Project a 3-D point with the non-tilted paraxial channel approximation.

Given a point X, find the pixel whose approximate ray passes through it. This helper is intentionally narrower than CMOPhysicalStereoModel.ray(): it uses the sub-pupil z = working_distance_mm - f_obj_mm and does not invert telecentric_offset_mm, theta_axis_tilt_rad or theta_pitch_rad. Use it only for the legacy non-tilted projection path; use ray() for the full fitted 19/21-parameter model.

Returns (uv, ok) where uv is (2,) and ok is True if the point projects inside the sensor.

Parameters:

• X (ndarray)

• max_iter (int)

Return type:

tuple[ndarray, bool]

ray(u, v)

Compute 3-D rays, delegating to the shared rig with this channel.

See CMOPhysicalStereoModel.ray().

Parameters:

• u (ndarray)

• v (ndarray)

Return type:

tuple[ndarray, ndarray]

class stereocomplex.physics.CMOPhysicalStereoFitResult(model, success, message, n_parameters, n_samples, n_residual_scalars, rss, left_rms_mm, right_rms_mm, rms_mm, aic, bic, parameter_vector, parameter_dict)

Bases: object

Result of fitting a shared physical CMO model to two rayfields.

Parameters:

• model (CMOPhysicalStereoModel)

• success (bool)

• message (str)

• n_parameters (int)

• n_samples (int)

• n_residual_scalars (int)

• rss (float)

• left_rms_mm (float)

• right_rms_mm (float)

• rms_mm (float)

• aic (float)

• bic (float)

• parameter_vector (ndarray)

• parameter_dict (dict[str, object])

class stereocomplex.physics.CMOPhysicalStereoModel(f_obj_mm, working_distance_mm, b_mm, f_tube_mm, cx_principal_px, cy_principal_px, pixel_pitch_mm, theta_axis_tilt_rad=0.0, theta_pitch_rad=0.0, telecentric_offset_mm=0.0, distortion_left=(0.0, 0.0, 0.0, 0.0, 0.0), distortion_right=(0.0, 0.0, 0.0, 0.0, 0.0), image_size=None, share_principal_point=True, delta_cx_diff_px=0.0, delta_cy_diff_px=0.0, name='cmo_physical_stereo', is_stereo_shared=True)

Bases: object

Shared-rig paraxial CMO stereo model.

The model uses a common main objective with two decentered effective sub-pupils separated by b_mm. For the central pixel, the left and right chief rays converge to the optical axis at working_distance_mm. The chief-ray angle is controlled by b_mm / (2 f_obj_mm) because the entrance-pupil plane is placed one objective focal length before the working plane.

Sensor coordinates are converted to object-plane coordinates through the tube-lens focal length and pixel pitch. The per-channel distortion is an effective direction distortion D_c, parameterized by five Brown-Conrady-like coefficients applied to normalized angular coordinates. It absorbs residual aberrations of the tube lens and main objective; it is not a derivation from one specific physical aberration model.

Parameters:

• f_obj_mm (float)

• working_distance_mm (float)

• b_mm (float)

• f_tube_mm (float)

• cx_principal_px (float)

• cy_principal_px (float)

• pixel_pitch_mm (float)

• theta_axis_tilt_rad (float)

• theta_pitch_rad (float)

• telecentric_offset_mm (float)

• distortion_left (tuple[float, float, float, float, float])

• distortion_right (tuple[float, float, float, float, float])

• image_size (tuple[int, int] | None)

• share_principal_point (bool)

• delta_cx_diff_px (float)

• delta_cy_diff_px (float)

• name (str)

• is_stereo_shared (bool)

channel(channel)

Return a single-channel facade for the given channel name.

The returned CMOPhysicalChannelModel delegates all ray-tracing and parameter queries to this shared rig, transparently passing the channel identifier. This lets downstream code treat each channel as an independent ray model while the underlying parameters remain coupled through the shared CMO geometry.

Parameters:

channel ({"left", "right"}) – Which stereo channel to wrap.

Return type:

CMOPhysicalChannelModel

flat_parameter_dict()

Return all free parameters as a flat dictionary keyed by name.

Distortion coefficients are named {channel}_{k} where channel is left or right and k is one of k1, k2, p1, p2, k3 (Brown-Conrady convention). Principal-point deltas are included only when share_principal_point=False.

Returns:

Mapping from parameter name (str) to value (float, in its native unit: mm, px, or rad).

Return type:

dict

classmethod from_parameter_vector(x, **kwargs)

Reconstruct the model from a flat parameter vector.

Inverse of parameter_vector(). The parameter layout depends on share_principal_point:

Shared PP (19 params)

0: f_obj_mm

1: working_distance_mm

2: b_mm

3: f_tube_mm

4: cx_principal_px

5: cy_principal_px

6: theta_axis_tilt_rad

7: theta_pitch_rad

8: telecentric_offset_mm

9-13: distortion_left (k1, k2, p1, p2, k3)

14-18: distortion_right

Per-channel PP (21 params)

0-5: as above

6: delta_cx_diff_px

7: delta_cy_diff_px

8: theta_axis_tilt_rad

9: theta_pitch_rad

10: telecentric_offset_mm

11-15: distortion_left

16-20: distortion_right

Parameters:

• x (ndarray of float, shape (19,) or (21,)) – Flattened parameter vector.

• **kwargs – Must include pixel_pitch_mm (float, mm). May include image_size, share_principal_point.

Return type:

CMOPhysicalStereoModel

property n_parameters: int

Number of free parameters in the flattened parameter vector.

Returns 19 when share_principal_point=True (a single principal point serves both channels) or 21 when each channel carries its own principal-point offset via delta_cx_diff_px and delta_cy_diff_px.

The layout is: 6 shared optical parameters (f_obj_mm, working_distance_mm, b_mm, f_tube_mm, cx, cy), optionally 2 principal-point deltas, 2 global tilt angles (theta_axis_tilt_rad, theta_pitch_rad), one axial telecentric offset/depth parameter (telecentric_offset_mm), and 5 Brown-Conrady distortion coefficients per channel (10 total).

parameter_dict()

Return the parameter set split into free and fixed groups.

Fixed parameters are quantities treated as known sensor constants: pixel_pitch_mm, image_width, image_height, and share_principal_point. Free parameters are the optical, geometric, and distortion coefficients (see flat_parameter_dict()).

Returns:

{"free": {...}, "fixed": {...}}. All values carry their native units (mm, px, or rad for free; mm or px for fixed).

Return type:

dict

parameter_vector()

Serialize the model to a flat parameter vector.

Inverse of from_parameter_vector(). The order matches the layout documented there: shared optical params, optional PP deltas, tilt angles, then left and right distortion tuples.

Return type:

ndarray of float, shape (19,) or (21,)

principal_point_for_channel(channel)

Compute the principal point in pixels for a given channel.

When share_principal_point=True, both channels share the same (cx_principal_px, cy_principal_px). When False, the left channel shifts by -0.5 * delta and the right by +0.5 * delta, so that delta_cx_diff_px / delta_cy_diff_px encode the total separation between the two principal points.

Parameters:

channel ({"left", "right"})

Returns:

Principal-point coordinates (cx, cy) in px.

Return type:

(float, float)

ray(u, v, channel)

Compute 3-D rays for pixel coordinates through the CMO paraxial model.

This is the core optical forward model. For each pixel (u, v) the pipeline is:

1. Convert pixel displacement from the principal point to angular coordinates via the tube lens: alpha = (pixel - principal) * pixel_pitch / f_tube.

2. Undo Brown-Conrady distortion to obtain undistorted angular coordinates (alpha_x, alpha_y).

3. Place the effective sub-pupil (ray origin) at (±b/2, 0, z_pupil) where z_pupil = working_distance - f_obj + telecentric_offset. The sign is negative for the left channel, positive for right.

4. Determine the object-plane intersection at (WD * alpha_x, WD * alpha_y, WD).

5. The ray direction is the unit vector from pupil to object-plane point.

6. If theta_axis_tilt_rad or theta_pitch_rad is non-zero, rotate both origin and direction by the corresponding yaw and pitch matrices.

Warning

f_obj_mm and telecentric_offset_mm are exactly degenerate — only their difference enters z_pupil. Do not assert either value independently; use working_distance_mm, b_mm, f_tube_mm, and f_obj_mm - telecentric_offset_mm.

Parameters:

• u (ndarray) – Horizontal pixel coordinates (column index, 0-based).

• v (ndarray) – Vertical pixel coordinates (row index, 0-based).

• channel ({"left", "right"})

Returns:

• origin (ndarray, shape (…, 3)) – Ray origin in mm (the effective sub-pupil position).

• direction (ndarray, shape (…, 3)) – Unit ray direction vector (dimensionless).

Return type:

tuple[ndarray, ndarray]

class stereocomplex.physics.CMOPlanePose(R, t)

Bases: object

Rigid pose (rotation + translation) of a planar calibration target.

The target is a plane: its points live at z = 0 in the board-local frame and are mapped to the CMO/world frame by x_world = R @ x_local + t.

Parameters:

• R (ndarray)

• t (ndarray)

R

Rotation from the board-local frame to the world frame.

Type:

ndarray, shape (3, 3)

t

Board-origin position in the world frame, in millimetres.

Type:

ndarray, shape (3,)

local_to_world(xy_plane_mm)

Map 2D board-plane points to 3D world coordinates.

The board-local Z coordinate is taken as 0 (the target is planar), then the rigid pose x_world = R @ [x, y, 0] + t is applied.

Parameters:

xy_plane_mm (ndarray, shape (N, 2) or (2,)) – Board-plane coordinates in millimetres.

Returns:

World-frame coordinates in millimetres.

Return type:

ndarray, shape (N, 3)

property normal_world: ndarray

World-frame unit normal of the target plane (its local +Z axis rotated by R).

world_to_local(xyz_world)

Map 3D world coordinates back into the board-local frame.

Inverse of the rigid map in local_to_world(): x_local = R.T @ (x_world - t). For points lying on the target the returned local Z is ~0.

Parameters:

xyz_world (ndarray, shape (..., 3)) – World-frame coordinates in millimetres.

Returns:

Board-local coordinates in millimetres, same shape as the input.

Return type:

ndarray

class stereocomplex.physics.CMOPlaneTargetSpec(squares_x=11, squares_y=7, square_size_mm=1.0, pixels_per_square=80, pattern='charuco', marker_size_ratio=0.7)

Bases: object

Textured planar calibration target used by the CMO image generator.

Parameters:

• squares_x (int)

• squares_y (int)

• square_size_mm (float)

• pixels_per_square (int)

• pattern (Literal['checker', 'charuco'])

• marker_size_ratio (float)

squares_x, squares_y

Number of board squares along each axis.

Type:

int

square_size_mm

Edge length of one square, in millimetres.

Type:

float

pixels_per_square

Texture resolution: rendered pixels per board square.

Type:

int

pattern

Target pattern; “charuco” needs OpenCV aruco support.

Type:

{“checker”, “charuco”}

marker_size_ratio

ChArUco marker size as a fraction of the square size.

Type:

float

property height_mm: float

Board height in mm.

inner_corners_local_mm()

Return the board’s inner-corner ids and their board-local coordinates.

Inner corners are the (squares_x - 1) * (squares_y - 1) chessboard vertices, centred on the board origin.

Returns:

• ids (ndarray of int32, shape (M,)) – Corner indices, row-major.

• xy (ndarray of float64, shape (M, 2)) – Corner coordinates in board-local millimetres.

Return type:

tuple[ndarray, ndarray]

make_texture_u8()

Render the target’s pattern as an 8-bit grayscale texture image.

For pattern="charuco" an OpenCV ChArUco board is generated (needs cv2.aruco); for pattern="checker" a plain checkerboard is drawn.

Returns:

Grayscale texture image.

Return type:

ndarray of uint8, shape (squares_y * pixels_per_square, squares_x * pixels_per_square)

Raises:

RuntimeError – If a ChArUco texture is requested but OpenCV aruco support is missing, or texture generation otherwise fails.

property width_mm: float

Board width in mm.

class stereocomplex.physics.CMORayfieldBundleAdjustmentResult(left_model, right_model, poses, success, message, n_observations, incidence_rms_mm, incidence_p95_mm, left_rayfield_rms_mm, right_rayfield_rms_mm, parameter_vector, pose_vectors)

Bases: object

Result of jointly fitting effective CMO channels and board poses.

Parameters:

• left_model (NonCentralPolynomialChannelModel)

• right_model (NonCentralPolynomialChannelModel)

• poses (list[CMOPlanePose])

• success (bool)

• message (str)

• n_observations (int)

• incidence_rms_mm (float)

• incidence_p95_mm (float)

• left_rayfield_rms_mm (float)

• right_rayfield_rms_mm (float)

• parameter_vector (ndarray)

• pose_vectors (ndarray)

left_model, right_model

Fitted per-channel surrogate models.

Type:

NonCentralPolynomialChannelModel

poses

Fitted board pose, one per frame.

Type:

list of CMOPlanePose

success

Whether the optimiser reported convergence.

Type:

bool

message

Optimiser status message.

Type:

str

n_observations

Number of scalar residuals used in the fit.

Type:

int

incidence_rms_mm, incidence_p95_mm

RMS and 95th-percentile point-to-ray incidence error, in millimetres.

Type:

float

left_rayfield_rms_mm, right_rayfield_rms_mm

RMS deviation from the measured Zernike rayfield, per channel, in mm.

Type:

float

parameter_vector

Concatenated fitted [left, right] model parameters.

Type:

ndarray

pose_vectors

Fitted pose parameters, 6 per frame (rotation vector + translation).

Type:

ndarray

parameter_summary()

Return the fitted left/right model parameters as nested dictionaries.

Returns:

{"left": {...}, "right": {...}} — each inner dict is the channel’s NonCentralPolynomialChannelModel.parameter_dict().

Return type:

dict[str, dict[str, float]]

class stereocomplex.physics.CMOStereoSpec(left, right, common_aberration=<factory>)

Bases: object

Full CMO stereo model: two channels plus a shared ray aberration.

Parameters:

• left (CMOChannelSpec)

• right (CMOChannelSpec)

• common_aberration (PolynomialRayAberration)

left, right

The two effective channels.

Type:

CMOChannelSpec

common_aberration

Ray aberration shared by both channels, added to each channel’s own differential aberration.

Type:

PolynomialRayAberration

channels()

Return the two channels as the tuple (left, right).

Return type:

tuple[CMOChannelSpec, CMOChannelSpec]

classmethod symmetric_default(width=1280, height=960, focal_mm=25.0, pitch_um=3.45, baseline_mm=5.0, common_aberration=None, left_distortion=None, right_distortion=None)

Build a symmetric default CMO stereo spec, both channels facing the screen.

The two channels share identical intrinsics and sit symmetrically on the world X axis at +/- baseline_mm / 2; mild opposite-sign vignetting is applied to each.

Parameters:

• width (int) – Image size in pixels.

• height (int) – Image size in pixels.

• focal_mm (float) – Lens focal length, in millimetres.

• pitch_um (float) – Sensor pixel pitch, in micrometres.

• baseline_mm (float) – Distance between the two sub-pupils, in millimetres.

• common_aberration (PolynomialRayAberration, optional) – Shared ray aberration; defaults to none.

• left_distortion (BrownConrady, optional) – Per-channel distortion; default to none.

• right_distortion (BrownConrady, optional) – Per-channel distortion; default to none.

Returns:

Symmetric stereo specification.

Return type:

CMOStereoSpec

class stereocomplex.physics.CMOTelecentricChannelModel(rig, channel, name='cmo_telecentric_channel', is_stereo_shared=True)

Bases: object

Single-channel facade for a shared telecentric CMO rig.

Parameters:

• rig (CMOTelecentricStereoModel)

• channel (Literal['left', 'right'])

• name (str)

• is_stereo_shared (bool)

classmethod from_parameter_vector(x, **kwargs)

Reconstruct a channel model from a flat parameter vector.

Builds the shared CMOTelecentricStereoModel from x, then wraps it with the channel given by kwargs["channel"] (default "left").

Parameters:

• x (ndarray of float) – Flattened parameter vector (see CMOTelecentricStereoModel.from_parameter_vector()).

• **kwargs – Must include pixel_pitch_mm. May include image_size and channel.

Return type:

CMOTelecentricChannelModel

property n_parameters: int

Number of free parameters, delegated to the shared rig.

See CMOTelecentricStereoModel.n_parameters.

parameter_dict()

Return free/fixed parameter groups, delegated to the shared rig.

See CMOTelecentricStereoModel.parameter_dict().

Return type:

dict[str, object]

parameter_vector()

Serialize to a flat parameter vector, delegated to the shared rig.

See CMOTelecentricStereoModel.parameter_vector().

Return type:

ndarray

ray(u, v)

Compute 3-D rays, delegating to the shared rig with this channel.

See CMOTelecentricStereoModel.ray().

Parameters:

• u (ndarray)

• v (ndarray)

Return type:

tuple[ndarray, ndarray]

class stereocomplex.physics.CMOTelecentricNModel(channels, name='cmo_telecentric_n', is_stereo_shared=False)

Bases: object

Named collection of telecentric CMO channels for N-camera workflows.

Parameters:

• channels (tuple[CMOTelecentricChannelModel, ...])

• name (str)

• is_stereo_shared (bool)

channel(name)

Look up a channel by name.

Parameters:

name (str) – Channel name (e.g. "left").

Return type:

CMOTelecentricChannelModel

Raises:

KeyError – If no channel matches name.

property channel_names: tuple[str, ...]

Names of all channels, in order.

Return type:

tuple of str

classmethod from_stereo(stereo)

Wrap a stereo telecentric model as a 2-channel N-camera container.

This is a convenience constructor for the N-camera migration: it takes an existing CMOTelecentricStereoModel and returns a CMOTelecentricNModel with channels ("left", "right"), allowing stereo models to be used wherever an N-channel container is expected.

Parameters:

stereo (CMOTelecentricStereoModel)

Return type:

CMOTelecentricNModel

property n_channels: int

Number of channels in the collection.

Return type:

int

property n_parameters: int

Total free parameters summed across all channels.

Return type:

int

ray(u, v, channel)

Compute 3-D rays for the named channel.

Delegates to the appropriate CMOTelecentricChannelModel.

Parameters:

• u (ndarray) – Horizontal pixel coordinates.

• v (ndarray) – Vertical pixel coordinates.

• channel (str) – Channel name.

Returns:

• origin (ndarray, shape (…, 3))

• direction (ndarray, shape (…, 3))

Return type:

tuple[ndarray, ndarray]

class stereocomplex.physics.CMOTelecentricStereoModel(f_obj_mm, working_distance_mm, b_mm, cx_principal_px, cy_principal_px, pixel_pitch_mm, f_angular_mm=0.0, theta_convergence_half_rad=0.0, d_y_common=0.0, s_x_L=0.0, s_y_L=0.0, s_x_R=0.0, s_y_R=0.0, s_xy_L=0.0, s_yx_L=0.0, s_xy_R=0.0, s_yx_R=0.0, shared_slopes=True, rho_x_L=0.0, rho_y_L=0.0, rho_x_R=0.0, rho_y_R=0.0, shared_shear=True, q_xx_L=0.0, q_yy_L=0.0, q_xx_R=0.0, q_yy_R=0.0, shared_quadratic=True, image_size=None, name='cmo_telecentric', is_stereo_shared=True, frame_convention='opencv_y_down')

Bases: object

Quasi-telecentric CMO model with rigid sub-pupil + affine direction field.

Each channel has a constant origin \(S_c\) (the effective sub-pupil) and a direction field that varies affinely across pixels. This captures the quasi-telecentric character of infinity-corrected CMO microscopes where the direction is nearly constant across the field of view.

The direction field is:

\[d_c(u,v) = \operatorname{normalize}\left( d_{c,0} + s_x \tilde{u}\, e_x + s_y \tilde{v}\, e_y \right)\]

where \(\tilde{u} = (u - c_x) \cdot p_{\text{pix}} / f_{\text{obj}}\) and \(\tilde{v} = (v - c_y) \cdot p_{\text{pix}} / f_{\text{obj}}\).

Parameters:

• f_obj_mm (float)

• working_distance_mm (float)

• b_mm (float)

• cx_principal_px (float)

• cy_principal_px (float)

• pixel_pitch_mm (float)

• f_angular_mm (float)

• theta_convergence_half_rad (float)

• d_y_common (float)

• s_x_L (float)

• s_y_L (float)

• s_x_R (float)

• s_y_R (float)

• s_xy_L (float)

• s_yx_L (float)

• s_xy_R (float)

• s_yx_R (float)

• shared_slopes (bool)

• rho_x_L (float)

• rho_y_L (float)

• rho_x_R (float)

• rho_y_R (float)

• shared_shear (bool)

• q_xx_L (float)

• q_yy_L (float)

• q_xx_R (float)

• q_yy_R (float)

• shared_quadratic (bool)

• image_size (tuple[int, int] | None)

• name (str)

• is_stereo_shared (bool)

• frame_convention (str)

channel(channel)

Return a single-channel facade for the given channel name.

See CMOPhysicalStereoModel.channel() — the pattern is identical: the returned CMOTelecentricChannelModel delegates to this shared rig.

Parameters:

channel ({"left", "right"})

Return type:

CMOTelecentricChannelModel

classmethod from_parameter_vector(x, **kwargs)

Reconstruct the telecentric model from a flat parameter vector.

Layout (12 params, shared slopes + shared shear):

0  f_obj_mm
1  working_distance_mm
2  b_mm
3  cx_principal_px
4  cy_principal_px
5  f_angular_mm
6  theta_convergence_half_rad
7  d_y_common
8  s_x_L         (also s_x_R when shared_slopes)
9  s_y_L         (also s_y_R when shared_slopes)
10 rho_x_L       (also rho_x_R when shared_shear)
11 rho_y_L       (also rho_y_R when shared_shear)

When shared_slopes=False (14 params), indices 10-11 are s_x_R, s_y_R and shear starts at 12.

Parameters:

• x (ndarray of float, shape (12,), (14,), or (16,))

• **kwargs – Must include pixel_pitch_mm (float, mm). May include image_size.

Return type:

CMOTelecentricStereoModel

property n_parameters: int

Number of free parameters in the flattened vector.

Public parameter vectors have 12, 14, or 16 entries. The 12-parameter variant uses shared slopes and shared shear; disabling shared slopes yields 14 entries, and disabling shared shear yields 16. There is no supported 10-parameter public vector.

See from_parameter_vector() for the exact layout.

parameter_dict()

Return free/fixed parameter groups.

Fixed keys: pixel_pitch_mm, image_width, image_height (sensor constants). Free keys include all optical/geometric parameters with rho consolidated when shared_shear=True and s_x/s_y consolidated when shared_slopes=True.

Returns:

{"free": {...}, "fixed": {...}}.

Return type:

dict

parameter_vector()

Serialize the telecentric model to a flat parameter vector.

Inverse of from_parameter_vector(). The order is: base optical params (10), optionally per-channel slopes (2), then shear coefficients (2 shared or 4 per-channel).

Return type:

ndarray of float, shape (12,), (14,), or (16,)

ray(u, v, channel)

Compute 3-D rays through the quasi-telecentric CMO model.

For each pixel (u, v):

1. Convert pixel displacement to normalised angular coordinates \(\tilde{u}, \tilde{v}\) using f_angular_mm (or f_obj_mm as fallback).

2. Set the chief-ray direction \(d_0\) from the convergence half-angle theta_convergence_half_rad and common vertical offset d_y_common. The left channel tilts rightward (\(+\sin\theta\)), the right channel leftward (\(-\sin\theta\)).

3. Apply an affine + cross-term + centered-quadratic correction to the direction’s x and y components, then re-normalize.

4. Place the ray origin at the rigid sub-pupil \((\pm b/2, 0, z_{\text{pupil}})\) plus a small affine pupil shear \((\rho_x \tilde{u}, \rho_y \tilde{v}, 0)\).

This model captures the quasi-telecentric character of infinity-corrected stereo microscopes: the direction field varies only slowly across the field of view, and the origin is nearly constant.

Parameters:

• u (ndarray) – Horizontal pixel coordinates (0-based column index).

• v (ndarray) – Vertical pixel coordinates (0-based row index).

• channel ({"left", "right"})

Returns:

• origin (ndarray, shape (…, 3)) – Ray origin in mm at the sub-pupil plane.

• direction (ndarray, shape (…, 3)) – Unit ray direction vector (dimensionless).

Return type:

tuple[ndarray, ndarray]

class stereocomplex.physics.CMOWarpedChannelModel(rig, channel, name='cmo_warped_channel', is_stereo_shared=True)

Bases: object

Single-channel facade for a shared warped CMO rig.

Parameters:

• rig (CMOWarpedStereoModel)

• channel (Literal['left', 'right'])

• name (str)

• is_stereo_shared (bool)

classmethod from_parameter_vector(x, **kwargs)

Reconstruct a channel model from a flat parameter vector.

Builds the shared CMOWarpedStereoModel from x, then wraps it with the channel given by kwargs["channel"].

Parameters:

• x (ndarray of float) – Flattened parameter vector (see CMOWarpedStereoModel.from_parameter_vector()).

• **kwargs – Must include pixel_pitch_mm, warp_level, and shared_warp. May include image_size and channel.

Return type:

CMOWarpedChannelModel

property n_parameters: int

Number of free parameters, delegated to the shared rig.

See CMOWarpedStereoModel.n_parameters.

parameter_dict()

Return free/fixed parameter groups, delegated to the shared rig.

See CMOWarpedStereoModel.parameter_dict().

Return type:

dict[str, object]

parameter_vector()

Serialize to a flat parameter vector, delegated to the shared rig.

See CMOWarpedStereoModel.parameter_vector().

Return type:

ndarray

ray(u, v)

Compute 3-D rays, delegating to the shared rig with this channel.

See CMOWarpedStereoModel.ray().

Parameters:

• u (ndarray)

• v (ndarray)

Return type:

tuple[ndarray, ndarray]

class stereocomplex.physics.CMOWarpedStereoModel(f_obj_mm, working_distance_mm, b_mm, cx_principal_px, cy_principal_px, pixel_pitch_mm, f_angular_mm=0.0, theta_convergence_half_rad=0.0, d_y_common=0.0, s_x_L=0.0, s_y_L=0.0, s_x_R=0.0, s_y_R=0.0, s_xy_L=0.0, s_yx_L=0.0, s_xy_R=0.0, s_yx_R=0.0, shared_slopes=True, rho_x_L=0.0, rho_y_L=0.0, rho_x_R=0.0, rho_y_R=0.0, shared_shear=True, q_xx_L=0.0, q_yy_L=0.0, q_xx_R=0.0, q_yy_R=0.0, shared_quadratic=True, image_size=None, name='cmo_warped_stereo', is_stereo_shared=True, warp_xi_L=(), warp_eta_L=(), warp_xi_R=(), warp_eta_R=(), warp_level=0, shared_warp=True)

Bases: object

CMO model with configurable polynomial pixel pre-warp.

Pipeline per channel:

(xi, eta) = W_c(u, v)              -- polynomial pre-warp (level 0..3)
d = normalize(d_chief + affine correction on warped coords)
O = S_c + pupil shear on warped coords

The warp maps pixel coordinates to optical field coordinates before the telecentric direction model acts. This captures non-radial, asymmetric field-angle distortions that a pure affine direction field cannot.

Parameters:

• f_obj_mm (float)

• working_distance_mm (float)

• b_mm (float)

• cx_principal_px (float)

• cy_principal_px (float)

• pixel_pitch_mm (float)

• f_angular_mm (float)

• theta_convergence_half_rad (float)

• d_y_common (float)

• s_x_L (float)

• s_y_L (float)

• s_x_R (float)

• s_y_R (float)

• s_xy_L (float)

• s_yx_L (float)

• s_xy_R (float)

• s_yx_R (float)

• shared_slopes (bool)

• rho_x_L (float)

• rho_y_L (float)

• rho_x_R (float)

• rho_y_R (float)

• shared_shear (bool)

• q_xx_L (float)

• q_yy_L (float)

• q_xx_R (float)

• q_yy_R (float)

• shared_quadratic (bool)

• image_size (tuple[int, int] | None)

• name (str)

• is_stereo_shared (bool)

• warp_xi_L (tuple[float, ...])

• warp_eta_L (tuple[float, ...])

• warp_xi_R (tuple[float, ...])

• warp_eta_R (tuple[float, ...])

• warp_level (int)

• shared_warp (bool)

channel(channel)

Return a single-channel facade for the given channel name.

See CMOPhysicalStereoModel.channel() — identical pattern.

Parameters:

channel ({"left", "right"})

Return type:

CMOWarpedChannelModel

classmethod from_parameter_vector(x, **kwargs)

Reconstruct the warped model from a flat parameter vector.

The vector layout is: telecentric base (see CMOTelecentricStereoModel.from_parameter_vector()), then warp polynomial coefficients in order warp_xi_L, warp_eta_L (and warp_xi_R, warp_eta_R if shared_warp=False).

The number of coefficients per polynomial axis is determined by warp_level (via _poly_terms_2d()). At level 0 (identity warp), no warp coefficients are present.

Parameters:

• x (ndarray of float)

• **kwargs – Must include pixel_pitch_mm (float, mm). Must include warp_level (int) and shared_warp (bool) for non-zero warp levels. May include image_size.

Return type:

CMOWarpedStereoModel

property n_parameters: int

Number of free parameters including warp coefficients.

The base count is the telecentric parameter count (12, 14, or 16 depending on shared flags). Added to this is the total warp coefficient count from _n_warp_coeff_total(), which depends on warp_level and shared_warp.

parameter_dict()

Return free/fixed parameter groups with warp coefficients.

Fixed keys are sensor constants. Free keys include telecentric base parameters plus per-channel, per-monomial warp coefficients keyed as warp_xi_{L|R}_u{pu}v{pv} and warp_eta_{L|R}_u{pu}v{pv}.

Returns:

{"free": {...}, "fixed": {...}}.

Return type:

dict

parameter_vector()

Serialize the warped model to a flat parameter vector.

The vector begins with the telecentric base parameters (see CMOTelecentricStereoModel.parameter_vector()), followed by the warp polynomial coefficients: warp_xi_L, warp_eta_L, and optionally warp_xi_R, warp_eta_R when shared_warp=False.

Return type:

ndarray of float

ray(u, v, channel)

Compute 3-D rays through the warped CMO model.

Extends CMOTelecentricStereoModel.ray() with an initial pixel-domain polynomial warp:

1. If warp_level > 0, map pixel coordinates (u, v) through the polynomial warp \(W_c\): (xi, eta) = W_c(u, v). Otherwise (xi, eta) = (u, v).

2. Convert the warped coordinates to normalised angular coordinates, then proceed with the telecentric direction model (chief-ray direction + affine/cross/quadratic correction + normalisation, sub-pupil origin + pupil shear).

The warp captures residual field-angle distortions that the affine direction-field model alone cannot represent, while the telecentric base handles the dominant quasi-telecentric behaviour.

Parameters:

• u (ndarray) – Horizontal pixel coordinates.

• v (ndarray) – Vertical pixel coordinates.

• channel ({"left", "right"})

Returns:

• origin (ndarray, shape (…, 3)) – Ray origin in mm.

• direction (ndarray, shape (…, 3)) – Unit ray direction vector.

Return type:

tuple[ndarray, ndarray]

class stereocomplex.physics.CentralBrownConradyModel(K, k1=0.0, k2=0.0, p1=0.0, p2=0.0, k3=0.0, name='central_brown_conrady')

Bases: object

Central Brown-Conrady optical candidate.

It can bend pixel directions, but all rays still share one camera center. Therefore it is intentionally unable to represent a pixel-dependent origin field generated by an inclined parallel plate.

Parameters:

• K (ndarray)

• k1 (float)

• k2 (float)

• p1 (float)

• p2 (float)

• k3 (float)

• name (str)

classmethod from_parameter_vector(x, **kwargs)

Reconstruct model from a parameter vector. K must be passed via kwargs.

Parameters:

x (ndarray)

Return type:

CentralBrownConradyModel

property n_parameters: int

Number of free parameters in this model (0 for pinhole, 5 for Brown-Conrady).

parameter_dict()

Model parameters as a dict keyed by coefficient name.

Return type:

dict[str, float]

parameter_vector()

Pack model parameters into a flat vector for optimisation.

Return type:

ndarray

project_point(X)

Analytic projection: 3-D point → pixel with Brown distortion.

Parameters:

X (ndarray)

Return type:

tuple[ndarray, bool]

ray(u, v)

Compute ray (origin at camera centre, distorted direction) for pixels.

Parameters:

• u (ndarray)

• v (ndarray)

Return type:

tuple[ndarray, ndarray]

class stereocomplex.physics.CentralPinholeModel(K, name='central_pinhole')

Bases: object

Central pinhole rayfield used as the zero-parameter baseline.

Parameters:

• K (ndarray)

• name (str)

classmethod from_parameter_vector(x, **kwargs)

Reconstruct model from a parameter vector. K must be passed via kwargs.

Parameters:

x (ndarray)

Return type:

CentralPinholeModel

property n_parameters: int

Number of free parameters in this model (0 for pinhole, 5 for Brown-Conrady).

parameter_dict()

Model parameters as a dict keyed by coefficient name.

Return type:

dict[str, float]

parameter_vector()

Pack model parameters into a flat vector for optimisation.

Return type:

ndarray

project_point(X)

Analytic projection: 3-D point → pixel via perspective division.

Parameters:

X (ndarray)

Return type:

tuple[ndarray, bool]

ray(u, v)

Compute ray (origin at camera centre, distorted direction) for pixels.

Parameters:

• u (ndarray)

• v (ndarray)

Return type:

tuple[ndarray, ndarray]

class stereocomplex.physics.MultiChannelOpticalModelSelectionReport(channel_reports, best_by_bic, bic_by_model)

Bases: object

Aggregated model-selection report across named camera channels.

Parameters:

• channel_reports (dict[str, OpticalModelSelectionReport])

• best_by_bic (str)

• bic_by_model (dict[str, float])

property channel_names: tuple[str, ...]

Return channel name strings.

property n_channels: int

Number of channels in the rayfield.

rows()

Return model comparison rows as a list of dicts (suitable for DataFrame).

Return type:

list[dict[str, float | int | str | bool]]

class stereocomplex.physics.NonCentralPolynomialChannelModel(K, image_size, origin_x_mm=0.0, origin_y_mm=0.0, origin_z_mm=0.0, k1=0.0, k2=0.0, p1=0.0, p2=0.0, k3=0.0, aberration_coeff_x=(), aberration_coeff_y=(), aberration_terms=('x', 'y', 'x2', 'xy', 'y2'), name='polynomial_surrogate_channel')

Bases: object

Fittable effective channel model for ray-space model selection.

This is a generic non-central surrogate: an effective sub-pupil origin (x, y, z free), a central Brown-Conrady distortion, and a low-order polynomial angular aberration field. It can represent a wide range of smooth rayfields — including CMO-like ones — without encoding any specific shared-objective constraint.

Parameters:

• K (ndarray)

• image_size (tuple[int, int])

• origin_x_mm (float)

• origin_y_mm (float)

• origin_z_mm (float)

• k1 (float)

• k2 (float)

• p1 (float)

• p2 (float)

• k3 (float)

• aberration_coeff_x (tuple[float, ...])

• aberration_coeff_y (tuple[float, ...])

• aberration_terms (tuple[str, ...])

• name (str)

classmethod default_terms()

Return the default polynomial aberration monomials, in packing order.

Return type:

tuple[str, …]

classmethod from_parameter_vector(x, **kwargs)

Rebuild the model from a flat parameter vector.

Inverse of parameter_vector(); see it for the parameter layout.

Parameters:

• x (ndarray, shape (8 + 2 * n_terms,)) – Flattened parameter vector.

• **kwargs – Must include K (3x3 intrinsics) and the image size as cmo_image_size or image_size (a (width, height) pair). May include aberration_terms.

Return type:

NonCentralPolynomialChannelModel

Raises:

ValueError – If the image size is missing or x has the wrong length.

property n_parameters: int

8 (3 origin + 5 distortion) + 2 per aberration term.

Type:

Free-parameter count

parameter_dict()

Return all free parameters as a flat {name: value} dictionary.

Origin entries are in millimetres; distortion entries are dimensionless; aberration entries are keyed aberr_x_<term> and aberr_y_<term>.

Return type:

dict[str, float]

parameter_vector()

Pack all free parameters into a flat optimisation vector.

Layout: [origin_x, origin_y, origin_z (mm), k1, k2, p1, p2, k3, aberration_coeff_x..., aberration_coeff_y...]. Each aberration block follows aberration_terms order and holds len(aberration_terms) entries.

Return type:

ndarray, shape (8 + 2 * len(aberration_terms),)

ray(u, v)

Compute the 3D ray (origin, direction) for each pixel.

Assembles a transient CMOChannelSpec from the model’s free parameters and delegates to CMOChannelRayField.ray().

Parameters:

• u (ndarray) – Pixel coordinates.

• v (ndarray) – Pixel coordinates.

Returns:

origins, directions – Ray origin (mm, world frame) and unit direction for each pixel.

Return type:

ndarray, shape (…, 3)

class stereocomplex.physics.OpticalModelSelectionReport(target_name, candidates, best_by_aic, best_by_bic, best_by_rms, warnings)

Bases: object

AIC/BIC/RMS comparison across fitted optical model candidates.

Parameters:

• target_name (str)

• candidates (list[PhysicalModelFitResult])

• best_by_aic (str)

• best_by_bic (str)

• best_by_rms (str)

• warnings (list[str])

rows()

Return model comparison rows as a list of dicts (suitable for DataFrame).

Return type:

list[dict[str, float | int | str | bool]]

class stereocomplex.physics.ParallelPlateFromRayfieldFitResult(params, success, message, rayfield_rms_support_mm, rayfield_median_support_mm, rayfield_p95_support_mm, rayfield_rms_full_mm, rayfield_median_full_mm, rayfield_p95_full_mm, n_support_samples, n_full_samples, parameter_error=None)

Bases: object

Parallel-plate physical fit and rayfield residual diagnostics.

Parameters:

• params (PinholeParallelPlateFitParams)

• success (bool)

• message (str)

• rayfield_rms_support_mm (float)

• rayfield_median_support_mm (float)

• rayfield_p95_support_mm (float)

• rayfield_rms_full_mm (float)

• rayfield_median_full_mm (float)

• rayfield_p95_full_mm (float)

• n_support_samples (int)

• n_full_samples (int)

• parameter_error (dict[str, float] | None)

class stereocomplex.physics.PhysicalModelFitResult(model_name, model, success, message, n_parameters, n_samples, n_residual_scalars, rss, rms_mm, median_mm, p95_mm, support_rms_mm, full_grid_rms_mm, aic, bic, parameter_vector, parameter_dict)

Bases: object

Fit metrics and optimal parameters for one physical rayfield model.

Parameters:

• model_name (str)

• model (PhysicalRayFieldModel)

• success (bool)

• message (str)

• n_parameters (int)

• n_samples (int)

• n_residual_scalars (int)

• rss (float)

• rms_mm (float)

• median_mm (float)

• p95_mm (float)

• support_rms_mm (float)

• full_grid_rms_mm (float)

• aic (float)

• bic (float)

• parameter_vector (ndarray)

• parameter_dict (dict[str, Any])

class stereocomplex.physics.PhysicalModelSpec(name, model_class, initial_parameters, bounds=None, model_kwargs=None)

Bases: object

Specification for one physical candidate to fit or score.

Parameters:

• name (str)

• model_class (type)

• initial_parameters (ndarray)

• bounds (tuple[ndarray, ndarray] | None)

• model_kwargs (dict[str, Any] | None)

class stereocomplex.physics.PinholeParallelPlateFitParams(alpha_deg, beta_deg, thickness_mm, eta=1.5, d1_mm=80.0)

Bases: object

Physical pinhole + inclined parallel-plate parameters.

Units are millimetres and degrees. d1_mm is kept for ray generation, but is not fitted by default because changing it only moves the plate exit point along the emergent ray and therefore does not change the 3D line.

Parameters:

• alpha_deg (float)

• beta_deg (float)

• thickness_mm (float)

• eta (float)

• d1_mm (float)

class stereocomplex.physics.PinholeParallelPlateModel(K, params)

Bases: PinholeParallelPlateRayField

Physical pinhole + inclined parallel-plate model-selection candidate.

Parameters:

• K (np.ndarray)

• params (PinholeParallelPlateFitParams)

classmethod from_parameter_vector(x, **kwargs)

Reconstruct model from a parameter vector. K must be passed via kwargs.

Parameters:

x (ndarray)

Return type:

PinholeParallelPlateModel

property n_parameters: int

Number of free parameters (2 for plate tilt, 0 for pinhole baseline).

parameter_dict()

Model parameters as a dict keyed by coefficient name.

Return type:

dict[str, float]

parameter_vector()

Pack model parameters into a flat vector for optimisation.

Return type:

ndarray

class stereocomplex.physics.PinholeParallelPlateRayField(K, params)

Bases: object

Small adapter exposing a .ray(u, v) method for a fitted plate model.

Parameters:

• K (np.ndarray)

• params (PinholeParallelPlateFitParams)

ray(u, v)

Compute ray (origin, direction) for a pixel through the inclined parallel plate model.

Parameters:

• u (ndarray)

• v (ndarray)

Return type:

tuple[ndarray, ndarray]

class stereocomplex.physics.PolynomialRayAberration(coeff_x=<factory>, coeff_y=<factory>)

Bases: object

Low-order polynomial perturbation of a ray’s normalised direction.

Models residual aberrations the Brown-Conrady term does not capture, as a cubic polynomial in the normalised image coordinates (x, y). Each of the two output components carries its own sparse coefficient dictionary.

Parameters:

• coeff_x (dict[str, float])

• coeff_y (dict[str, float])

coeff_x, coeff_y

Maps a monomial name to its coefficient, for the x and y direction perturbation respectively. Allowed monomials: 1, x, y, x2, xy, y2, x3, x2y, xy2, y3. Absent terms are treated as zero.

Type:

dict[str, float]

add(other)

Return the coefficient-wise sum of this aberration and other.

Coefficients present in only one operand are kept; coefficients present in both are added. Used to compose a per-channel aberration on top of a shared one.

Parameters:

other (PolynomialRayAberration) – Aberration whose coefficients are added to this one.

Returns:

New instance holding the merged coefficients.

Return type:

PolynomialRayAberration

delta(x, y)

Evaluate the polynomial direction perturbation at normalised coordinates.

Parameters:

• x (ndarray) – Normalised image coordinates (unitless).

• y (ndarray) – Normalised image coordinates (unitless).

Returns:

dx, dy – Additive perturbation of the normalised ray direction, same shape as the inputs.

Return type:

ndarray

Raises:

ValueError – If a coefficient dictionary contains an unknown monomial name.

class stereocomplex.physics.SensorWarp(du_coeff_px=<factory>, dv_coeff_px=<factory>)

Bases: object

Low-order polynomial deformation of the image plane, expressed in pixels.

Models small sensor-mounting / readout geometry errors as a cubic polynomial in image coordinates normalised by the principal-point offset.

Parameters:

• du_coeff_px (dict[str, float])

• dv_coeff_px (dict[str, float])

du_coeff_px, dv_coeff_px

Maps a monomial name to its coefficient (in pixels) for the u and v pixel offset. Allowed monomials: 1, x, y, x2, xy, y2, x3, x2y, xy2, y3. Absent terms are treated as zero.

Type:

dict[str, float]

delta_px(uv, intr)

Evaluate the sensor-plane warp offset, in pixels, at given pixels.

The polynomial is evaluated in coordinates normalised by the principal point: x = (u - cx) / max(|cx|, 1) and likewise for y.

Parameters:

• uv (ndarray, shape (..., 2)) – Pixel coordinates.

• intr (CMOIntrinsics) – Intrinsics supplying the principal point used for normalisation.

Returns:

Pixel offset (du, dv) to add to uv.

Return type:

ndarray, shape (…, 2)

Raises:

ValueError – If a coefficient dictionary contains an unknown monomial name.

class stereocomplex.physics.Vignetting(strength=0.0, floor=0.25, x_shift=0.0, y_shift=0.0)

Bases: object

Multiplicative radial shading (vignetting) of the rendered image.

Brightness falls off quadratically from a (possibly shifted) centre and is clamped to a floor so it never reaches zero.

Parameters:

• strength (float)

• floor (float)

• x_shift (float)

• y_shift (float)

strength

Quadratic fall-off rate; 0 disables vignetting.

Type:

float

floor

Minimum gain (0-1), reached at the image corners.

Type:

float

x_shift, y_shift

Shift of the vignetting centre, in principal-point-normalised units.

Type:

float

gain(intr)

Compute the per-pixel multiplicative vignetting gain map.

The gain is 1 - strength * (x^2 + y^2) in principal-point-normalised coordinates, clamped to [floor, 1].

Parameters:

intr (CMOIntrinsics) – Intrinsics defining the image size and principal point.

Returns:

Multiplicative gain in [floor, 1] to apply to the image.

Return type:

ndarray, shape (height, width)

stereocomplex.physics.aggregate_model_selection_reports(channel_reports)

Aggregate per-channel model-selection reports by summing BIC values.

Parameters:

channel_reports (dict[str, OpticalModelSelectionReport])

Return type:

MultiChannelOpticalModelSelectionReport

stereocomplex.physics.apply_blur_noise(img_u8, blur_sigma_px, noise_std_gray, rng)

Simulate acquisition defects: Gaussian blur followed by Gaussian noise.

Parameters:

• img_u8 (ndarray of uint8) – Clean rendered image.

• blur_sigma_px (float) – Gaussian blur standard deviation, in pixels; 0 disables blur (also a no-op when OpenCV is unavailable).

• noise_std_gray (float) – Standard deviation of the additive Gaussian noise, in gray levels; 0 disables noise.

• rng (numpy.random.Generator) – Random generator used to draw the noise.

Returns:

Degraded image.

Return type:

ndarray of uint8

stereocomplex.physics.apply_sensor_warp(img_u8, warp, intr)

Apply a sensor-plane deformation to an image by inverse mapping.

Each output pixel is sampled from (u, v) - SensorWarp.delta_px of the input. A no-op when the warp has no coefficients or OpenCV is unavailable.

Parameters:

• img_u8 (ndarray of uint8) – Input grayscale image.

• warp (SensorWarp) – Image-plane deformation to apply.

• intr (CMOIntrinsics) – Intrinsics defining the image grid and principal point.

Returns:

Warped image, same shape as the input.

Return type:

ndarray of uint8

stereocomplex.physics.brown_conrady_distort_normalized(x, y, k1, k2, p1, p2, k3)

Apply Brown-Conrady distortion to normalised camera coordinates.

Uses the standard OpenCV convention: xd = x * (1 + k1*r2 + k2*r4 + k3*r6) + 2*p1*x*y + p2*(r2 + 2*x^2) yd = y * (1 + k1*r2 + k2*r4 + k3*r6) + p1*(r2 + 2*y^2) + 2*p2*x*y where r2 = x^2 + y^2.

Parameters:

• x (ndarray) – Undistorted normalised image coordinates (unitless).

• y (ndarray) – Undistorted normalised image coordinates (unitless).

• k1 (float) – Radial distortion coefficients (k3 is optional, often 0).

• k2 (float) – Radial distortion coefficients (k3 is optional, often 0).

• k3 (float) – Radial distortion coefficients (k3 is optional, often 0).

• p1 (float) – Tangential distortion coefficients.

• p2 (float) – Tangential distortion coefficients.

Returns:

xd, yd – Distorted normalised coordinates (unitless).

Return type:

ndarray

stereocomplex.physics.compute_cmo_zernike_residuals(cmo_model, zernike_left, zernike_right, grid_shape=(17, 13), image_size=None, zernike_order=4)

Compute direction/moment residuals between a CMO model and Zernike rayfield.

Returns delta_d (deg), delta_m (mm), and Zernike modal projection of the direction residual field.

Parameters:

• grid_shape (tuple[int, int])

• image_size (tuple[int, int] | None)

• zernike_order (int)

Return type:

dict[str, Any]

stereocomplex.physics.default_physical_model_specs(*, include_telecentric=False)

Return the standard candidate set used in the parallel-plate notebook.

Set include_telecentric to True to add the quasi-telecentric CMO candidate.

Parameters:

include_telecentric (bool)

Return type:

list[PhysicalModelSpec]

stereocomplex.physics.fit_cmo_physical_stereo_model_to_rayfields(left_field, right_field, image_size, initial_parameters, bounds=None, *, pixel_pitch_mm, z_planes=(50.0, 250.0), grid_shape=(17, 13), support_pixels_left=None, support_pixels_right=None, support_weight=1.0, full_grid_weight=0.25, robust_loss='huber', max_nfev=2000)

Fit the shared physical CMO rig to left and right measured Zernike rayfields.

This entry point fits the shared 19/21-parameter paraxial CMO model: baseline, working distance, objective focal length, tube focal length, principal-point terms, two global tilt angles, one axial telecentric offset/depth parameter, and per-channel Brown-Conrady distortion. It does not fit the paper’s 26-parameter CMO + per-arm SE(3) bundle-adjustment model.

Parameters:

• left_field (ZernikeRayField) – Measured left-channel rayfield (origin + direction).

• right_field (ZernikeRayField) – Measured right-channel rayfield.

• image_size ((int, int)) – Sensor dimensions in pixels (width, height).

• initial_parameters (ndarray, shape (19,) or (21,)) – Starting parameter vector. 19 = shared PP, 21 = aligned PP.

• bounds (tuple of ndarray, optional) – Lower and upper bounds for the parameters.

• pixel_pitch_mm (float) – Sensor pixel pitch in millimetres.

• z_planes ((float, float)) – Two z-planes in mm (default 50, 250) where ray intersections are evaluated.

• grid_shape ((int, int)) – Subsampling grid for the full-image residual.

• support_pixels_left (ndarray, optional) – Observed-pixel coords (N, 2) whose ray gap is up-weighted.

• support_pixels_right (ndarray, optional) – Observed-pixel coords (N, 2) whose ray gap is up-weighted.

• support_weight (float) – Relative weight of support-pixel vs full-grid residuals.

• full_grid_weight (float) – Relative weight of the full-grid residual term.

• robust_loss (str) – "huber" or "soft_l1" — robust loss for least_squares.

• max_nfev (int) – Maximum number of function evaluations for the optimiser.

Returns:

Dataclass result object with parameter_vector (optimal params), message, success, model (the fitted CMO stereo model), and diagnostics.

Return type:

CMOPhysicalStereoFitResult

Notes

The two-zone loss (sparse support + subsampled full grid) balances fidelity to observation pixels with smooth ray-space behaviour across the image. It is a rayfield-to-model fit, not the final per-arm SE(3) paper BA.

stereocomplex.physics.fit_cmo_stereo_model_and_poses_from_zernike_rayfields(left_field, right_field, K, image_size, object_points, left_pixels, right_pixels, pose_initials, *, initial_left_parameters=None, initial_right_parameters=None, parameter_bounds=None, aberration_terms=None, z_planes=(80.0, 260.0), incidence_weight=1.0, rayfield_weight=0.25, pose_regularization=0.0, max_nfev=800, robust_loss='huber')

Jointly fit effective CMO channel parameters and per-frame board poses.

The measured left/right Zernike rayfields supply the pixel-to-line observations. The fit minimises two coupled residual terms:

• incidence: each ChArUco object point must lie on the back-projected ray of its observed pixel (point-to-line distance);

• rayfield anchor: the CMO model rays must stay close to the measured Zernike rayfield, sampled on two depth planes.

A robust loss down-weights outliers.

Parameters:

• left_field (ZernikeRayField) – Measured rayfields providing the per-channel ray anchor.

• right_field (ZernikeRayField) – Measured rayfields providing the per-channel ray anchor.

• K (ndarray, shape (3, 3)) – Shared pinhole intrinsics used to seed the surrogate channels.

• image_size (tuple of 2 int) – Image (width, height) in pixels.

• object_points (ndarray or list of ndarray) – ChArUco corner coordinates in board millimetres — one (M, 2) array per frame, or a single (M, 2) array shared by all frames.

• left_pixels (list of ndarray) – Observed corner pixels per frame, one (M, 2) array each.

• right_pixels (list of ndarray) – Observed corner pixels per frame, one (M, 2) array each.

• pose_initials (list of CMOPlanePose) – Initial board pose, one per frame.

• initial_left_parameters (ndarray, optional) – Initial per-channel parameter vectors; default to zeros.

• initial_right_parameters (ndarray, optional) – Initial per-channel parameter vectors; default to zeros.

• parameter_bounds (tuple of (ndarray, ndarray), optional) – Lower/upper bounds for the per-channel parameters; sensible defaults are used when omitted.

• aberration_terms (tuple of str, optional) – Polynomial aberration monomials to fit.

• z_planes (tuple of 2 float) – The two depth planes (mm) on which the rayfield anchor is evaluated.

• incidence_weight (float) – Weight of the point-to-ray incidence residual.

• rayfield_weight (float) – Weight of the rayfield-anchor residual.

• pose_regularization (float) – L2 penalty pulling poses toward their initial values.

• max_nfev (int) – Maximum optimiser function evaluations.

• robust_loss (str) – SciPy least_squares loss name (e.g. "huber", "linear").

Returns:

Fitted models, poses, and incidence / rayfield diagnostics.

Return type:

CMORayfieldBundleAdjustmentResult

stereocomplex.physics.fit_cmo_telecentric_model_to_rayfields(left_field, right_field, image_size, initial_parameters, *, pixel_pitch_mm, z_planes=(50.0, 250.0), grid_shape=(17, 13), full_grid_weight=0.0, max_nfev=500)

Fit the telecentric CMO model to left and right measured Zernike rayfields.

This variant assumes telecentricity in object space, reducing the parameter count compared to the full physical model. It fits baseline, working distance, and per-channel sub-pupil positions while keeping the objective focal length fixed at infinity in object space.

Parameters:

• left_field (ZernikeRayField) – Measured left-channel rayfield (origin field + direction field).

• right_field (ZernikeRayField) – Measured right-channel rayfield.

• image_size ((int, int)) – Sensor dimensions in pixels (width, height).

• initial_parameters (ndarray, shape (12,), (14,), or (16,)) – Starting parameter vector. The supported variants are shared slopes/shear (12), per-channel slopes with shared shear (14), and per-channel slopes plus per-channel shear (16).

• pixel_pitch_mm (float) – Sensor pixel pitch in millimetres.

• z_planes ((float, float)) – Two z-planes in mm (default 50, 250) for ray intersection evaluation.

• grid_shape ((int, int)) – Subsampling grid (width, height) for the full-image residual.

• full_grid_weight (float) – Relative weight of the full-grid residual term (0 = only support pixels).

• max_nfev (int) – Maximum number of function evaluations for the optimiser.

Returns:

Dataclass result object with parameter_vector (optimal parameters), message, success, and model (the fitted CMOTelecentricStereoModel).

Return type:

CMOPhysicalStereoFitResult

stereocomplex.physics.fit_cmo_warped_model_to_rayfields(left_field, right_field, image_size, initial_parameters, *, pixel_pitch_mm, z_planes=(50.0, 250.0), grid_shape=(17, 13), max_nfev=500, warp_level=0, shared_warp=True)

Fit the warped CMO model with sensor-plane polynomial corrections.

The most flexible CMO variant. It adds a per-channel 2-D polynomial warp on the sensor plane before ray evaluation, capturing residual non-idealities beyond the physical model.

Parameters:

• left_field (ZernikeRayField) – Measured left-channel rayfield.

• right_field (ZernikeRayField) – Measured right-channel rayfield.

• image_size ((int, int)) – Sensor dimensions in pixels (width, height).

• initial_parameters (ndarray) – Starting parameter vector including CMO rig + warp coefficients.

• pixel_pitch_mm (float) – Sensor pixel pitch in millimetres.

• z_planes ((float, float)) – Two z-planes in mm (default 50, 250) for ray intersection evaluation.

• grid_shape ((int, int)) – Subsampling grid for the full-image residual.

• max_nfev (int) – Maximum number of function evaluations.

• warp_level (int) – Polynomial level for the sensor-plane warp.

• shared_warp (bool) – If True, left and right channels share the same warp coefficients.

Returns:

Dataclass result object with parameter_vector (optimal params), message, success, and model (the fitted CMOWarpedStereoModel).

Return type:

CMOPhysicalStereoFitResult

stereocomplex.physics.fit_parallel_plate_to_zernike_rayfield(zernike_field, K, image_size, initial_params=None, eta=1.5, z_planes=(100.0, 1000.0), grid_shape=(25, 19), support_pixels=None, support_weight=1.0, full_grid_weight=0.25, fit_eta=False, robust_loss='huber', oracle_params=None)

Fit a compact pinhole + plate model to an already measured rayfield.

The target rayfield is treated as a geometric observable. The residual is evaluated in ray space by intersecting both rayfields with two z-planes; raw ray origins are never compared directly.

Parameters:

• K (ndarray)

• image_size (tuple[int, int])

• initial_params (PinholeParallelPlateFitParams | None)

• eta (float)

• z_planes (tuple[float, float])

• grid_shape (tuple[int, int])

• support_pixels (ndarray | None)

• support_weight (float)

• full_grid_weight (float)

• fit_eta (bool)

• robust_loss (str)

• oracle_params (PinholeParallelPlateFitParams | ParallelPlateSyntheticParams | None)

Return type:

ParallelPlateFromRayfieldFitResult

stereocomplex.physics.fit_physical_model_to_rayfield(model_class, target_field, K, image_size, initial_parameters=None, bounds=None, z_planes=(100.0, 1000.0), grid_shape=(25, 19), support_pixels=None, support_weight=1.0, full_grid_weight=0.25, robust_loss='huber', max_nfev=2000, name=None, **model_kwargs)

Fit a physical model candidate to a measured rayfield in ray space.

This is the core model selection routine. Given a measured rayfield and a physical model class, it optimises the model parameters so that the model rays best reproduce the measured rays, then returns a fit result with RMS error and parameter estimates.

Parameters:

• model_class (type) – Physical model class with ray(u,v) -> (origin, direction).

• target_field (ZernikeRayField) – Measured rayfield to match (origin + direction field).

• K (ndarray, shape (3, 3)) – Camera matrix.

• image_size ((int, int)) – Sensor dimensions in pixels (width, height).

• initial_parameters (ndarray, optional) – Starting parameter vector (defaults to model_class default).

• bounds ((lo, hi), optional) – Lower and upper bounds for the parameters.

• z_planes ((float, float)) – Two z-planes in mm (default 100, 1000) for ray intersection evaluation.

• grid_shape ((int, int)) – Subsampling grid for the full-image residual.

• support_pixels (ndarray, optional) – Observed-pixel coords (N, 2) whose ray gap is up-weighted.

• support_weight (float) – Relative weight of support-pixel residuals.

• full_grid_weight (float) – Relative weight of the full-grid residual term.

• robust_loss (str) – "huber" or "soft_l1" — robust loss for least_squares.

• max_nfev (int) – Maximum number of function evaluations.

• name (str, optional) – Human-readable model name for reporting.

• **model_kwargs – Additional keyword arguments forwarded to the model constructor.

Returns:

Dataclass result object with parameter_vector (optimal parameters), rms_mm, success, and model (the fitted instance).

Return type:

PhysicalModelFitResult

stereocomplex.physics.generate_cmo_plane_dataset(out_dir, cmo, target, poses, image_format='png', blur_sigma_px=0.0, noise_std_gray=2.0, seed=0)

Render and write a full CMO stereo planar-target dataset to disk.

For each pose, both channels are rendered with the CMO physics model and the target inner corners are projected to ground-truth pixels. The output directory receives left/ and right/ PNG folders, meta.json, frames.jsonl and gt_charuco_corners.npz.

Parameters:

• out_dir (Path) – Output directory; created if missing.

• cmo (CMOStereoSpec) – Stereo CMO model used for rendering and ground-truth projection.

• target (CMOPlaneTargetSpec) – Planar target geometry.

• poses (list of CMOPlanePose) – One target pose per frame.

• image_format ({"png"}) – Output image format (only PNG is supported).

• blur_sigma_px (float) – Gaussian blur sigma in pixels applied to the rendered images.

• noise_std_gray (float) – Gaussian noise standard deviation, in gray levels.

• seed (int) – Seed for the noise random generator.

Raises:

ValueError – If image_format is not “png”.

Return type:

None

stereocomplex.physics.intersect_ray_with_z_plane(origin_points, d, z)

Intersect one or more rays with a horizontal z-plane at a given depth.

Parameters:

• origin_points (ndarray, shape (N, 3)) – Ray origins in world coordinates, in millimetres.

• d (ndarray, shape (N, 3)) – Ray directions (unit vectors).

• z (float) – Z-coordinate of the target plane in millimetres.

Returns:

Intersection points in millimetres.

Return type:

ndarray, shape (N, 3)

Raises:

ValueError – If any ray direction has a z-component smaller than 1e-12 in absolute value (ray is parallel to the plane).

stereocomplex.physics.intersect_rays_with_plane(origins, directions, pose)

Intersect a dense rayfield with a planar target.

Solves, per ray, for tau such that origin + tau * direction lies on the plane through pose.t with normal pose.normal_world.

Parameters:

• origins (ndarray, shape (..., 3)) – Ray origins (mm) and directions in the world frame.

• directions (ndarray, shape (..., 3)) – Ray origins (mm) and directions in the world frame.

• pose (CMOPlanePose) – Pose of the target plane.

Returns:

• X (ndarray, shape (…, 3)) – Intersection points in world millimetres (NaN where the ray is parallel to the plane).

• valid (ndarray of bool, shape (…)) – True where the intersection is finite and in front of the ray origin (tau > 0).

Return type:

tuple[ndarray, ndarray]

stereocomplex.physics.make_reference_cmo_scenario()

Build a canonical CMO test scenario: stereo model, target and poses.

Returns a fixed, reproducible setup — a symmetric CMO stereo head carrying a shared aberration plus per-channel distortion / aberration asymmetries, a ChArUco planar target, and a list of target poses — used as a known-truth case for tests and demonstrations.

Returns:

• cmo (CMOStereoSpec) – The stereo CMO model.

• target (CMOPlaneTargetSpec) – The planar ChArUco target.

• poses (list of CMOPlanePose) – Target poses spanning the working volume.

Return type:

tuple[CMOStereoSpec, CMOPlaneTargetSpec, list[CMOPlanePose]]

stereocomplex.physics.normalize_vectors(v, eps=1e-15)

Normalize an array of vectors to unit length along the last axis.

Parameters:

• v (ndarray, shape (..., D)) – Stack of vectors; the last axis holds the vector components.

• eps (float) – Lower bound on the divisor norm, so a (near-)zero vector stays finite instead of producing a division by zero.

Returns:

Each vector divided by its Euclidean norm (or by eps when that norm is smaller than eps).

Return type:

ndarray, shape (…, D)

stereocomplex.physics.pinhole_parallel_plate_ray_from_pixel(u, v, K, params)

Compute the 3-D ray (origin, direction) for a pixel through a pinhole camera with an inclined parallel plate in front of the sensor.

The plate shifts the apparent ray origin while preserving the direction.

Parameters:

• u (ndarray) – Pixel x-coordinates.

• v (ndarray) – Pixel y-coordinates.

• K (ndarray, shape (3, 3)) – Camera matrix.

• params (PinholeParallelPlateFitParams) – Plate geometry (normal, thickness, refractive index, distance).

Returns:

(origin, direction) – Ray origins in mm and unit directions, each shape (N, 3).

Return type:

tuple of ndarray

stereocomplex.physics.polynomial_channel_parameters_from_spec(channel, common_aberration=None, aberration_terms=None)

Convert a CMOChannelSpec into a NonCentralPolynomialChannelModel vector.

The fittable CMO surrogate is per-channel: its polynomial aberration is the sum of the shared (common) CMO aberration and the channel’s differential aberration. This packs that effective channel into the flat vector the surrogate model optimises.

Parameters:

• channel (CMOChannelSpec) – Channel to convert.

• common_aberration (PolynomialRayAberration, optional) – Shared aberration; defaults to none.

• aberration_terms (tuple of str, optional) – Monomials to keep; defaults to NonCentralPolynomialChannelModel.default_terms().

Returns:

Parameter vector in NonCentralPolynomialChannelModel.parameter_vector() layout.

Return type:

ndarray, shape (8 + 2 * len(aberration_terms),)

stereocomplex.physics.pose_from_euler_xyz(rx, ry, rz, t_xyz)

Build a planar-target pose from intrinsic XYZ Euler angles and a translation.

The rotation is composed as R = Rz(rz) @ Ry(ry) @ Rx(rx): the board is rotated first about X, then Y, then Z, all in the CMO/world frame.

Parameters:

• rx (float) – Euler angles in radians about the world X, Y and Z axes.

• ry (float) – Euler angles in radians about the world X, Y and Z axes.

• rz (float) – Euler angles in radians about the world X, Y and Z axes.

• t_xyz (tuple of 3 float) – Target-origin position in the world frame, in millimetres.

Returns:

Rigid pose mapping board-plane coordinates to the world frame.

Return type:

CMOPlanePose

stereocomplex.physics.project_cmo_points(channel, common_aberration, xyz_world_mm, *, max_nfev=40)

Project world points by inverting the channel’s pixel-to-ray model.

The exact sparse counterpart of the renderer’s pixel -> ray -> plane model: for each point, the pixel whose CMO ray passes closest to the point (minimum point-to-ray / Plücker distance) is found by least squares. project_cmo_points_approx() provides the optimiser initialisation.

Parameters:

• channel (CMOChannelSpec) – Target channel.

• common_aberration (PolynomialRayAberration) – Shared aberration added to the channel’s differential aberration.

• xyz_world_mm (ndarray, shape (N, 3)) – World points to project, in millimetres.

• max_nfev (int) – Maximum optimiser function evaluations per point.

Returns:

Sub-pixel pixel coordinates minimising point-to-ray distance.

Return type:

ndarray, shape (N, 2)

stereocomplex.physics.project_cmo_points_approx(channel, common_aberration, xyz_world_mm)

First-order (pinhole-like) forward projection of world points into a channel.

Transforms points into the channel camera frame, applies the perspective divide, the polynomial aberration, Brown-Conrady distortion and the sensor warp. This is an approximation — it ignores the non-central sub-pupil geometry — used mainly to seed the exact project_cmo_points().

Parameters:

• channel (CMOChannelSpec) – Target channel.

• common_aberration (PolynomialRayAberration) – Shared aberration added to the channel’s differential aberration.

• xyz_world_mm (ndarray, shape (N, 3)) – World points to project, in millimetres.

Returns:

Pixel coordinates; rows behind the camera (z <= 0) are NaN.

Return type:

ndarray, shape (N, 2)

stereocomplex.physics.project_cmo_target_corners(cmo, target, pose)

Project the target’s inner corners into both CMO channels.

Inner corners are placed in the world frame via pose and projected with project_cmo_points(); only corners visible (in bounds) in both channels are kept.

Parameters:

• cmo (CMOStereoSpec) – Stereo model.

• target (CMOPlaneTargetSpec) – Planar target geometry.

• pose (CMOPlanePose) – Pose of the target in the world frame.

Returns:

Keys: corner_id (ndarray int), XYZ_world_mm (N, 3 float32), uv_left_px and uv_right_px (N, 2 float32) — restricted to corners visible in both channels.

Return type:

dict

stereocomplex.physics.rayfield_two_plane_residuals(field_a, field_b, pixels, z_planes=(100.0, 1000.0))

Compare two rayfields by intersections with two reference z-planes.

Both field_a and field_b must declare frame_convention = "opencv_y_down" (the internal StereoComplex convention). A ValueError is raised if either declares a different convention.

Parameters:

• pixels (ndarray)

• z_planes (tuple[float, float])

Return type:

ndarray

stereocomplex.physics.rays_from_cmo_pixels(channel, common_aberration)

Compute the dense per-pixel CMO rayfield of a channel, in world coordinates.

Parameters:

• channel (CMOChannelSpec) – Channel whose optics define the rays.

• common_aberration (PolynomialRayAberration) – Shared aberration added to the channel’s differential aberration.

Returns:

origins, directions – Per-pixel ray origin (mm) and unit direction in the world frame.

Return type:

ndarray, shape (H, W, 3)

stereocomplex.physics.render_cmo_channel_image(cmo, channel, target, pose, texture_u8, interpolation='linear', background_gray=20, blur_sigma_px=0.0, noise_std_gray=0.0, rng=None)

Render one CMO channel image: pixel -> physical ray -> target-plane sampling.

For every pixel the channel’s physical ray is traced, intersected with the posed target plane, and the target texture is sampled at the hit point. Pixels that miss the target get background_gray; vignetting, then optional blur and noise, are applied last.

Parameters:

• cmo (CMOStereoSpec) – Stereo model (supplies the shared common aberration).

• channel (CMOChannelSpec) – Channel to render.

• target (CMOPlaneTargetSpec) – Planar target geometry.

• pose (CMOPlanePose) – Pose of the target in the world frame.

• texture_u8 (ndarray of uint8) – Target texture, e.g. from CMOPlaneTargetSpec.make_texture_u8().

• interpolation ({"nearest", "linear", "cubic", "lanczos4"}) – Texture resampling kernel.

• background_gray (int) – Gray level (0-255) for pixels that miss the target.

• blur_sigma_px (float) – Gaussian blur sigma in pixels (0 disables).

• noise_std_gray (float) – Gaussian noise standard deviation in gray levels (0 disables).

• rng (numpy.random.Generator, optional) – Random generator for the noise; a default-seeded one is used if omitted.

Returns:

The rendered channel image.

Return type:

ndarray of uint8, shape (height, width)

stereocomplex.physics.reprojection_guard_penalty(px_rms, *, threshold_px=1.5, n_pixel_observations, hard_penalty=1000000.0, alpha=1.0)

Penalty term for models exceeding a pixel reprojection threshold.

Returns 0 if px_rms <= threshold_px. Otherwise returns a hard barrier plus a log-ratio term that ranks non-usable models among themselves:

penalty = hard_penalty + alpha * n_obs * log((px_rms / threshold)^2)

This is designed to be added to a ray-space BIC to produce an operational bic_usable that enforces a usability constraint.

Notes

This penalty is not a statistical likelihood term. It is an operational guard: a model whose direct pixel reprojection RMS is above threshold_px is considered non-usable for calibration, even if it explains the rayfield compactly.

Parameters:

• px_rms (float)

• threshold_px (float)

• n_pixel_observations (int)

• hard_penalty (float)

• alpha (float)

Return type:

float

stereocomplex.physics.rotx(a)

Active 3x3 rotation matrix about the world X axis (right-hand rule); a in radians.

Parameters:

a (float)

Return type:

ndarray

stereocomplex.physics.roty(a)

Active 3x3 rotation matrix about the world Y axis (right-hand rule); a in radians.

Parameters:

a (float)

Return type:

ndarray

stereocomplex.physics.rotz(a)

Active 3x3 rotation matrix about the world Z axis (right-hand rule); a in radians.

Parameters:

a (float)

Return type:

ndarray

stereocomplex.physics.sample_cmo_target_texture(target, texture_u8, local_xy_mm, inside, interpolation='linear')

Sample a target texture at board-local metric coordinates.

Board-local millimetre coordinates are mapped to texture pixel coordinates, then resampled (via cv2.remap when OpenCV is available, else nearest-neighbour). Samples outside inside are set to 0.

Parameters:

• target (CMOPlaneTargetSpec) – Target geometry (supplies the board width/height in mm).

• texture_u8 (ndarray of uint8, shape (Ht, Wt)) – Texture image to sample.

• local_xy_mm (ndarray, shape (..., 2)) – Board-local coordinates, in millimetres.

• inside (ndarray of bool, shape (...)) – Mask of samples that fall on the physical target.

• interpolation ({"nearest", "linear", "cubic", "lanczos4"}) – Resampling kernel.

Returns:

Sampled grayscale values, 0 outside inside.

Return type:

ndarray of uint8

stereocomplex.physics.save_gray(path, img_u8)

Write a grayscale image to disk as a PNG.

Uses Pillow when available, otherwise OpenCV.

Parameters:

• path (Path) – Destination file path; parent directories are created as needed.

• img_u8 (ndarray of uint8) – Grayscale image to save.

Raises:

RuntimeError – If neither Pillow nor OpenCV is available, or the write fails.

Return type:

None

stereocomplex.physics.select_physical_model_from_rayfield(target_field, candidate_specs, K, image_size, z_planes=(100.0, 1000.0), grid_shape=(25, 19), support_pixels=None, support_weight=1.0, full_grid_weight=0.25, max_nfev=2000, target_right=None, K_right=None, support_pixels_right=None)

Fit candidate physical models and select the best in ray space.

With only target_field this keeps the historical single-channel behavior. When target_right is provided, non-shared candidates are fitted independently to both channels and aggregated, while stereo-shared candidates such as CMOPhysicalStereoModel are fitted once with their shared parameter vector.

Parameters:

• candidate_specs (list[PhysicalModelSpec] | None)

• K (ndarray)

• image_size (tuple[int, int])

• z_planes (tuple[float, float])

• grid_shape (tuple[int, int])

• support_pixels (ndarray | None)

• support_weight (float)

• full_grid_weight (float)

• max_nfev (int)

• K_right (ndarray | None)

• support_pixels_right (ndarray | None)

Return type:

OpticalModelSelectionReport

stereocomplex.physics.undistort_brown_normalized(xd, yd, k1, k2, p1, p2, k3, n_iter=10)

Invert Brown-Conrady distortion by fixed-point iteration.

The model-selection use case only needs a stable central candidate, not a high-performance undistorter. The iteration is vectorized and initialized at the distorted normalized coordinates.

Parameters:

• xd (ndarray)

• yd (ndarray)

• k1 (float)

• k2 (float)

• p1 (float)

• p2 (float)

• k3 (float)

• n_iter (int)

Return type:

tuple[ndarray, ndarray]

stereocomplex.physics.usable_bic(bic_ray, px_rms, *, threshold_px=1.5, n_pixel_observations, hard_penalty=1000000.0, alpha=1.0)

Return ray-space BIC plus an operational pixel-RMS usability guard.

bic_ray remains the Gaussian BIC computed from ray-space residuals. usable_bic adds a hard penalty when the same model is not usable in direct reprojection, according to threshold_px.

This deliberately separates two questions:

• ray-space BIC: which optical family explains the measured rayfield?

• usable BIC: which model is accurate enough for calibration use?

Parameters:

• bic_ray (float)

• px_rms (float)

• threshold_px (float)

• n_pixel_observations (int)

• hard_penalty (float)

• alpha (float)

Return type:

float

Zernike rayfields — stereocomplex.rayfields

Zernike origin / ray-field models and the N-camera rayfield container.

Zernike-based ray-field models for non-central stereo calibration.

class stereocomplex.rayfields.MultiCameraZernikeRayField(channels)

Bases: object

Ordered collection of named Zernike rayfields, one per camera.

Container for an N-camera calibration result: each camera contributes one ZernikeRayField, addressed by name. Channel names must be unique and non-empty.

Parameters:

channels (tuple[ZernikeRayFieldChannel, ...])

channels

The per-camera rayfields, in a fixed order.

Type:

tuple of ZernikeRayFieldChannel

channel(name)

Return the rayfield of the named channel.

Parameters:

name (str) – Channel name.

Return type:

ZernikeRayField

Raises:

KeyError – If no channel has that name.

classmethod from_camera_configs(intrinsics_by_channel, configs_by_channel)

Build zero-initialised rayfields for a set of cameras.

Creates one ZernikeRayField per channel from its intrinsics and Zernike configuration, with all coefficients at zero (i.e. the plain pinhole model). The two mappings must cover exactly the same set of channel names.

Parameters:

• intrinsics_by_channel (dict[str, ndarray]) – 3x3 pinhole intrinsic matrix per channel.

• configs_by_channel (dict[str, ZernikeOriginFieldConfig]) – Zernike field configuration per channel.

Return type:

MultiCameraZernikeRayField

Raises:

ValueError – If the two mappings do not cover the same set of channel names.

classmethod from_fields(fields)

Build a multi-camera rayfield from a mapping of named rayfields.

Parameters:

fields (dict[str, ZernikeRayField]) – Rayfield per channel name; iteration order fixes the channel order.

Return type:

MultiCameraZernikeRayField

property n_channels: int

Total number of channels.

property names: tuple[str, ...]

Channel names in insertion order.

ray(name, u, v)

Compute the 3D ray for a pixel in a named channel.

Parameters:

• name (str) – Channel name.

• u (ndarray) – Pixel coordinates.

• v (ndarray) – Pixel coordinates.

Returns:

origin, direction – Ray origin (mm) and unit direction per pixel, in the channel frame.

Return type:

ndarray, shape (N, 3)

class stereocomplex.rayfields.ZernikeCandidate(K, config, coefficients, name='zernike_compact', is_stereo_shared=False, fit_directions=True)

Bases: object

Compact Zernike origin-field candidate for ray-space model selection.

This wraps a ZernikeOriginField into the PhysicalRayFieldModel protocol so it can compete alongside the physical candidates (pinhole, Brown-Conrady, CMO, polynomial surrogate) in select_physical_model_from_rayfield().

The candidate usually uses a lower max-order than the measured Zernike rayfield. The raw coefficient count is n_modes * 6 when directions are fitted and n_modes * 3 for origin-only fitting. The number therefore depends on the exact Zernike mode list and on whether direction coefficients are part of the candidate.

By default both origin and direction Zernike fields are fitted (fit_directions=True, using ZernikeRayField). Set fit_directions=False for origin-only fitting with ZernikeOriginField (3 scalar coefficients per mode instead of 6).

Note

The transverse gauge \(O(u,v)\cdot d(u,v)=0\) is enforced at ray-evaluation time. Depending on the gauge and on whether pose parameters are included in a surrounding fit, the effective comparison count may differ from the raw coefficient count. The n_parameters property intentionally reports the raw coefficient count (6 or 3 per mode) for BIC consistency across candidates.

Parameters:

• K (ndarray)

• config (ZernikeOriginFieldConfig)

• coefficients (ZernikeRayFieldCoefficients)

• name (str)

• is_stereo_shared (bool)

• fit_directions (bool)

classmethod from_parameter_vector(x, **kwargs)

Rebuild a candidate from a flat parameter vector.

Inverse of parameter_vector(); see it for the layout.

Parameters:

• x (ndarray) – Flat coefficient vector.

• **kwargs – Must include config (ZernikeOriginFieldConfig) and K (3x3 intrinsics); may include fit_directions (default True).

Return type:

ZernikeCandidate

Raises:

ValueError – If the length of x does not match the mode count and the fit_directions setting.

property n_parameters: int

n_modes * 6 with directions, * 3 without.

This is the raw coefficient count. The transverse gauge removes one redundant degree of freedom per mode, so the effective count is slightly lower — see the class docstring.

Type:

Raw free-parameter count

parameter_dict()

Return all coefficients as a flat {name: value} dictionary.

Keys encode the mode index and its (n, m, kind) descriptor, suffixed by the component: _Ox/_Oy/_Oz for the origin field (mm) and, when directions are fitted, _dx/_dy/_dz for the direction perturbation (dimensionless).

Return type:

dict[str, float]

parameter_vector()

Pack the Zernike coefficients into a flat optimisation vector.

Layout: the (n_modes, 3) origin coefficients flattened, followed — when fit_directions is set — by the (n_modes, 3) direction coefficients.

Return type:

ndarray, shape (n_modes * 6,) or (n_modes * 3,)

ray(u, v)

Compute the 3D ray (origin, direction) for the given pixels.

Builds the underlying ZernikeRayField (or ZernikeOriginField when fit_directions is False) from the candidate coefficients and evaluates it.

Parameters:

• u (ndarray) – Pixel coordinates.

• v (ndarray) – Pixel coordinates.

Returns:

origin, direction – Ray origin (mm) and unit direction per pixel.

Return type:

ndarray, shape (N, 3)

class stereocomplex.rayfields.ZernikeOriginField(K, config, coefficients=None)

Bases: object

Generic non-central ray model with pinhole directions and a Zernike origin field.

The physical oracle may choose any point on a ray. This model uses the canonical transverse gauge O(u,v) dot d(u,v) = 0 by default.

Parameters:

• K (np.ndarray)

• config (ZernikeOriginFieldConfig)

• coefficients (ZernikeOriginFieldCoefficients | None)

basis(u, v)

Evaluate the Zernike design matrix at the given pixels.

Pixel coordinates are mapped to the unit disk (via the image diagonal), then every Zernike mode is evaluated to form one column of the matrix.

Parameters:

• u (ndarray) – Pixel coordinates (broadcast against each other).

• v (ndarray) – Pixel coordinates (broadcast against each other).

Returns:

Design matrix A; A @ coeffs gives the field sampled at the N flattened pixels.

Return type:

ndarray, shape (N, n_modes)

Raises:

ValueError – If the configured image is not larger than one pixel per axis.

property coeffs: ndarray

Origin-field Zernike coefficients, shape (n_modes, 3), in millimetres.

direction(u, v)

Return the unit pinhole ray directions at the given pixels.

In this model the origin field carries the non-central behaviour; directions are the plain pinhole rays from the intrinsic matrix K.

Parameters:

• u (ndarray) – Pixel coordinates.

• v (ndarray) – Pixel coordinates.

Returns:

Unit ray directions.

Return type:

ndarray, shape (N, 3)

origin(u, v)

Return the origin field O(u, v), with the transverse gauge applied.

When config.enforce_transverse_gauge is set, the raw Zernike origin is projected perpendicular to the ray direction (O . d = 0), removing the redundant longitudinal displacement along each ray.

Parameters:

• u (ndarray) – Pixel coordinates.

• v (ndarray) – Pixel coordinates.

Returns:

Ray origin per pixel, in millimetres.

Return type:

ndarray, shape (N, 3)

raw_origin(u, v)

Return the Zernike origin field before the transverse gauge is applied.

Parameters:

• u (ndarray) – Pixel coordinates.

• v (ndarray) – Pixel coordinates.

Returns:

Origin field basis(u, v) @ coeffs, in millimetres.

Return type:

ndarray, shape (N, 3)

ray(u, v)

Return the rays (O(u, v), d(u, v)) for the given pixels.

Parameters:

• u (ndarray) – Pixel coordinates.

• v (ndarray) – Pixel coordinates.

Returns:

• origin (ndarray, shape (N, 3)) – Ray origin per pixel (mm), gauge-projected when configured.

• direction (ndarray, shape (N, 3)) – Unit pinhole ray direction per pixel.

Return type:

tuple[ndarray, ndarray]

class stereocomplex.rayfields.ZernikeOriginFieldCoefficients(coeffs)

Bases: object

Zernike coefficients of an origin field O(u, v).

Parameters:

coeffs (ndarray)

coeffs

One 3-vector per Zernike mode, in millimetres; the origin field is basis(u, v) @ coeffs.

Type:

ndarray, shape (n_modes, 3)

class stereocomplex.rayfields.ZernikeOriginFieldConfig(image_size, max_order=4, normalization='diagonal_disk', enforce_transverse_gauge=True)

Bases: object

Configuration of a Zernike origin / ray field: domain, order and gauge.

Parameters:

• image_size (tuple[int, int])

• max_order (int)

• normalization (str)

• enforce_transverse_gauge (bool)

image_size

Image (width, height) in pixels; defines the disk over which the Zernike polynomials are evaluated.

Type:

tuple of 2 int

max_order

Maximum Zernike radial order; sets the number of modes.

Type:

int

normalization

Zernike normalisation scheme. Only "diagonal_disk" is supported: pixel coordinates are mapped to the unit disk via the image diagonal.

Type:

str

enforce_transverse_gauge

If True, the origin field is projected transverse to the ray direction (O . d = 0) at evaluation time, removing the redundant longitudinal degree of freedom along each ray.

Type:

bool

modes()

Return the Zernike mode descriptors selected by max_order.

Returns:

One descriptor (radial order n, azimuthal order m, parity) per polynomial, in canonical order — this is the column order of the design matrix returned by ZernikeOriginField.basis().

Return type:

tuple of ZernikeMode

class stereocomplex.rayfields.ZernikeRayField(K, config, coefficients=None)

Bases: ZernikeOriginField

Generic ray model with both origin and direction Zernike fields.

Directions are initialized from the pinhole model and corrected by a smooth Zernike perturbation:

d(u,v) = normalize(d0(u,v) + delta_d_perp(u,v)).

The perturbation is projected transverse to the pinhole direction. This keeps the parameterization well conditioned around the central initialization and avoids wasting coefficients on direction-scale changes.

Parameters:

• K (np.ndarray)

• config (ZernikeOriginFieldConfig)

• coefficients (ZernikeRayFieldCoefficients | None)

direction(u, v)

Return the unit fitted ray directions.

The pinhole direction d0 plus the transverse Zernike perturbation, then renormalised: d = normalize(d0 + direction_delta(u, v)).

Parameters:

• u (ndarray) – Pixel coordinates.

• v (ndarray) – Pixel coordinates.

Returns:

Unit ray directions.

Return type:

ndarray, shape (N, 3)

property direction_coeffs: ndarray

Direction-perturbation Zernike coefficients, shape (n_modes, 3), dimensionless.

direction_delta(u, v)

Return the transverse direction perturbation, before renormalisation.

The raw Zernike direction field is projected perpendicular to the pinhole direction d0, so the perturbation cannot change the ray scale — only its tilt.

Parameters:

• u (ndarray) – Pixel coordinates.

• v (ndarray) – Pixel coordinates.

Returns:

Additive direction perturbation, transverse to d0.

Return type:

ndarray, shape (N, 3)

property origin_coeffs: ndarray

Origin-field Zernike coefficients O(u, v), shape (n_modes, 3), in mm.

class stereocomplex.rayfields.ZernikeRayFieldChannel(name, field)

Bases: object

One named camera channel of a multi-camera Zernike rayfield.

Parameters:

• name (str)

• field (ZernikeRayField)

name

Channel identifier (e.g. "left", "cam0").

Type:

str

field

The channel’s fitted rayfield.

Type:

ZernikeRayField

class stereocomplex.rayfields.ZernikeRayFieldCoefficients(origin_coeffs, direction_coeffs)

Bases: object

Zernike coefficients for a generic central-reference rayfield.

origin_coeffs are in millimetres. direction_coeffs are dimensionless perturbations added to the pinhole direction before renormalization.

Parameters:

• origin_coeffs (ndarray)

• direction_coeffs (ndarray)

Synthetic datasets — stereocomplex.synthetic

Synthetic dataset generation: the parallel-plate non-central oracle and rendered ChArUco scenes.

Synthetic dataset generators and image renderers.

class stereocomplex.synthetic.ParallelPlateImageRenderParams(pixels_per_square=90, texture_interp='linear', blur_fwhm_px=0.6, blur_edge_factor=1.4, blur_edge_start=0.55, blur_edge_power=2.0, noise_std=0.002, vignette_strength=0.24, illumination_gradient_x=0.08, illumination_gradient_y=0.05, background_level=0.18, image_format='png', seed=1234)

Bases: object

Photometric parameters for rendered non-central ChArUco images.

Parameters:

• pixels_per_square (int)

• texture_interp (str)

• blur_fwhm_px (float)

• blur_edge_factor (float)

• blur_edge_start (float)

• blur_edge_power (float)

• noise_std (float)

• vignette_strength (float)

• illumination_gradient_x (float)

• illumination_gradient_y (float)

• background_level (float)

• image_format (str)

• seed (int)

class stereocomplex.synthetic.ParallelPlateSyntheticParams(eta=1.5, thickness=8.0, alpha_deg=12.0, beta_deg=5.0, d1=80.0)

Bases: object

Physical parameters used only by the inclined parallel-plate oracle.

Parameters:

• eta (float)

• thickness (float)

• alpha_deg (float)

• beta_deg (float)

• d1 (float)

class stereocomplex.synthetic.RenderedParallelPlateImageDataset(dataset, board, left_images, right_images, render_params)

Bases: object

Rendered image counterpart of a synthetic parallel-plate observation set.

Parameters:

• dataset (SyntheticStereoDataset)

• board (CharucoBoardSpec)

• left_images (list[Path])

• right_images (list[Path])

• render_params (ParallelPlateImageRenderParams)

class stereocomplex.synthetic.SyntheticStereoDataset(object_points, board_poses, left_pixels, right_pixels, K_left, K_right, T_left_world, T_right_world, image_size, oracle_left_params=None, oracle_right_params=None, per_frame_object_points=None)

Bases: object

Synthetic stereo observations generated by an oracle.

Conventions: - units are millimetres except pixels and K entries; - board_poses are 4x4 transforms from board coordinates to world coordinates; - T_left_world and T_right_world are 4x4 transforms from world to camera coordinates.

Parameters:

• object_points (ndarray)

• board_poses (list[ndarray])

• left_pixels (list[ndarray])

• right_pixels (list[ndarray])

• K_left (ndarray)

• K_right (ndarray)

• T_left_world (ndarray)

• T_right_world (ndarray)

• image_size (tuple[int, int])

• oracle_left_params (ParallelPlateSyntheticParams | None)

• oracle_right_params (ParallelPlateSyntheticParams | None)

• per_frame_object_points (list[ndarray] | None)

property T_right_left: ndarray

4x4 transform mapping left-camera coordinates to right-camera coordinates.

property oracle_left_ray_function

Exact ray function for the left channel (no noise).

property oracle_right_ray_function

Exact ray function for the right channel (no noise).

subset(indices)

Return a new dataset restricted to the frames at indices.

Parameters:

indices (Sequence[int])

Return type:

SyntheticStereoDataset

stereocomplex.synthetic.charuco_inner_corners_object_points(board)

Return ChArUco inner-corner ids and board-frame 3D points.

The convention matches the CPU dataset generator: the board is centered at (0,0) and lies in the z=0 plane.

Parameters:

board (CharucoBoardSpec)

Return type:

tuple[ndarray, ndarray]

stereocomplex.synthetic.detected_observations_from_rendered_parallel_plate(rendered, min_common_corners=12, method2d='raw')

Detect ChArUco corners in rendered images and return BA-ready observations.

Each frame contributes its own detected corner subset. Frames with different board poses (including poses where part of the board is outside the image) naturally see different corners. per_frame_object_points carries the per-frame 3D point arrays so the BA handles variable-size observation sets.

Parameters:

• rendered (RenderedParallelPlateImageDataset)

• min_common_corners (int)

• method2d (Literal['raw', 'rayfield_tps_robust'])

Return type:

SyntheticStereoDataset

stereocomplex.synthetic.generate_parallel_plate_stereo_dataset(object_points, board_poses, K_left, K_right, T_left_world, T_right_world, plate_left, plate_right, image_size, noise_std_px=0.0, keep_oracle_rayfields=True)

Generate synthetic stereo pixel observations from inclined-plate oracle cameras.

For each board pose, projects the known object points through the left and right parallel-plate camera models and optionally adds Gaussian pixel noise.

Parameters:

• object_points (ndarray, shape (N, 3)) – Board-plane object points in mm (Z=0).

• board_poses (sequence of ndarray) – Board-to-world transforms, each shape (4, 4).

• K_left (ndarray, shape (3, 3)) – Camera matrices for the two channels.

• K_right (ndarray, shape (3, 3)) – Camera matrices for the two channels.

• T_left_world (ndarray, shape (4, 4)) – World-to-camera transforms.

• T_right_world (ndarray, shape (4, 4)) – World-to-camera transforms.

• plate_left (ParallelPlateSyntheticParams) – Plate geometry for each channel.

• plate_right (ParallelPlateSyntheticParams) – Plate geometry for each channel.

• image_size ((int, int)) – Sensor dimensions in pixels (width, height).

• noise_std_px (float) – Standard deviation of additive Gaussian pixel noise (default 0).

• keep_oracle_rayfields (bool) – If True, attach exact ray functions to the returned dataset for ground-truth evaluation.

Returns:

Dataclass dataset object with left_pixels, right_pixels, object_points, board_poses, and optional oracle rayfields.

Return type:

SyntheticStereoDataset

stereocomplex.synthetic.normal_from_tilts(alpha_deg, beta_deg)

Return the unit normal q of the tilted parallel plate.

Parameters:

• alpha_deg (float)

• beta_deg (float)

Return type:

ndarray

stereocomplex.synthetic.parallel_plate_ray_from_pixel(u, v, K, params)

Return the physical oracle ray (O_true, d_true) for a pixel.

The origin is the plate exit point I2. It is not gauge-projected here: the generator keeps the physical ray, and evaluation code compares rays geometrically rather than by raw origin equality.

Parameters:

• u (float | ndarray)

• v (float | ndarray)

• K (ndarray)

• params (ParallelPlateSyntheticParams)

Return type:

tuple[ndarray, ndarray]

stereocomplex.synthetic.pinhole_ray_from_pixel(u, v, K)

Compute normalised pinhole ray directions from pixel coordinates.

Uses the camera matrix K to back-project pixels to unit vectors in camera space. The origin is implicitly at (0, 0, 0) — this function returns directions only.

Parameters:

• u (float or ndarray) – Pixel x-coordinate(s).

• v (float or ndarray) – Pixel y-coordinate(s).

• K (ndarray, shape (3, 3)) – Camera matrix.

Returns:

Unit ray directions in camera coordinates.

Return type:

ndarray, shape (…, 3)

stereocomplex.synthetic.project_point_with_parallel_plate(P_cam, K, params, image_size=None)

Find the pixel whose generated plate-distorted ray passes closest to a 3-D point.

Uses iterative least-squares optimisation. The point must be in front of the camera (Z > 0).

Parameters:

• P_cam (ndarray, shape (3,)) – 3-D point in camera coordinates, in millimetres.

• K (ndarray, shape (3, 3)) – Camera matrix.

• params (ParallelPlateSyntheticParams) – Plate geometry parameters.

• image_size ((int, int), optional) – Sensor dimensions, used to validate the returned pixel.

Returns:

(u, v) – Pixel coordinates of the closest ray.

Return type:

(float, float)

stereocomplex.synthetic.render_parallel_plate_charuco_images(dataset, board, out_dir, params=None)

Render stereo ChArUco images from the non-central parallel-plate oracle.

Rendering is done by ray tracing each camera pixel through the oracle rayfield, intersecting the calibration board plane, then sampling the ChArUco texture. Vignetting, spatially varying blur and sensor noise are applied after geometric rendering.

Parameters:

• dataset (SyntheticStereoDataset)

• board (CharucoBoardSpec)

• out_dir (str | Path)

• params (ParallelPlateImageRenderParams | None)

Return type:

RenderedParallelPlateImageDataset

Calibration, refinement and I/O — stereocomplex.api

Calibration entry points, ChArUco detection / refinement, reconstruction and model I/O. Symbols re-exported from the namespaces above are documented in their own sections and omitted here to avoid duplication.

class stereocomplex.api.BenchmarkReport(fit_result, reconstruction_comparison, oracle_floor, left_rayfield_comparison, right_rayfield_comparison)

Bases: object

Synthetic parallel-plate origin-field benchmark outputs.

Parameters:

• fit_result (StereoZernikeOriginFieldFitResult)

• reconstruction_comparison (ReconstructionComparisonReport)

• oracle_floor (OracleReconstructionFloorReport)

• left_rayfield_comparison (RayfieldComparisonReport)

• right_rayfield_comparison (RayfieldComparisonReport)

class stereocomplex.api.CalibrationAssessment(status, messages=<factory>, recommendations=<factory>)

Bases: object

Structured quality assessment for a stereo calibration result.

Parameters:

• status (str)

• messages (list[str])

• recommendations (list[str])

status

"ok", "warning", or "failed".

Type:

str

messages

Human-readable diagnostic messages.

Type:

list of str

recommendations

Actionable suggestions.

Type:

list of str

class stereocomplex.api.CameraSetup(name: 'str', image_dir: 'Path')

Bases: object

Parameters:

• name (str)

• image_dir (Path)

class stereocomplex.api.CharucoBoardSpec(squares_x: 'int', squares_y: 'int', square_size_mm: 'float', marker_size_mm: 'float', aruco_dictionary: 'str' = 'DICT_4X4_1000', adaptive_thresh_win_size_max: 'int | None' = None, corner_refinement_win_size: 'int' = 5, corner_refinement_max_iterations: 'int' = 50, corner_refinement_min_accuracy: 'float' = 0.001, check_markers: 'bool | None' = None, min_markers: 'int | None' = None, try_refine_markers: 'bool | None' = None, legacy_pattern: 'bool' = False)

Bases: object

Parameters:

• squares_x (int)

• squares_y (int)

• square_size_mm (float)

• marker_size_mm (float)

• aruco_dictionary (str)

• adaptive_thresh_win_size_max (int | None)

• corner_refinement_win_size (int)

• corner_refinement_max_iterations (int)

• corner_refinement_min_accuracy (float)

• check_markers (bool | None)

• min_markers (int | None)

• try_refine_markers (bool | None)

• legacy_pattern (bool)

classmethod from_dict(payload)

Build a CharucoBoardSpec from a configuration dictionary.

Parameters:

payload (dict) – Dictionary with board geometry fields.

Return type:

CharucoBoardSpec

classmethod from_meta(meta)

Build a CharucoBoardSpec from dataset metadata.

Parameters:

meta (dict) – Dataset metadata dictionary with a ‘board’ key.

Return type:

CharucoBoardSpec

class stereocomplex.api.NCameraCalibrationResult(channel_names, stereo_result=None)

Bases: object

Public calibration result for named camera sets.

Parameters:

• channel_names (tuple[str, ...])

• stereo_result (StereoCentralRayFieldFitResult | None)

property n_channels: int

Number of channels in this multi-camera dataset.

class stereocomplex.api.OracleReconstructionFloorReport(oracle_clean_pixels, oracle_observed_pixels)

Bases: object

Noise-free and observed-pixel oracle reconstruction floors.

Parameters:

• oracle_clean_pixels (ReconstructionErrorReport)

• oracle_observed_pixels (ReconstructionErrorReport)

class stereocomplex.api.RayfieldComparisonReport(plane_intersection_rms, plane_intersection_median, plane_intersection_p95, direction_angle_rms_deg, n_samples)

Bases: object

Summary of rayfield comparison between two models.

Parameters:

• plane_intersection_rms (float)

• plane_intersection_median (float)

• plane_intersection_p95 (float)

• direction_angle_rms_deg (float)

• n_samples (int)

plane_intersection_rms

RMS of 3D intersection point distances at the z-plane, in mm.

Type:

float

plane_intersection_median

Median intersection point distance at the z-plane, in mm.

Type:

float

plane_intersection_p95

95th percentile intersection distance at the z-plane, in mm.

Type:

float

direction_angle_rms_deg

RMS angular difference between ray directions, in degrees.

Type:

float

n_samples

Number of rays compared.

Type:

int

class stereocomplex.api.ReconstructionComparisonReport(central, with_origin_field, improvement_rms_factor, improvement_median_factor, improvement_p95_factor)

Bases: object

Central-vs-origin-field reconstruction comparison summary.

Parameters:

• central (ReconstructionErrorReport)

• with_origin_field (ReconstructionErrorReport)

• improvement_rms_factor (float)

• improvement_median_factor (float)

• improvement_p95_factor (float)

class stereocomplex.api.ReconstructionErrorReport(rms_3d, median_3d, p95_3d, max_3d, rms_x, rms_y, rms_z, ray_gap_rms, ray_gap_median, ray_gap_p95, n_points)

Bases: object

Aggregate 3-D reconstruction errors in millimetres.

Parameters:

• rms_3d (float)

• median_3d (float)

• p95_3d (float)

• max_3d (float)

• rms_x (float)

• rms_y (float)

• rms_z (float)

• ray_gap_rms (float)

• ray_gap_median (float)

• ray_gap_p95 (float)

• n_points (int)

class stereocomplex.api.ReconstructionResult(points_3d, ray_gap, valid_mask)

Bases: object

Triangulated 3-D points and ray-gap validity diagnostics.

Parameters:

• points_3d (ndarray)

• ray_gap (ndarray)

• valid_mask (ndarray)

class stereocomplex.api.RenderedImageBenchmarkReport(fit_result, reconstruction_comparison, oracle_detected, rendered, detected_dataset, method2d, n_common_corners, n_frames, n_points_total)

Bases: object

Rendered-image parallel-plate benchmark outputs and metadata.

Parameters:

• fit_result (StereoZernikeOriginFieldFitResult)

• reconstruction_comparison (ReconstructionComparisonReport)

• oracle_detected (ReconstructionErrorReport)

• rendered (RenderedParallelPlateImageDataset)

• detected_dataset (SyntheticStereoDataset)

• method2d (Literal['raw', 'rayfield_tps_robust'])

• n_common_corners (int)

• n_frames (int)

• n_points_total (int)

class stereocomplex.api.StereoCentralRayFieldFitReport(image_width_px, image_height_px, n_input_pairs, n_detected_pairs, n_observation_frames, n_initialized_frames, used_frame_ids, method2d, min_common_corners, nmax, train_skew_rms_mm, train_skew_p95_mm, train_point_to_ray_rms_mm, train_point_to_ray_p95_mm, n_points_total, mean_common_corners_per_frame, diagnostics, exported_model_json=None)

Bases: object

Quality metrics for a fitted stereo central rayfield calibration.

Parameters:

• image_width_px (int)

• image_height_px (int)

• n_input_pairs (int)

• n_detected_pairs (int)

• n_observation_frames (int)

• n_initialized_frames (int)

• used_frame_ids (tuple[int, ...])

• method2d (Literal['raw', 'rayfield_tps_robust'])

• min_common_corners (int)

• nmax (int)

• train_skew_rms_mm (float)

• train_skew_p95_mm (float)

• train_point_to_ray_rms_mm (float)

• train_point_to_ray_p95_mm (float)

• n_points_total (int)

• mean_common_corners_per_frame (float)

• diagnostics (dict[str, float])

• exported_model_json (str | None)

class stereocomplex.api.StereoCentralRayFieldFitResult(model, report)

Bases: object

Fitted stereo central rayfield model plus calibration report.

Parameters:

• model (StereoCentralRayFieldModel)

• report (StereoCentralRayFieldFitReport)

class stereocomplex.api.StereoCentralRayFieldModel(image_width_px, image_height_px, left, right, R_RL, t_RL)

Bases: object

Stereo reconstruction model with a central ray-field per camera.

The left camera frame is the reference frame. The right camera pose is expressed as X_R = R_RL @ X_L + t_RL, so the right camera centre in the left frame is C_R = -R_RL.T @ t_RL.

Parameters:

• image_width_px (int)

• image_height_px (int)

• left (CentralRayFieldZernike)

• right (CentralRayFieldZernike)

• R_RL (ndarray)

• t_RL (ndarray)

image_width_px, image_height_px

Image size in pixels.

Type:

int

left, right

Per-camera central ray-field models.

Type:

CentralRayFieldZernike

R_RL

Rotation of the right camera relative to the left.

Type:

ndarray, shape (3, 3)

t_RL

Translation of the right camera relative to the left, in millimetres.

Type:

ndarray, shape (3,)

property C_L_mm: ndarray

Left camera centre in world coordinates (origin, in mm).

property C_R_in_L_mm: ndarray

Right camera centre expressed in the left camera frame (in mm).

classmethod from_coeffs(*, image_width_px, image_height_px, nmax, u0_px, v0_px, radius_px, coeffs_left_x, coeffs_left_y, coeffs_right_x, coeffs_right_y, R_RL, t_RL, C_L_mm=None)

Build a StereoCentralRayFieldModel from raw coefficient arrays.

Parameters:

• image_width_px (int) – Sensor dimensions in pixels.

• image_height_px (int) – Sensor dimensions in pixels.

• nmax (int) – Maximum Zernike radial order.

• u0_px (float) – Unit-disk centre in pixels.

• v0_px (float) – Unit-disk centre in pixels.

• radius_px (float) – Unit-disk radius in pixels.

• coeffs_left_x (ndarray) – Zernike coefficients for the left camera.

• coeffs_left_y (ndarray) – Zernike coefficients for the left camera.

• coeffs_right_x (ndarray) – Zernike coefficients for the right camera.

• coeffs_right_y (ndarray) – Zernike coefficients for the right camera.

• R_RL (ndarray, shape (3, 3)) – Rotation from left to right camera frame.

• t_RL (ndarray, shape (3,)) – Translation from left to right camera frame.

• C_L_mm (ndarray, optional) – Left camera centre in millimetres (defaults to origin).

Returns:

The reconstructed central rayfield model.

Return type:

StereoCentralRayFieldModel

ray_direction_maps()

Precompute per-pixel ray direction maps for left and right cameras.

Returns (dL_map, dR_map) with shape (H, W, 3). dL_map contains directions expressed in the left camera frame; dR_map contains directions expressed in the right camera frame. Transform right-channel directions with R_RL.T before triangulating in the left frame.

Return type:

tuple[ndarray, ndarray]

triangulate(uv_left_px, uv_right_px)

Triangulate corresponding pixels into 3D points in the left camera frame.

Returns (XYZ_L_mm, skew_mm).

Parameters:

• uv_left_px (ndarray)

• uv_right_px (ndarray)

Return type:

tuple[ndarray, ndarray]

class stereocomplex.api.StereoImagePair(left_path: 'Path', right_path: 'Path', frame_id: 'int | None' = None)

Bases: object

Parameters:

• left_path (Path)

• right_path (Path)

• frame_id (int | None)

class stereocomplex.api.StereoOpenCVCalibrationReport(image_width_px, image_height_px, n_input_pairs, n_detected_pairs, n_mono_frames_left, n_mono_frames_right, n_stereo_frames, used_frame_ids, method2d, min_common_corners, mono_left_rms_px, mono_right_rms_px, stereo_rms_px, baseline_mm)

Bases: object

Frame counts and RMS metrics for OpenCV stereo calibration.

Parameters:

• image_width_px (int)

• image_height_px (int)

• n_input_pairs (int)

• n_detected_pairs (int)

• n_mono_frames_left (int)

• n_mono_frames_right (int)

• n_stereo_frames (int)

• used_frame_ids (tuple[int, ...])

• method2d (Literal['raw', 'rayfield_tps_robust'])

• min_common_corners (int)

• mono_left_rms_px (float)

• mono_right_rms_px (float)

• stereo_rms_px (float)

• baseline_mm (float)

class stereocomplex.api.StereoOpenCVCalibrationResult(K_left, dist_left, K_right, dist_right, R_right_from_left, t_right_from_left_mm, essential_matrix, fundamental_matrix, report)

Bases: object

OpenCV stereo intrinsics, distortion, rig transform and report.

Parameters:

• K_left (ndarray)

• dist_left (ndarray)

• K_right (ndarray)

• dist_right (ndarray)

• R_right_from_left (ndarray)

• t_right_from_left_mm (ndarray)

• essential_matrix (ndarray)

• fundamental_matrix (ndarray)

• report (StereoOpenCVCalibrationReport)

to_dict()

Return a JSON-serialisable summary.

Return type:

dict

to_opencv()

Return (K1, d1, K2, d2, R, T) as used by OpenCV.

Return type:

tuple

class stereocomplex.api.StereoZernikeOriginFieldFitResult(left_field, right_field, stereo_transform, board_poses, residual_rms, residual_median, residual_p95, n_observations, success, message)

Bases: object

Fitted stereo Zernike origin fields and residual diagnostics.

Parameters:

• left_field (ZernikeOriginField)

• right_field (ZernikeOriginField)

• stereo_transform (ndarray)

• board_poses (list[ndarray])

• residual_rms (float)

• residual_median (float)

• residual_p95 (float)

• n_observations (int)

• success (bool)

• message (str)

stereocomplex.api.assess_calibration(result)

Assess whether a stereo calibration result is usable.

Works with StereoOpenCVCalibrationResult, StereoCentralRayFieldFitResult, and StereoZernikeOriginFieldFitResult.

Parameters:

result (Any) – A calibration result object with a .report attribute.

Return type:

CalibrationAssessment

stereocomplex.api.build_charuco_board(board)

Build an OpenCV aruco.CharucoBoard from a stable Python dataclass.

Parameters:

board (CharucoBoardSpec)

Return type:

Any

stereocomplex.api.calibrate(*, cameras, board, max_pairs=0, method2d='rayfield_tps_robust', min_common_corners=10, nmax=10, lam_coeff=0.001, tps_lam=10.0, huber_c=3.0, iters=3, max_nfev=800, export_model_dir=None)

Calibrate a named camera set.

Phase 1 exposes an N-camera API surface while preserving the existing stereo implementation for the supported left/right case.

Parameters:

• cameras (Sequence[CameraSetup])

• board (CharucoBoardSpec)

• max_pairs (int)

• method2d (Literal['raw', 'rayfield_tps_robust'])

• min_common_corners (int)

• nmax (int)

• lam_coeff (float)

• tps_lam (float)

• huber_c (float)

• iters (int)

• max_nfev (int)

• export_model_dir (str | Path | None)

Return type:

NCameraCalibrationResult

stereocomplex.api.compare_3d_reconstruction_with_without_origin_field(dataset, central_model_result, origin_field_result)

Compare central stereo against non-central reconstruction with origin fields.

Triangulates the same point correspondences using a central model (all rays from a single camera centre) and a non-central model (per-pixel origins). Reports RMS, median, and P95 reconstruction error in 3-D.

Parameters:

• dataset (SyntheticStereoDataset) – Stereo observations with ground-truth 3-D points.

• central_model_result (StereoCentralRayFieldFitResult) – Result from central rayfield calibration.

• origin_field_result (StereoZernikeOriginFieldFitResult) – Result from non-central Zernike origin field calibration.

Returns:

Dataclass result object with central and with_origin_field error statistics.

Return type:

ReconstructionComparisonReport

stereocomplex.api.compare_opencv_stereo_calibration(left_dir, right_dir, board, *, max_pairs=None, method2d='rayfield_tps_robust', **kwargs)

Run OpenCV stereo calibration with raw AND refined corners.

This is the recommended first step for an OpenCV user: it runs fit_opencv_stereo_from_image_dirs twice (once with method2d="raw", once with method2d) and returns a comparison dictionary.

Parameters:

• left_dir (str or Path) – Directory containing left-camera calibration images.

• right_dir (str or Path) – Directory containing right-camera calibration images.

• board (CharucoBoardSpec) – ChArUco board geometry used for detection and calibration.

• max_pairs (int or None) – Maximum number of stereo pairs to process. None means the default of fit_opencv_stereo_from_image_dirs.

• method2d (str) – Refined 2-D corner method used for the second calibration pass.

• **kwargs – Additional keyword arguments forwarded to fit_opencv_stereo_from_image_dirs.

Returns:

Dictionary containing raw/refined dataclass result objects, their serialised dictionaries, and the RMS improvement in pixels.

Return type:

dict

stereocomplex.api.compare_rayfields_on_planes(fitted_field, oracle_ray_function, image_size, z_planes, grid_shape=(25, 19))

Compare two ray fields by intersecting each ray with two reference z planes.

This avoids comparing raw origins that may be expressed in different gauges.

Parameters:

• oracle_ray_function (Callable[[ndarray, ndarray], tuple[ndarray, ndarray]])

• image_size (tuple[int, int])

• z_planes (tuple[float, float])

• grid_shape (tuple[int, int])

Return type:

RayfieldComparisonReport

stereocomplex.api.detect_charuco_corners(*, image, board)

Detect ArUco markers and ChArUco corners in one image.

Parameters:

• image (str | Path | ndarray)

• board (CharucoBoardSpec)

Return type:

CharucoDetections | None

stereocomplex.api.fit_opencv_stereo_from_dataset(*, dataset_root, split='train', scene='scene_0000', max_frames=0, method2d='raw', min_common_corners=10, tps_lam=10.0, huber_c=3.0, iters=3)

Fit an OpenCV stereo model to a pre-organized dataset.

Parameters:

• dataset_root (str or Path) – Root directory of the dataset.

• split (str) – Dataset split name (‘train’, ‘val’, ‘test’).

• scene (str) – Scene identifier.

• max_frames (int) – Maximum number of frames to process (0 = all).

• method2d (str) – 2-D corner detection/refinement method.

• min_common_corners (int) – Minimum number of corners common to both views.

• tps_lam (float) – TPS smoothing parameter.

• huber_c (float) – Huber loss threshold in pixels.

• iters (int) – Number of IRLS refinement iterations.

Returns:

Dataclass result object with OpenCV calibration parameters per channel.

Return type:

StereoOpenCVCalibrationResult

stereocomplex.api.fit_opencv_stereo_from_image_dirs(*, left_dir, right_dir, board, max_pairs=0, method2d='raw', min_common_corners=10, tps_lam=10.0, huber_c=3.0, iters=3)

Fit an OpenCV stereo model to images in left/right directories.

Parameters:

• left_dir (str or Path) – Directory containing left-camera images.

• right_dir (str or Path) – Directory containing right-camera images.

• board (CharucoBoardSpec) – ChArUco board geometry.

• max_pairs (int) – Maximum number of stereo pairs to process (0 = all).

• method2d (str) – 2-D corner detection/refinement method.

• min_common_corners (int) – Minimum number of corners common to both views.

• tps_lam (float) – TPS smoothing parameter.

• huber_c (float) – Huber loss threshold in pixels.

• iters (int) – Number of IRLS refinement iterations.

Returns:

Dataclass result object with OpenCV calibration parameters per channel.

Return type:

StereoOpenCVCalibrationResult

stereocomplex.api.fit_opencv_stereo_from_image_pairs(*, image_pairs, board, method2d='raw', min_common_corners=10, tps_lam=10.0, huber_c=3.0, iters=3)

Calibrate a standard OpenCV stereo pinhole model from image pairs.

This is the onboarding-friendly companion to the 3D ray-field API: it uses the same public ChArUco detection/refinement path, then runs plain OpenCV mono and stereo calibration. Use method2d=”raw” for baseline OpenCV and method2d=”rayfield_tps_robust” for OpenCV fed with refined corners.

Parameters:

• image_pairs (Sequence[StereoImagePair | tuple[str | Path, str | Path]])

• board (CharucoBoardSpec)

• method2d (Literal['raw', 'rayfield_tps_robust'])

• min_common_corners (int)

• tps_lam (float)

• huber_c (float)

• iters (int)

Return type:

StereoOpenCVCalibrationResult

stereocomplex.api.fit_stereo_central_rayfield_from_dataset(*, dataset_root, split='train', scene='scene_0000', max_frames=0, method2d='rayfield_tps_robust', min_common_corners=10, nmax=10, lam_coeff=0.001, tps_lam=10.0, huber_c=3.0, iters=3, max_nfev=800, export_model_dir=None)

Fit a central rayfield stereo model to a pre-organized dataset.

Parameters:

• dataset_root (str or Path) – Root directory of the dataset.

• split (str) – Dataset split name.

• scene (str) – Scene identifier.

• max_frames (int) – Maximum number of frames (0 = all).

• method2d (str) – 2-D corner refinement method.

• min_common_corners (int) – Minimum common corners per pair.

• nmax (int) – Maximum Zernike radial order.

• lam_coeff (float) – Regularisation weight for Zernike coefficients.

• tps_lam (float) – TPS smoothing parameter.

• huber_c (float) – Huber loss threshold in pixels.

• iters (int) – Number of IRLS iterations.

• max_nfev (int) – Maximum LS function evaluations.

• export_model_dir (str or Path or None) – If set, export the fitted model to this directory.

Returns:

Dataclass result object with the fitted central rayfield model and diagnostics.

Return type:

StereoCentralRayFieldFitResult

stereocomplex.api.fit_stereo_central_rayfield_from_image_dirs(*, left_dir, right_dir, board, max_pairs=0, method2d='rayfield_tps_robust', min_common_corners=10, nmax=10, lam_coeff=0.001, tps_lam=10.0, huber_c=3.0, iters=3, max_nfev=800, export_model_dir=None)

Fit a central rayfield stereo model to images in left/right directories.

Parameters:

• left_dir (str or Path) – Directory containing left-camera images.

• right_dir (str or Path) – Directory containing right-camera images.

• board (CharucoBoardSpec) – ChArUco board geometry.

• max_pairs (int) – Maximum number of stereo pairs (0 = all).

• method2d (str) – 2-D corner refinement method.

• min_common_corners (int) – Minimum common corners per pair.

• nmax (int) – Maximum Zernike radial order.

• lam_coeff (float) – Regularisation weight for Zernike coefficients.

• tps_lam (float) – TPS smoothing parameter.

• huber_c (float) – Huber loss threshold in pixels.

• iters (int) – Number of IRLS iterations.

• max_nfev (int) – Maximum LS function evaluations.

• export_model_dir (str or Path or None) – If set, export the fitted model to this directory.

Returns:

Dataclass result object with the fitted central rayfield model and diagnostics.

Return type:

StereoCentralRayFieldFitResult

stereocomplex.api.fit_stereo_central_rayfield_from_image_pairs(*, image_pairs, board, method2d='rayfield_tps_robust', min_common_corners=10, nmax=10, lam_coeff=0.001, tps_lam=10.0, huber_c=3.0, iters=3, max_nfev=800, export_model_dir=None)

Calibrate a public stereo central ray-field model directly from image pairs.

This is the stable high-level entry point for users who already have left/right image pairs and a known ChArUco board.

Parameters:

• image_pairs (Sequence[StereoImagePair | tuple[str | Path, str | Path]])

• board (CharucoBoardSpec)

• method2d (Literal['raw', 'rayfield_tps_robust'])

• min_common_corners (int)

• nmax (int)

• lam_coeff (float)

• tps_lam (float)

• huber_c (float)

• iters (int)

• max_nfev (int)

• export_model_dir (str | Path | None)

Return type:

StereoCentralRayFieldFitResult

stereocomplex.api.fit_stereo_zernike_origin_field(observations, K_left, K_right, T_right_left_initial, board_poses_initial, config_left, config_right, optimize_board_poses=False, optimize_stereo_extrinsics=False, optimize_directions=False, robust_loss='huber', regularization=1e-06, direction_regularization=None, pose_regularization=0.0, rig_regularization=0.0, max_nfev=200)

Fit stereo non-central Zernike origin fields from point-to-ray residuals.

The default mode identifies per-pixel ray origins O_left(u,v) and O_right(u,v) on top of fixed pinhole directions, fixed board poses and a fixed stereo rig. Optional flags can extend the optimisation to direction perturbations, per-frame board poses and the stereo extrinsics. The fit is purely geometric: it uses only observed pixels, camera intrinsics, initial poses and the board object points, never the physical oracle parameters used to generate synthetic data.

Parameters:

• observations (SyntheticStereoDataset) – Stereo calibration observations. left_pixels and right_pixels are per-frame pixel arrays; object_points or per_frame_object_points provide matching board coordinates in mm.

• K_left (ndarray, shape (3, 3)) – Left and right pinhole intrinsics used for the fixed base directions.

• K_right (ndarray, shape (3, 3)) – Left and right pinhole intrinsics used for the fixed base directions.

• T_right_left_initial (ndarray, shape (4, 4)) – Initial transform from left-camera coordinates to right-camera coordinates.

• board_poses_initial (sequence of ndarray, each shape (4, 4)) – Initial board-to-world transforms, one per observed frame.

• config_left (ZernikeOriginFieldConfig) – Zernike basis, image size and gauge settings for each channel.

• config_right (ZernikeOriginFieldConfig) – Zernike basis, image size and gauge settings for each channel.

• optimize_board_poses (bool) – If True, include one SE(3) board pose block per frame in the least- squares vector.

• optimize_stereo_extrinsics (bool) – If True, refine the stereo rig transform around T_right_left_initial.

• optimize_directions (bool) – If True, fit Zernike direction perturbation coefficients as well as origin coefficients.

• robust_loss ({"linear", "huber", "soft_l1", "cauchy", "arctan"}) – Robust loss passed to scipy.optimize.least_squares.

• regularization (float) – L2 weight for origin-field coefficients.

• direction_regularization (float or None) – L2 weight for direction coefficients. None reuses regularization.

• pose_regularization (float) – L2 weight anchoring optimised board poses to their initial values.

• rig_regularization (float) – L2 weight anchoring optimised stereo extrinsics to the initial rig.

• max_nfev (int) – Maximum number of least-squares function evaluations.

Returns:

Dataclass result object containing the fitted left/right rayfields, optional direction coefficients, refined poses/rig and residual diagnostics.

Return type:

StereoZernikeOriginFieldFitResult

stereocomplex.api.fit_stereo_zernike_origin_field_from_image_dirs(*, left_dir, right_dir, board, max_order=4, max_pairs=0, method2d='raw', min_common_corners=10, tps_lam=10.0, huber_c=3.0, iters=3, regularization=1e-06, max_nfev=200)

Calibrate a non-central stereo Zernike origin-field model from image directories.

Detects ChArUco corners, runs OpenCV mono+stereo calibration to obtain K and the stereo rig transform, solves per-frame board poses, then fits a Zernike origin field O(u,v) on top of the pinhole directions.

Parameters:

• left_dir (str | Path) – Directories containing sorted left/right calibration images (same count).

• right_dir (str | Path) – Directories containing sorted left/right calibration images (same count).

• board (CharucoBoardSpec) – ChArUco board specification.

• max_order (int) – Maximum Zernike radial order for the origin field.

• max_pairs (int) – Cap on the number of image pairs used (0 = use all).

• method2d (Literal['raw', 'rayfield_tps_robust']) – Corner refinement method passed to refine_charuco_corners.

• min_common_corners (int) – Minimum corners common to left and right per frame.

• tps_lam (float) – Thin-plate-spline smoothing parameter forwarded to refine_charuco_corners when method2d="rayfield_tps_robust".

• huber_c (float) – Huber threshold in pixels for robust 2-D corner refinement.

• iters (int) – Number of IRLS iterations for robust 2-D corner refinement.

• regularization (float) – L2 regularization weight on the Zernike origin coefficients.

• max_nfev (int) – Maximum function evaluations for the Zernike BA.

Return type:

StereoZernikeOriginFieldFitResult

Notes

All frames are restricted to the intersection of corners visible in EVERY frame, because SyntheticStereoDataset requires a single shared object_points array. Corners not detected in all frames are dropped. If this intersection is too small, add more frames with full board coverage or reduce min_common_corners.

stereocomplex.api.intersect_rays_with_z_plane(origin, direction, z_plane)

Intersect rays with a horizontal z-plane.

Parameters:

• origin (np.ndarray) – Ray origins, shape (N, 3).

• direction (np.ndarray) – Ray directions (unit vectors), shape (N, 3).

• z_plane (float) – Z-coordinate of the target plane.

Returns:

Intersection points, shape (N, 3).

Return type:

np.ndarray

Raises:

ValueError – If any ray is parallel to the z-plane (z-component < 1e-12).

stereocomplex.api.load_stereo_central_rayfield(model_dir)

Load a fitted StereoCentralRayFieldModel from a directory.

Parameters:

model_dir (Path) – Directory containing model.json and coefficient .npy files.

Returns:

The loaded central rayfield model.

Return type:

StereoCentralRayFieldModel

stereocomplex.api.make_default_parallel_plate_charuco_board()

Return the ChArUco board used by the rendered non-central image demo.

Return type:

CharucoBoardSpec

stereocomplex.api.make_default_parallel_plate_charuco_dataset(noise_std_px=0.0)

Default parallel-plate dataset whose object points are ChArUco inner corners.

This is the geometric counterpart of the rendered-image benchmark. The same board poses and optical oracle are used, but observations are exact projected ChArUco inner corners rather than OpenCV detections.

Parameters:

noise_std_px (float)

Return type:

SyntheticStereoDataset

stereocomplex.api.make_default_parallel_plate_dataset(noise_std_px=0.0)

Generate the default synthetic parallel-plate dataset.

Parameters:

noise_std_px (float)

Return type:

SyntheticStereoDataset

stereocomplex.api.make_parallel_plate_wide_coverage_dataset(noise_std_px=0.0)

Dataset with a larger board and wider pose coverage for rayfield support plots.

The default dataset is intentionally small and fast because it is used by multiple regression tests. This variant is used for physical rayfield interpretation figures where the observed pixel support should cover much more of the image.

Six central poses keep the full 11x9 board within both cameras. Four axis-aligned paired edge poses cover the top/bottom/right image borders. One additional left-only monocular frame (empty right_pixels sentinel) fills the left-edge gap that paired stereo geometry cannot reach: u_min_paired = baseline * fx / z = 90 * 620 / 650 ≈ 86 px. The total is 11 frames; only the monocular frame contributes no right-camera residuals.

Parameters:

noise_std_px (float)

Return type:

SyntheticStereoDataset

stereocomplex.api.oracle_reconstruction_floor_report(dataset_observed, dataset_clean=None)

Compute the oracle floor for clean and observed/noisy pixels.

dataset_clean should share the same geometry and oracle parameters as dataset_observed, but with noise-free pixels. If omitted, the clean case is evaluated with dataset_observed pixels.

Parameters:

• dataset_observed (SyntheticStereoDataset)

• dataset_clean (SyntheticStereoDataset | None)

Return type:

OracleReconstructionFloorReport

stereocomplex.api.reconstruct_points_central_stereo(left_pixels, right_pixels, K_left, K_right, T_right_left)

Reconstruct 3-D points from stereo pixel correspondences using central pinhole rays.

Back-projects each pixel pair through the camera matrices, transforms the right ray into the left camera frame via T_right_left, then triangulates by midpoint of closest approach.

Parameters:

• left_pixels (ndarray, shape (N, 2)) – Left pixel coordinates (u, v) in pixels.

• right_pixels (ndarray, shape (N, 2)) – Right pixel coordinates (u, v) in pixels.

• K_left (ndarray, shape (3, 3)) – Camera matrices for each channel.

• K_right (ndarray, shape (3, 3)) – Camera matrices for each channel.

• T_right_left (ndarray, shape (4, 4)) – Rigid transform from left to right camera frame.

Returns:

Dataclass result object with points_3d (N, 3), ray_gap (N,), and valid_mask (N, bool).

Return type:

ReconstructionResult

stereocomplex.api.reconstruct_points_with_origin_fields(left_pixels, right_pixels, left_field, right_field, T_right_left)

Reconstruct 3-D points using per-pixel origin fields (non-central rays).

Unlike the central model where all rays share one camera centre, each pixel gets its own ray origin O(u,v) and direction d(u,v) from the Zernike origin field. Triangulation uses midpoint of closest approach between the two skew rays.

Parameters:

• left_pixels (ndarray, shape (N, 2)) – Left pixel coordinates (u, v) in pixels.

• right_pixels (ndarray, shape (N, 2)) – Right pixel coordinates (u, v) in pixels.

• left_field (ZernikeOriginField) – Fitted left-channel non-central rayfield.

• right_field (ZernikeOriginField) – Fitted right-channel non-central rayfield.

• T_right_left (ndarray, shape (4, 4)) – Rigid transform from left to right camera frame.

Returns:

Dataclass result object with points_3d (N, 3), ray_gap (N,), and valid_mask (N, bool).

Return type:

ReconstructionResult

stereocomplex.api.reconstruct_points_with_parallel_plate_oracle(left_pixels, right_pixels, dataset)

Reconstruct correspondences with the physical oracle rayfields.

The oracle keeps the physical exit point I2. This function is for evaluation only and must not be used by the generic Zernike fit.

Parameters:

• left_pixels (ndarray)

• right_pixels (ndarray)

• dataset (SyntheticStereoDataset)

Return type:

ReconstructionResult

stereocomplex.api.reconstruction_error_report(result, true_points)

Compute 3D reconstruction error statistics against ground truth.

Parameters:

• result (ReconstructionResult) – Reconstructed points, ray gaps, and validity mask.

• true_points (np.ndarray) – Ground truth 3D points, shape (N, 3).

Returns:

RMS, median, P95, and max 3D errors plus per-axis RMS and ray-gap stats.

Return type:

ReconstructionErrorReport

stereocomplex.api.refine_charuco_corners(*, method, board, detections=None, marker_ids=None, marker_corners=None, charuco_ids=None, charuco_xy=None, tps_lam=10.0, huber_c=3.0, iters=3)

Refine ChArUco corners using geometric priors on the board plane.

The function accepts either a bundled CharucoDetections object or the four raw detection arrays. method="raw" returns the ChArUco detector coordinates unchanged; method="rayfield_tps_robust" fits a robust 2-D board-plane warp from marker corners to image pixels and evaluates it at the requested ChArUco corner IDs.

Parameters:

• method ({"raw", "rayfield_tps_robust"}) – Refinement strategy.

• board (CharucoBoardSpec or OpenCV CharucoBoard) – Board geometry. CharucoBoardSpec is converted with build_charuco_board; an OpenCV board must provide getIds, getObjPoints and getChessboardCorners.

• detections (CharucoDetections, optional) – Bundled marker and ChArUco detections for one image. If provided, the four raw detection arguments below are ignored.

• marker_ids (ndarray, shape (M,), optional) – ArUco marker IDs detected in the image.

• marker_corners (list of ndarray, optional) – Marker corner coordinates in pixels, one (4, 2) array per marker.

• charuco_ids (ndarray, shape (K,), optional) – ChArUco corner IDs to refine.

• charuco_xy (ndarray, shape (K, 2), optional) – Initial ChArUco corner coordinates in pixels.

• tps_lam (float) – Thin-plate-spline smoothing parameter for rayfield_tps_robust.

• huber_c (float) – Huber threshold in pixels for robust TPS fitting.

• iters (int) – Number of robust reweighting iterations.

Returns:

Refined corner positions in pixels, in the same order as charuco_ids.

Return type:

ndarray, shape (K, 2)

stereocomplex.api.run_parallel_plate_origin_field_benchmark(max_order=4, noise_std_px=0.05, optimize_directions=False, optimize_board_poses=False, optimize_stereo_extrinsics=False, pose_regularization=0.0, rig_regularization=0.0)

Run the full origin-field benchmark end-to-end on the default parallel-plate dataset.

Generates data, fits a Zernike origin field, and compares central vs non-central reconstruction accuracy.

Parameters:

• max_order (int) – Maximum Zernike radial order for the origin field fit.

• noise_std_px (float) – Pixel noise standard deviation added to the synthetic observations.

• optimize_directions (bool) – If True, jointly optimise ray directions in the BA.

• optimize_board_poses (bool) – If True, refine board poses during BA.

• optimize_stereo_extrinsics (bool) – If True, refine the stereo rig transform during BA.

• pose_regularization (float) – Regularisation weight for pose parameters.

• rig_regularization (float) – Regularisation weight for the stereo rig transform.

Returns:

Dataclass result object with reconstruction comparison and diagnostics.

Return type:

BenchmarkReport

stereocomplex.api.run_parallel_plate_rendered_image_benchmark(out_dir, max_order=3, render_params=None, method2d='raw')

Render non-central ChArUco images, detect them with OpenCV, then run full BA.

This is the first end-to-end image front-end check for the parallel-plate oracle. The fit does not receive oracle plate parameters; it only receives detected 2D ChArUco corners, the board model, and a central initialization.

Parameters:

• max_order (int)

• render_params (ParallelPlateImageRenderParams | None)

• method2d (Literal['raw', 'rayfield_tps_robust'])

Return type:

RenderedImageBenchmarkReport

stereocomplex.api.save_stereo_central_rayfield(model_dir, model)

Save a stereo central ray-field model into a directory:

model.json + weights.npz

The JSON is small and ML-friendly (pure metadata + paths). The NPZ stores arrays.

Parameters:

• model_dir (Path)

• model (StereoCentralRayFieldModel)

Return type:

Path

stereocomplex.api.triangulate_two_rays(O_left, d_left, O_right, d_right)

Midpoint triangulation of two 3-D rays, returning the 3-D point of closest approach and the ray gap (minimum distance between the two skew lines).

The triangulated point is the midpoint of the shortest segment connecting the two rays. No gauge constraint is applied to the ray origins — they are used as given. If the rays are parallel or nearly parallel (denominator < 1e-12), the midpoint of the origins is returned and the ray gap is computed as the orthogonal distance from one origin to the other ray.

Parameters:

• O_left (ndarray, shape (3,)) – Left ray origin in world coordinates, in millimetres.

• d_left (ndarray, shape (3,)) – Left ray direction (unit vector, or will be normalised).

• O_right (ndarray, shape (3,)) – Right ray origin in world coordinates, in millimetres.

• d_right (ndarray, shape (3,)) – Right ray direction (unit vector, or will be normalised).

Returns:

• P (ndarray, shape (3,)) – Midpoint of the closest-approach segment, in millimetres.

• gap (float) – Minimum distance between the two rays, in millimetres. Zero when the rays intersect exactly.

Return type:

tuple[ndarray, float]