Transfo manager base by ajkswamy · Pull Request #1164 · scverse/spatialdata

ajkswamy · 2026-07-14T15:29:53Z

Issue Description

Currently, each spatial element stores its transformations as a dictionary in its attrs (key: TRANSFORM_KEY = "
transform"). This means transformation information is distributed across elements, and there is no mechanism to define
or query transformations between coordinate systems. The proposed change introduces a centralized TransformationManager
object at the
root of SpatialData that owns all coordinate system and transformation metadata, replacing the current per-element
attrs["transform"] dictionaries.

Motivation

Missing inter-CS transforms: With per-element storage, defining a transformation from coordinate system A to B
requires
touching both element dictionaries independently. A central registry avoids this duplication and inconsistency.
Single source of truth: A unified TransformationManager makes it straightforward to inspect the full transformation
graph, validate
connectivity/acyclicity, and add new features on top of a stable graph API.

Current Architecture

Currently, transformation information is stored inside each spatial element's attrs dictionary under the key
TRANSFORM_KEY = "transform". Access and mutation happen through _get_transformations() and _set_transformations()
utility functions. Each element independently maps its native pixel/point space to one or more coordinate systems, but
there is no global view of the transformation graph and no way to define transformations between coordinate systems
without touching each element dictionary.

Proposed Solution

Add a TransformationManager attribute to SpatialData.

TransformationManager stores:

nx.MultiDiGraph with NgffCoordinateSystem objects as nodes and pass transforms as attributes while adding edges
_element_to_cs_mapping: mapping of element → NgffCoordinateSystem object

Scope

Out-of-Scope

File format changes or support of new file formats

TransformationManager serialization to file formats

Advanced transformation graph operations

Exposing new class into Public API

Technical Constraints

Compatibility: Must support all existing spatial element types (images, labels, points, shapes, tables)

Tomaz-Vieira

I left a bunch of mostly typing-related comments, as you might imagine 😆

Also, this is something we might need to decide as a team, but it's a bit funny that often the docstring is way longer than the code itself, and often there isn't much more to say, like:

souce_cs
    The name of the source coordinate system

I often feel like the typing signature is more concise and more informative than the docstrings, and that sometimes we could survive just with the headline and the "raises" part.

But anyway, good stuff, it's nice to see we're moving already =)

Tomaz-Vieira · 2026-07-14T16:15:39Z

+                associated_transformations.append(transformation_key)
+        return associated_transformations
+
+    def _get_elements_associated_with_cs(self, cs_name: str) -> list[tuple[ELEMENT_TYPE, str]]:


Maybe we need a word that is better than "associated" to mean that the element belongs or exists in the coordinate system. It's a stronger relation than the transforms that are "associated" with the coordinate systems, because an element can only belong so a single CS, but a CS can have many transforms.

I agree, I like belongs for instance, but no hard opinions.

How about "element set in a coordinate system"? the API would be like

class TransformationManager:

__ init__

.......

........

set_element_in_coordinate_system(....)

unset_element_from_coordinate_system(....)

get _element_coordinate_system (....) "Get the coordinate system in which an element is set"

get_elements_set_in_cs(....)

Currently, I have tried to stick to "transformations associated with a cs" and "elements belonging to a cs". Only exception is "unset_element" for which I don't have a better idea. Any ideas?

codecov · 2026-07-16T13:10:24Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.73%. Comparing base (eb4fb3d) to head (ab98633).

Additional details and impacted files

@@                    Coverage Diff                     @@
##           transformation_manager    #1164      +/-   ##
==========================================================
+ Coverage                   92.44%   92.73%   +0.29%     
==========================================================
  Files                          51       53       +2     
  Lines                        7820     8028     +208     
==========================================================
+ Hits                         7229     7445     +216     
+ Misses                        591      583       -8

Files with missing lines	Coverage Δ
src/spatialdata/__init__.py	`95.65% <ø> (ø)`
src/spatialdata/_core/spatialdata.py	`93.87% <100.00%> (+0.01%)`	⬆️
...atialdata/_core/transformation_manager/__init__.py	`100.00% <100.00%> (ø)`
...ialdata/_core/transformation_manager/exceptions.py	`100.00% <100.00%> (ø)`
src/spatialdata/_io/io_raster.py	`89.52% <100.00%> (+0.47%)`	⬆️
src/spatialdata/_io/io_zarr.py	`92.38% <100.00%> (ø)`
src/spatialdata/_types.py	`100.00% <100.00%> (ø)`

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

LucaMarconato · 2026-07-16T13:33:25Z

(to be moved to a separate issue)
We can probably restore networkx as a global import, as you can see from running profimp, dask.dataframe is what is driving the slow import time.

Importing networkx is actually 273 ms.

LucaMarconato · 2026-07-16T13:43:28Z

+    def get_existing_transformation(self, input_cs: str, output_cs: str) -> BaseTransformation | None:
+        """
+        Retrieve a transformation defined between coordinate systems.
+
+        Parameters
+        ----------
+        input_cs


TODO: check if the specs allows multi edges between the coordinate systems. There was some discussion regarding this at the Heidelberg hackathon and I don't remmber the outcome.

I don't see anything in the specification that forbids multiple edges between coordinate systems. Also, transformnd uses nx.MultiDiGraph and does not check if an edge already exists between two nodes when adding edges to graph.

LucaMarconato · 2026-07-16T13:44:42Z

+        key = (input_cs, output_cs)
+        return self._coordinate_transforms.get(key)
+
+    def remove_transformation(self, input_cs: str, output_cs: str) -> None:


if we have a multigraph, we need to change the signature to let the user remove a specific transformation.

LucaMarconato · 2026-07-16T13:47:28Z

+            g.add_edge(input_cs, output_cs, transformation=transformation)
+        return g
+
+    def get_shortest_transformation_sequence(self, source_cs: str, target_cs: str) -> list[BaseTransformation]:


We will sometimes have multiple shortest paths between 2 coordinate systems (this may happen even if we don't have a multigraph). What we do in spatialdata is shown here. It's not the cleanest approach, but it could be used also here to get the job done:

spatialdata/src/spatialdata/transformations/operations.py

Line 218 in eb4fb3d

intermediate_coordinate_systems: SpatialElement | str | None = None,

. Note one can still construct edge cases that fail, the clean approach may be to pass the full list of cs as a path.

LucaMarconato · 2026-07-16T13:48:14Z

+            transformations.append(g[path[i]][path[i + 1]]["transformation"])
+        return transformations
+
+    def get_all_transformation_sequences(self, source_cs: str, target_cs: str) -> list[list[BaseTransformation]]:


We could return directly a list[spatialdata.transformation.Sequence]

Ideas:

@ajkswamy suggested to let the user choose the return type list of list vs list of Sequence. This has the con of complicating typing.

Comments:

Pro: of returning a list of list: the user can easily extract sub transformations

Con: if you have a Sequence you can directly use it to get an affine, to transform things. At the cost that you have to call my_sequence.transformations to get the subcomponents (but it's not that bad)

LucaMarconato · 2026-07-16T13:51:40Z

+            all_sequences.append(sequence)
+        return all_sequences
+
+    def __repr__(self) -> str:


For later: it would be very nice to let the user be able to plot this. An option could be a hard coded HTML rendering with no additional dependencies, but this comes with extra code to maintain.

If the user already import matplotlib (via spatialdata-plot), we could plot via networkx + matplotlib.

ajkswamy added 6 commits July 10, 2026 11:29

chore: added pandas-stubs as dev dependency; helps with type checking

30511a7

chore: added local hatch.toml to gitignore

986f0bb

chore: Add .kilo and plans to .gitignore

5e0d12f

feat: added literals and types for element types and group names

81bb674

feat: added .coverage and htmlcov to gitignore

787770a

feat: transformation manager at the root of spatialdata object

9b2d259

Tomaz-Vieira reviewed Jul 14, 2026

View reviewed changes

fix: io_zarr.py mixup between ELEMENT_TYPE_VECTOR/RASTER

ca80f91

LucaMarconato reviewed Jul 16, 2026

View reviewed changes

Comment thread src/spatialdata/_core/transformation_manager/__init__.py Outdated

LucaMarconato reviewed Jul 16, 2026

View reviewed changes

Comment thread src/spatialdata/__init__.py Outdated

LucaMarconato reviewed Jul 16, 2026

View reviewed changes

Comment thread src/spatialdata/__init__.py Outdated

LucaMarconato reviewed Jul 16, 2026

View reviewed changes

Comment thread src/spatialdata/__init__.py

ajkswamy added 10 commits July 16, 2026 16:59

fix: avoid exposing TransformationManager in spatialdata __init__.py

8f9d07f

fix: element associated to cs -> element belonging to cs

dce3dc6

refac: transformation_manager now uses nx.MultiDiGraph

367d99e

refac: tests to match new transformation manager implementation

65aadb6

fix: restored unintentionally removed functions + others fixes

611abee

feat: custom error messages for transformation graph elements

fd042a6

feat: custom exceptions for transform manager

070db93

refac: transform manager attributes private; added missing method

5314e02

feat: more custom error and warnings + fixes

5eadef4

feat: more test coverage + fixes

ab98633

ajkswamy self-assigned this Jul 21, 2026

Uh oh!

Conversation

ajkswamy commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Issue Description

Motivation

Current Architecture

Proposed Solution

Scope

Out-of-Scope

Technical Constraints

Uh oh!

Tomaz-Vieira left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Tomaz-Vieira Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

LucaMarconato commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ajkswamy commented Jul 14, 2026 •

edited

Loading

Tomaz-Vieira left a comment •

edited

Loading

Tomaz-Vieira Jul 14, 2026 •

edited

Loading

codecov Bot commented Jul 16, 2026 •

edited

Loading

LucaMarconato commented Jul 16, 2026 •

edited

Loading