spatialdata.transform

spatialdata.transform(data, transformation=None, maintain_positioning=False, to_coordinate_system=None)

Transform a SpatialElement using the transformation to a coordinate system, and returns the transformed element.

Parameters:

• data (Any) – SpatialElement to transform.

• transformation (Optional[BaseTransformation] (default: None)) – The transformation to apply to the element. This parameter can be used only when maintain_positioning=True, otherwise to_coordinate_system must be used.

• maintain_positioning (bool (default: False)) –

  The default and recommended behavior is to leave this parameter to False.

  • If True, in the transformed element, each transformation that was present in the original element will be

    prepended with the inverse of the transformation used to transform the data (i.e. the current transformation for which .transform() is called). In this way the data is transformed but the positioning (for each coordinate system) is maintained. A use case is changing the orientation/scale/etc. of the data but keeping the alignment of the data within each coordinate system.

  • If False, the data is transformed and the positioning changes; only the coordinate system in which the

    data is transformed to is kept. For raster data, the translation part of the transformation is assigned to the element (see Notes below for more details). Furthermore, for raster data, the returned object will have a translation to take into account for the pixel (0, 0) position. Also, rotated raster data will be padded in the corners with a black color, such padding will be reflected into the rotation. Please see notes for more details of how this parameter interact with xarray.DataArray for raster data.

• to_coordinate_system (Optional[str] (default: None)) – The coordinate system to which the data should be transformed. The coordinate system must be present in the element.

Return type:

Any

Returns:

: SpatialElement: Transformed SpatialElement.

Notes

An affine transformation contains a linear transformation and a translation. For raster types, only the linear transformation is applied to the data (e.g. the data is rotated or resized), but not the translation part. This means that calling Translation(…).transform(raster_element) will have the same effect as pre-pending the translation to each transformation of the raster element (if maintain_positioning=True), or assigning this translation to the element in the new coordinate system (if maintain_positioning=False). Analougous considerations apply to the black corner padding due to the rotation part of the transformation. We are considering to change this behavior by letting translations modify the coordinates stored with xarray.DataArray; this is tracked here: scverse/spatialdata#308