goatpy.auto_align

Auto-registration of a MALDI imzML dataset against a whole-slide H&E image.

Key design decisions

  1. Registration is performed at MALDI native pixel size (default 10 um/px) so the H&E thumbnail is tiny and peak RAM stays manageable.

  2. Matching uses normalised grayscale cross-correlation (TM_CCOEFF_NORMED) on the TIC image vs inverted H&E intensity.

  3. A two-pass rotation search (coarse 0-360, then fine) finds the correct slide orientation without assuming any starting angle.

  4. Registration, canvas building, and annotation transforms all use cv2.warpAffine with the same analytically derived affine matrix. This guarantees that best_idx, canvas pixels, and annotation coordinates all live in the same coordinate system.

Coordinate system

All three steps share the same affine matrix M_stored:

M_stored maps: reg-resolution H&E coords -> canvas coords

_match_at_rotation uses cv2.warpAffine(M_stored) to build the search canvas _build_affine_and_canvas uses cv2.warpAffine(M_stored) to build output canvas _transform_geojson applies M_up @ M_stored @ M_scale to annotation vertices

Because the same matrix is used everywhere, best_idx from matchTemplate is directly valid as the MALDI placement offset in the output canvas.

Functions

load_and_align(→ spatialdata.SpatialData)

Load a MALDI imzML dataset and an H&E image, auto-register them,

Module Contents

goatpy.auto_align.load_and_align(imzml_path: str, he_path: str, peaks_path: str | None = None, geojson_path: str | pathlib.Path | None = None, geojson_shapes_key: str = 'annotations', geojson_classification_key: str = 'classification', maldi_pixel_um: float | None = None, he_pixel_um: float | None = None, spectra_chunk_size: int = 10, coarse_rotation_step: int = 15, fine_rotation_range: float = 5.0, fine_rotation_step: float = 1.0, buffer_px: int = 150, img_upscaling: int = 10) → spatialdata.SpatialData[source]

Load a MALDI imzML dataset and an H&E image, auto-register them, and return a merged SpatialData object.

All three coordinate-sensitive steps — registration search, canvas building, and annotation transform — use the same cv2.warpAffine matrix (_build_affine_matrix), so best_idx, canvas pixels, and annotation vertices are all guaranteed to be in the same coordinate system.

Parameters:

  • imzml_path (str) – Path to the .imzML file.

  • he_path (str) – Path to the H&E image. SVS/NDPI require openslide.

  • peaks_path (str or None) – Path to peaks CSV. Uses bundled PEAKS.csv when None.

  • geojson_path (str, Path, or None) – Optional path to a QuPath GeoJSON annotation export.

  • geojson_shapes_key (str, default "annotations") – Key under which annotations are stored in sdata.shapes.

  • geojson_classification_key (str, default "classification") – Column name for the QuPath class label in the GeoDataFrame.

  • maldi_pixel_um (float or None) – Native MALDI pixel size in um. Auto-read from imzML when None.

  • he_pixel_um (float or None) – Native H&E pixel size in um. Auto-read from metadata when None.

  • spectra_chunk_size (int) – Ion images loaded in parallel at once.

  • coarse_rotation_step (int) – Degrees between candidates in the 0-360 coarse sweep.

  • fine_rotation_range (float) – +/- degrees searched around the best coarse angle.

  • fine_rotation_step (float) – Degree increment for fine search.

  • buffer_px (int) – Extra canvas padding (px at reg resolution).

  • img_upscaling (int) – Each MALDI pixel is upscaled to img_upscaling x img_upscaling canvas pixels in the output.

Returns:

images[‘he_image’] – full rotated H&E canvas shapes[‘pixels’] – one square per MALDI pixel shapes[geojson_shapes_key] – annotations (if geojson_path given) points[‘centroids’] – centroid of each MALDI pixel tables[‘maldi_adata’] – AnnData with ion intensities

Return type:

SpatialData with