goatpy.auto_align

Auto-registration of a MALDI imzML dataset against a whole-slide H&E image, or against a multichannel IHC TIFF / OME-TIFF 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/IHC 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.

IHC support

When ihc_path is supplied to load_and_align, the function loads a multichannel TIFF or OME-TIFF (any format readable by tifffile) instead of an H&E image. Registration uses a single channel selected by ihc_channel (default: the channel with the highest mean intensity, which is usually the DAPI / nuclear stain — a good proxy for tissue shape). The full multichannel canvas is stored in sdata.images["ihc_image"]; the channel used for registration is stored in sdata.images["ihc_reg_channel"] for inspection.

Coordinate system

All three steps share the same affine matrix M_stored:

M_stored maps: reg-resolution image 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 or IHC image, auto-register them,

Module Contents

goatpy.auto_align.load_and_align(imzml_path: str, he_path: str | None = None, 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, tol: float = 0.1, reduce_func: Any = sum, ihc_path: str | None = None, ihc_pixel_um: float | None = None, ihc_channel: int | None = None, ihc_invert: bool = False) → spatialdata.SpatialData[source]

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

Exactly one of he_path or ihc_path must be supplied. When ihc_path is given the function loads a multichannel TIFF / OME-TIFF (any format readable by tifffile) and uses a single channel for registration. The full multichannel canvas is stored in sdata.images["ihc_image"]; the H&E slot is left empty.

Parameters:

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

  • he_path (str or None) – Path to an H&E image (SVS, NDPI, TIFF, PNG, …). Supply either he_path or ihc_path, not both.

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

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

  • geojson_shapes_key (str, default "annotations")

  • geojson_classification_key (str, default "classification")

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

  • he_pixel_um (float or None) – H&E native pixel size in µm. Auto-read from metadata when None. Also used as the pixel size for IHC when ihc_pixel_um is None.

  • spectra_chunk_size (int)

  • coarse_rotation_step (int)

  • fine_rotation_range (float)

  • fine_rotation_step (float)

  • buffer_px (int)

  • img_upscaling (int)

  • tol (float)

  • reduce_func (callable)

  • parameters (IHC)

  • --------------

  • ihc_path (str or None) – Path to a multichannel IHC TIFF / OME-TIFF. Supply either he_path or ihc_path, not both.

  • ihc_pixel_um (float or None) – Native IHC pixel size in µm. Auto-read from OME-XML / TIFF tags when None. Falls back to he_pixel_um and then to 0.2527 µm/px.

  • ihc_channel (int or None) – Index of the channel to use for registration. None (default) → auto-select the channel with the highest mean intensity (typically the nuclear stain, which captures tissue shape).

  • ihc_invert (bool, default False) – Invert the registration channel before matching. H&E images are automatically inverted (tissue is dark → bright after inversion, matching the bright MALDI TIC signal). For brightfield IHC, set ihc_invert=True. For fluorescence IHC, leave as False (tissue is already bright).

Returns:

images[‘he_image’] – H&E canvas (if he_path supplied) images[‘ihc_image’] – multichannel IHC canvas (if ihc_path supplied) 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