voxeldata 0.0.1__tar.gz

voxeldata-0.0.1/LICENSE

@@ -0,0 +1,27 @@
+BSD 3-Clause License
+
+Copyright (c) 2025-2026, The VoxelData developers
+
+Redistribution and use in source and binary forms, with or without modification, are
+permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of
+   conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list
+   of conditions and the following disclaimer in the documentation and/or other
+   materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be
+   used to endorse or promote products derived from this software without specific prior
+   written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
+THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
+OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

voxeldata-0.0.1/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: voxeldata
+Version: 0.0.1
+Summary: Spatially referenced voxel arrays built on xarray.
+Author: Samuel Le Meur-Diebolt
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Typing :: Typed
+Requires-Dist: numpy>=2.3.4
+Requires-Dist: pandas>=2.2.0
+Requires-Dist: xarray>=2025.1.0
+Requires-Python: >=3.11, <3.15
+Description-Content-Type: text/markdown
+
+# VoxelData
+
+**VoxelData** is a small, modality-independent data model for spatially referenced
+voxel arrays, built on [xarray](https://docs.xarray.dev).
+
+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`](src/voxeldata/geometry.py) 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
+
+```bash
+uv add voxeldata
+```
+
+Or with pip:
+
+```bash
+pip install voxeldata
+```
+
+## Quick start
+
+```python
+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:
+
+```python
+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:
+
+```python
+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`](src/voxeldata/accessors.py)) |
+| 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](https://github.com/confusius-tools/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
+
+```bash
+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`.

voxeldata-0.0.1/README.md

@@ -0,0 +1,119 @@
+# VoxelData
+
+**VoxelData** is a small, modality-independent data model for spatially referenced
+voxel arrays, built on [xarray](https://docs.xarray.dev).
+
+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`](src/voxeldata/geometry.py) 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
+
+```bash
+uv add voxeldata
+```
+
+Or with pip:
+
+```bash
+pip install voxeldata
+```
+
+## Quick start
+
+```python
+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:
+
+```python
+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:
+
+```python
+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`](src/voxeldata/accessors.py)) |
+| 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](https://github.com/confusius-tools/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
+
+```bash
+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`.

voxeldata-0.0.1/pyproject.toml

@@ -0,0 +1,88 @@
+[project]
+name = "voxeldata"
+version = "0.0.1"
+description = "Spatially referenced voxel arrays built on xarray."
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+requires-python = ">=3.11,<3.15"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Image Processing",
+    "Typing :: Typed",
+]
+dependencies = [
+    "numpy>=2.3.4",
+    "pandas>=2.2.0",
+    "xarray>=2025.1.0",
+]
+
+[[project.authors]]
+name = "Samuel Le Meur-Diebolt"
+
+[build-system]
+requires = ["uv-build>=0.9.5,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "codespell>=2.3.0",
+    "numpydoc>=1.11.0",
+    "prek>=0.4.8",
+    "pytest>=9.1.1",
+    "pytest-cov>=6.0.0",
+    "ruff>=0.16.5",
+    "ty>=0.0.77,<0.1.0",
+    "zensical>=0.0.67",
+    "mkdocstrings[python]>=1.0.4",
+]
+
+[tool.numpydoc_validation]
+exclude = [
+    '\.__init__$',
+    '\._.*$',
+]
+checks = [
+    "all",
+    "GL01",
+    "ES01",
+    "SA01",
+    "EX01",
+]
+
+[tool.ruff]
+line-length = 88
+
+[tool.ty.src]
+include = [
+    "src",
+    "tests",
+]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+pythonpath = ["."]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+    "--import-mode=importlib",
+    "--showlocals",
+    "--cov=voxeldata",
+    "--cov-report=term-missing",
+    "--cov-report=html",
+    "--cov-report=xml",
+]
+filterwarnings = ["error"]

voxeldata-0.0.1/pyproject.toml.orig

@@ -0,0 +1,83 @@
+[project]
+name = "voxeldata"
+version = "0.0.1"
+description = "Spatially referenced voxel arrays built on xarray."
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [{ name = "Samuel Le Meur-Diebolt" }]
+requires-python = ">=3.11,<3.15"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Image Processing",
+    "Typing :: Typed",
+]
+dependencies = [
+    "numpy>=2.3.4",
+    "pandas>=2.2.0",
+    "xarray>=2025.1.0",
+]
+
+[build-system]
+requires = ["uv-build>=0.9.5,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "codespell>=2.3.0",
+    "numpydoc>=1.11.0",
+    "prek>=0.4.8",
+    "pytest>=9.1.1",
+    "pytest-cov>=6.0.0",
+    "ruff>=0.16.5",
+    "ty>=0.0.77,<0.1.0",
+    "zensical>=0.0.67",
+    "mkdocstrings[python]>=1.0.4",
+]
+
+[tool.numpydoc_validation]
+exclude = [
+    '\.__init__$',
+    '\._.*$',
+]
+checks = [
+    "all",
+    "GL01",
+    "ES01",
+    "SA01",
+    "EX01",
+]
+
+[tool.ruff]
+line-length = 88
+
+[tool.ty.src]
+include = ["src", "tests"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+pythonpath = ["."]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+    "--import-mode=importlib",
+    "--showlocals",
+    "--cov=voxeldata",
+    "--cov-report=term-missing",
+    "--cov-report=html",
+    "--cov-report=xml",
+]
+filterwarnings = ["error"]

voxeldata-0.0.1/src/voxeldata/__init__.py

@@ -0,0 +1,82 @@
+"""VoxelData: spatially referenced voxel arrays built on xarray.
+
+VoxelData defines a small, modality-independent data model for arrays gridded in
+space. A VoxelData array is an `xarray.DataArray` with native voxel dimensions
+`(k, j, i)` (plus any extra leading dimensions) and a single
+[VoxelToWorldIndex][voxeldata.geometry.VoxelToWorldIndex] that lazily derives world
+coordinates `(z, y, x)` from a voxel-to-world affine.
+"""
+
+from voxeldata._dims import CORE_DIMS, GRID_DIM, TIME_DIM, VOXEL_DIMS, WORLD_DIMS
+from voxeldata.accessors import VoxelDataAccessor
+from voxeldata.affine import (
+    apply_affine,
+    get_bounding_box,
+    get_relative_affine,
+    reindex_voxels,
+    reindex_voxels_like,
+)
+from voxeldata.create import create_voxeldata
+from voxeldata.geometry import (
+    VoxelToWorldIndex,
+    VoxelToWorldTransform,
+    attach_voxel_to_world_index,
+    convert_length_units,
+    get_affine_axis_scalings,
+    get_affine_direction_matrix,
+    get_voxel_to_world_affine,
+    get_voxel_to_world_direction_matrix,
+    get_voxel_to_world_index,
+    get_voxel_to_world_index_origin,
+    get_voxel_to_world_index_spacing,
+    get_voxel_to_world_spatial_dims,
+    get_voxel_to_world_units,
+    has_axis_aligned_voxel_to_world_index,
+    has_voxel_to_world_index,
+    require_scalar_grid_affine,
+    restore_voxel_to_world_index,
+)
+from voxeldata.validation import (
+    canonicalize_voxeldata,
+    ensure_voxeldata,
+    require_dataarray,
+    require_positive_finite,
+    validate_voxeldata,
+)
+
+__all__ = [
+    "CORE_DIMS",
+    "GRID_DIM",
+    "TIME_DIM",
+    "VOXEL_DIMS",
+    "WORLD_DIMS",
+    "VoxelDataAccessor",
+    "VoxelToWorldIndex",
+    "VoxelToWorldTransform",
+    "apply_affine",
+    "attach_voxel_to_world_index",
+    "canonicalize_voxeldata",
+    "convert_length_units",
+    "create_voxeldata",
+    "ensure_voxeldata",
+    "get_affine_axis_scalings",
+    "get_affine_direction_matrix",
+    "get_bounding_box",
+    "get_relative_affine",
+    "get_voxel_to_world_affine",
+    "get_voxel_to_world_direction_matrix",
+    "get_voxel_to_world_index",
+    "get_voxel_to_world_index_origin",
+    "get_voxel_to_world_index_spacing",
+    "get_voxel_to_world_spatial_dims",
+    "get_voxel_to_world_units",
+    "has_axis_aligned_voxel_to_world_index",
+    "has_voxel_to_world_index",
+    "reindex_voxels",
+    "reindex_voxels_like",
+    "require_dataarray",
+    "require_positive_finite",
+    "require_scalar_grid_affine",
+    "restore_voxel_to_world_index",
+    "validate_voxeldata",
+]