Add assign_z_coordinates function for 3D reconstruction from multiple 2D slices

[Copilot]

Overview

This PR addresses issue about z-axis coordinate calculation for 3D reconstruction by adding a new utility function assign_z_coordinates() that systematically assigns z-coordinates to multiple 2D spatial transcriptomics slices.

Problem

Users performing 3D reconstruction from sequential 2D tissue sections previously had no clear guidance or automated method for:

• Determining appropriate z-spacing between slices
• Calculating and assigning z-axis coordinates
• Handling non-uniform sections or missing slices
• Following best practices for 3D model construction

Currently, when 2D data is encountered, Spateo automatically adds zeros for z-coordinates, but there was no documented workflow for properly spacing slices in the z-dimension.

Solution

New Function: assign_z_coordinates()

Added a comprehensive function accessible via st.tl.assign_z_coordinates() or st.align.assign_z_coordinates() that supports three z-spacing strategies:

1. Default/Custom Uniform Spacing

# Default spacing of 1.0
st.tl.assign_z_coordinates(slices, spatial_key="align_spatial")

# Custom uniform spacing
st.tl.assign_z_coordinates(slices, z_spacing=10.0)

2. Tissue Thickness-Based Spacing

# Use known tissue section thickness
st.tl.assign_z_coordinates(slices, tissue_thickness=15.0)  # 15 µm sections

3. Variable Spacing for Non-Uniform Sections

# Handle missing sections or variable spacing
st.tl.assign_z_coordinates(slices, z_spacing=[10.0, 30.0, 10.0])  # Larger gap for missing section

Complete Workflow Example

import spateo as st

# Step 1: Load and align 2D slices (existing functionality)
slices = [slice1, slice2, slice3, slice4]
for i in range(1, len(slices)):
    st.tl.morpho_align(sliceA=slices[i], sliceB=slices[i-1], 
                       spatial_key='spatial', key_added='align_spatial')

# Step 2: Assign z-coordinates (NEW)
st.tl.assign_z_coordinates(slices, spatial_key='align_spatial', 
                           tissue_thickness=15.0)

# Step 3: Visualize 3D model (existing functionality)
st.pl.three_d_multi_plot.multi_models(*slices, spatial_key='align_spatial')

Key Features

• ✅ Flexible spacing strategies: uniform, tissue thickness-based, or variable
• ✅ Handles edge cases: single slices, missing sections, different coordinate systems
• ✅ Preserves data: Original XY coordinates unchanged, option for in-place or copy
• ✅ Well-tested: 8 comprehensive unit tests (all passing)
• ✅ Documented: 561 lines of technical documentation and practical examples
• ✅ Zero breaking changes: Purely additive functionality

Documentation Added

1. Technical Documentation (docs/technicals/3d_reconstruction.md):

   • Understanding z-spacing strategies
   • Complete 3D reconstruction workflow
   • Best practices and recommendations
   • Common pitfalls and troubleshooting
   • Advanced topics (global refinement, coordinate systems)

2. Practical Examples (docs/examples/3d_reconstruction_example.md):

   • Quick start code snippets
   • Complete workflow examples
   • Handling different coordinate systems
   • Dealing with missing sections

Testing

Added 8 comprehensive unit tests in tests/alignment/test_utils.py covering:

• Default uniform spacing
• Custom uniform spacing
• Tissue thickness-based spacing
• Variable spacing
• Z-offset functionality
• In-place vs. copy modification
• XY coordinate preservation
• Single slice handling

All tests verified passing ✓

Files Changed

• spateo/alignment/utils.py (+146 lines) - Core function implementation
• spateo/alignment/__init__.py (+1 line) - Export function
• spateo/align.py (+1 line) - Module integration
• docs/technicals/3d_reconstruction.md (+339 lines) - Technical documentation
• docs/technicals/index.md (+2 lines) - Add to documentation index
• docs/examples/3d_reconstruction_example.md (+203 lines) - Practical examples
• docs/examples/README.md (+18 lines) - Examples directory index
• tests/alignment/test_utils.py (+164 lines) - Comprehensive test suite

Total: 8 files changed, 874 insertions (+)

Impact

This PR provides users with a systematic, flexible, and well-documented approach to z-coordinate assignment for 3D reconstruction, directly addressing the questions raised about:

• ✅ How to determine appropriate z-spacing between slices
• ✅ Whether Spateo provides automatic z-coordinate calculation
• ✅ Best practices for assigning z-values when building 3D models
• ✅ Recommended workflow for 3D reconstruction in Spateo

The implementation follows Spateo's existing patterns and conventions, integrating seamlessly with the current alignment and visualization workflows.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Inquiry about 3D Model Z-axis Coordinate Calculation in Spateo</issue_title>
<issue_description>Dear Spateo Developers,

First, I want to express my sincere gratitude for developing such a powerful and comprehensive package for spatial transcriptomics analysis. Spateo has been instrumental in advancing our research, and we truly appreciate the effort you've put into creating this excellent tool.

I've been thoroughly studying the Spateo documentation and tutorials, and while I found the 2D spatial analysis features exceptionally well-documented, I'm having some difficulty understanding how to properly calculate and assign z-axis coordinates when building 3D models from multiple tissue slices.

Specifically, in our current project we have:

Multiple aligned 2D spatial transcriptomics slices

Successfully performed 2D alignment using Spateo's alignment functions

Now need to reconstruct these into a proper 3D model

From the documentation, I can see functions for 3D visualization and analysis, but I couldn't find clear guidance on:

How to determine appropriate z-spacing between slices

Whether Spateo provides automatic z-coordinate calculation

Best practices for assigning z-values when building 3D models from sequential sections

Could you please provide some guidance on:

What is the recommended workflow for 3D reconstruction in Spateo?

Are there specific functions for calculating optimal z-axis coordinates?

Should we use equal spacing, tissue thickness-based spacing, or is there a more sophisticated method available?

Thank you again for your incredible work on Spateo, and I would be extremely grateful for any advice you could offer on 3D model construction.

</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #348

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.