Skip to main content

PyPI version Python versions License ConfUSIus preprint DOI Discord

VoxelData

VoxelData is a small, modality-independent data model for spatially referenced voxel arrays, built on xarray.

A VoxelData array is an xarray.DataArray that is always:

  • dimensioned (*nonspatial_dims, k, j, i) — leading dimensions may appear in any order, including the optional temporal dimension time; the native voxel indices k/j/i are always present and always last;
  • backed by a single VoxelToWorldIndex attached to the world coordinates z/y/x, which derives them lazily from a shared affine or an affine stack indexed by named nonspatial geometry_dims.

World coordinates are never stored directly. This keeps cropping, slicing, registration, and I/O consistent: the affine always describes the whole physical grid, and indexing updates it exactly.

Installation

uv add voxeldata

Or with pip:

pip install voxeldata

Quick start

import numpy as np
import voxeldata as vd

data = vd.create_voxeldata(
    np.zeros((3, 64, 128)),
    dims=("k", "j", "i"),
    spacing=(0.5, 0.1, 0.1),          # z, y, x in millimetres
    origin=(0.0, 0.0, 0.0),
)

data.coords["x"]        # lazily derived world coordinates
data.sel(x=5.0)          # select in world space
vd.validate_voxeldata(data)

data.vd.origin           # {'z': 0.0, 'y': 0.0, 'x': 0.0}
data.vd.spacing          # {'k': 0.5, 'j': 0.1, 'i': 0.1}
data.vd.direction        # (3, 3) world direction matrix

Oblique grids work the same way:

data = vd.create_voxeldata(
    np.zeros((3, 64, 128)),
    dims=("k", "j", "i"),
    voxel_to_world=affine,           # (4, 4) homogeneous affine
)

geometry_dims names the nonspatial dimensions indexing an affine stack. For example, geometry_dims=("time", "view") requires (ntime, nview, 4, 4) matrices; other axes, such as channels, share geometry. A single (4, 4) affine has no geometry dependencies, even when nonspatial dimensions are present. Timing coordinates are independent of these geometry dependencies. A named time DataArray may use (time, view, channel, ...), with any number of nonspatial dependencies. Each timestamp series must increase along time. Select all additional timestamp axes before using a shared-time index or analysis. Auxiliary coordinates such as slice_time(time, k) may be added with assign_coords; their acquisition-specific meaning belongs to the consumer.

All affine stacks require explicit geometry_dims; dimension names or matching lengths never determine their meaning. Coordinates for arbitrary nonspatial axes are supplied through extra_coords:

data = vd.create_voxeldata(
    np.zeros((2, 3, 64, 128)),
    dims=("view", "k", "j", "i"),
    extra_coords={"view": [0, 1]},
    voxel_to_world=affines,          # (2, 4, 4)
    geometry_dims=("view",),
)

assert data.vd.geometry_dims == ("view",)

Limitation: native Xarray .reindex() is unsupported on geometry dimensions; use .isel() or .sel() to select/reorder existing labels instead. Alignment that changes those labels is also unsupported. This does not affect the explicit .vd.reindex_voxels() and .vd.reindex_voxels_like() geometry operations.

Creation preserves the supplied nonspatial dimension order. For example, both (time, view, k, j, i) and (view, time, k, j, i) are valid. data.vd.canonicalize() and data.vd.ensure() normalize to (...extra_dims, time, k, j, i), preserving the relative order of extra dimensions and omitting absent time dimensions. Canonicalization also restores scalar-selected spatial dimensions, but does not restore selected nonspatial dimensions.

Public API

Area Functions
Dimensions VOXEL_DIMS, WORLD_DIMS, TIME_DIM, CORE_DIMS
Construction create_voxeldata, attach_voxel_to_world_index
Accessor data.vd (VoxelDataAccessor)
Geometry get_voxel_to_world_affine, get_voxel_to_world_units, get_voxel_to_world_index_origin, get_voxel_to_world_index_spacing, get_voxel_to_world_direction_matrix, convert_length_units
Validation validate_voxeldata, ensure_voxeldata, canonicalize_voxeldata
Affine operations apply_affine, reindex_voxels, reindex_voxels_like, get_bounding_box, get_relative_affine
Named affines data.vd.get_affine, set_affine, remove_affine, apply, to
Extraction extract_with_mask, extract_with_labels, unmask
Persistence load, save
Masks and labels ensure_mask, validate_mask, ensure_labels, validate_labels, check_spatial_alignment

The VoxelToWorldIndex and VoxelToWorldTransform classes implement the xarray indexing machinery and are exported for advanced use.

Extraction

voxeldata.extract provides generic mask extraction, region aggregation, and reconstruction. All three functions work out of the box using Xarray. Install voxeldata[accel] for optional flox group-reduction acceleration, voxeldata[lazy] for Dask arrays, voxeldata[io] for storage backends, or voxeldata[all] for all runtime features:

uv add 'voxeldata[all]'

all includes optional runtime features, not development tools.

signals = vd.extract_with_mask(data, mask)  # (..., space), selected native labels.
regions = vd.extract_with_labels(data, labels, reduction="mean")  # (..., region).
restored = vd.unmask(signals, mask)         # Rebuild the mask's full spatial grid.

Masks/labels must share the physical voxel grid. Select varying geometry before using a shared spatial mask. Extraction preserves lazy signal data; unmask is eager. See the extraction guide for formats and chunking limits.

Saving and loading

Install voxeldata[io] for Zarr and NetCDF persistence:

vd.save(data, "volume.zarr")  # Or "volume.nc" for NetCDF.
with vd.load("volume.zarr") as restored:
    volume = restored.compute()

Both formats restore the spatial index, ordered geometry dependencies, units, native voxel labels, and named frames without storing dense world coordinates. Loading works without Dask; use chunks={} with voxeldata[lazy] for Dask-backed arrays. NetCDF overwrites existing files by default, following Xarray. See the persistence guide for metadata restrictions and writer options.

Relationship to ConfUSIus

VoxelData is extracted from ConfUSIus, which uses it for functional ultrasound imaging data. The model itself makes no assumption about modality, acquisition hardware, or signal semantics, so it is usable by any package working with spatially referenced voxel data.

Development

See the roadmap for planned geometry and extraction work.

uv sync            # install dependencies
just test          # run tests
just pre-commit    # run lint, format, type checks, docstring checks
just docs          # build documentation

License

BSD-3-Clause. Portions derived from ConfUSIus; see NOTICE.

Metadata

Release files for voxeldata 0.0.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for voxeldata 0.0.5
File Size Uploaded Provenance Actions
voxeldata-0.0.5.tar.gz 53.2 kB Without provenance Details for voxeldata-0.0.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for voxeldata 0.0.5
File Interpreter ABI Platform Actions
voxeldata-0.0.5-py3-none-any.whl Python 3 none any Details for voxeldata-0.0.5-py3-none-any.whl

Total release size: 113.7 kB

Release files / voxeldata-0.0.5.tar.gz

Download URL voxeldata-0.0.5.tar.gz
Size 53.2 kB
Tags Source
SHA-256 checksum
How to use checksums
e25fe1ecfb570c96ae5ee6a67c8e4687e15167e3845e2e8929c05deec7ae270b
BLAKE2b-256 checksum
How to use checksums
222964b0b633793f0e7e1598881cc84d471dbbd6f1cc5669c5575e35bf78e723
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / voxeldata-0.0.5-py3-none-any.whl

Download URL voxeldata-0.0.5-py3-none-any.whl
Size 60.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
88ca37a4fc001b1660d08c4e220149f3cba3a925e7489bcc2f3222a4efab445c
BLAKE2b-256 checksum
How to use checksums
7ad550391480859b1ebc66e7bf8fd3dce80aa1d3788caa3a8f99155189133a54
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for voxeldata 0.0.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page