Skip to main content

spatial-image

Project description

spatial-image

Test DOI

A multi-dimensional spatial image data structure for scientific Python.

To facilitate:

  • Multi-scale processing and analysis
  • Registration
  • Resampling
  • Subregion parallel processing
  • Coupling with meshes, point sets, and annotations

with scientific images, which are typically multi-dimensional with anisotropic sampling, this package provides a spatial-image data structure. In addition to an N-dimensional array of pixel values, spatial metadata defines the location of the pixel sampling grid in space time. We also label the array dimensions. This metadata is easily utilized and elegantly carried through image processing pipelines.

This package defines spatial image metadata, provides a function, is_spatial_image, to verify the expected behavior of a spatial image instance, and provides a reference function, to_spatial_image to convert an array-like, e.g. a NumPy ndarray or a Dask array, to a spatial image.

The spatial-image data structure is implemented with Xarray, a library for N-D labeled arrays and datasets in Python. The Xarray library is well-tested, relatively mature, and integrates well with scientific Python ecosystem tooling. The Xarray library leverages NumPy and pandas for labeled array indexing, integrates well with machine-learning libraries utilizing the scikit-learn interface, integrates with Dask for distributed computing, and zarr for serialization.

In essence, a spatial image is an xarray.DataArray with a defined set of dims labels, {'c', 'x', 'y', 'z', 't'}, constraints on the coords, to enforce uniform spacing in a given direction, and defined set of additional metadata attrs.

Installation

pip install spatial-image

Definitions

Data Dimensions

A spatial image's xarray dims belong to the set: {'c', 'x', 'y', 'z', 't'}. These dimensions are:

c
Component / channel dimension.
x
First spatial dimension.
y
Second spatial dimension.
z
Third spatial dimension.
t
Time dimension.

Axis attributes

Each dim has an axis with additional attributes to describe the dimension.

long_name
A descriptive name for the axis, e.g. anterior-posterior or x-axis. Defaults to the dim name.
units
Units for the axis, e.g. millimeters. Defaults to the empty string.

Coordinates

A spatial image's Xarray coords specify the spatial location of pixels in the image for the 'x', 'y', and 'z' data dimensions. For the 'c' and 't' data dimensions, component identities and timestamps can optionally be provided.

Spatial coordinates define the position in the coordinate reference frame of the image. In general, the image's coordinate reference frame may be different from the world coordinate reference frame.

Pixels are sampled on a uniform, possibly anisotropic, spatial grid. Spatial coordinates have a 64-bit float type. The difference between adjacent coordinates, i.e. the pixel spacing, for a dimension must be uniform. The first coordinate value defines the origin or offset of an image.

The component or channel dimension coordinates defaults to a sequence of integer identifiers but can be strings describing the channels, e.g. ['r', 'g', 'b'].

The time coordinates can have integer, float, or datetime64 type.

Motivational Notes

  • Image-axis-aligned Cartesian coordinate reference frames enable Pythonic subscripting in processing pipelines on xarray.DataArray's. When indexing with slices, the same slices are applied to the multi-dimensional pixel array as the 1-D coordinate arrays, and the result is valid.

  • Regular coordinate spacing enables processing optimizations, both algorithmically and computationally.

Development

Contributions are welcome and appreciated.

To run the test suite:

git clone https://github.com/spatial-image/spatial-image
cd spatial-image
pip install -e ".[test]"
pytest

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

spatial_image-1.1.0.tar.gz (12.3 kB view details)

Uploaded Source

Built Distribution

spatial_image-1.1.0-py3-none-any.whl (8.0 kB view details)

Uploaded Python 3

File details

Details for the file spatial_image-1.1.0.tar.gz.

File metadata

  • Download URL: spatial_image-1.1.0.tar.gz
  • Upload date:
  • Size: 12.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.0 CPython/3.11.9

File hashes

Hashes for spatial_image-1.1.0.tar.gz
Algorithm Hash digest
SHA256 e7fb185644093e96cac510c4184f2777b965b5a7ca25688f379e9acb48e3e07d
MD5 e2e79a89fdc7c6b319f721c0c09a54ac
BLAKE2b-256 61687a5b2711c84d4ce5a129555c41a43f05d275ec68aed883ca9633b25f6dfb

See more details on using hashes here.

File details

Details for the file spatial_image-1.1.0-py3-none-any.whl.

File metadata

File hashes

Hashes for spatial_image-1.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 f7f9b89e20ced35ee50efb588399d384d44c8242bee686a2e8add2fc9ab3ef56
MD5 dbf2a90e00224c258b85f2e06adac4d1
BLAKE2b-256 10e5134cfa437c0d87ce33b28b593a9990ceb4dd425e104c8da3efc299dccc55

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page