mlarray 0.0.26__tar.gz → 0.0.28__tar.gz

{mlarray-0.0.26 → mlarray-0.0.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mlarray
-Version: 0.0.26
+Version: 0.0.28
 Summary: Array format specialized for Machine Learning with Blosc2 backend and standardized metadata.
 Author-email: Karol Gotkowski <karol.gotkowski@dkfz.de>
 License: MIT
@@ -88,16 +88,16 @@ from mlarray import MLArray
 import numpy as np
 
 # read-only, partial access (default)
-image = MLArray().open("sample.mla", mmap='r')  
+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 = 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 = MLArray.open("sample.mla", shape=array.shape, dtype=array.dtype, mmap='w+')  
 image[...] = array  # Modify image in memory and disk
 ```
 
@@ -113,20 +113,20 @@ image = MLArray(
     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)
+    meta={"patient_id": "123", "modality": "CT"},  # Any metadata from the original image source (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"}
+print(image.meta.original)  # {"patient_id": "123", "modality": "CT"}
 
 image.spacing[1] = 5.3
-image.meta.image["study_id"] = "study-001"
+image.meta.original["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 = MLArray.open("with-metadata.mla", mmap='r+')  
+image.meta.original["study_id"] = "new-study"  # Modify metadata
 image.close()  # Close and save metadata, only necessary to save modified metadata
 ```
 
@@ -157,13 +157,13 @@ 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
+    meta=Meta(original={"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.original)  # {"patient_id": "123", "modality": "CT"}
 print(image.meta.is_seg)  # True
 
-image.meta.image["study_id"] = "study-001"
+image.meta.original["study_id"] = "study-001"
 image.meta.is_seg = False
 image.save("with-metadata.mla")
 ```

{mlarray-0.0.26 → mlarray-0.0.28}/README.md

@@ -54,16 +54,16 @@ from mlarray import MLArray
 import numpy as np
 
 # read-only, partial access (default)
-image = MLArray().open("sample.mla", mmap='r')  
+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 = 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 = MLArray.open("sample.mla", shape=array.shape, dtype=array.dtype, mmap='w+')  
 image[...] = array  # Modify image in memory and disk
 ```
 
@@ -79,20 +79,20 @@ image = MLArray(
     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)
+    meta={"patient_id": "123", "modality": "CT"},  # Any metadata from the original image source (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"}
+print(image.meta.original)  # {"patient_id": "123", "modality": "CT"}
 
 image.spacing[1] = 5.3
-image.meta.image["study_id"] = "study-001"
+image.meta.original["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 = MLArray.open("with-metadata.mla", mmap='r+')  
+image.meta.original["study_id"] = "new-study"  # Modify metadata
 image.close()  # Close and save metadata, only necessary to save modified metadata
 ```
 
@@ -123,13 +123,13 @@ 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
+    meta=Meta(original={"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.original)  # {"patient_id": "123", "modality": "CT"}
 print(image.meta.is_seg)  # True
 
-image.meta.image["study_id"] = "study-001"
+image.meta.original["study_id"] = "study-001"
 image.meta.is_seg = False
 image.save("with-metadata.mla")
 ```

{mlarray-0.0.26 → mlarray-0.0.28}/docs/api.md

@@ -8,10 +8,22 @@
 
 ::: mlarray.meta.Meta
 
-::: mlarray.meta.MetaBlosc2
+::: mlarray.meta.MetaOriginal
+
+::: mlarray.meta.MetaExtra
 
 ::: mlarray.meta.MetaSpatial
 
 ::: mlarray.meta.MetaStatistics
 
 ::: mlarray.meta.MetaBbox
+
+::: mlarray.meta.MetaIsSeg
+
+::: mlarray.meta.MetaBlosc2
+
+::: mlarray.meta.MetaHasArray
+
+::: mlarray.meta.MetaImageFormat
+
+::: mlarray.meta.MetaVersion

{mlarray-0.0.26 → mlarray-0.0.28}/docs/optimization.md

@@ -96,7 +96,7 @@ For large files, you typically want **mmap reads** so random patches don’t req
 from mlarray import MLArray
 
 # read-only mmap: fast random access without loading the full volume
-image = MLArray().open("patch-non-iso.mla", mmap='r')
+image = MLArray.open("patch-non-iso.mla", mmap='r')
 
 patch = image[10:20, 50:60]  # Read a crop/patch (partial read)
 ```
@@ -119,7 +119,7 @@ You can modify regions in-place with `mmap='r+'`. This is useful for workflows l
 ```python
 from mlarray import MLArray
 
-image = MLArray().open("patch-non-iso.mla", mmap='r+')
+image = MLArray.open("patch-non-iso.mla", mmap='r+')
 image[10:20, 50:60] *= 5  # Modify crop in memory and on disk
 image.close()
 ```
@@ -137,7 +137,7 @@ from mlarray import MLArray
 shape = (128, 256, 256)
 dtype = np.float32
 
-image = MLArray().open(
+image = MLArray.open(
     "streamed-write.mla",
     shape=shape,
     dtype=dtype,

{mlarray-0.0.26 → mlarray-0.0.28}/docs/schema.md

@@ -19,15 +19,15 @@ Top-level metadata container.
 
 ### Overview
 
-`Meta` is the root object that groups all metadata into well-defined namespaces. Some namespaces are **standardized** (e.g., `spatial`, `stats`), while others are intentionally **free-form** (`image`, `extra`) to support arbitrary metadata and long-term extensibility.
+`Meta` is the root object that groups all metadata into well-defined namespaces. Some namespaces are **standardized** (e.g., `spatial`, `stats`), while others are intentionally **free-form** (`original`, `extra`) to support arbitrary metadata and long-term extensibility.
 
 ---
 
-### image
+### original
 
-* **Description:** Arbitrary JSON-serializable dictionary for image-level metadata.
-  Stores information from medical image sources such as DICOM, NIfTI, NRRD,
-  or other medical imaging formats.
+* **Description:** Arbitrary JSON-serializable dictionary for metadata from the original image source.
+  Stores information from image sources such as DICOM, NIfTI, NRRD,
+  or other imaging formats.
 * **Dataclass:** None (plain dict).
 
 ---

{mlarray-0.0.26 → mlarray-0.0.28}/docs/usage.md

@@ -34,16 +34,16 @@ from mlarray import MLArray
 import numpy as np
 
 # read-only, partial access (default)
-image = MLArray().open("sample.mla", mmap='r')  
+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 = 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 = MLArray.open("sample.mla", shape=array.shape, dtype=array.dtype, mmap='w+')  
 image[...] = array  # Modify image in memory and disk
 ```
 
@@ -51,7 +51,7 @@ image[...] = array  # Modify image in memory and disk
 
 ## Metadata inspection and manipulation
 
-MLArray provides first-class support for common image metadata (spacing, origin, direction), and also lets you attach arbitrary metadata via `meta=...` (e.g., raw DICOM fields, acquisition parameters, dataset identifiers).
+MLArray provides first-class support for common image metadata (spacing, origin, direction), and also lets you attach arbitrary metadata from the original image source via `meta=...` (e.g., raw DICOM fields, acquisition parameters, dataset identifiers).
 
 ```python
 import numpy as np
@@ -63,20 +63,20 @@ image = MLArray(
     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)
+    meta={"patient_id": "123", "modality": "CT"},  # Any metadata from the original image source (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"}
+print(image.meta.original)  # {"patient_id": "123", "modality": "CT"}
 
 image.spacing[1] = 5.3
-image.meta.image["study_id"] = "study-001"
+image.meta.original["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 = MLArray.open("with-metadata.mla", mmap='r+')  
+image.meta.original["study_id"] = "new-study"  # Modify metadata
 image.close()  # Close and save metadata, only necessary to save modified metadata
 ```
 
@@ -115,13 +115,13 @@ 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
+    meta=Meta(original={"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.original)  # {"patient_id": "123", "modality": "CT"}
 print(image.meta.is_seg)  # True
 
-image.meta.image["study_id"] = "study-001"
+image.meta.original["study_id"] = "study-001"
 image.meta.is_seg = False
 image.save("with-metadata.mla")
 ```

{mlarray-0.0.26 → mlarray-0.0.28}/examples/example_channel.py

@@ -20,13 +20,13 @@ if __name__ == '__main__':
         os.remove(filepath)
 
     print("Initializing image...")
-    image = MLArray(array, spacing=spacing, origin=origin, direction=direction, channel_axis=channel_axis, meta=Meta(image=image_meta, bbox=bboxes))
+    image = MLArray(array, spacing=spacing, origin=origin, direction=direction, channel_axis=channel_axis, meta=Meta(original=image_meta, bbox=bboxes))
     print("Saving image...")
     image.save(filepath)
 
     print("Loading image...")
     image = MLArray(filepath)
-    print(json.dumps(image.meta.to_dict(), indent=2, sort_keys=True))
+    print(json.dumps(image.meta.to_mapping(), indent=2, sort_keys=True))
     print("Image mean value: ", np.mean(image.to_numpy()))
     print("Some array data: \n", image[:2, :2, 0])
 

{mlarray-0.0.26 → mlarray-0.0.28}/examples/example_metadata_only.py

@@ -19,13 +19,13 @@ if __name__ == '__main__':
         os.remove(filepath)
 
     print("Initializing image...")
-    image = MLArray(spacing=spacing, origin=origin, direction=direction, meta=Meta(image=image_meta, bbox=bboxes))
+    image = MLArray(spacing=spacing, origin=origin, direction=direction, meta=Meta(original=image_meta, bbox=bboxes))
     print("Saving image...")
     image.save(filepath)
 
     print("Loading image...")
     image = MLArray(filepath)
-    print(json.dumps(image.meta.to_dict(), indent=2, sort_keys=True))
+    print(json.dumps(image.meta.to_mapping(), indent=2, sort_keys=True))
 
     if Path(filepath).is_file():
         os.remove(filepath)

{mlarray-0.0.26 → mlarray-0.0.28}/examples/example_open.py

@@ -1,7 +1,7 @@
 import numpy as np
 import os
 from pathlib import Path
-from mlarray import MLArray, Meta
+from mlarray import MLArray, Meta, MetaSpatial
 import json
 
 
@@ -19,17 +19,16 @@ if __name__ == '__main__':
         os.remove(filepath)
 
     print("Initializing image...")
-    image = MLArray(spacing=spacing, origin=origin, direction=direction, meta=Meta(image=image_meta, bbox=bboxes))
-    image.open(filepath, shape=array.shape, dtype=array.dtype, mmap='w+')
+    image = MLArray.open(filepath, shape=array.shape, dtype=array.dtype, mmap='w+')
     print("Saving image...")
     image[...] = array
+    image.meta.copy_from(Meta(original=image_meta, spatial=MetaSpatial(spacing=spacing, origin=origin, direction=direction), bbox=bboxes))
     image.meta.is_seg = True
     image.close()
 
     print("Loading image...")
-    image = MLArray()
-    image.open(filepath)
-    print(json.dumps(image.meta.to_dict(), indent=2, sort_keys=True))
+    image = MLArray.open(filepath)
+    print(json.dumps(image.meta.to_mapping(), indent=2, sort_keys=True))
     print("Image mean value: ", np.mean(image.to_numpy()))
     print("Some array data: \n", image[:2, :2, 0])
 

{mlarray-0.0.26 → mlarray-0.0.28}/examples/example_save_load.py

@@ -2,6 +2,7 @@ import numpy as np
 import os
 from pathlib import Path
 from mlarray import MLArray, Meta
+from mlarray.meta import MetaOriginal, MetaIsSeg
 import json
 
 
@@ -19,13 +20,14 @@ if __name__ == '__main__':
         os.remove(filepath)
 
     print("Initializing image...")
-    image = MLArray(array, spacing=spacing, origin=origin, direction=direction, meta=Meta(image=image_meta, bbox=bboxes))
+    image = MLArray(array, spacing=spacing, origin=origin, direction=direction, meta=Meta(original=image_meta, bbox=bboxes, is_seg=True))
     print("Saving image...")
     image.save(filepath)
 
     print("Loading image...")
     image = MLArray(filepath)
-    print(json.dumps(image.meta.to_dict(), indent=2, sort_keys=True))
+    image = MLArray.load(filepath)  # Just testing both load methods
+    print(json.dumps(image.meta.to_mapping(), indent=2, sort_keys=True))
     print("Image mean value: ", np.mean(image.to_numpy()))
     print("Some array data: \n", image[:2, :2, 0])
 

mlarray-0.0.28/mlarray/__init__.py

@@ -0,0 +1,79 @@
+"""A standardized blosc2 image reader and writer for medical images."""
+
+from importlib import metadata as _metadata
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mlarray.mlarray import MLArray, MLARRAY_DEFAULT_PATCH_SIZE
+    from mlarray.meta import (
+        Meta,
+        MetaBbox,
+        MetaBlosc2,
+        MetaExtra,
+        MetaHasArray,
+        MetaOriginal,
+        MetaImageFormat,
+        MetaIsSeg,
+        MetaSpatial,
+        MetaStatistics,
+        MetaVersion,
+    )
+    from mlarray.utils import is_serializable
+    from mlarray.cli import cli_print_header, cli_convert_to_mlarray
+
+__all__ = [
+    "__version__",
+    "MLArray",
+    "MLARRAY_DEFAULT_PATCH_SIZE",
+    "Meta",
+    "MetaBbox",
+    "MetaBlosc2",
+    "MetaExtra",
+    "MetaHasArray",
+    "MetaOriginal",
+    "MetaImageFormat",
+    "MetaIsSeg",
+    "MetaSpatial",
+    "MetaStatistics",
+    "MetaVersion",
+    "is_serializable",
+    "cli_print_header",
+    "cli_convert_to_mlarray",
+]
+
+try:
+    __version__ = _metadata.version(__name__)
+except _metadata.PackageNotFoundError:  # pragma: no cover - during editable installs pre-build
+    __version__ = "0.0.0"
+
+
+_LAZY_ATTRS = {
+    "MLArray": ("mlarray.mlarray", "MLArray"),
+    "MLARRAY_DEFAULT_PATCH_SIZE": ("mlarray.mlarray", "MLARRAY_DEFAULT_PATCH_SIZE"),
+    "Meta": ("mlarray.meta", "Meta"),
+    "MetaBbox": ("mlarray.meta", "MetaBbox"),
+    "MetaBlosc2": ("mlarray.meta", "MetaBlosc2"),
+    "MetaExtra": ("mlarray.meta", "MetaExtra"),
+    "MetaHasArray": ("mlarray.meta", "MetaHasArray"),
+    "MetaOriginal": ("mlarray.meta", "MetaOriginal"),
+    "MetaImageFormat": ("mlarray.meta", "MetaImageFormat"),
+    "MetaIsSeg": ("mlarray.meta", "MetaIsSeg"),
+    "MetaSpatial": ("mlarray.meta", "MetaSpatial"),
+    "MetaStatistics": ("mlarray.meta", "MetaStatistics"),
+    "MetaVersion": ("mlarray.meta", "MetaVersion"),
+    "is_serializable": ("mlarray.utils", "is_serializable"),
+    "cli_print_header": ("mlarray.cli", "cli_print_header"),
+    "cli_convert_to_mlarray": ("mlarray.cli", "cli_convert_to_mlarray"),
+}
+
+
+def __getattr__(name: str):
+    if name in _LAZY_ATTRS:
+        module_name, attr_name = _LAZY_ATTRS[name]
+        module = __import__(module_name, fromlist=[attr_name])
+        return getattr(module, attr_name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(__all__)

{mlarray-0.0.26 → mlarray-0.0.28}/mlarray/cli.py

@@ -20,7 +20,7 @@ def print_header(filepath: Union[str, Path]) -> None:
     if meta is None:
         print("null")
         return
-    print(json.dumps(meta.to_dict(include_none=True), indent=2, sort_keys=True))
+    print(json.dumps(meta.to_plain(include_none=True), indent=2, sort_keys=True))
 
 
 def convert_to_mlarray(load_filepath: Union[str, Path], save_filepath: Union[str, Path]):