Transformations utils#

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

Get the transformation/s of an element.

Parameters:
  • element (DataArray | DataTree | GeoDataFrame | DataFrame) – The element.

  • to_coordinate_system (Optional[str] (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:

Union[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)#

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

Parameters:
  • element (DataArray | DataTree | GeoDataFrame | DataFrame) – The element to set the transformation/s to.

  • transformation (Union[BaseTransformation, dict[str, BaseTransformation]]) – The transformation/s to set.

  • to_coordinate_system (Optional[str] (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 (Optional[SpatialData] (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)#

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

Parameters:
  • element (DataArray | DataTree | GeoDataFrame | DataFrame) – The element to remove the transformation/s from.

  • to_coordinate_system (Optional[str] (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 (Optional[SpatialData] (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)#

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

Parameters:
  • source_coordinate_system (Union[DataArray, DataTree, GeoDataFrame, DataFrame, str]) – The source coordinate system. Can be a SpatialElement (intrinsic coordinate system) or a string (extrinsic coordinate system).

  • target_coordinate_system (Union[DataArray, DataTree, GeoDataFrame, DataFrame, 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)#

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 (Union[GeoDataFrame, DataFrame]) – landmarks annotating the reference element. Must be a valid element describing points or circles.

  • moving_coords (Union[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)#

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 (Union[GeoDataFrame, DataFrame]) – landmarks annotating the reference element. Must be a valid element describing points or circles.

  • moving_coords (Union[GeoDataFrame, DataFrame]) – landmarks annotating the moving element. Must be a valid element describing points or circles.

  • reference_element (DataArray | DataTree | GeoDataFrame | DataFrame) – the reference element.

  • moving_element (DataArray | DataTree | GeoDataFrame | DataFrame) – 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 (Optional[str] (default: None)) – If provided, both elements will be mapped to this new coordinate system with the new transformations just computed.

  • write_to_sdata (Optional[SpatialData] (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)#

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