Skip to main content

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 optional special dimensions time and grid; 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 one affine shared by all data or one affine per grid.

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
)

The grid dimension selects a spatial sampling grid: each grid has one affine, shared across time and all other nonspatial dimensions. Affines may be identical across grids. A grid dimension requires an (ngrid, 4, 4) affine stack, even for one grid; without it, geometry uses a single (4, 4) affine.

Grid-dependent geometry carries one affine per grid:

data = vd.create_voxeldata(
    np.zeros((2, 3, 64, 128)),
    dims=("grid", "k", "j", "i"),
    grid=np.array([0, 1]),
    voxel_to_world=affines,          # (2, 4, 4)
)

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

Public API

Area Functions
Dimensions VOXEL_DIMS, WORLD_DIMS, GRID_DIM, 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

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

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

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.1

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.1
File Size Uploaded Provenance Actions
voxeldata-0.0.1.tar.gz 40.8 kB Without provenance Details for voxeldata-0.0.1.tar.gz

Built distribution (wheel)

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

Total release size: 86.2 kB

Release files / voxeldata-0.0.1.tar.gz

Download URL voxeldata-0.0.1.tar.gz
Size 40.8 kB
Tags Source
SHA-256 checksum
How to use checksums
9179ceb9e0d300c9f3299435d21f61303abfce333f787dce7245e13d8de65a28
BLAKE2b-256 checksum
How to use checksums
773d546ef1b5840377bd8c7fe2ba46cd5c17f8520c696dcf20dd9b2850ce7f3f
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.1-py3-none-any.whl

Download URL voxeldata-0.0.1-py3-none-any.whl
Size 45.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
abbe8d69f339a47b74b0854dccdae437a5c4b780880b4c7da2aedd7935b34687
BLAKE2b-256 checksum
How to use checksums
31ac2a800e7676087be1cd797b54bb73f85f9fb474e0d22bddbe43dd9ea12770
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.1

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