alproj.gcp module

alproj.gcp.filter_gcp_distance(gcp, params, min_distance=None, max_distance=None)[source]

Filter GCPs based on 3D distance from the camera position.

Parameters:

  • gcp (pd.DataFrame) – GCP data with columns u, v, x, y, z (geographic coordinates in projected CRS, e.g., meters). Typically the result of set_gcp().

  • params (dict) – Camera parameters containing ‘x’, ‘y’, ‘z’ keys (camera position in the same projected CRS as gcp).

  • min_distance (float, optional) – Minimum distance threshold in coordinate units (e.g., meters). Points closer than this are excluded. Must be non-negative if specified.

  • max_distance (float, optional) – Maximum distance threshold. Points farther than this are excluded. Must be >= min_distance if both are specified.

Returns:

gcp_filtered – Filtered GCP data with reset index.

Return type:

pd.DataFrame

Raises:

  • KeyError – If params lacks ‘x’, ‘y’, or ‘z’ keys.

  • ValueError – If min_distance < 0 or max_distance < min_distance.

Notes

  • Coordinates must be in a projected CRS (e.g., UTM) for accurate Euclidean distance. Using lat/lon directly will produce incorrect results.

  • Rows with NaN in x, y, or z are excluded from the result.

Examples

>>> gcps = set_gcp(match, df)
>>> gcps_filtered = filter_gcp_distance(gcps, params, min_distance=100)
alproj.gcp.image_match(path_org, path_sim, method='akaze', outlier_filter='fundamental', params=None, threshold=10.0, ransac_method='USAC_MAGSAC', spatial_thin_grid=None, spatial_thin_selection='first', spatial_thin_random_state=None, plot_result=False, device='cpu', resize=None, **kwargs)[source]

Feature matching between the original (real) photograph and a simulated landscape image.

The workflow is:

  • Local feature detection (method-dependent)

  • Feature matching with Lowe’s ratio test

  • Geometric outlier filtering (Essential/Fundamental Matrix)

  • Optional spatial thinning (grid-based sampling)

Parameters:

  • path_org (str) – Path for original photograph.

  • path_sim (str) – Path for simulated landscape image.

  • method (str, default "akaze") – Matching method to use. Built-in methods: “akaze”, “sift”. With vismatch package installed, any method supported by vismatch can be used (e.g., “superpoint-lightglue”, “roma”, “minima-roma”, “loftr”, “dedode-lightglue”, “xfeat”, etc.). See https://github.com/gmberton/vismatch for the full list of 70+ methods.

  • outlier_filter (str, default "fundamental") –

    Outlier filtering method:

    • ”fundamental”: Fundamental Matrix filtering (default). Use when camera intrinsics are unknown. Requires at least 8 matches.

    • ”essential”: Essential Matrix filtering. Recommended when params with fov is provided. Requires at least 5 matches.

    • ”none”: No geometric filtering. Use this when you plan to apply custom filtering later.

  • params (dict, optional) – Camera parameters dict containing fov, w, h, and optionally cx, cy. Used to compute focal_length and principal_point for “essential” filter. focal_length is calculated as: (w / 2) / tan(fov * pi / 180 / 2)

  • threshold (float, default 10.0) – Outlier threshold in pixels for Essential/Fundamental filtering. Higher values are more permissive (allow more matches through).

  • ransac_method (str, default "USAC_MAGSAC") –

    RANSAC variant for geometric filtering:

    • ”RANSAC”: Standard RANSAC

    • ”LMEDS”: Least-Median of Squares

    • ”USAC_MAGSAC”: MAGSAC++ (most robust, recommended)

    • ”USAC_DEFAULT”: Default USAC configuration

  • spatial_thin_grid (int, optional) – Grid cell size in pixels for spatial thinning. If specified, keeps at most one match per grid cell. Example: 100 keeps ~1 point per 100x100 px region. Applied AFTER geometric outlier filtering.

  • spatial_thin_selection (str, default "first") –

    Selection method for spatial thinning:

    • ”first”: First point by input order (deterministic, fastest)

    • ”random”: Random selection (use spatial_thin_random_state for reproducibility)

    • ”center”: Point closest to cell center

  • spatial_thin_random_state (int, optional) – Random seed when spatial_thin_selection=”random”.

  • plot_result (bool, default False) – Whether to return a result plot.

  • device (str, default "cpu") – Device to use for vismatch methods (“cpu” or “cuda”). Ignored for built-in methods.

  • resize (int, optional) –

    Resize images to this size for vismatch methods. Keypoints are automatically scaled back to original coordinates.

    Note

    For memory-intensive methods (roma, tiny-roma, minima-roma, loftr, minima-loftr, ufm, rdd, master), if resize is None, images are automatically resized to 640px to prevent out-of-memory errors. LightGlue-based methods (sift-lightglue, superpoint-lightglue, minima-superpoint-lightglue) can handle full-resolution images and do not auto-resize.

  • **kwargs – Additional keyword arguments passed to vismatch’s get_matcher (e.g., max_num_keypoints).

Returns:

  • points (pd.DataFrame) – The coordinates of matched points. (Left-Top origin)

  • plot (np.array or None) – An OpenCV image of result plot if plot_result=True, otherwise None.

Examples

Basic matching with Fundamental Matrix filtering (default):

>>> match, _ = image_match(path_org, path_sim, method="akaze")

Matching with Essential Matrix filtering using params:

>>> match, _ = image_match(path_org, path_sim, method="minima-roma",
...                        outlier_filter="essential", params=params,
...                        device="cuda")
alproj.gcp.plot_matches(image, matches, color=(180, 105, 255), thickness=None, tip_length=0.3, font_scale=None, font_thickness=None)[source]

Plot feature matches on an image.

Parameters:

  • image (numpy.ndarray) – Image to draw on (BGR format).

  • matches (pd.DataFrame) – Match coordinates with columns u_org, v_org, u_sim, v_sim.

  • color (tuple, default (180, 105, 255)) – Arrow color in BGR.

  • thickness (int or None, default None) – Arrow thickness. If None, automatically scaled based on image size.

  • tip_length (float, default 0.3) – Arrow tip length as fraction of arrow length.

  • font_scale (float or None, default None) – Font size for the label text. If None, automatically scaled based on image size.

  • font_thickness (int or None, default None) – Font stroke thickness. If None, automatically scaled based on image size.

Returns:

plot – Image with arrows drawn.

Return type:

numpy.ndarray

alproj.gcp.set_gcp(match, rev_proj)[source]

Adds geographic coordinates to the matched point pairs. The result of this function will be used as the Ground Control Points (GCPs) during camera parameter estimation.

Parameters:

  • match (pd.DataFrame) – Result of alproj.gcp.image_match()

  • rev_proj (pd.DataFrame) – Result of alproj.project.reverse_proj

Returns:

gcp – A dataframe with 5 columns

uint

x_axis coordinates of the Ground Control Points on the original photograph. Left-Top origin.

vint

y_axis coordinates of the GCPs.

xfloat

X coordinates of GCPs in a projected coordinate system (e.g., UTM in meters).

yfloat

Y coordinates of GCPs in the same projected coordinate system.

zfloat

Z coordinates (elevation) of GCPs in the same unit (e.g., meters).

Return type:

pd.DataFrame