curryer.correction.image_match

Attributes

logger

Classes

ImageMatchingFunc

Protocol for image matching functions in Correction pipeline.

IntegratedImageMatchResult

Functions

validate_image_matching_output(→ None)

Validate image matching output conforms to expected format.

integrated_image_match(→ IntegratedImageMatchResult)

Perform complete image matching workflow with PSF modeling.

load_image_grid_from_mat(...)

Load ImageGrid from MATLAB .mat file.

load_optical_psf_from_mat(...)

Load optical PSF entries from MATLAB .mat file.

load_los_vectors_from_mat(→ numpy.ndarray)

Load line-of-sight vectors from MATLAB .mat file.

Module Contents

curryer.correction.image_match.logger
class curryer.correction.image_match.ImageMatchingFunc

Bases: Protocol

Protocol for image matching functions in Correction pipeline.

Image matching functions perform spatial correlation between geolocated observations and GCP reference imagery to measure geolocation errors.

Standard Signature:
def image_matching(

geolocated_data: xr.Dataset, gcp_reference_file: Path, telemetry: pd.DataFrame, calibration_dir: Path, params_info: list, config, los_vectors_cached: Optional[np.ndarray] = None, optical_psfs_cached: Optional[list] = None,

) -> xr.Dataset

Required Output Fields:

  • lat_error_deg: (measurement,) Latitude errors in degrees

  • lon_error_deg: (measurement,) Longitude errors in degrees

  • gcp_lat_deg, gcp_lon_deg, gcp_alt: GCP location

  • Spacecraft state: position, boresight, transformation matrix

See correction.image_matching() for reference implementation.

__call__(geolocated_data: xarray.Dataset, gcp_reference_file: pathlib.Path, telemetry: pandas.DataFrame, calibration_dir: pathlib.Path, params_info: list, config, los_vectors_cached: numpy.ndarray | None = None, optical_psfs_cached: list | None = None) → xarray.Dataset

Perform image matching and return error measurements.

curryer.correction.image_match.validate_image_matching_output(output: xarray.Dataset) → None

Validate image matching output conforms to expected format.

Parameters:

output (xr.Dataset) – Dataset returned by image matching function.

Raises:

  • TypeError – If output is not an xarray Dataset.

  • ValueError – If required fields are missing or malformed.

Examples

>>> result = image_matching_func(...)
>>> validate_image_matching_output(result)
class curryer.correction.image_match.IntegratedImageMatchResult
lat_error_km: float
lon_error_km: float
ccv_final: float
final_index_row: int
final_index_col: int
final_grid_step_m: float
dynamic_psf: curryer.correction.data_structures.PSFGrid
projected_psf: curryer.correction.data_structures.ProjectedPSF
convolved_gcp: curryer.correction.data_structures.ImageGrid
curryer.correction.image_match.integrated_image_match(subimage: curryer.correction.data_structures.ImageGrid, gcp: curryer.correction.data_structures.ImageGrid, r_iss_midframe_m: numpy.ndarray, los_vectors_hs: numpy.ndarray, optical_psfs: collections.abc.Iterable[curryer.correction.data_structures.OpticalPSFEntry], geolocation_config: curryer.correction.data_structures.GeolocationConfig | None = None, search_config: curryer.correction.data_structures.SearchConfig | None = None) → IntegratedImageMatchResult

Perform complete image matching workflow with PSF modeling.

Replicates MATLAB IntegratedImageMatch: projects PSF, applies spacecraft motion blur, convolves with GCP, and performs correlation-based search.

Parameters:

  • subimage (ImageGrid) – Observed image data with geolocation.

  • gcp (ImageGrid) – Ground control point reference image.

  • r_iss_midframe_m (np.ndarray) – Spacecraft position at mid-frame, shape (3,), units: meters.

  • los_vectors_hs (np.ndarray) – Line-of-sight vectors in instrument frame, shape (n_pixels, 3).

  • optical_psfs (Iterable[OpticalPSFEntry]) – Optical PSF samples at different field angles.

  • geolocation_config (GeolocationConfig, optional) – PSF geolocation parameters. Defaults to standard config.

  • search_config (SearchConfig, optional) – Image search parameters. Defaults to standard config.

Returns:

Geolocation errors, correlation value, and intermediate products.

Return type:

IntegratedImageMatchResult

curryer.correction.image_match.load_image_grid_from_mat(mat_file: pathlib.Path, key: str = 'subimage', name: str | None = None, as_named: bool = False) → curryer.correction.data_structures.ImageGrid | curryer.correction.data_structures.NamedImageGrid

Load ImageGrid from MATLAB .mat file.

Parameters:

  • mat_file (Path) – Path to .mat file.

  • key (str, default="subimage") – MATLAB struct key (e.g., “subimage” for L1A, “GCP” for reference).

  • name (str, optional) – Name for NamedImageGrid. Defaults to file path.

  • as_named (bool, default=False) – If True, return NamedImageGrid; otherwise return ImageGrid.

Returns:

Loaded image grid with data, lat, lon, h fields.

Return type:

ImageGrid or NamedImageGrid

Raises:

  • FileNotFoundError – If mat_file doesn’t exist.

  • KeyError – If key not found in MATLAB file.

Examples

>>> # Load L1A subimage
>>> l1a = load_image_grid_from_mat(Path("subimage.mat"), key="subimage")
>>> # Load GCP reference
>>> gcp = load_image_grid_from_mat(Path("gcp.mat"), key="GCP")
curryer.correction.image_match.load_optical_psf_from_mat(mat_file: pathlib.Path, key: str = 'PSF_struct_675nm') → list[curryer.correction.data_structures.OpticalPSFEntry]

Load optical PSF entries from MATLAB .mat file.

Parameters:

  • mat_file (Path) – Path to MATLAB file with PSF data.

  • key (str, default="PSF_struct_675nm") – Primary key to try for PSF data.

Returns:

Optical PSF samples with data, x, and field_angle arrays.

Return type:

list[OpticalPSFEntry]

Raises:

  • FileNotFoundError – If mat_file doesn’t exist.

  • KeyError – If no PSF data found with common key names.

  • ValueError – If PSF entries missing field angle attribute.

curryer.correction.image_match.load_los_vectors_from_mat(mat_file: pathlib.Path, key: str = 'b_HS') → numpy.ndarray

Load line-of-sight vectors from MATLAB .mat file.

Parameters:

  • mat_file (Path) – Path to MATLAB file with LOS vectors.

  • key (str, default="b_HS") – Primary key to try for LOS data.

Returns:

LOS unit vectors in instrument frame, shape (n_pixels, 3).

Return type:

np.ndarray

Raises:

  • FileNotFoundError – If mat_file doesn’t exist.

  • KeyError – If no LOS vectors found with common key names.