mlarray 0.0.9__tar.gz

mlarray-0.0.9/.github/workflows/workflow.yml

@@ -0,0 +1,67 @@
+name: CI
+
+permissions:
+  contents: read
+  id-token: write
+
+on:
+  push:
+    branches: ["main"]
+    tags:
+      - "v*"
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+
+      - name: Run tests
+        run: |
+          pytest || if [ $? -eq 5 ]; then echo "No tests collected; skipping."; exit 0; else exit $?; fi
+
+  publish:
+    needs: tests
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine setuptools_scm
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check metadata
+        run: python -m twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

mlarray-0.0.9/.gitignore

@@ -0,0 +1,40 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+env/
+venv/
+.env
+.python-version
+
+# Distribution / packaging
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+wheelhouse/
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+.pytest_cache/
+.coverage*
+coverage.xml
+htmlcov/
+
+# Editors
+.DS_Store
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Blosc2 files
+*.b2nd
+*.mla

mlarray-0.0.9/API.md

@@ -0,0 +1,78 @@
+# MLArray Public API
+
+This document lists the public API surface of `MLArray`.
+
+## Class: `MLArray`
+
+### Constructor
+
+```python
+MLArray(
+    array: Union[np.ndarray, str, Path],
+    spacing: Optional[Union[List, Tuple, np.ndarray]] = None,
+    origin: Optional[Union[List, Tuple, np.ndarray]] = None,
+    direction: Optional[Union[List, Tuple, np.ndarray]] = None,
+    meta: Optional[Union[Dict, Meta]] = None,
+    mmap: bool = False,
+    num_threads: int = 1,
+    mode: str = "r",
+    copy: Optional["MLArray"] = None,
+)
+```
+
+| argument | type | description |
+| --- | --- | --- |
+| array | Union[np.ndarray, str, Path] | Input data or file path. Use a numpy ndarray for in-memory arrays. Use a string or Path to load a ".b2nd" or ".mla" file. |
+| spacing | Optional[Union[List, Tuple, np.ndarray]] | Spacing per axis. Provide a list/tuple/ndarray with length equal to the number of dimensions (e.g., [sx, sy, sz]). |
+| origin | Optional[Union[List, Tuple, np.ndarray]] | Origin per axis. Provide a list/tuple/ndarray with length equal to the number of dimensions. |
+| direction | Optional[Union[List, Tuple, np.ndarray]] | Direction cosine matrix. Provide a 2D list/tuple/ndarray with shape (ndims, ndims). |
+| meta | Optional[Union[Dict, Meta]] | Free-form metadata dictionary or Meta instance. Must be JSON-serializable when saving. If meta is passed as a Dict, it will internally be converted into a Meta object with the dict being interpreted as meta.image metadata. |
+| mmap | bool | Whether to keep the loaded array memory-mapped when loading from disk. If true, MLArray.array will be an blosc2.ndarray.NDArray, else np.ndarray. |
+| num_threads | int | Number of threads for Blosc2 operations. |
+| mode | str | Blosc2 open mode: 'r' read-only (default), 'a' read/write create if doesn't exist (not supported), 'w' create overwrite if exists (not supported). |
+| copy | Optional[MLArray] | Another MLArray instance to copy metadata fields from. |
+
+### Properties
+
+| name | type | description |
+| --- | --- | --- |
+| spacing | Optional[List[float]] | Image spacing per axis. |
+| origin | Optional[List[float]] | Image origin per axis. |
+| direction | Optional[List[List[float]]] | Direction cosine matrix. |
+| affine | List[List[float]] | Affine transform matrix. |
+| translation | List[float] | Translation vector from the affine. |
+| scale | List[float] | Scale factors from the affine. |
+| rotation | List[List[float]] | Rotation matrix from the affine. |
+| shear | List[List[float]] | Shear matrix from the affine. |
+| shape | Tuple[int, ...] | Shape of the underlying array. |
+| ndims | int | Number of array dimensions. |
+
+### Methods
+
+| name | signature | description |
+| --- | --- | --- |
+| save | `save(filepath, patch_size="default", chunk_size=None, block_size=None, clevel=8, codec=blosc2.Codec.ZSTD, num_threads=1)` | Save to `.b2nd` or `.mla`. |
+| comp_blosc2_params | `comp_blosc2_params(image_size, patch_size, bytes_per_pixel=4, l1_cache_size_per_core_in_bytes=32768, l3_cache_size_per_core_in_bytes=1441792, safety_factor=0.8)` | Compute recommended chunk/block sizes. |
+
+#### save arguments
+
+| argument | type | description |
+| --- | --- | --- |
+| filepath | Union[str, Path] | Path to save the file. Must end with ".b2nd" or ".mla". |
+| patch_size | Optional[Union[int, List, Tuple]] | Patch size hint for chunk/block optimization. Provide an int for isotropic sizes or a list/tuple with length equal to the number of dimensions. Use "default" to use the default patch size of 192. |
+| chunk_size | Optional[Union[int, List, Tuple]] | Explicit chunk size. Provide an int or a tuple/list with length equal to the number of dimensions, or None to let Blosc2 decide. Ignored when patch_size is not None. |
+| block_size | Optional[Union[int, List, Tuple]] | Explicit block size. Provide an int or a tuple/list with length equal to the number of dimensions, or None to let Blosc2 decide. Ignored when patch_size is not None. |
+| clevel | int | Compression level from 0 (no compression) to 9 (maximum compression). |
+| codec | blosc2.Codec | Compression codec to use. |
+| num_threads | int | Number of threads to use for saving the file. |
+
+#### comp_blosc2_params arguments
+
+| argument | type | description |
+| --- | --- | --- |
+| image_size | Tuple[int, int, int, int] | Image shape. Use a 2D, 3D, or 4D size; 2D/3D inputs are internally expanded. |
+| patch_size | Union[Tuple[int, int], Tuple[int, int, int]] | Patch size for spatial dimensions. Use a 2-tuple (x, y) or 3-tuple (x, y, z). |
+| bytes_per_pixel | int | Number of bytes per element. Defaults to 4 for float32. |
+| l1_cache_size_per_core_in_bytes | int | L1 cache per core in bytes. |
+| l3_cache_size_per_core_in_bytes | int | L3 cache per core in bytes. |
+| safety_factor | float | Safety factor to avoid filling caches. |

mlarray-0.0.9/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karol Gotkowski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mlarray-0.0.9/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include assets *

mlarray-0.0.9/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.4
+Name: mlarray
+Version: 0.0.9
+Summary: A standardized blosc2 image reader and writer for medical images.
+Author-email: Karol Gotkowski <karol.gotkowski@dkfz.de>
+License: MIT
+Project-URL: Homepage, https://github.com/Karol-G/mlarray
+Project-URL: Source, https://github.com/Karol-G/mlarray
+Project-URL: Issues, https://github.com/Karol-G/mlarray/issues
+Keywords: copier,template,python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: blosc2>=3
+Requires-Dist: numpy>=2
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Requires-Dist: setuptools_scm[toml]>=8.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: medvol; extra == "all"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Karol-G/mlarray/main/assets/banner.png" alt="{ML Array} banner" width="700" />
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/mlarray/"><img src="https://img.shields.io/pypi/v/mlarray?logo=pypi&color=brightgreen&cacheSeconds=300&v=2026-01-22" alt="PyPI" align="middle" /></a>
+  <a href="https://pypi.org/project/mlarray/"><img src="https://img.shields.io/pypi/pyversions/mlarray?logo=python&cacheSeconds=300&v=2026-01-22" alt="Python Version" align="middle" /></a>
+  <a href="https://github.com/Karol-G/mlarray/actions"><img src="https://img.shields.io/github/actions/workflow/status/Karol-G/mlarray/workflow.yml?branch=main&logo=github" alt="Tests" align="middle" /></a>
+  <a href="https://github.com/copier-org/copier"><img src="https://img.shields.io/badge/template-copier-2ebd59?logo=jinja" alt="Copier Template" align="middle" /></a>
+  <a href="https://github.com/Karol-G/mlarray/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Karol-G/mlarray" alt="License" align="middle" /></a>
+</p>
+
+**tl;dr:** Using large, medical or scientific images for Machine Learning? => Use MLArray
+
+A standardized Blosc2 image reader and writer for medical images. The MLArray
+file format (".mla") is a Blosc2-compressed container with standardized
+metadata support for N-dimensional medical images. Plain ".b2nd" files are also
+supported, but they do not participate in the MLArray metadata standard.
+
+## Installation
+
+You can install mlarray via [pip](https://pypi.org/project/mlarray/):
+```bash
+pip install mlarray
+```
+
+To enable the `mlarray_convert` CLI command, install MLArray with the necessary extra dependencies:
+```bash
+pip install mlarray[all]
+```
+
+## API
+
+See [API.md](API.md) for the full MLArray api, including argument
+descriptions and types.
+
+## Metadata schema
+
+See [SCHEMA.md](SCHEMA.md) for the full MLArray metadata schema, including field
+descriptions and types.
+
+## Usage
+
+Below are common usage patterns for loading, saving, and working with metadata.
+
+### Default usage
+
+```python
+import numpy as np
+from mlarray import MLArray
+
+array = np.random.random((128, 256, 256))
+image = MLArray(array)  # Create MLArray image
+image.save("sample.mla")
+
+image = MLArray("sample.mla")  # Loads image
+```
+
+### Memory-mapped usage
+
+```python
+from mlarray import MLArray
+import numpy as np
+
+# read-only, partial access (default)
+image = MLArray().open("sample.mla", mmap='r')  
+crop = image[10:20, 50:60]  # Read crop
+
+# read/write, partial access
+image = MLArray().open("sample.mla", mmap='r+')  
+image[10:20, 50:60] *= 5  # Modify crop in memory and disk
+
+# read/write, partial access, create/overwrite
+array = np.random.random((128, 256, 256))
+image = MLArray().open("sample.mla", shape=array.shape, dtype=array.dtype, mmap='w+')  
+image[...] = array  # Modify image in memory and disk
+```
+
+### Metadata inspection and manipulation
+
+```python
+import numpy as np
+from mlarray import MLArray
+
+array = np.random.random((64, 128, 128))
+image = MLArray(
+    array,
+    spacing=(1.0, 1.0, 1.5),
+    origin=(10.0, 10.0, 30.0),
+    direction=[[1, 0, 0], [0, 1, 0], [0, 0, 1]],
+    meta={"patient_id": "123", "modality": "CT"},  # Any image metadata (for example raw DICOM metadata)
+)
+
+print(image.spacing)  # [1.0, 1.0, 1.5]
+print(image.origin)  # [10.0, 10.0, 30.0]
+print(image.meta.image)  # {"patient_id": "123", "modality": "CT"}
+
+image.spacing[1] = 5.3
+image.meta.image["study_id"] = "study-001"
+image.save("with-metadata.mla")
+
+# Open memory-mapped
+image = MLArray().open("with-metadata.mla", mmap='r+')  
+image.meta.image["study_id"] = "new-study"  # Modify metadata
+image.close()  # Close and save metadata, only necessary to save modified metadata
+```
+
+### Copy metadata with overrides
+
+```python
+import numpy as np
+from mlarray import MLArray
+
+base = MLArray("sample.mla")
+array = np.random.random(base.shape)
+
+image = MLArray(
+    array,
+    spacing=(0.8, 0.8, 1.0),
+    copy=base,  # Copies all non-explicitly set arguments from base
+)
+
+image.save("copied-metadata.mla")
+```
+
+### Standardized metadata usage
+
+```python
+import numpy as np
+from mlarray import MLArray, Meta
+
+array = np.random.random((64, 128, 128))
+image = MLArray(
+    array,
+    meta=Meta(image={"patient_id": "123", "modality": "CT"}, is_seg=True),  # Add metadata in a pre-defined format
+)
+
+print(image.meta.image)  # {"patient_id": "123", "modality": "CT"}
+print(image.meta.is_seg)  # True
+
+image.meta.image["study_id"] = "study-001"
+image.meta.is_seg = False
+image.save("with-metadata.mla")
+```
+
+### Patch size variants
+
+Default patch size (192):
+```python
+from mlarray import MLArray
+
+image = MLArray("sample.mla")
+image.save("default-patch.mla")  # Default patch_size is 'default' -> Isotropic patch size of 192 pixels
+image.save("default-patch.mla", patch_size='default')
+```
+
+Custom isotropic patch size (512):
+```python
+from mlarray import MLArray
+
+image = MLArray("sample.mla")
+image.save("patch-512.mla", patch_size=512)
+```
+
+Custom non-isotropic patch size:
+```python
+from mlarray import MLArray
+
+image = MLArray("sample.mla")
+image.save("patch-non-iso.mla", patch_size=(128, 192, 256))
+```
+
+Manual chunk/block size:
+```python
+from mlarray import MLArray
+
+image = MLArray("sample.mla")
+image.save("manual-chunk-block.mla", chunk_size=(1, 128, 128), block_size=(1, 32, 32))
+```
+
+Let Blosc2 itself configure chunk/block size:
+```python
+from mlarray import MLArray
+
+image = MLArray("sample.mla")
+# If patch_size, chunk_size and block_size are all None, Blosc2 will auto-configure chunk and block size
+image.save("manual-chunk-block.mla", patch_size=None)
+```
+
+## CLI
+
+### mlarray_header
+
+Print the metadata header from a `.mla` or `.b2nd` file.
+
+```bash
+mlarray_header sample.mla
+```
+
+### mlarray_convert
+
+Convert a NIfTI or NRRD file to MLArray and copy metadata.
+
+```bash
+mlarray_convert sample.nii.gz output.mla
+```
+
+## Contributing
+
+Contributions are welcome! Please open a pull request with clear changes and add tests when appropriate.
+
+## Issues
+
+Found a bug or have a request? Open an issue at https://github.com/Karol-G/mlarray/issues.
+
+## License
+
+Distributed under the MIT license. See `LICENSE` for details.

mlarray-0.0.9/README.md

@@ -0,0 +1,218 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Karol-G/mlarray/main/assets/banner.png" alt="{ML Array} banner" width="700" />
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/mlarray/"><img src="https://img.shields.io/pypi/v/mlarray?logo=pypi&color=brightgreen&cacheSeconds=300&v=2026-01-22" alt="PyPI" align="middle" /></a>
+  <a href="https://pypi.org/project/mlarray/"><img src="https://img.shields.io/pypi/pyversions/mlarray?logo=python&cacheSeconds=300&v=2026-01-22" alt="Python Version" align="middle" /></a>
+  <a href="https://github.com/Karol-G/mlarray/actions"><img src="https://img.shields.io/github/actions/workflow/status/Karol-G/mlarray/workflow.yml?branch=main&logo=github" alt="Tests" align="middle" /></a>
+  <a href="https://github.com/copier-org/copier"><img src="https://img.shields.io/badge/template-copier-2ebd59?logo=jinja" alt="Copier Template" align="middle" /></a>
+  <a href="https://github.com/Karol-G/mlarray/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Karol-G/mlarray" alt="License" align="middle" /></a>
+</p>
+
+**tl;dr:** Using large, medical or scientific images for Machine Learning? => Use MLArray
+
+A standardized Blosc2 image reader and writer for medical images. The MLArray
+file format (".mla") is a Blosc2-compressed container with standardized
+metadata support for N-dimensional medical images. Plain ".b2nd" files are also
+supported, but they do not participate in the MLArray metadata standard.
+
+## Installation
+
+You can install mlarray via [pip](https://pypi.org/project/mlarray/):
+```bash
+pip install mlarray
+```
+
+To enable the `mlarray_convert` CLI command, install MLArray with the necessary extra dependencies:
+```bash
+pip install mlarray[all]
+```
+
+## API
+
+See [API.md](API.md) for the full MLArray api, including argument
+descriptions and types.
+
+## Metadata schema
+
+See [SCHEMA.md](SCHEMA.md) for the full MLArray metadata schema, including field
+descriptions and types.
+
+## Usage
+
+Below are common usage patterns for loading, saving, and working with metadata.
+
+### Default usage
+
+```python
+import numpy as np
+from mlarray import MLArray
+
+array = np.random.random((128, 256, 256))
+image = MLArray(array)  # Create MLArray image
+image.save("sample.mla")
+
+image = MLArray("sample.mla")  # Loads image
+```
+
+### Memory-mapped usage
+
+```python
+from mlarray import MLArray
+import numpy as np
+
+# read-only, partial access (default)
+image = MLArray().open("sample.mla", mmap='r')  
+crop = image[10:20, 50:60]  # Read crop
+
+# read/write, partial access
+image = MLArray().open("sample.mla", mmap='r+')  
+image[10:20, 50:60] *= 5  # Modify crop in memory and disk
+
+# read/write, partial access, create/overwrite
+array = np.random.random((128, 256, 256))
+image = MLArray().open("sample.mla", shape=array.shape, dtype=array.dtype, mmap='w+')  
+image[...] = array  # Modify image in memory and disk
+```
+
+### Metadata inspection and manipulation
+
+```python
+import numpy as np
+from mlarray import MLArray
+
+array = np.random.random((64, 128, 128))
+image = MLArray(
+    array,
+    spacing=(1.0, 1.0, 1.5),
+    origin=(10.0, 10.0, 30.0),
+    direction=[[1, 0, 0], [0, 1, 0], [0, 0, 1]],
+    meta={"patient_id": "123", "modality": "CT"},  # Any image metadata (for example raw DICOM metadata)
+)
+
+print(image.spacing)  # [1.0, 1.0, 1.5]
+print(image.origin)  # [10.0, 10.0, 30.0]
+print(image.meta.image)  # {"patient_id": "123", "modality": "CT"}
+
+image.spacing[1] = 5.3
+image.meta.image["study_id"] = "study-001"
+image.save("with-metadata.mla")
+
+# Open memory-mapped
+image = MLArray().open("with-metadata.mla", mmap='r+')  
+image.meta.image["study_id"] = "new-study"  # Modify metadata
+image.close()  # Close and save metadata, only necessary to save modified metadata
+```
+
+### Copy metadata with overrides
+
+```python
+import numpy as np
+from mlarray import MLArray
+
+base = MLArray("sample.mla")
+array = np.random.random(base.shape)
+
+image = MLArray(
+    array,
+    spacing=(0.8, 0.8, 1.0),
+    copy=base,  # Copies all non-explicitly set arguments from base
+)
+
+image.save("copied-metadata.mla")
+```
+
+### Standardized metadata usage
+
+```python
+import numpy as np
+from mlarray import MLArray, Meta
+
+array = np.random.random((64, 128, 128))
+image = MLArray(
+    array,
+    meta=Meta(image={"patient_id": "123", "modality": "CT"}, is_seg=True),  # Add metadata in a pre-defined format
+)
+
+print(image.meta.image)  # {"patient_id": "123", "modality": "CT"}
+print(image.meta.is_seg)  # True
+
+image.meta.image["study_id"] = "study-001"
+image.meta.is_seg = False
+image.save("with-metadata.mla")
+```
+
+### Patch size variants
+
+Default patch size (192):
+```python
+from mlarray import MLArray
+
+image = MLArray("sample.mla")
+image.save("default-patch.mla")  # Default patch_size is 'default' -> Isotropic patch size of 192 pixels
+image.save("default-patch.mla", patch_size='default')
+```
+
+Custom isotropic patch size (512):
+```python
+from mlarray import MLArray
+
+image = MLArray("sample.mla")
+image.save("patch-512.mla", patch_size=512)
+```
+
+Custom non-isotropic patch size:
+```python
+from mlarray import MLArray
+
+image = MLArray("sample.mla")
+image.save("patch-non-iso.mla", patch_size=(128, 192, 256))
+```
+
+Manual chunk/block size:
+```python
+from mlarray import MLArray
+
+image = MLArray("sample.mla")
+image.save("manual-chunk-block.mla", chunk_size=(1, 128, 128), block_size=(1, 32, 32))
+```
+
+Let Blosc2 itself configure chunk/block size:
+```python
+from mlarray import MLArray
+
+image = MLArray("sample.mla")
+# If patch_size, chunk_size and block_size are all None, Blosc2 will auto-configure chunk and block size
+image.save("manual-chunk-block.mla", patch_size=None)
+```
+
+## CLI
+
+### mlarray_header
+
+Print the metadata header from a `.mla` or `.b2nd` file.
+
+```bash
+mlarray_header sample.mla
+```
+
+### mlarray_convert
+
+Convert a NIfTI or NRRD file to MLArray and copy metadata.
+
+```bash
+mlarray_convert sample.nii.gz output.mla
+```
+
+## Contributing
+
+Contributions are welcome! Please open a pull request with clear changes and add tests when appropriate.
+
+## Issues
+
+Found a bug or have a request? Open an issue at https://github.com/Karol-G/mlarray/issues.
+
+## License
+
+Distributed under the MIT license. See `LICENSE` for details.