Transformations utils#

spatialdata.transformations.get_transformation(element, to_coordinate_system=None, get_all=False)[source]#

Get the transformation/s of an element.

Parameters:
element SpatialElement

The element.

to_coordinate_system str | None (default: None)

The coordinate system to which the transformation should be returned.

  • If None and get_all=False returns the transformation from the ‘global’ coordinate system (default system).

  • If None and get_all=True returns all transformations.

get_all bool (default: False)

If True, all transformations are returned. If True, to_coordinate_system needs to be None.

Return type:

BaseTransformation | dict[str, BaseTransformation]

Returns:

The transformation, if to_coordinate_system is not None, otherwise a dictionary of transformations to all the coordinate systems.

spatialdata.transformations.set_transformation(element, transformation, to_coordinate_system=None, set_all=False, write_to_sdata=None)[source]#

Set a transformation/s to an element, in-memory or to disk.

Parameters:
element SpatialElement

The element to set the transformation/s to.

transformation BaseTransformation | dict[str, BaseTransformation]

The transformation/s to set.

to_coordinate_system str | None (default: None)

The coordinate system to set the transformation/s to.

  • If None and set_all=False sets the transformation to the ‘global’ coordinate system (default system).

  • If None and set_all=True sets all transformations.

set_all bool (default: False)

If True, all transformations are set. If False, only the transformation to the specified coordinate system is set. If True, to_coordinate_system needs to be None.

write_to_sdata SpatialData | None (default: None)

The SpatialData object to set the transformation/s to. If None, the transformation/s are set in-memory. If not None, the element needs to belong to the SpatialData object, and the SpatialData object needs to be backed.

Return type:

None

spatialdata.transformations.remove_transformation(element, to_coordinate_system=None, remove_all=False, write_to_sdata=None)[source]#

Remove a transformation/s from an element, in-memory or from disk.

Parameters:
element SpatialElement

The element to remove the transformation/s from.

to_coordinate_system str | None (default: None)

The coordinate system to remove the transformation/s from. If None, all transformations are removed.

  • If None and remove_all=False removes the transformation from the ‘global’ coordinate system

    (default system).

  • If None and remove_all=True removes all transformations.

remove_all bool (default: False)

If True, all transformations are removed. If True, to_coordinate_system needs to be None.

write_to_sdata SpatialData | None (default: None)

The SpatialData object to remove the transformation/s from. If None, the transformation/s are removed in-memory. If not None, the element needs to belong to the SpatialData object, and the SpatialData object needs to be backed.

Return type:

None

spatialdata.transformations.get_transformation_between_coordinate_systems(sdata, source_coordinate_system, target_coordinate_system, intermediate_coordinate_systems=None, shortest_path=True)[source]#

Get the transformation to map a coordinate system (intrinsic or extrinsic) to another one.

Parameters:
source_coordinate_system SpatialElement | str

The source coordinate system. Can be a SpatialElement (intrinsic coordinate system) or a string (extrinsic coordinate system).

target_coordinate_system SpatialElement | str

The target coordinate system. Can be a SpatialElement (intrinsic coordinate system) or a string (extrinsic coordinate system).

shortest_path bool (default: True)

Whether to return the shortest paths when multiple paths are found between the coordinate systems and a single shortest path is found. If False, an error is raised when multiple paths exist. The same error is raised if True, but multiple paths of the same shortest lenghts are found.

Return type:

BaseTransformation

Returns:

The transformation to map the source coordinate system to the target coordinate system.

spatialdata.transformations.get_transformation_between_landmarks(references_coords, moving_coords)[source]#

Get a similarity transformation between two lists of (n >= 3) landmarks.

Note that landmarks are assumed to be in the same space.

Parameters:
references_coords GeoDataFrame | DataFrame

landmarks annotating the reference element. Must be a valid element describing points or circles.

moving_coords GeoDataFrame | DataFrame

landmarks annotating the moving element. Must be a valid element describing points or circles.

Return type:

Affine

Returns:

The Affine transformation that maps the moving element to the reference element.

Examples

If you save the landmark points using napari_spatialdata, they will be alredy saved as circles. Here is an example on how to call this function on two sets of numpy arrays describing x, y coordinates. >>> import numpy as np >>> from spatialdata.models import PointsModel >>> from spatialdata.transformations import get_transformation_between_landmarks >>> points_moving = np.array([[0, 0], [1, 1], [2, 2]]) >>> points_reference = np.array([[0, 0], [10, 10], [20, 20]]) >>> moving_coords = PointsModel(points_moving) >>> references_coords = PointsModel(points_reference) >>> transformation = get_transformation_between_landmarks(references_coords, moving_coords)

spatialdata.transformations.align_elements_using_landmarks(references_coords, moving_coords, reference_element, moving_element, reference_coordinate_system='global', moving_coordinate_system='global', new_coordinate_system=None, write_to_sdata=None)[source]#

Maps a moving object into a reference object using two lists of (n >= 3) landmarks.

This returns the transformations that enable this mapping and optionally saves them, to map to a new shared coordinate system.

Parameters:
references_coords GeoDataFrame | DataFrame

landmarks annotating the reference element. Must be a valid element describing points or circles.

moving_coords GeoDataFrame | DataFrame

landmarks annotating the moving element. Must be a valid element describing points or circles.

reference_element SpatialElement

the reference element.

moving_element SpatialElement

the moving element.

reference_coordinate_system str (default: 'global')

the coordinate system of the reference element that have been used to annotate the landmarks.

moving_coordinate_system str (default: 'global')

the coordinate system of the moving element that have been used to annotate the landmarks.

new_coordinate_system str | None (default: None)

If provided, both elements will be mapped to this new coordinate system with the new transformations just computed.

write_to_sdata SpatialData | None (default: None)

If provided, the transformations will be saved to disk in the specified SpatialData object. The SpatialData object must be backed and must contain both the reference and moving elements.

Return type:

BaseTransformation

Returns:

A similarity transformation that maps the moving element to the same coordinate of reference element in the coordinate system specified by reference_coordinate_system.

spatialdata.transformations.remove_transformations_to_coordinate_system(sdata, coordinate_system)[source]#

Remove (inplace) all transformations to a specific coordinate system from all the elements of a SpatialData object.

Parameters:
sdata SpatialData

The SpatialData object.

coordinate_system str

The coordinate system to remove the transformations from.

Return type:

None