mlarray 0.0.47__tar.gz → 0.0.49__tar.gz

{mlarray-0.0.47 → mlarray-0.0.49}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mlarray
-Version: 0.0.47
+Version: 0.0.49
 Summary: Array format specialized for Machine Learning with Blosc2 backend and standardized metadata.
 Author-email: Karol Gotkowski <karol.gotkowski@dkfz.de>
 License: MIT

mlarray-0.0.49/examples/example_compressed_vs_uncompressed.py

@@ -0,0 +1,42 @@
+from pathlib import Path
+
+import numpy as np
+
+from mlarray import MLArray
+
+
+def main():
+    array = np.arange(2 * 4 * 4, dtype=np.float32).reshape(2, 4, 4)
+
+    compressed_img = MLArray.asarray(
+        array,
+        compressed=True,
+        patch_size=None,
+        chunk_size=(1, 4, 4),
+        block_size=(1, 2, 2),
+    )
+    uncompressed_img = MLArray.asarray(array, compressed=False)
+
+    compressed_path = Path("example_compressed_output.mla")
+    uncompressed_path = Path("example_uncompressed_output.mla")
+
+    print("compressed in-memory backend (before save):", type(compressed_img._store))
+    print(
+        "uncompressed in-memory backend (before save):",
+        type(uncompressed_img._store),
+    )
+
+    compressed_img.save(compressed_path)
+    uncompressed_img.save(uncompressed_path)
+
+    print("compressed in-memory backend (after save):", type(compressed_img._store))
+    print(
+        "uncompressed in-memory backend (after save):",
+        type(uncompressed_img._store),
+    )
+    print("saved compressed file:", compressed_path)
+    print("saved uncompressed->compressed file:", uncompressed_path)
+
+
+if __name__ == "__main__":
+    main()

{mlarray-0.0.47 → mlarray-0.0.49}/mlarray/meta.py

@@ -393,6 +393,44 @@ def _cast_to_list(value: Any, label: str):
     return out
 
 
+def _to_jsonable(value: Any) -> Any:
+    """Recursively convert values to JSON-serializable plain Python objects."""
+    if isinstance(value, Enum):
+        return value.value
+
+    if isinstance(value, Mapping):
+        return {str(k): _to_jsonable(v) for k, v in value.items()}
+
+    if isinstance(value, (list, tuple)):
+        return [_to_jsonable(v) for v in value]
+
+    if isinstance(value, np.generic):
+        return value.item()
+
+    return value
+
+
+def _cast_to_jsonable_mapping(value: Any, label: str) -> dict[str, Any]:
+    """Cast a value to a JSON-serializable mapping.
+
+    Accepts mappings directly or objects exposing ``__dict__`` (for example
+    Blosc2 ``CParams`` / ``DParams`` objects).
+    """
+    if isinstance(value, Mapping):
+        out = dict(value)
+    elif hasattr(value, "__dict__"):
+        out = dict(vars(value))
+    else:
+        raise TypeError(f"{label} must be a mapping or object with __dict__")
+
+    out = _to_jsonable(out)
+    if not isinstance(out, dict):
+        raise TypeError(f"{label} could not be converted to a mapping")
+    if not is_serializable(out):
+        raise TypeError(f"{label} is not JSON-serializable")
+    return out
+
+
 def _validate_int(value: Any, label: str) -> None:
     """Validate that value is an int.
 
@@ -565,10 +603,14 @@ class MetaBlosc2(BaseMeta):
         chunk_size: List of per-dimension chunk sizes. Length must match ndims.
         block_size: List of per-dimension block sizes. Length must match ndims.
         patch_size: List of per-dimension patch sizes. Length must match spatial ndims.
+        cparams: Blosc2 compression parameters as a JSON-serializable dict.
+        dparams: Blosc2 decompression parameters as a JSON-serializable dict.
     """
     chunk_size: Optional[list] = None
     block_size: Optional[list] = None
     patch_size: Optional[list] = None
+    cparams: Optional[dict[str, Any]] = None
+    dparams: Optional[dict[str, Any]] = None
 
     def _validate_and_cast(self, *, ndims: Optional[int] = None, spatial_ndims: Optional[int] = None, **_: Any) -> None:
         """Validate and normalize tiling sizes.
@@ -591,6 +633,12 @@ class MetaBlosc2(BaseMeta):
             self.patch_size = _cast_to_list(self.patch_size, "meta.blosc2.patch_size")
             _validate_float_int_list(self.patch_size, "meta.blosc2.patch_size", spatial_ndims)
 
+        if self.cparams is not None:
+            self.cparams = _cast_to_jsonable_mapping(self.cparams, "meta.blosc2.cparams")
+
+        if self.dparams is not None:
+            self.dparams = _cast_to_jsonable_mapping(self.dparams, "meta.blosc2.dparams")
+
 
 class AxisLabelEnum(str, Enum):
     """Axis label/role identifiers used for spatial metadata.
@@ -628,6 +676,7 @@ class MetaSpatial(BaseMeta):
         spacing: Per-dimension spacing values. Length must match ndims.
         origin: Per-dimension origin values. Length must match ndims.
         direction: Direction cosine matrix of shape [ndims, ndims].
+        affine: Homogeneous affine matrix of shape [ndims + 1, ndims + 1].
         shape: Array shape. Length must match (spatial + non-spatial) ndims.
         axis_labels: Per-axis labels or roles. Length must match ndims.
         axis_units: Per-axis units. Length must match ndims.
@@ -638,6 +687,7 @@ class MetaSpatial(BaseMeta):
     spacing: Optional[list[Union[int,float]]] = None
     origin: Optional[list[Union[int,float]]] = None
     direction: Optional[list[list[Union[int,float]]]] = None
+    affine: Optional[list[list[Union[int,float]]]] = None
     shape: Optional[list[int]] = None
     axis_labels: Optional[list[Union[str,AxisLabel]]] = None
     axis_units: Optional[list[str]] = None
@@ -668,6 +718,21 @@ class MetaSpatial(BaseMeta):
             self.direction = _cast_to_list(self.direction, "meta.spatial.direction")
             _validate_float_int_matrix(self.direction, "meta.spatial.direction", spatial_ndims)
 
+        if self.affine is not None:
+            self.affine = _cast_to_list(self.affine, "meta.spatial.affine")
+            if spatial_ndims is not None:
+                _validate_float_int_matrix(
+                    self.affine,
+                    "meta.spatial.affine",
+                    spatial_ndims + 1,
+                )
+            else:
+                _validate_float_int_matrix(self.affine, "meta.spatial.affine")
+                n_rows = len(self.affine)
+                for row in self.affine:
+                    if len(row) != n_rows:
+                        raise ValueError("meta.spatial.affine must be a square matrix")
+
         if self.shape is not None:
             self.shape = _cast_to_list(self.shape, "meta.spatial.shape")
             _validate_float_int_list(self.shape, "meta.spatial.shape", ndims)
@@ -867,7 +932,7 @@ class Meta(BaseMeta):
     Attributes:
         source: Source metadata from the original image source (JSON-serializable dict).
         extra: Additional metadata (JSON-serializable dict).
-        spatial: Spatial metadata (spacing, origin, direction, shape).
+        spatial: Spatial metadata (spacing, origin, direction, affine, shape).
         stats: Summary statistics.
         bbox: Bounding boxes.
         is_seg: Segmentation flag.

{mlarray-0.0.47 → mlarray-0.0.49}/mlarray/mlarray.py

@@ -2,11 +2,13 @@ from copy import deepcopy
 import numpy as np
 import blosc2
 import math
-from typing import Dict, Optional, Union, List, Tuple
+from typing import Any, Dict, Optional, Union, List, Tuple
 from pathlib import Path
 import os
 from mlarray.meta import Meta, MetaBlosc2, AxisLabel, _spatial_axis_mask
 from mlarray.utils import is_serializable
+import pickle
+import gzip
 
 MLARRAY_SUFFIX = "mla"
 MLARRAY_VERSION = "v0"
@@ -20,6 +22,7 @@ class MLArray:
             spacing: Optional[Union[List, Tuple, np.ndarray]] = None,
             origin: Optional[Union[List, Tuple, np.ndarray]] = None,
             direction: Optional[Union[List, Tuple, np.ndarray]] = None,
+            affine: Optional[Union[List, Tuple, np.ndarray]] = None,
             meta: Optional[Union[Dict, Meta]] = None,
             axis_labels: Optional[List[Union[str, AxisLabel]]] = None,
             copy: Optional['MLArray'] = None,
@@ -28,6 +31,7 @@ class MLArray:
             block_size: Optional[Union[int, List, Tuple]] = None,
             cparams: Optional[Union[Dict, blosc2.CParams]] = None,
             dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+            compressed: bool = True,
         ) -> None:
         """Initializes a MLArray instance.
 
@@ -48,6 +52,9 @@ class MLArray:
             direction (Optional[Union[List, Tuple, np.ndarray]]): Direction
                 cosine matrix. Provide a 2D list/tuple/ndarray with shape
                 (ndims, ndims) for spatial dimensions.
+            affine (Optional[Union[List, Tuple, np.ndarray]]): Homogeneous
+                affine matrix. Provide a 2D list/tuple/ndarray with shape
+                (spatial_ndims + 1, spatial_ndims + 1).
             meta (Optional[Dict | Meta]): Free-form metadata dictionary or Meta
                 instance. Must be JSON-serializable when saving. 
                 If meta is passed as a Dict, it is internally converted into a
@@ -75,10 +82,12 @@ class MLArray:
         self.mmap_mode = None
         self.meta = None
         self._store = None
+        self._backend = None
         if isinstance(array, (str, Path)) and (
             spacing is not None
             or origin is not None
             or direction is not None
+            or affine is not None
             or meta is not None
             or axis_labels is not None
             or copy is not None
@@ -89,14 +98,23 @@ class MLArray:
             or dparams is not None
         ):
             raise RuntimeError(
-                "Spacing, origin, direction, meta, axis_labels, copy, patch_size, "
+                "Spacing, origin, direction, affine, meta, axis_labels, copy, patch_size, "
                 "chunk_size, block_size, cparams or dparams cannot be set when "
                 "array is a filepath."
             )
         if isinstance(array, (str, Path)):
-            self._load(array)
+            self._load(array, compressed=compressed)
         else:
-            self._validate_and_add_meta(meta, spacing, origin, direction, axis_labels, False, validate=False)
+            self._validate_and_add_meta(
+                meta,
+                spacing=spacing,
+                origin=origin,
+                direction=direction,
+                affine=affine,
+                axis_labels=axis_labels,
+                has_array=False,
+                validate=False,
+            )
             if array is not None:
                 self._asarray(
                     array,
@@ -106,10 +124,16 @@ class MLArray:
                     block_size=block_size,
                     cparams=cparams,
                     dparams=dparams,
+                    compressed=compressed,
                 )
                 has_array = True
             else:
-                self._store = blosc2.empty((0,))
+                if compressed:
+                    self._store = blosc2.empty((0,))
+                    self._backend = "blosc2"
+                else:
+                    self._store = np.empty((0,))
+                    self._backend = "numpy"
                 has_array = False
             if copy is not None:
                 self.meta.copy_from(copy.meta)
@@ -224,6 +248,7 @@ class MLArray:
             cls,
             filepath: Union[str, Path], 
             dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+            compressed: bool = True,
         ):
         """Loads a MLArray file as a whole. Does not use memory-mapping. Both MLArray ('.mla') and Blosc2 ('.b2nd') files are supported.
 
@@ -243,7 +268,7 @@ class MLArray:
             RuntimeError: If the file extension is not ".b2nd" or ".mla".
         """
         class_instance = cls()
-        class_instance._load(filepath, dparams)
+        class_instance._load(filepath, dparams, compressed=compressed)
         return class_instance
 
     @classmethod
@@ -257,6 +282,7 @@ class MLArray:
             block_size: Optional[Union[int, List, Tuple]] = None,
             cparams: Optional[Union[Dict, blosc2.CParams]] = None,
             dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+            compressed: bool = True,
         ):
         """Create an in-memory MLArray with uninitialized values.
 
@@ -284,6 +310,7 @@ class MLArray:
         """
         class_instance = cls()
         class_instance._construct_in_memory(
+            constructor="empty",
             shape=shape,
             dtype=dtype,
             meta=meta,
@@ -292,7 +319,7 @@ class MLArray:
             block_size=block_size,
             cparams=cparams,
             dparams=dparams,
-            store_builder=lambda **kwargs: blosc2.empty(**kwargs),
+            compressed=compressed,
         )
         return class_instance
 
@@ -307,6 +334,7 @@ class MLArray:
             block_size: Optional[Union[int, List, Tuple]] = None,
             cparams: Optional[Union[Dict, blosc2.CParams]] = None,
             dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+            compressed: bool = True,
         ):
         """Create an in-memory MLArray filled with zeros.
 
@@ -332,6 +360,7 @@ class MLArray:
         """
         class_instance = cls()
         class_instance._construct_in_memory(
+            constructor="zeros",
             shape=shape,
             dtype=dtype,
             meta=meta,
@@ -340,7 +369,7 @@ class MLArray:
             block_size=block_size,
             cparams=cparams,
             dparams=dparams,
-            store_builder=lambda **kwargs: blosc2.zeros(**kwargs),
+            compressed=compressed,
         )
         return class_instance
 
@@ -355,6 +384,7 @@ class MLArray:
             block_size: Optional[Union[int, List, Tuple]] = None,
             cparams: Optional[Union[Dict, blosc2.CParams]] = None,
             dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+            compressed: bool = True,
         ):
         """Create an in-memory MLArray filled with ones.
 
@@ -382,6 +412,7 @@ class MLArray:
         dtype = blosc2.DEFAULT_FLOAT if dtype is None else dtype
         class_instance = cls()
         class_instance._construct_in_memory(
+            constructor="ones",
             shape=shape,
             dtype=dtype,
             meta=meta,
@@ -390,7 +421,7 @@ class MLArray:
             block_size=block_size,
             cparams=cparams,
             dparams=dparams,
-            store_builder=lambda **kwargs: blosc2.ones(**kwargs),
+            compressed=compressed,
         )
         return class_instance
 
@@ -406,6 +437,7 @@ class MLArray:
             block_size: Optional[Union[int, List, Tuple]] = None,
             cparams: Optional[Union[Dict, blosc2.CParams]] = None,
             dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+            compressed: bool = True,
         ):
         """Create an in-memory MLArray filled with ``fill_value``.
 
@@ -439,6 +471,7 @@ class MLArray:
                 dtype = np.dtype(type(fill_value))
         class_instance = cls()
         class_instance._construct_in_memory(
+            constructor="full",
             shape=shape,
             dtype=dtype,
             meta=meta,
@@ -447,7 +480,8 @@ class MLArray:
             block_size=block_size,
             cparams=cparams,
             dparams=dparams,
-            store_builder=lambda **kwargs: blosc2.full(fill_value=fill_value, **kwargs),
+            compressed=compressed,
+            constructor_kwargs={"fill_value": fill_value},
         )
         return class_instance
 
@@ -466,6 +500,7 @@ class MLArray:
             block_size: Optional[Union[int, List, Tuple]] = None,
             cparams: Optional[Union[Dict, blosc2.CParams]] = None,
             dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+            compressed: bool = True,
         ):
         """Create an in-memory MLArray with evenly spaced values.
 
@@ -525,6 +560,7 @@ class MLArray:
 
         class_instance = cls()
         class_instance._construct_in_memory(
+            constructor="arange",
             shape=shape,
             dtype=dtype,
             meta=meta,
@@ -533,13 +569,13 @@ class MLArray:
             block_size=block_size,
             cparams=cparams,
             dparams=dparams,
-            store_builder=lambda **kwargs: blosc2.arange(
-                start=start,
-                stop=stop,
-                step=step,
-                c_order=c_order,
-                **kwargs,
-            ),
+            compressed=compressed,
+            constructor_kwargs={
+                "start": start,
+                "stop": stop,
+                "step": step,
+                "c_order": c_order,
+            },
         )
         return class_instance
 
@@ -559,6 +595,7 @@ class MLArray:
             block_size: Optional[Union[int, List, Tuple]] = None,
             cparams: Optional[Union[Dict, blosc2.CParams]] = None,
             dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+            compressed: bool = True,
         ):
         """Create an in-memory MLArray with evenly spaced samples.
 
@@ -617,6 +654,7 @@ class MLArray:
 
         class_instance = cls()
         class_instance._construct_in_memory(
+            constructor="linspace",
             shape=shape,
             dtype=dtype,
             meta=meta,
@@ -625,14 +663,14 @@ class MLArray:
             block_size=block_size,
             cparams=cparams,
             dparams=dparams,
-            store_builder=lambda **kwargs: blosc2.linspace(
-                start=start,
-                stop=stop,
-                num=num,
-                endpoint=endpoint,
-                c_order=c_order,
-                **kwargs,
-            ),
+            compressed=compressed,
+            constructor_kwargs={
+                "start": start,
+                "stop": stop,
+                "num": num,
+                "endpoint": endpoint,
+                "c_order": c_order,
+            },
         )
         return class_instance
 
@@ -645,7 +683,8 @@ class MLArray:
             chunk_size: Optional[Union[int, List, Tuple]]= None,
             block_size: Optional[Union[int, List, Tuple]] = None,
             cparams: Optional[Union[Dict, blosc2.CParams]] = None,
-            dparams: Optional[Union[Dict, blosc2.DParams]] = None
+            dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+            compressed: bool = True,
         ):
         """Convert a NumPy array into an in-memory Blosc2-backed MLArray.
 
@@ -688,7 +727,16 @@ class MLArray:
                 implemented for the provided dimensionality.
         """
         class_instance = cls()
-        class_instance._asarray(array, meta, patch_size, chunk_size, block_size, cparams, dparams)
+        class_instance._asarray(
+            array,
+            meta,
+            patch_size,
+            chunk_size,
+            block_size,
+            cparams,
+            dparams,
+            compressed=compressed,
+        )
         return class_instance
 
     @classmethod
@@ -702,6 +750,7 @@ class MLArray:
             block_size: Optional[Union[int, List, Tuple]] = None,
             cparams: Optional[Union[Dict, blosc2.CParams]] = None,
             dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+            compressed: bool = True,
         ):
         """Create an in-memory MLArray with the same shape as ``x``.
 
@@ -730,6 +779,7 @@ class MLArray:
         class_instance = cls()
         shape, dtype, meta = class_instance._resolve_like_input(x, dtype, meta)
         class_instance._construct_in_memory(
+            constructor="empty",
             shape=shape,
             dtype=dtype,
             meta=meta,
@@ -738,7 +788,7 @@ class MLArray:
             block_size=block_size,
             cparams=cparams,
             dparams=dparams,
-            store_builder=lambda **kwargs: blosc2.empty(**kwargs),
+            compressed=compressed,
         )
         return class_instance
 
@@ -753,6 +803,7 @@ class MLArray:
             block_size: Optional[Union[int, List, Tuple]] = None,
             cparams: Optional[Union[Dict, blosc2.CParams]] = None,
             dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+            compressed: bool = True,
         ):
         """Create an in-memory MLArray of zeros with the same shape as ``x``.
 
@@ -781,6 +832,7 @@ class MLArray:
         class_instance = cls()
         shape, dtype, meta = class_instance._resolve_like_input(x, dtype, meta)
         class_instance._construct_in_memory(
+            constructor="zeros",
             shape=shape,
             dtype=dtype,
             meta=meta,
@@ -789,7 +841,7 @@ class MLArray:
             block_size=block_size,
             cparams=cparams,
             dparams=dparams,
-            store_builder=lambda **kwargs: blosc2.zeros(**kwargs),
+            compressed=compressed,
         )
         return class_instance
 
@@ -804,6 +856,7 @@ class MLArray:
             block_size: Optional[Union[int, List, Tuple]] = None,
             cparams: Optional[Union[Dict, blosc2.CParams]] = None,
             dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+            compressed: bool = True,
         ):
         """Create an in-memory MLArray of ones with the same shape as ``x``.
 
@@ -832,6 +885,7 @@ class MLArray:
         class_instance = cls()
         shape, dtype, meta = class_instance._resolve_like_input(x, dtype, meta)
         class_instance._construct_in_memory(
+            constructor="ones",
             shape=shape,
             dtype=dtype,
             meta=meta,
@@ -840,7 +894,7 @@ class MLArray:
             block_size=block_size,
             cparams=cparams,
             dparams=dparams,
-            store_builder=lambda **kwargs: blosc2.ones(**kwargs),
+            compressed=compressed,
         )
         return class_instance
 
@@ -856,6 +910,7 @@ class MLArray:
             block_size: Optional[Union[int, List, Tuple]] = None,
             cparams: Optional[Union[Dict, blosc2.CParams]] = None,
             dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+            compressed: bool = True,
         ):
         """Create an in-memory MLArray filled with ``fill_value`` and shape of ``x``.
 
@@ -886,6 +941,7 @@ class MLArray:
         class_instance = cls()
         shape, dtype, meta = class_instance._resolve_like_input(x, dtype, meta)
         class_instance._construct_in_memory(
+            constructor="full",
             shape=shape,
             dtype=dtype,
             meta=meta,
@@ -894,7 +950,8 @@ class MLArray:
             block_size=block_size,
             cparams=cparams,
             dparams=dparams,
-            store_builder=lambda **kwargs: blosc2.full(fill_value=fill_value, **kwargs),
+            compressed=compressed,
+            constructor_kwargs={"fill_value": fill_value},
         )
         return class_instance
 
@@ -923,7 +980,8 @@ class MLArray:
 
         if Path(filepath).is_file():
             os.remove(str(filepath))
-        
+
+        self._ensure_blosc2_store()
         self._write_metadata(force=True)
         self._store.save(str(filepath))
         self._update_blosc2_meta()
@@ -937,6 +995,7 @@ class MLArray:
         """
         self._write_metadata()
         self._store = None
+        self._backend = None
         self.filepath = None
         self.support_metadata = None
         self.mode = None  
@@ -1069,6 +1128,8 @@ class MLArray:
         """
         if self._store is None or self.meta._has_array.has_array == False:
             return None
+        if self.meta.spatial.affine is not None:
+            return self.meta.spatial.affine
         spacing  = np.array(self.spacing) if self.spacing is not None else np.ones(self.spatial_ndim)
         origin  = np.array(self.origin) if self.origin is not None else np.zeros(self.spatial_ndim)
         direction = np.array(self.direction) if self.direction is not None else np.eye(self.spatial_ndim)
@@ -1360,6 +1421,7 @@ class MLArray:
         dparams = MLArray._resolve_dparams(dparams)
         
         self._store = blosc2.open(urlpath=str(filepath), dparams=dparams, mode=mode, mmap_mode=mmap_mode)
+        self._backend = "blosc2"
         self._read_meta()
         self._update_blosc2_meta()
         self.mode = mode
@@ -1439,15 +1501,13 @@ class MLArray:
     
         self._validate_and_add_meta(meta, has_array=True)
         spatial_axis_mask = [True] * len(shape) if self.meta.spatial.axis_labels is None else _spatial_axis_mask(self.meta.spatial.axis_labels)
-        self.meta.blosc2 = self._comp_and_validate_blosc2_meta(self.meta.blosc2, patch_size, chunk_size, block_size, shape, np.dtype(dtype).itemsize, spatial_axis_mask)   
+        self.meta.blosc2 = self._comp_and_validate_blosc2_meta(self.meta.blosc2, patch_size, chunk_size, block_size, shape, np.dtype(dtype).itemsize, spatial_axis_mask, cparams, dparams)   
         self.meta._has_array.has_array = True
         
         self.support_metadata = str(filepath).endswith(f".{MLARRAY_SUFFIX}")
-
-        cparams = MLArray._resolve_cparams(cparams)
-        dparams = MLArray._resolve_dparams(dparams)
         
-        self._store = blosc2.empty(shape=shape, dtype=np.dtype(dtype), urlpath=str(filepath), chunks=self.meta.blosc2.chunk_size, blocks=self.meta.blosc2.block_size, cparams=cparams, dparams=dparams, mmap_mode=mmap_mode)
+        self._store = blosc2.empty(shape=shape, dtype=np.dtype(dtype), urlpath=str(filepath), chunks=self.meta.blosc2.chunk_size, blocks=self.meta.blosc2.block_size, cparams=MLArray._resolve_cparams(self.meta.blosc2.cparams), dparams=MLArray._resolve_dparams(self.meta.blosc2.dparams), mmap_mode=mmap_mode)
+        self._backend = "blosc2"
         self._update_blosc2_meta()
         self.mode = mode
         self.mmap_mode = mmap_mode
@@ -1458,6 +1518,7 @@ class MLArray:
             self,
             filepath: Union[str, Path], 
             dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+            compressed: bool = True,
         ):
         """Internal MLArray load method. Loads a MLArray file. Both MLArray ('.mla') and Blosc2 ('.b2nd') files are supported.
 
@@ -1484,10 +1545,14 @@ class MLArray:
         ondisk = blosc2.open(str(filepath), dparams=dparams, mode="r")
         cframe = ondisk.to_cframe()
         self._store = blosc2.ndarray_from_cframe(cframe, copy=True)
+        self._backend = "blosc2"
         self.mode = None
         self.mmap_mode = None
         self._read_meta()        
         self._update_blosc2_meta()
+        if not compressed:
+            self._store = np.asarray(self._store[...])
+            self._backend = "numpy"
 
     def _asarray(
             self,
@@ -1497,7 +1562,8 @@ class MLArray:
             chunk_size: Optional[Union[int, List, Tuple]]= None,
             block_size: Optional[Union[int, List, Tuple]] = None,
             cparams: Optional[Union[Dict, blosc2.CParams]] = None,
-            dparams: Optional[Union[Dict, blosc2.DParams]] = None
+            dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+            compressed: bool = True,
         ):
         """Internal MLArray asarray method.
 
@@ -1539,25 +1605,20 @@ class MLArray:
         if not isinstance(array, np.ndarray):
             raise TypeError("array must be a numpy.ndarray")
         self._construct_in_memory(
-            source_array=array,
+            constructor="asarray",
+            source_array=np.ascontiguousarray(array[...]),
             meta=meta,
             patch_size=patch_size,
             chunk_size=chunk_size,
             block_size=block_size,
             cparams=cparams,
             dparams=dparams,
-            store_builder=lambda **kwargs: blosc2.asarray(
-                kwargs["source_array"],
-                chunks=kwargs["chunks"],
-                blocks=kwargs["blocks"],
-                cparams=kwargs["cparams"],
-                dparams=kwargs["dparams"],
-            ),
+            compressed=compressed,
         )
 
     def _construct_in_memory(
             self,
-            store_builder,
+            constructor: str,
             shape: Optional[Union[int, List, Tuple, np.ndarray]] = None,
             dtype: Optional[np.dtype] = None,
             source_array: Optional[np.ndarray] = None,
@@ -1567,6 +1628,8 @@ class MLArray:
             block_size: Optional[Union[int, List, Tuple]] = None,
             cparams: Optional[Union[Dict, blosc2.CParams]] = None,
             dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+            compressed: bool = True,
+            constructor_kwargs: Optional[dict[str, Any]] = None,
         ):
         """Internal generic constructor for in-memory Blosc2-backed MLArrays.
 
@@ -1575,8 +1638,7 @@ class MLArray:
                 array shape, required when ``source_array`` is None.
             dtype (Optional[np.dtype]): Target dtype, required when
                 ``source_array`` is None.
-            store_builder (Callable): Callable receiving normalized kwargs and
-                returning a Blosc2 NDArray.
+            constructor (str): Constructor operation name.
             source_array (Optional[np.ndarray]): Source array that should be
                 converted into an in-memory Blosc2-backed store.
             meta (Optional[Union[Dict, Meta]]): Optional metadata attached to
@@ -1599,12 +1661,13 @@ class MLArray:
         Raises:
             ValueError: If constructor inputs are inconsistent.
         """
+        constructor_kwargs = {} if constructor_kwargs is None else dict(constructor_kwargs)
+
         if source_array is not None:
             if shape is not None or dtype is not None:
                 raise ValueError(
                     "shape/dtype must not be set when source_array is provided."
                 )
-            source_array = np.ascontiguousarray(source_array[...])
             shape = self._normalize_shape(source_array.shape)
             dtype = np.dtype(source_array.dtype)
         else:
@@ -1621,6 +1684,7 @@ class MLArray:
             if self.meta.spatial.axis_labels is None
             else _spatial_axis_mask(self.meta.spatial.axis_labels)
         )
+
         self.meta.blosc2 = self._comp_and_validate_blosc2_meta(
             self.meta.blosc2,
             patch_size,
@@ -1629,29 +1693,101 @@ class MLArray:
             shape,
             dtype.itemsize,
             spatial_axis_mask,
+            cparams,
+            dparams,
         )
         self.meta._has_array.has_array = True
 
-        cparams = MLArray._resolve_cparams(cparams)
-        dparams = MLArray._resolve_dparams(dparams)
+        backend_lib = blosc2 if compressed else np
+        blosc2_storage_kwargs = {}
+        if compressed:
+            blosc2_storage_kwargs = {
+                "chunks": self.meta.blosc2.chunk_size,
+                "blocks": self.meta.blosc2.block_size,
+                "cparams": MLArray._resolve_cparams(self.meta.blosc2.cparams),
+                "dparams": MLArray._resolve_dparams(self.meta.blosc2.dparams),
+            }
+
+        if constructor == "asarray":
+            if compressed:
+                self._store = blosc2.asarray(source_array, **blosc2_storage_kwargs)
+            else:
+                self._store = np.asarray(source_array, dtype=dtype)
+        else:
+            call_kwargs = self._build_constructor_call_kwargs(
+                constructor=constructor,
+                shape=shape,
+                dtype=dtype,
+                constructor_kwargs=constructor_kwargs,
+            )
 
-        builder_kwargs = dict(
-            shape=shape,
-            dtype=dtype,
-            chunks=self.meta.blosc2.chunk_size,
-            blocks=self.meta.blosc2.block_size,
-            cparams=cparams,
-            dparams=dparams,
-        )
-        if source_array is not None:
-            builder_kwargs["source_array"] = source_array
+            if not compressed and constructor in ("arange", "linspace"):
+                self._store = self._construct_numpy_range(constructor, call_kwargs)
+            else:
+                func = getattr(backend_lib, constructor, None)
+                if func is None:
+                    raise ValueError(f"Unknown constructor '{constructor}'.")
+                if compressed:
+                    call_kwargs.update(blosc2_storage_kwargs)
+                self._store = func(**call_kwargs)
+
+        self._backend = "blosc2" if compressed else "numpy"
 
-        self._store = store_builder(**builder_kwargs)
+        self.support_metadata = True
 
         self._update_blosc2_meta()
         self._validate_and_add_meta(self.meta)
 
-    def _comp_and_validate_blosc2_meta(self, meta_blosc2, patch_size, chunk_size, block_size, shape, dtype_itemsize, spatial_axis_mask):
+    @staticmethod
+    def _build_constructor_call_kwargs(
+            constructor: str,
+            shape: Tuple[int, ...],
+            dtype: np.dtype,
+            constructor_kwargs: dict[str, Any],
+        ) -> dict[str, Any]:
+        """Build constructor kwargs shared by NumPy and Blosc2 backends."""
+        if constructor in ("empty", "zeros", "ones"):
+            return {"shape": shape, "dtype": dtype}
+        if constructor == "full":
+            return {
+                "shape": shape,
+                "fill_value": constructor_kwargs["fill_value"],
+                "dtype": dtype,
+            }
+        if constructor == "arange":
+            return {
+                "start": constructor_kwargs["start"],
+                "stop": constructor_kwargs["stop"],
+                "step": constructor_kwargs["step"],
+                "dtype": dtype,
+                "shape": shape,
+                "c_order": constructor_kwargs.get("c_order", True),
+            }
+        if constructor == "linspace":
+            return {
+                "start": constructor_kwargs["start"],
+                "stop": constructor_kwargs["stop"],
+                "num": constructor_kwargs["num"],
+                "dtype": dtype,
+                "shape": shape,
+                "endpoint": constructor_kwargs.get("endpoint", True),
+                "c_order": constructor_kwargs.get("c_order", True),
+            }
+        raise ValueError(f"Unknown constructor '{constructor}'.")
+
+    @staticmethod
+    def _construct_numpy_range(
+            constructor: str,
+            call_kwargs: dict[str, Any],
+        ) -> np.ndarray:
+        """Construct NumPy arange/linspace arrays and apply shape/order reshaping."""
+        shape = call_kwargs.pop("shape")
+        c_order = call_kwargs.pop("c_order", True)
+        func = getattr(np, constructor)
+        arr = func(**call_kwargs)
+        return np.reshape(arr, shape, order="C" if c_order else "F")
+
+    def _comp_and_validate_blosc2_meta(self, meta_blosc2, patch_size, chunk_size, block_size, shape, dtype_itemsize, spatial_axis_mask, cparams, dparams):
         """Compute and validate Blosc2 chunk/block metadata.
 
         Args:
@@ -1693,11 +1829,30 @@ class MLArray:
         if patch_size is not None:
             chunk_size, block_size = MLArray.comp_blosc2_params(shape, patch_size, spatial_axis_mask, bytes_per_pixel=dtype_itemsize)
 
-        meta_blosc2 = MetaBlosc2(chunk_size, block_size, patch_size)
+        cparams = MLArray._resolve_cparams(cparams)
+        dparams = MLArray._resolve_dparams(dparams)
+
+        meta_blosc2 = MetaBlosc2(
+            chunk_size=chunk_size,
+            block_size=block_size,
+            patch_size=patch_size,
+            cparams=cparams,
+            dparams=dparams,
+        )
         meta_blosc2._validate_and_cast(ndims=len(shape), spatial_ndims=num_spatial_axes)
         return meta_blosc2
 
-    def _validate_and_add_meta(self, meta, spacing=None, origin=None, direction=None, axis_labels=None, has_array=None, validate=True):
+    def _validate_and_add_meta(
+            self,
+            meta,
+            spacing=None,
+            origin=None,
+            direction=None,
+            affine=None,
+            axis_labels=None,
+            has_array=None,
+            validate=True,
+        ):
         """Validate and attach metadata to the MLArray instance.
 
         Args:
@@ -1709,6 +1864,8 @@ class MLArray:
                 spatial axis.
             direction (Optional[Union[List, Tuple, np.ndarray]]): Direction
                 cosine matrix with shape (ndims, ndims).
+            affine (Optional[Union[List, Tuple, np.ndarray]]): Homogeneous
+                affine matrix with shape (spatial_ndims + 1, spatial_ndims + 1).
             axis_labels (Optional[List[Union[str, AxisLabel]]]): Per-axis labels or roles. Length must match ndims.
             has_array (Optional[bool]): Explicitly set whether array data is
                 present. When True, metadata is validated with array-dependent
@@ -1726,12 +1883,22 @@ class MLArray:
             meta = Meta()
         self.meta = meta
         self.meta._mlarray_version = MLARRAY_VERSION
+
+        if affine is not None and (
+            spacing is not None or origin is not None or direction is not None
+        ):
+            raise ValueError(
+                "affine cannot be provided together with spacing, origin, or direction."
+            )
+
         if spacing is not None:
             self.meta.spatial.spacing = spacing
         if origin is not None:
             self.meta.spatial.origin = origin
         if direction is not None:
             self.meta.spatial.direction = direction
+        if affine is not None:
+            self.meta.spatial.affine = affine
         if axis_labels is not None:
             self.meta.spatial.axis_labels = axis_labels
         if has_array == True:
@@ -1747,15 +1914,18 @@ class MLArray:
         Updates ``self.meta.blosc2`` from the underlying store when the array
         is present.
         """
-        if self.meta._has_array.has_array == True:
+        if self._backend != "blosc2":
+            return
+        if self.support_metadata and self.meta._has_array.has_array == True:
             self.meta.blosc2.chunk_size = list(self._store.chunks)
             self.meta.blosc2.block_size = list(self._store.blocks)
 
     def _read_meta(self):
         """Read MLArray metadata from the underlying store, if available."""
         meta = Meta()
-        if self.support_metadata and isinstance(self._store, blosc2.ndarray.NDArray):
+        if self.support_metadata and self._backend == "blosc2":
             meta = self._store.vlmeta["mlarray"]
+            meta = pickle.loads(gzip.decompress(meta))
             meta = Meta.from_mapping(meta)
         self._validate_and_add_meta(meta)
 
@@ -1766,7 +1936,7 @@ class MLArray:
             force (bool): If True, write even when mmap_mode is read-only.
         """
         is_writable = False
-        if self.support_metadata and isinstance(self._store, blosc2.ndarray.NDArray):
+        if self.support_metadata:
             if self.mode in ('a', 'w') and self.mmap_mode is None:
                 is_writable = True
             elif self.mmap_mode in ('r+', 'w+'):
@@ -1776,11 +1946,58 @@ class MLArray:
         
         if not is_writable:
             return
-        
-        metadata = self.meta.to_mapping()
-        if not is_serializable(metadata):
+
+        if self._backend != "blosc2":
+            return
+
+        meta = self.meta.to_mapping()
+        if not is_serializable(meta):
             raise RuntimeError("Metadata is not serializable.")
-        self._store.vlmeta["mlarray"] = metadata
+
+        meta = gzip.compress(pickle.dumps(meta, protocol=pickle.HIGHEST_PROTOCOL))
+        self._store.vlmeta["mlarray"] = meta
+
+    def _ensure_blosc2_store(self):
+        """Ensure underlying store is Blosc2, converting from NumPy when needed."""
+        if self._store is None:
+            self._store = blosc2.empty((0,))
+            self._backend = "blosc2"
+            return
+
+        if self._backend == "blosc2":
+            return
+
+        array = np.asarray(self._store)
+        if not self.meta._has_array.has_array:
+            self._store = blosc2.empty((0,))
+            self._backend = "blosc2"
+            return
+
+        shape = self._normalize_shape(array.shape)
+        spatial_axis_mask = (
+            [True] * len(shape)
+            if self.meta.spatial.axis_labels is None
+            else _spatial_axis_mask(self.meta.spatial.axis_labels)
+        )
+        self.meta.blosc2 = self._comp_and_validate_blosc2_meta(
+            self.meta.blosc2,
+            patch_size="default",
+            chunk_size=self.meta.blosc2.chunk_size,
+            block_size=self.meta.blosc2.block_size,
+            shape=shape,
+            dtype_itemsize=np.dtype(array.dtype).itemsize,
+            spatial_axis_mask=spatial_axis_mask,
+            cparams=self.meta.blosc2.cparams,
+            dparams=self.meta.blosc2.dparams,
+        )
+        self._store = blosc2.asarray(
+            np.ascontiguousarray(array),
+            chunks=self.meta.blosc2.chunk_size,
+            blocks=self.meta.blosc2.block_size,
+            cparams=MLArray._resolve_cparams(self.meta.blosc2.cparams),
+            dparams=MLArray._resolve_dparams(self.meta.blosc2.dparams),
+        )
+        self._backend = "blosc2"
 
     @staticmethod
     def _normalize_shape(shape: Union[int, List, Tuple, np.ndarray]) -> Tuple[int, ...]:
@@ -1812,6 +2029,19 @@ class MLArray:
         """Resolve compression params with MLArray defaults."""
         if cparams is None:
             return {"codec": blosc2.Codec.LZ4HC, "clevel": 8}
+        if isinstance(cparams, dict):
+            cparams = dict(cparams)
+            if "codec" in cparams and not isinstance(cparams["codec"], blosc2.Codec):
+                cparams["codec"] = blosc2.Codec(cparams["codec"])
+            if "splitmode" in cparams and not isinstance(cparams["splitmode"], blosc2.SplitMode):
+                cparams["splitmode"] = blosc2.SplitMode(cparams["splitmode"])
+            if "tuner" in cparams and not isinstance(cparams["tuner"], blosc2.Tuner):
+                cparams["tuner"] = blosc2.Tuner(cparams["tuner"])
+            if "filters" in cparams and isinstance(cparams["filters"], (list, tuple)):
+                cparams["filters"] = [
+                    f if isinstance(f, blosc2.Filter) else blosc2.Filter(f)
+                    for f in cparams["filters"]
+                ]
         return cparams
 
     @staticmethod

{mlarray-0.0.47 → mlarray-0.0.49}/mlarray.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mlarray
-Version: 0.0.47
+Version: 0.0.49
 Summary: Array format specialized for Machine Learning with Blosc2 backend and standardized metadata.
 Author-email: Karol Gotkowski <karol.gotkowski@dkfz.de>
 License: MIT

{mlarray-0.0.47 → mlarray-0.0.49}/mlarray.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ docs/why.md
 examples/example_asarray.py
 examples/example_bboxes_only.py
 examples/example_channel.py
+examples/example_compressed_vs_uncompressed.py
 examples/example_in_memory_constructors.py
 examples/example_metadata_only.py
 examples/example_non_spatial.py

{mlarray-0.0.47 → mlarray-0.0.49}/tests/test_asarray.py

@@ -64,6 +64,22 @@ class TestAsArray(unittest.TestCase):
         self.assertEqual(image.meta.source.to_plain(), {"patient_id": "p-001"})
         self.assertTrue(image.meta.is_seg)
 
+    def test_asarray_uncompressed_numpy_store_and_save(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            array = _make_array(seed=3)
+            image = MLArray.asarray(array, meta={"case_id": "np"}, compressed=False)
+
+            self.assertTrue(isinstance(image._store, np.ndarray))
+            self.assertTrue(np.allclose(image.to_numpy(), array))
+            self.assertEqual(image.meta.source.to_plain(), {"case_id": "np"})
+
+            path = Path(tmpdir) / "asarray-numpy-save.mla"
+            image.save(path)
+            loaded = MLArray(path)
+            self.assertFalse(isinstance(loaded._store, np.ndarray))
+            self.assertTrue(np.allclose(loaded.to_numpy(), array))
+            self.assertEqual(loaded.meta.source.to_plain(), {"case_id": "np"})
+
 
 if __name__ == "__main__":
     unittest.main()

{mlarray-0.0.47 → mlarray-0.0.49}/tests/test_usage.py

@@ -25,6 +25,18 @@ class TestUsage(unittest.TestCase):
             loaded = MLArray(path)
             self.assertEqual(loaded.shape, array.shape)
 
+    def test_default_usage_uncompressed_backend(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            array = _make_array(seed=11)
+            image = MLArray(array, compressed=False)
+            self.assertTrue(isinstance(image._store, np.ndarray))
+
+            path = Path(tmpdir) / "sample-uncompressed.mla"
+            image.save(path)
+            loaded = MLArray(path)
+            self.assertEqual(loaded.shape, array.shape)
+            self.assertTrue(np.allclose(loaded.to_numpy(), array))
+
     def test_mmap_loading(self):
         with tempfile.TemporaryDirectory() as tmpdir:
             array = _make_array()
@@ -34,6 +46,16 @@ class TestUsage(unittest.TestCase):
             loaded = MLArray.open(path, mmap_mode="r")
             self.assertFalse(isinstance(loaded._store, np.ndarray))
 
+    def test_load_uncompressed_store(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            array = _make_array()
+            path = Path(tmpdir) / "sample-load-uncompressed.mla"
+            MLArray(array).save(path)
+
+            loaded = MLArray.load(path, compressed=False)
+            self.assertTrue(isinstance(loaded._store, np.ndarray))
+            self.assertTrue(np.allclose(loaded.to_numpy(), array))
+
     def test_loading_and_saving(self):
         with tempfile.TemporaryDirectory() as tmpdir:
             array = _make_array()
@@ -66,6 +88,32 @@ class TestUsage(unittest.TestCase):
             self.assertEqual(loaded.origin, [10.0, 10.0, 30.0])
             self.assertEqual(loaded.meta.source["study_id"], "study-001")
 
+    def test_affine_stored_in_meta_spatial(self):
+        array = _make_array(shape=(8, 8, 8))
+        affine = [
+            [1.0, 0.0, 0.0, 10.0],
+            [0.0, 2.0, 0.0, 20.0],
+            [0.0, 0.0, 3.0, 30.0],
+            [0.0, 0.0, 0.0, 1.0],
+        ]
+        image = MLArray(array, affine=affine)
+
+        self.assertEqual(image.meta.spatial.affine, affine)
+        self.assertIsNone(image.meta.spatial.spacing)
+        self.assertIsNone(image.meta.spatial.origin)
+        self.assertIsNone(image.meta.spatial.direction)
+
+    def test_affine_and_spacing_origin_direction_mix_raises(self):
+        array = _make_array(shape=(8, 8, 8))
+        affine = [
+            [1.0, 0.0, 0.0, 10.0],
+            [0.0, 1.0, 0.0, 20.0],
+            [0.0, 0.0, 1.0, 30.0],
+            [0.0, 0.0, 0.0, 1.0],
+        ]
+        with self.assertRaises(ValueError):
+            MLArray(array, spacing=(1.0, 1.0, 1.0), affine=affine)
+
     def test_copy_metadata_with_override(self):
         with tempfile.TemporaryDirectory() as tmpdir:
             array = _make_array()