USAGE.md

Python usage

This package exposes a single function, easy_sba, for running sparse bundle adjustment from Python.

Quickstart

import numpy as np
from easysba import easy_sba

num_points = 10
num_cams = 4
rng = np.random.default_rng(0)

image_uv = rng.normal(scale=0.5, size=(num_points, num_cams, 2)).astype(np.float64)
visibility_mask = np.ones((num_points, num_cams), dtype=np.uint8)
world_xyz = rng.normal(scale=2.0, size=(num_points, 3)).astype(np.float64)

# 12-parameter cameras: [fu, u0, v0, ar, skew, qw, qx, qy, qz, tx, ty, tz]
camera_params = np.zeros((num_cams, 12), dtype=np.float64)
camera_params[:, 0] = 1.0  # fu
camera_params[:, 3] = 1.0  # aspect ratio
camera_params[:, 5] = 1.0  # quaternion w
camera_params[:, 9:] = rng.normal(scale=0.1, size=(num_cams, 3))

world_out, cams_out, info = easy_sba(
    image_uv,
    visibility_mask,
    world_xyz,
    camera_params,
    intrinsics_fixed=5,
    distortion_fixed=-1,
    max_iter=50,
    verbose=False,
)

print(info)

Function signature

world_out, cams_out, info = easy_sba(
    image_uv,
    visibility_mask,
    world_xyz,
    camera_params,
    intrinsics_fixed=-1,
    distortion_fixed=-1,
    max_iter=150,
    verbose=False,
)

Inputs

• image_uv

  • Either shape (num_points, num_cams, 2) or (num_points, num_cams * 2).
  • Must be float64.
  • For invisible measurements, set visibility_mask to 0 and store NaNs at the corresponding image_uv location.

• visibility_mask

  • Shape (num_points, num_cams).
  • uint8, with nonzero values for visible projections.

• world_xyz

  • Shape (num_points, 3).
  • float64.

• camera_params

  • Shape (num_cams, num_camera_params).
  • float64.
  • num_camera_params must be 7, 12, or 17.

Camera parameter layouts

• 7 parameters (default intrinsics):

  • [qw, qx, qy, qz, tx, ty, tz]
  • Intrinsics are assumed to be [fu=1, u0=0, v0=0, ar=1, skew=0].

• 12 parameters (fixed intrinsics in array):

  • [fu, u0, v0, ar, skew, qw, qx, qy, qz, tx, ty, tz]

• 17 parameters (intrinsics + distortion):

  • [fu, u0, v0, ar, skew, k1, k2, p1, p2, k3, qw, qx, qy, qz, tx, ty, tz]

Notes:

• Quaternions are normalized internally. A zero-norm quaternion raises an error.
• Translation is in the camera coordinate system used by the projection model in the SBA implementation.

Options

• intrinsics_fixed

  • Controls which intrinsics are held fixed.
  • Must be -1 for 7-parameter cameras (intrinsics not provided).
  • For 12- or 17-parameter cameras, use values 0..5 as defined by SBA.
  • Common choice is 5 to fix all intrinsics.

• distortion_fixed

  • Controls which distortion parameters are held fixed for 17-parameter cameras.
  • Use -1 to free all distortion params, or 0..5 to fix subsets.
  • For 7- or 12-parameter cameras, use -1.

• max_iter

  • Maximum LM iterations.

• verbose

  • Print iteration details.

Outputs

• world_out: optimized 3D point array, shape (num_points, 3).
• cams_out: optimized camera parameters, same shape as camera_params.
• info: dict with keys like return_code, initial_error, final_error, num_iterations.

Tips

• Provide reasonable initial guesses. BA is non-convex and sensitive to initialization.
• Use NaNs in image_uv for masked entries; the visibility mask must match.
• Start with max_iter=1 to validate inputs and shapes.

Testing

To run the optional solver tests:

EASYSBA_RUN_SOLVER=1 pytest