---
id: spatial-image
version: "1.2.3"
license: The MIT License (MIT) Copyright (c) 2020 NumFOCUS Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to… (full text in the JSON record)
license_treatment: permissive
maintenance: aging
---

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

License: permissive · Maintenance: aging · Downloads: 93.9K/mo

## What it is and what it does

spatial-image wraps xarray.DataArray to create a standardized data structure for scientific images that are typically multi-dimensional and anisotropic. It enforces a consistent schema: dimensions from the set {c, x, y, z, t}, uniform spacing per axis, and spatial metadata (origin, units, axis names) stored as coordinates and attributes. This allows pixel values and their spatial context to move together through processing pipelines without manual bookkeeping.

The package is designed for workflows involving registration, resampling, multi-scale analysis, and coupling with meshes or annotations. It integrates with the broader scientific Python ecosystem through numpy, xarray, and related tools, so that standard slicing operations preserve both data and metadata correctly.

Use it for:

- Medical imaging: carry voxel spacing and anatomical axis labels through registration and resampling workflows.
- Multi-scale image analysis: track origin and spacing metadata as images are processed at different resolutions.
- Subregion parallel processing: slice spatial images with xarray and maintain valid coordinates for each chunk.
- Image-to-mesh coupling: preserve spatial coordinates when linking pixel data to mesh or point-cloud annotations.
- Distributed image processing: pass spatial images to Dask-based pipelines without losing spatial metadata.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

spatial-image provides an N-dimensional spatial image data structure built on xarray that carries pixel values alongside spatial metadata—origin, spacing, and dimension labels—through image processing pipelines.

Yes, if you work with multi-dimensional scientific images and need spatial metadata (origin, spacing, axis labels) to persist through processing pipelines. The low install friction and permissive license make adoption straightforward. However, the aging maintenance status (371 days since last release) means you should accept slower bug fixes and check that the package's current dependencies remain compatible with your environment before committing to it for new projects.

## Install

pip install spatial-image
uv add spatial-image
poetry add spatial-image

## Installing spatial_image

Before you install: Low install friction; pure Python wheel. Maintenance status is aging—last release 371 days ago—so expect slower bug fixes and feature updates, though the package remains functional for current Python versions.

License in practice: MIT license (permissive); you may use, modify, and distribute this package freely in commercial or private projects with minimal restrictions.

Quickstart:

pip install spatial-image

import numpy as np
from spatial_image import to_spatial_image

array = np.random.rand(10, 10, 10)
img = to_spatial_image(array)

Requires Python 3.10 or later.

Verify before relying:

- Whether the package is actively maintained or in maintenance-only mode given the 371-day gap since last release.
- Performance characteristics when working with very large multi-dimensional arrays or distributed computing via Dask.
- Compatibility with specific downstream libraries beyond what the description claims.

## Package facts

- License: The MIT License (MIT) Copyright (c) 2020 NumFOCUS Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 93.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

spatial image data structure, multi-dimensional image metadata, xarray-based image processing, anisotropic image sampling, labeled array image data, scientific image coordinates, image registration and resampling, image-processing, scientific-computing, xarray-ecosystem

[View on SkillFed](https://skillfed.io/packages/spatial-image) · [View on PyPI](https://pypi.org/project/spatial-image/)