{"author":null,"author_email":"Matt McCormick ","bugtrack_url":null,"classifiers":["Intended Audience :: Developers","Intended Audience :: Science/Research","License :: OSI Approved :: MIT License","Programming Language :: Python","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.13"],"description":"# spatial-image\n\n[![Test](https://github.com/spatial-image/spatial-image/actions/workflows/test.yml/badge.svg)](https://github.com/spatial-image/spatial-image/actions/workflows/test.yml)\n[![DOI](https://zenodo.org/badge/234798632.svg)](https://zenodo.org/badge/latestdoi/234798632)\n\nA multi-dimensional spatial image data structure for scientific Python.\n\nTo facilitate:\n\n- Multi-scale processing and analysis\n- Registration\n- Resampling\n- Subregion parallel processing\n- Coupling with meshes, point sets, and annotations\n\nwith scientific images, which are typically multi-dimensional with anisotropic\nsampling, this package provides a spatial-image data structure. In addition to\nan N-dimensional array of pixel values, spatial metadata defines the location\nof the pixel sampling grid in space time. We also label the array dimensions.\nThis metadata is easily utilized and elegantly carried through image\nprocessing pipelines.\n\nThis package defines spatial image metadata, provides a function,\n`is_spatial_image`, to verify the expected behavior of a spatial image\ninstance, and provides a reference function, `to_spatial_image` to convert an\narray-like, e.g. a [NumPy\nndarray](https://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html)\nor a [Dask array](https://docs.dask.org/en/latest/array.html), to a spatial\nimage.\n\nThe spatial-image data structure is implemented with [Xarray], a library for\nN-D labeled arrays and datasets in Python. The Xarray library is well-tested,\nrelatively mature, and integrates well with scientific Python ecosystem\ntooling. The Xarray library leverages [NumPy](https://numpy.org/) and\n[pandas](https://pandas.pydata.org/) for labeled array indexing, integrates\nwell with machine-learning libraries utilizing the\n[scikit-learn](https://scikit-learn.org/) interface, integrates with\n[Dask](https://dask.org) for distributed computing, and\n[zarr](https://zarr.readthedocs.io/) for serialization.\n\nIn essence, a spatial image is an\n[`xarray.DataArray`](https://xarray.pydata.org/en/stable/data-structures.html#dataarray)\nwith a defined set of [`dims`] labels, `{'c', 'x', 'y', 'z', 't'}`,\nconstraints on the [`coords`], to enforce uniform spacing in a given\ndirection, and defined set of additional metadata [`attrs`].\n\n## Installation\n\n```\npip install spatial-image\n```\n\n## Definitions\n\n### Data Dimensions\n\nA spatial image's xarray [`dims`] belong to the set: `{'c', 'x', 'y', 'z', 't'}`. These dimensions are:\n\n

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

\n\n### Axis attributes\n\nEach `dim` has an axis with additional attributes to describe the dimension.\n\n

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.

\n\n### Coordinates\n\nA spatial image's Xarray [`coords`] specify the spatial location of pixels in\nthe image for the `'x'`, `'y'`, and `'z'` data dimensions. For the `'c'` and\n`'t'` data dimensions, component identities and timestamps can optionally\nbe provided.\n\nSpatial coordinates define the position *in the coordinate reference frame of\nthe image*. In general, the image's coordinate reference frame may be\ndifferent from the world coordinate reference frame.\n\nPixels are sampled on a uniform, possibly anisotropic, spatial grid. Spatial\ncoordinates have a 64-bit float type. The difference between adjacent\ncoordinates, i.e. the pixel *spacing*, for a dimension must be uniform. The\nfirst coordinate value defines the *origin* or *offset* of an image.\n\nThe component or channel dimension coordinates defaults to a sequence of\ninteger identifiers but can be strings describing the channels, e.g. ['r',\n'g', 'b'].\n\nThe time coordinates can have integer, float, or [`datetime64`] type.\n\n### Motivational Notes\n\n* 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.\n\n* Regular coordinate spacing enables processing optimizations, both algorithmically and computationally.\n\n\n## Development\n\nContributions are welcome and appreciated.\n\nTo run the test suite:\n\n```\ngit clone https://github.com/spatial-image/spatial-image\ncd spatial-image\npip install -e \".[test]\"\npytest\n```\n\n[Xarray]: https://xarray.pydata.org/en/stable/\n[`dims`]: https://xarray.pydata.org/en/stable/terminology.html\n[`coords`]: https://xarray.pydata.org/en/stable/terminology.html\n[`attrs`]: https://xarray.pydata.org/en/stable/data-structures.html\n[`datetime64`]: https://docs.scipy.org/doc/numpy/reference/arrays.datetime.html\n","description_content_type":"text/markdown","docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":null,"keywords":null,"license":"The MIT License (MIT)\n \n Copyright (c) 2020 NumFOCUS\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in\n all copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\n THE SOFTWARE.","license_expression":null,"license_files":["LICENSE.txt"],"maintainer":null,"maintainer_email":null,"name":"spatial-image","package_url":"https://pypi.org/project/spatial-image/","platform":null,"project_url":"https://pypi.org/project/spatial-image/","project_urls":null,"provides_extra":null,"release_url":"https://pypi.org/project/spatial-image/1.2.1/","requires_dist":["numpy","xarray-dataclasses","xarray>=2024.10.0"],"requires_python":">=3.10","summary":"A multi-dimensional spatial image data structure for scientific Python.","version":"1.2.1","yanked":false,"yanked_reason":null}

Dependencies of spatial-image (3).
Dependency	Optional
numpy	false
xarray	false
xarray-dataclasses	false

Package search

spatial-image

project_urls

Dependencies

All package metadata

Releases