alproj.optimize module

class alproj.optimize.BaseOptimizer(obj_points, img_points, params_init)[source]

Bases: object

Base class for camera parameter optimizers.

obj_points

Geographic coordinates of the Ground Control Points. The column names must be x, y, z. See alproj.gcp.set_gcp()

Type:

pandas.DataFrame

img_points

Image coordinates of the Ground Control Points. The column names must be u, v. See alproj.gcp.set_gcp()

Type:

pandas.DataFrame

params_init

Initial values of camera parameters. Must contain: - x, y, z: Camera position in projected CRS (e.g., UTM in meters) - fov: Field of view in degrees - pan, tilt, roll: Orientation angles in degrees - a1, a2, k1-k6, p1, p2, s1-s4: Distortion coefficients - w, h: Image width and height in pixels - cx, cy: Principal point coordinates

Type:

dict

set_target(target_params=['fov', 'pan', 'tilt', 'roll', 'a1', 'a2', 'k1', 'k2', 'k3', 'k4', 'k5', 'k6', 'p1', 'p2', 's1', 's2', 's3', 's4'])[source]

Set which parameters to be optimized.

Parameters:

target_params (list default ["fov", "pan", "tilt", "roll", "a1", "a2", "k1", "k2", "k3", "k4", "k5", "k6", "p1", "p2", "s1", "s2", "s3", "s4"]) – Parameters to be optimized. You can also include x, y, and z for camera location.

class alproj.optimize.CMAOptimizer(obj_points, img_points, params_init)[source]

Bases: BaseOptimizer

Camera parameter optimizer using Covariance Matrix Adaptation Evolution Strategy (CMA-ES). See https://pypi.org/project/cmaes/ . You can select which parameters to be optimized, including camera location (x, y, z).

optimize(sigma=0.2, bound_widths=None, generation=1000, population_size=10, n_max_resampling=100, f_scale=None, weights=None)[source]

CMA-optimization of camera parameters. See https://github.com/CyberAgent/cmaes/blob/main/cmaes/_cma.py .

Parameters are normalized to [0, 1] range internally for efficient optimization.

Parameters:

  • sigma (float default 0.2) – Initial standard deviation of covariance matrix (in normalized [0, 1] space).

  • bound_widths (dict default None) – Width from initial value for each parameter (e.g., {“fov”: 30, “x”: 50}). If None or parameter not specified, uses default widths: +-45 degrees for fov, pan, tilt, roll; +-30 meters for x, y, z; +-0.2 for distortion coefficients. Note that large absolute values of distortion coefficients may cause broken projection.

  • generation (int default 1000) – Number of generations to run.

  • population_size (int default 10) – Population size.

  • n_max_resampling (int default 100) – A maximum number of resampling parameters (default: 100). If all sampled parameters are infeasible, the last sampled one will be clipped with lower and upper bounds.

  • f_scale (float default None) – Threshold for Huber loss in pixels. If None, uses mean reprojection error. If specified (e.g., 10.0), uses Huber loss which is more robust to outliers.

  • weights (numpy.ndarray, default None) – Per-GCP weights for the loss function. Higher weights increase the importance of the corresponding GCPs. Useful for balancing center and edge region accuracy.

Returns:

  • params (dict) – Optimized camera parameters.

  • error (float) – Mean reprojection error in pixels (unweighted).

class alproj.optimize.LsqOptimizer(obj_points, img_points, params_init)[source]

Bases: BaseOptimizer

Camera parameter optimizer using scipy.optimize.least_squares. Supports Trust Region Reflective (trf), dogbox, and Levenberg-Marquardt (lm) methods.

optimize(method='trf', bound_widths=None, loss='linear', f_scale=1.0, weights=None, **kwargs)[source]

Least-squares optimization of camera parameters.

Parameters:

  • method (str default "trf") – Algorithm to use: “trf” (Trust Region Reflective), “dogbox”, or “lm” (Levenberg-Marquardt). Note: “lm” does not support bounds or robust loss functions.

  • bound_widths (dict default None) – Width from initial value for each parameter (e.g., {“fov”: 30, “x”: 50}). If None, uses default widths. Ignored when method=”lm”.

  • loss (str default "linear") – Loss function to use. Options: - “linear”: Standard least squares (L2 loss). - “huber”: Huber loss, robust to outliers. - “soft_l1”: Smooth approximation of L1 loss. - “cauchy”: Cauchy loss, strongly robust to outliers. - “arctan”: Arctan loss. Note: Only “linear” is supported when method=”lm”.

  • f_scale (float default 1.0) – Soft threshold for inlier residuals (in pixels). Residuals below f_scale are treated normally, while those above are down-weighted according to the loss function. Has no effect when loss=”linear”. Typical values: 1.0-20.0 pixels depending on expected outlier magnitude.

  • weights (numpy.ndarray, default None) – Per-GCP weights for the loss function. Applied as sqrt(weight) scaling to the residual vector. Useful for region-balanced optimization.

  • **kwargs – Additional arguments passed to scipy.optimize.least_squares.

Returns:

  • params (dict) – Optimized camera parameters.

  • error (float) – Mean reprojection error in pixels (unweighted).

alproj.optimize.bounds_to_array(params_init, target_params, bound_widths=None)[source]

Convert bound widths (dict) to numpy array for CMA-ES optimizer.

Parameters:

  • params_init (dict) – Initial values of camera parameters.

  • target_params (list) – Parameters to be optimized.

  • bound_widths (dict default None) – Width from initial value for each parameter (e.g., {“fov”: 45, “x”: 30}). If None or parameter not specified, uses DEFAULT_BOUND_WIDTHS.

Returns:

bounds – Bounds array with shape (len(target_params), 2).

Return type:

numpy.ndarray

alproj.optimize.compute_residuals(obj_points, img_points, params)[source]

Compute residual vector for least_squares optimization.

Parameters:

  • obj_points (pandas.DataFrame) – Geographic coordinates of the Ground Control Points.

  • img_points (pandas.DataFrame) – Image coordinates of the Ground Control Points.

  • params (dict) – Camera parameters.

Returns:

residuals – Flattened residual vector (observed - projected).

Return type:

numpy.ndarray

alproj.optimize.extrinsic_mat(pan_deg, tilt_deg, roll_deg, t_x, t_y, t_z)[source]

Makes an extrinsic camera matrix from given parameters. See https://learnopencv.com/geometry-of-image-formation/ .

Parameters:

  • pan_deg (float) – Pan angle in degree.

  • tilt_deg (float) – Tilt angle in degree.

  • roll_deg (float) – Roll angle in degree.

  • t_x (float) – X-axis coordinate of the camera location.

  • t_y (float) – Y-axis coordinate of the camera location.

  • t_z (float) – Z-axis coordinate of the camera location.

Returns:

mat – Extrinsic camera matrix.

Return type:

numpy.ndarray

alproj.optimize.huber_loss(img_points, projected, f_scale=10.0, weights=None)[source]

Calculate Huber loss for robust optimization.

Huber loss is less sensitive to outliers than squared error loss. For residuals below f_scale, it behaves like L2 (squared) loss. For residuals above f_scale, it behaves like L1 (linear) loss.

Parameters:

  • img_points (pandas.DataFrame) – Observed image coordinates with columns u, v.

  • projected (pandas.DataFrame) – Projected image coordinates with columns u, v.

  • f_scale (float default 10.0) – Threshold in pixels. Residuals below f_scale use L2, above use L1.

  • weights (numpy.ndarray, default None) – Per-point weights. If provided, returns weighted average.

Returns:

loss – Mean Huber loss value.

Return type:

float

alproj.optimize.intrinsic_mat(fov_x_deg, w, h, cx=None, cy=None)[source]

Makes an intrinsic camera matrix (in OpenCV style) from given parameters. See https://learnopencv.com/geometry-of-image-formation/ .

Parameters:

  • fov_x_deg (float) – Field of View in degree.

  • w (int) – Width of the image

  • h (int) – Height of the image

  • cx (float default None) – X-coordinate of the principal point. If None, cx = w/2.

  • cy (float default None) – Y-coordinate of the principal point. If None, cy = h/2.

Returns:

mat – Intrinsic matrix.

Return type:

numpy.ndarray

alproj.optimize.mean_reprojection_error(img_points, projected, weights=None)[source]

Calculate mean reprojection error (mean Euclidean distance) of the projection.

Parameters:

  • img_points (pandas.DataFrame) – Observed image coordinates with columns u, v.

  • projected (pandas.DataFrame) – Projected image coordinates with columns u, v.

  • weights (numpy.ndarray, default None) – Per-point weights. If provided, returns weighted average.

Returns:

error – Mean reprojection error in pixels.

Return type:

float

alproj.optimize.project(obj_points, params)[source]

3D to 2D Perspective projection of given points with given camera parameters.

Parameters:

  • obj_points (pandas.DataFrame) – Coordinates of the points (usually GCPs) in 3D geographic coordinate system. The column names must be x, y, z.

  • params (dict) – Camera parameters. For detailed parameter descriptions, see alproj.project.persp_proj(). If params contains "model": "fisheye", uses equidistant fisheye projection. Otherwise uses the default pinhole projection.

Returns:

uv – 2D projected coordinates with columns u, v.

Return type:

pandas.DataFrame

alproj.optimize.rmse(img_points, projected, weights=None)[source]

Deprecated alias for mean_reprojection_error().

Deprecated since version 1.2.0: Use mean_reprojection_error() instead. This function computes mean Euclidean distance, not root-mean-square error.