stereo-seq-image-registration

name: stereo-seq-image-registration description: Use when Stereo-seq or STOmics expression coordinates, heatmaps, GEM/GEF-derived spatial maps, ssDNA, DAPI, nuclei, histology, HE, IF, tissue masks, cell masks, or image tiles need image-to-expression registration, transform application, landmark/template matching QC, affine/TPS coordinate warping, registered overlay checks, or handoff to STCellbin/GEM3D/Thor-style image-expression integration.

Stereo-seq Image Registration

Use This For

• Registering Stereo-seq expression maps to ssDNA, DAPI, histology, HE, IF, nuclei, cell-boundary, or tissue-mask images.
• Applying an affine transform, landmark-derived transform, XML transform, or manually curated image-to-expression transform to GEM/h5ad coordinates.
• Auditing image/expression coordinate orientation, pixel scale, transform direction, landmark error, and overlay quality before cellbin segmentation or histology-linked interpretation.
• Preparing inputs for STCellbin, GEM3D, Thor, bin2cell, image-based domain tools, or downstream spatial plotting.

For segmentation and cellbin aggregation after registration, use stereo-seq-cellbin-segmentation. For serial-section 3D alignment, use stereo-seq-3d-reconstruction.

Default Requirements

• Read source_code.md before designing a registration workflow. These entries come from public Stereo-seq image/expression registration and histology integration code.
• If no curated entry fits, search code_candidates.tsv and stereo-seq-publication-story/references/github_code_registry.tsv before external search.
• Always identify transform direction: image-to-expression, expression-to-image, moving-to-fixed, or fixed-to-moving. Do not apply an inverse transform unless explicitly required.
• Keep pixel size, bin size, coordinate origin, axis orientation, and y-axis inversion explicit.
• Validate registration with at least one QC output: landmark RMSE, before/after coordinate bounds, expression-image overlay, mask overlap, or tissue contour overlay.
• Treat missing images, landmarks, masks, transforms, or method packages as blockers for that step. Do not silently replace image registration with expression-only clustering.
• In the final response, state the reused paper, DOI, repository/source file, and dataset-specific edits.

Workflow

1. Identify inputs:
   • expression coordinates: GEM table, h5ad obsm['spatial'], Seurat spatial metadata, or heatmap coordinates;
   • image modality: ssDNA, DAPI, HE/histology, IF, nuclei/cell mask, tissue mask;
   • transform source: STCellbin transform, GEM3D XML/matrix, landmarks, affine matrix, TPS landmarks, or manual registration.
2. Choose a route from source_code.md:
   • STCellbin route for image-expression alignment inside cellbin generation;
   • GEM3D route for ssDNA/expression heatmap registration and transform application;
   • Thor/HumanPilot/wholebrain route for histology-linked cell/spot registration and QC;
   • lightweight bundled scripts for table-level transform application or landmark QC.
3. Run scripts/apply_spatial_transform_template.py when a coordinate table and transform matrix/landmarks are already available.
4. Run scripts/registration_landmark_qc_template.py to quantify fiducial/landmark error and create before/after QC plots.
5. Export transformed coordinates, transform metadata, QC plots, and an explicit handoff statement for segmentation, domain, annotation, or 3D skills.

Reusable Article Code

• scripts/apply_spatial_transform_template.py: affine/landmark transform application template derived from GEM3D transform application, STCellbin alignment separation, and wholebrain registration patterns.
• scripts/registration_landmark_qc_template.py: landmark error and overlay QC template derived from STCellbin template matching, GEM3D ssDNA/heatmap registration, and HumanPilot histology registration checks.

When using any bundled script, report the paper and original source file from source_code.md.

Output Expectations

• Transform source, direction, coordinate system, image modality, and pixel/bin scale assumptions.
• Transformed coordinate table or updated object.
• QC report with coordinate bounds and landmark RMSE or overlay/contour evidence.
• Blockers for missing transforms, landmarks, images, masks, packages, or ambiguous transform direction.
• Reused article code source, DOI, repository, original file name, and dataset-specific edits.