mlarray 0.0.26__tar.gz → 0.0.27__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mlarray
-Version: 0.0.26
+Version: 0.0.27
 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
 ```
 
@@ -125,7 +125,7 @@ image.meta.image["study_id"] = "study-001"
 image.save("with-metadata.mla")
 
 # Open memory-mapped
-image = MLArray().open("with-metadata.mla", mmap='r+')  
+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
 ```

{mlarray-0.0.26 → mlarray-0.0.27}/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
 ```
 
@@ -91,7 +91,7 @@ image.meta.image["study_id"] = "study-001"
 image.save("with-metadata.mla")
 
 # Open memory-mapped
-image = MLArray().open("with-metadata.mla", mmap='r+')  
+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
 ```

{mlarray-0.0.26 → mlarray-0.0.27}/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.27}/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
 ```
 
@@ -75,7 +75,7 @@ image.meta.image["study_id"] = "study-001"
 image.save("with-metadata.mla")
 
 # Open memory-mapped
-image = MLArray().open("with-metadata.mla", mmap='r+')  
+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
 ```

{mlarray-0.0.26 → mlarray-0.0.27}/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,16 +19,15 @@ 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 = Meta(image=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)
+    image = MLArray.open(filepath)
     print(json.dumps(image.meta.to_dict(), 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.27}/examples/example_save_load.py

@@ -25,6 +25,7 @@ if __name__ == '__main__':
 
     print("Loading image...")
     image = MLArray(filepath)
+    image = MLArray.load(filepath)  # Just testing both load methods
     print(json.dumps(image.meta.to_dict(), 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.27}/mlarray/mlarray.py

@@ -55,22 +55,22 @@ class MLArray:
                 set via arguments.
         """
         self.filepath = None
-        self.support_metadata = None   
+        self.support_metadata = None
         self.mmap = None
         self.meta = None
         if isinstance(array, (str, Path)) and (spacing is not None or origin is not None or direction is not None or meta is not None or channel_axis is not None or copy is not None):
             raise ("Spacing, origin, direction, meta, channel_axis or copy cannot be set when array is a filepath.")
         if isinstance(array, (str, Path)):
-            self.load(array, num_threads)
+            self._load(array, num_threads)
         else:
             self._store = array
-            self._validate_and_add_meta(meta, spacing, origin, direction, channel_axis)
-        
-        if copy is not None:
-            self.meta.copy_from(copy.meta)
+            self._validate_and_add_meta(meta, spacing, origin, direction, channel_axis)        
+            if copy is not None:
+                self.meta.copy_from(copy.meta)
 
+    @classmethod
     def open(
-            self,
+            cls,
             filepath: Union[str, Path],
             shape: Optional[Union[List, Tuple, np.ndarray]] = None,
             dtype: Optional[np.dtype] = None,
@@ -89,6 +89,66 @@ class MLArray:
         files. When creating a new file, both ``shape`` and ``dtype`` must be
         provided.
 
+        WARNING:
+            MLArray supports both ".b2nd" and ".mla" files. The MLArray
+            format standard and standardized metadata are honored only for
+            ".mla". For ".b2nd", metadata is ignored when loading.
+
+        Args:
+            filepath (Union[str, Path]): Target file path. Must end with
+                ".b2nd" or ".mla".
+            shape (Optional[Union[List, Tuple, np.ndarray]]): Shape of the array
+                to create. If provided, a new file is created. Length must match
+                the full array dimensionality (including channels if present).
+            dtype (Optional[np.dtype]): Numpy dtype for a newly created array.
+            channel_axis (Optional[int]): Axis index for channels in the array.
+                Used for patch/chunk/block calculations.
+            mmap (str): Blosc2 mmap mode. One of "r", "r+", "w+", "c".
+            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 spatial
+                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 tuple/list with length equal to the array
+                dimensions. Ignored when ``patch_size`` is provided.
+            block_size (Optional[Union[int, List, Tuple]]): Explicit block size.
+                Provide an int or tuple/list with length equal to the array
+                dimensions. Ignored when ``patch_size`` is provided.
+            num_threads (int): Number of threads for Blosc2 operations.
+            cparams (Optional[Dict]): Blosc2 compression parameters.
+            dparams (Optional[Dict]): Blosc2 decompression parameters.
+
+        Returns:
+            MLArray: The current instance (for chaining).
+
+        Raises:
+            RuntimeError: If the file extension is invalid, if shape/dtype are
+                inconsistent, or if mmap mode is invalid for creation.
+        """
+        class_instance = cls()
+        class_instance._open(filepath, shape, dtype, channel_axis, mmap, patch_size, chunk_size, block_size, num_threads, cparams, dparams)
+        return class_instance
+
+    def _open(
+            self,
+            filepath: Union[str, Path],
+            shape: Optional[Union[List, Tuple, np.ndarray]] = None,
+            dtype: Optional[np.dtype] = None,
+            channel_axis: Optional[int] = None,
+            mmap: str = 'r',
+            patch_size: Optional[Union[int, List, Tuple]] = 'default',  # 'default' means that the default of 192 is used. However, if set to 'default', the patch_size will be skipped if self.patch_size is set from a previously loaded MLArray image. In that case the self.patch_size is used.
+            chunk_size: Optional[Union[int, List, Tuple]]= None,
+            block_size: Optional[Union[int, List, Tuple]] = None,
+            num_threads: int = 1,
+            cparams: Optional[Dict] = None,
+            dparams: Optional[Dict] = None
+        ):
+        """Internal open method. Open an existing Blosc2 file or create a new one with memory mapping.
+
+        This method supports both MLArray (".mla") and plain Blosc2 (".b2nd")
+        files. When creating a new file, both ``shape`` and ``dtype`` must be
+        provided.
+
         WARNING:
             MLArray supports both ".b2nd" and ".mla" files. The MLArray
             format standard and standardized metadata are honored only for
@@ -164,7 +224,6 @@ class MLArray:
             self.meta._blosc2.block_size = list(self._store.blocks)
         self.mmap = mmap
         self._write_metadata()
-        return self
 
     def close(self):
         """Flush metadata and close the underlying store.
@@ -177,14 +236,39 @@ class MLArray:
         self.support_metadata = None   
         self.mmap = None
         self.meta = None
-        
+
+    @classmethod
     def load(
-            self,
+            cls,
             filepath: Union[str, Path], 
             num_threads: int = 1,
         ):
         """Loads a Blosc2-compressed file. Both MLArray ('.mla') and Blosc2 ('.b2nd') files are supported.
 
+        WARNING:
+            MLArray supports both ".b2nd" and ".mla" files. The MLArray
+            format standard and standardized metadata are honored only for
+            ".mla". For ".b2nd", metadata is ignored when loading.
+
+        Args:
+            filepath (Union[str, Path]): Path to the Blosc2 file to be loaded.
+                The filepath needs to have the extension ".b2nd" or ".mla".
+            num_threads (int): Number of threads to use for loading the file.
+
+        Raises:
+            RuntimeError: If the file extension is not ".b2nd" or ".mla".
+        """
+        class_instance = cls()
+        class_instance._load(filepath, num_threads)
+        return class_instance
+    
+    def _load(
+            self,
+            filepath: Union[str, Path], 
+            num_threads: int = 1,
+        ):
+        """Internal MLArray load method. Loads a Blosc2-compressed file. Both MLArray ('.mla') and Blosc2 ('.b2nd') files are supported.
+
         WARNING:
             MLArray supports both ".b2nd" and ".mla" files. The MLArray
             format standard and standardized metadata are honored only for

{mlarray-0.0.26 → mlarray-0.0.27}/mlarray.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mlarray
-Version: 0.0.26
+Version: 0.0.27
 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
 ```
 
@@ -125,7 +125,7 @@ image.meta.image["study_id"] = "study-001"
 image.save("with-metadata.mla")
 
 # Open memory-mapped
-image = MLArray().open("with-metadata.mla", mmap='r+')  
+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
 ```

{mlarray-0.0.26 → mlarray-0.0.27}/tests/test_metadata.py

@@ -61,7 +61,7 @@ class TestMetadataStorage(unittest.TestCase):
             image = MLArray(array, meta={"a": 1})
             image.save(path)
 
-            opened = MLArray().open(path, mmap="r")
+            opened = MLArray.open(path, mmap="r")
             opened.meta.image["a"] = 2
             opened.close()
 
@@ -75,7 +75,7 @@ class TestMetadataStorage(unittest.TestCase):
             image = MLArray(array, meta={"a": 1})
             image.save(path)
 
-            opened = MLArray().open(path, mmap="r+")
+            opened = MLArray.open(path, mmap="r+")
             opened.meta.image["a"] = 2
             opened.close()
 
@@ -89,7 +89,7 @@ class TestMetadataStorage(unittest.TestCase):
             image = MLArray(array, meta={"a": 1})
             image.save(path)
 
-            opened = MLArray().open(path, mmap="c")
+            opened = MLArray.open(path, mmap="c")
             opened.meta.image["a"] = 3
             opened.close()
 
@@ -102,7 +102,7 @@ class TestMetadataStorage(unittest.TestCase):
             shape = (8, 16, 16)
             dtype = np.float32
 
-            opened = MLArray().open(path, shape=shape, dtype=dtype, mmap="w+")
+            opened = MLArray.open(path, shape=shape, dtype=dtype, mmap="w+")
             opened.meta.extra["created"] = True
             opened.close()
 

{mlarray-0.0.26 → mlarray-0.0.27}/tests/test_optimization.py

@@ -43,7 +43,7 @@ class TestOptimizationExamples(unittest.TestCase):
 
             MLArray(array).save(path, patch_size=(8, 16, 16))
 
-            image = MLArray().open(path, mmap="r")
+            image = MLArray.open(path, mmap="r")
             patch = image[10:20, 5:15, 7:17]
 
             self.assertEqual(patch.shape, (10, 10, 10))
@@ -55,7 +55,7 @@ class TestOptimizationExamples(unittest.TestCase):
 
             MLArray(array).save(path, patch_size=(8, 16, 16))
 
-            image = MLArray().open(path, mmap="r+")
+            image = MLArray.open(path, mmap="r+")
             image[0:2, 0:2, 0:2] *= 0.0
             image.close()
 
@@ -68,7 +68,7 @@ class TestOptimizationExamples(unittest.TestCase):
             dtype = np.float32
             path = Path(tmpdir) / "streamed-write.mla"
 
-            image = MLArray().open(
+            image = MLArray.open(
                 path,
                 shape=shape,
                 dtype=dtype,

{mlarray-0.0.26 → mlarray-0.0.27}/tests/test_usage.py

@@ -31,8 +31,7 @@ class TestUsage(unittest.TestCase):
             path = Path(tmpdir) / "sample.mla"
             MLArray(array).save(path)
 
-            loaded = MLArray(array)
-            loaded.open(path, mmap="r")
+            loaded = MLArray.open(path, mmap="r")
             self.assertFalse(isinstance(loaded._store, np.ndarray))
 
     def test_loading_and_saving(self):