ome-arrow 0.0.5__py3-none-any.whl → 0.0.6__py3-none-any.whl

ome_arrow/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.5'
-__version_tuple__ = version_tuple = (0, 0, 5)
+__version__ = version = '0.0.6'
+__version_tuple__ = version_tuple = (0, 0, 6)
 
 __commit_id__ = commit_id = None

ome_arrow/core.py

@@ -59,6 +59,7 @@ class OMEArrow:
         tcz: Tuple[int, int, int] = (0, 0, 0),
         column_name: str = "ome_arrow",
         row_index: int = 0,
+        image_type: str | None = None,
     ) -> None:
         """
         Construct an OMEArrow from:
@@ -71,6 +72,7 @@ class OMEArrow:
             with from_numpy defaults)
         - a dict already matching the OME-Arrow schema
         - a pa.StructScalar already typed to OME_ARROW_STRUCT
+        - optionally override/set image_type metadata on ingest
         """
 
         # set the tcz for viewing
@@ -83,6 +85,7 @@ class OMEArrow:
                 default_dim_for_unspecified="C",
                 map_series_to="T",
                 clamp_to_uint16=True,
+                image_type=image_type,
             )
 
         # --- 2) String path/URL: OME-Zarr / OME-Parquet / OME-TIFF ---------------
@@ -98,6 +101,8 @@ class OMEArrow:
                 or (path.exists() and path.is_dir() and path.suffix.lower() == ".zarr")
             ):
                 self.data = from_ome_zarr(s)
+                if image_type is not None:
+                    self.data = self._wrap_with_image_type(self.data, image_type)
 
             # OME-Parquet
             elif s.lower().endswith((".parquet", ".pq")) or path.suffix.lower() in {
@@ -107,18 +112,24 @@ class OMEArrow:
                 self.data = from_ome_parquet(
                     s, column_name=column_name, row_index=row_index
                 )
+                if image_type is not None:
+                    self.data = self._wrap_with_image_type(self.data, image_type)
 
             # Vortex
             elif s.lower().endswith(".vortex") or path.suffix.lower() == ".vortex":
                 self.data = from_ome_vortex(
                     s, column_name=column_name, row_index=row_index
                 )
+                if image_type is not None:
+                    self.data = self._wrap_with_image_type(self.data, image_type)
 
             # TIFF
             elif path.suffix.lower() in {".tif", ".tiff"} or s.lower().endswith(
                 (".tif", ".tiff")
             ):
                 self.data = from_tiff(s)
+                if image_type is not None:
+                    self.data = self._wrap_with_image_type(self.data, image_type)
 
             elif path.exists() and path.is_dir():
                 raise ValueError(
@@ -140,15 +151,20 @@ class OMEArrow:
             # Uses from_numpy defaults: dim_order="TCZYX", clamp_to_uint16=True, etc.
             # If the array is YX/ZYX/CYX/etc.,
             # from_numpy will expand/reorder accordingly.
-            self.data = from_numpy(data)
+            self.data = from_numpy(data, image_type=image_type)
 
         # --- 4) Already-typed Arrow scalar ---------------------------------------
         elif isinstance(data, pa.StructScalar):
             self.data = data
+            if image_type is not None:
+                self.data = self._wrap_with_image_type(self.data, image_type)
 
         # --- 5) Plain dict matching the schema -----------------------------------
         elif isinstance(data, dict):
-            self.data = pa.scalar(data, type=OME_ARROW_STRUCT)
+            record = {f.name: data.get(f.name) for f in OME_ARROW_STRUCT}
+            self.data = pa.scalar(record, type=OME_ARROW_STRUCT)
+            if image_type is not None:
+                self.data = self._wrap_with_image_type(self.data, image_type)
 
         # --- otherwise ------------------------------------------------------------
         else:
@@ -156,6 +172,18 @@ class OMEArrow:
                 "input data must be str, dict, pa.StructScalar, or numpy.ndarray"
             )
 
+    @staticmethod
+    def _wrap_with_image_type(
+        data: pa.StructScalar, image_type: str
+    ) -> pa.StructScalar:
+        return pa.scalar(
+            {
+                **data.as_py(),
+                "image_type": str(image_type),
+            },
+            type=OME_ARROW_STRUCT,
+        )
+
     def export(  # noqa: PLR0911
         self,
         how: str = "numpy",
@@ -212,7 +240,8 @@ class OMEArrow:
         compression / compression_level / tile:
             OME-TIFF options (passed through to tifffile via BioIO).
         chunks / zarr_compressor / zarr_level :
-            OME-Zarr options (chunk shape, compressor hint, level).
+            OME-Zarr options (chunk shape, compressor hint, level). If chunks is
+            None, a TCZYX default is chosen (1,1,<=4,<=512,<=512).
         use_channel_colors:
             Try to embed per-channel display colors when safe; otherwise omitted.
         parquet_*:

ome_arrow/export.py

@@ -21,7 +21,8 @@ def to_numpy(
     Convert an OME-Arrow record into a NumPy array shaped (T,C,Z,Y,X).
 
     The OME-Arrow "planes" are flattened YX slices indexed by (z, t, c).
-    This function reconstitutes them into a dense TCZYX ndarray.
+    When chunks are present, this function reconstitutes the dense TCZYX array
+    from chunked pixels instead of planes.
 
     Args:
         data:
@@ -58,7 +59,7 @@ def to_numpy(
     if sx <= 0 or sy <= 0 or sz <= 0 or sc <= 0 or st <= 0:
         raise ValueError("All size_* fields must be positive integers.")
 
-    expected_len = sx * sy
+    expected_plane_len = sx * sy
 
     # Prepare target array (T,C,Z,Y,X), zero-filled by default.
     out = np.zeros((st, sc, sz, sy, sx), dtype=dtype)
@@ -78,6 +79,70 @@ def to_numpy(
             a = np.clip(a, lo, hi)
         return a.astype(dtype, copy=False)
 
+    chunks = data.get("chunks") or []
+    if chunks:
+        chunk_grid = data.get("chunk_grid") or {}
+        chunk_order = str(chunk_grid.get("chunk_order") or "ZYX").upper()
+        if chunk_order != "ZYX":
+            raise ValueError("Only chunk_order='ZYX' is supported for now.")
+
+        for i, ch in enumerate(chunks):
+            # Chunk coordinates include time/channel plus spatial indices.
+            t = int(ch["t"])
+            c = int(ch["c"])
+            z = int(ch["z"])
+            y = int(ch["y"])
+            x = int(ch["x"])
+            # Chunk shape is only spatial (Z, Y, X).
+            shape_z = int(ch["shape_z"])
+            shape_y = int(ch["shape_y"])
+            shape_x = int(ch["shape_x"])
+
+            # Validate chunk indices and extents within the full 5D array.
+            if not (0 <= t < st and 0 <= c < sc and 0 <= z < sz):
+                raise ValueError(
+                    f"chunks[{i}] index out of range: (t,c,z)=({t},{c},{z})"
+                )
+            if y < 0 or x < 0 or shape_z <= 0 or shape_y <= 0 or shape_x <= 0:
+                raise ValueError(f"chunks[{i}] has invalid shape or origin.")
+            if z + shape_z > sz:
+                raise ValueError(
+                    f"chunks[{i}] extent out of range: z+shape_z={z + shape_z} "
+                    f"> sz={sz}"
+                )
+            if y + shape_y > sy:
+                raise ValueError(
+                    f"chunks[{i}] extent out of range: y+shape_y={y + shape_y} "
+                    f"> sy={sy}"
+                )
+            if x + shape_x > sx:
+                raise ValueError(
+                    f"chunks[{i}] extent out of range: x+shape_x={x + shape_x} "
+                    f"> sx={sx}"
+                )
+
+            pix = ch["pixels"]
+            try:
+                n = len(pix)
+            except Exception as e:
+                raise ValueError(f"chunks[{i}].pixels is not a sequence") from e
+
+            expected_len = shape_z * shape_y * shape_x
+            if n != expected_len:
+                if strict:
+                    raise ValueError(
+                        f"chunks[{i}].pixels length {n} != expected {expected_len}"
+                    )
+                if n > expected_len:
+                    pix = pix[:expected_len]
+                else:
+                    pix = list(pix) + [0] * (expected_len - n)
+
+            arr3d = np.asarray(pix).reshape(shape_z, shape_y, shape_x)
+            arr3d = _cast_plane(arr3d)
+            out[t, c, z : z + shape_z, y : y + shape_y, x : x + shape_x] = arr3d
+        return out
+
     # Fill planes.
     for i, p in enumerate(data.get("planes", [])):
         z = int(p["z"])
@@ -94,16 +159,17 @@ def to_numpy(
         except Exception as e:
             raise ValueError(f"planes[{i}].pixels is not a sequence") from e
 
-        if n != expected_len:
+        if n != expected_plane_len:
             if strict:
                 raise ValueError(
-                    f"planes[{i}].pixels length {n} != size_x*size_y {expected_len}"
+                    f"planes[{i}].pixels length {n} != size_x*size_y "
+                    f"{expected_plane_len}"
                 )
             # Lenient mode: fix length by truncation or zero-pad.
-            if n > expected_len:
-                pix = pix[:expected_len]
+            if n > expected_plane_len:
+                pix = pix[:expected_plane_len]
             else:
-                pix = list(pix) + [0] * (expected_len - n)
+                pix = list(pix) + [0] * (expected_plane_len - n)
 
         # Reshape to (Y,X) and cast.
         arr2d = np.asarray(pix).reshape(sy, sx)
@@ -113,6 +179,162 @@ def to_numpy(
     return out
 
 
+# Note: x/y are implicit because this returns the full XY plane for (t, c, z).
+def plane_from_chunks(
+    data: Dict[str, Any] | pa.StructScalar,
+    *,
+    t: int,
+    c: int,
+    z: int,
+    dtype: np.dtype = np.uint16,
+    strict: bool = True,
+    clamp: bool = False,
+) -> np.ndarray:
+    """Extract a single (t, c, z) plane using chunked pixels when available.
+
+    Args:
+        data: OME-Arrow data as a Python dict or a `pa.StructScalar`.
+        t: Time index for the plane.
+        c: Channel index for the plane.
+        z: Z index for the plane.
+        dtype: Output dtype (default: np.uint16).
+        strict: When True, raise if chunk pixels are malformed.
+        clamp: If True, clamp values to the valid range of the target dtype.
+
+    Returns:
+        np.ndarray: 2D array with shape (Y, X).
+
+    Raises:
+        KeyError: If required OME-Arrow fields are missing.
+        ValueError: If indices are out of range or pixels are malformed.
+    """
+    # The plane spans full X/Y for the given (t, c, z); x/y are implicit.
+    if isinstance(data, pa.StructScalar):
+        data = data.as_py()
+
+    # Read pixel metadata and validate requested plane indices.
+    pm = data["pixels_meta"]
+    sx, sy = int(pm["size_x"]), int(pm["size_y"])
+    sz, sc, st = int(pm["size_z"]), int(pm["size_c"]), int(pm["size_t"])
+    if not (0 <= t < st and 0 <= c < sc and 0 <= z < sz):
+        raise ValueError(f"Requested plane (t={t}, c={c}, z={z}) out of range.")
+
+    # Prepare dtype conversion (optional clamping for integer outputs).
+    if np.issubdtype(dtype, np.integer):
+        info = np.iinfo(dtype)
+        lo, hi = info.min, info.max
+    elif np.issubdtype(dtype, np.floating):
+        lo, hi = -np.inf, np.inf
+    else:
+        lo, hi = -np.inf, np.inf
+
+    def _cast_plane(a: np.ndarray) -> np.ndarray:
+        if clamp:
+            a = np.clip(a, lo, hi)
+        return a.astype(dtype, copy=False)
+
+    # Prefer chunked pixels if present, assembling the requested Z plane.
+    chunks = data.get("chunks") or []
+    if chunks:
+        chunk_grid = data.get("chunk_grid") or {}
+        chunk_order = str(chunk_grid.get("chunk_order") or "ZYX").upper()
+        if chunk_order != "ZYX":
+            raise ValueError("Only chunk_order='ZYX' is supported for now.")
+
+        # Allocate an empty XY plane; fill in tiles from matching chunks.
+        plane = np.zeros((sy, sx), dtype=dtype)
+        any_chunk_matched = False
+        for i, ch in enumerate(chunks):
+            # Skip chunks from other (t, c) positions.
+            if int(ch["t"]) != t or int(ch["c"]) != c:
+                continue
+            z0 = int(ch["z"])
+            szc = int(ch["shape_z"])
+            # Skip chunks whose Z slab does not cover the target plane.
+            if not (z0 <= z < z0 + szc):
+                continue
+            y0 = int(ch["y"])
+            x0 = int(ch["x"])
+            syc = int(ch["shape_y"])
+            sxc = int(ch["shape_x"])
+            # Validate chunk bounds (strict mode can fail fast).
+            if z0 < 0 or y0 < 0 or x0 < 0:
+                msg = f"chunks[{i}] has negative origin: (z,y,x)=({z0},{y0},{x0})"
+                if strict:
+                    raise ValueError(msg)
+                continue
+            if z0 + szc > sz:
+                msg = f"chunks[{i}] extent out of range: z+shape_z={z0 + szc} > sz={sz}"
+                if strict:
+                    raise ValueError(msg)
+                continue
+            if y0 + syc > sy:
+                msg = f"chunks[{i}] extent out of range: y+shape_y={y0 + syc} > sy={sy}"
+                if strict:
+                    raise ValueError(msg)
+                continue
+            if x0 + sxc > sx:
+                msg = f"chunks[{i}] extent out of range: x+shape_x={x0 + sxc} > sx={sx}"
+                if strict:
+                    raise ValueError(msg)
+                continue
+            pix = ch["pixels"]
+            try:
+                n = len(pix)
+            except Exception as e:
+                raise ValueError(f"chunks[{i}].pixels is not a sequence") from e
+            expected_len = szc * syc * sxc
+            if n != expected_len:
+                if strict:
+                    raise ValueError(
+                        f"chunks[{i}].pixels length {n} != expected {expected_len}"
+                    )
+                # Lenient mode: truncate or zero-pad to match the expected size.
+                if n > expected_len:
+                    pix = pix[:expected_len]
+                else:
+                    pix = list(pix) + [0] * (expected_len - n)
+
+            # Convert to a Z/Y/X slab and copy the requested Z slice into the plane.
+            slab = np.asarray(pix).reshape(szc, syc, sxc)
+            slab = _cast_plane(slab)
+            zi = z - z0
+            plane[y0 : y0 + syc, x0 : x0 + sxc] = slab[zi]
+            any_chunk_matched = True
+
+        if any_chunk_matched:
+            return plane
+
+    # Fallback to planes list if chunks are absent.
+    target = next(
+        (
+            p
+            for p in data.get("planes", [])
+            if int(p["t"]) == t and int(p["c"]) == c and int(p["z"]) == z
+        ),
+        None,
+    )
+    if target is None:
+        raise ValueError(f"plane (t={t}, c={c}, z={z}) not found")
+
+    pix = target["pixels"]
+    try:
+        n = len(pix)
+    except Exception as e:
+        raise ValueError("plane pixels is not a sequence") from e
+    expected_len = sx * sy
+    if n != expected_len:
+        if strict:
+            raise ValueError(f"plane pixels length {n} != size_x*size_y {expected_len}")
+        if n > expected_len:
+            pix = pix[:expected_len]
+        else:
+            pix = list(pix) + [0] * (expected_len - n)
+
+    arr2d = np.asarray(pix).reshape(sy, sx)
+    return _cast_plane(arr2d)
+
+
 def to_ome_tiff(
     data: Dict[str, Any] | pa.StructScalar,
     out_path: str,
@@ -255,6 +477,7 @@ def to_ome_zarr(
     - Creates level shapes for a multiscale pyramid (if multiscale_levels>1).
     - Chooses Blosc codec compatible with zarr_format (v2 vs v3).
     - Populates axes names/types/units and physical pixel sizes from pixels_meta.
+    - Uses default TCZYX chunks if none are provided.
     """
     # --- local import to avoid hard deps at module import time
     # Use the class you showed
@@ -317,6 +540,15 @@ def to_ome_zarr(
     def _down(a: int, f: int) -> int:
         return max(1, a // f)
 
+    def _default_chunks_tcxyz(
+        shape: Tuple[int, int, int, int, int],
+    ) -> Tuple[int, int, int, int, int]:
+        _t, _c, z, y, x = shape
+        cz = min(z, 4) if z > 1 else 1
+        cy = min(y, 512)
+        cx = min(x, 512)
+        return (1, 1, cz, cy, cx)
+
     def _level_shapes_tcxyz(levels: int) -> List[Tuple[int, int, int, int, int]]:
         shapes = [(st, sc, sz, sy, sx)]
         for _ in range(levels - 1):
@@ -340,6 +572,8 @@ def to_ome_zarr(
     # 5) Chunking / shards (can be single-shape or per-level;
     # we pass single-shape if provided)
     chunk_shape: Optional[List[Tuple[int, ...]]] = None
+    if chunks is None:
+        chunks = _default_chunks_tcxyz((st, sc, sz, sy, sx))
     if chunks is not None:
         chunk_shape = [tuple(int(v) for v in chunks)] * multiscale_levels
 
@@ -393,7 +627,8 @@ def to_ome_parquet(
         record_dict = data.as_py()
     else:
         # Validate by round-tripping through a typed scalar, then back to dict.
-        record_dict = pa.scalar(data, type=OME_ARROW_STRUCT).as_py()
+        record_dict = {f.name: data.get(f.name) for f in OME_ARROW_STRUCT}
+        record_dict = pa.scalar(record_dict, type=OME_ARROW_STRUCT).as_py()
 
     # 2) Build a single-row struct array from the dict, explicitly passing the schema
     struct_array = pa.array([record_dict], type=OME_ARROW_STRUCT)  # len=1
@@ -456,7 +691,8 @@ def to_ome_vortex(
         record_dict = data.as_py()
     else:
         # Validate by round-tripping through a typed scalar, then back to dict.
-        record_dict = pa.scalar(data, type=OME_ARROW_STRUCT).as_py()
+        record_dict = {f.name: data.get(f.name) for f in OME_ARROW_STRUCT}
+        record_dict = pa.scalar(record_dict, type=OME_ARROW_STRUCT).as_py()
 
     # 2) Build a single-row struct array from the dict, explicitly passing the schema
     struct_array = pa.array([record_dict], type=OME_ARROW_STRUCT)  # len=1

ome_arrow/ingest.py

@@ -50,8 +50,9 @@ def _ome_arrow_from_table(
     # 1) Locate the OME-Arrow column
     def _struct_matches_ome_fields(t: pa.StructType) -> bool:
         ome_fields = {f.name for f in OME_ARROW_STRUCT}
+        required_fields = ome_fields - {"image_type", "chunk_grid", "chunks"}
         col_fields = {f.name for f in t}
-        return ome_fields == col_fields
+        return required_fields.issubset(col_fields)
 
     requested_name = column_name
     candidate_col = None
@@ -105,6 +106,11 @@ def _ome_arrow_from_table(
 
     # 2) Extract the row as a Python dict
     record_dict: Dict[str, Any] = candidate_col.slice(row_index, 1).to_pylist()[0]
+    # Back-compat: older files won't include image_type; default to None.
+    if "image_type" not in record_dict:
+        record_dict["image_type"] = None
+    # Drop unexpected fields before casting to the canonical schema.
+    record_dict = {f.name: record_dict.get(f.name) for f in OME_ARROW_STRUCT}
 
     # 3) Reconstruct a typed StructScalar using the canonical schema
     scalar = pa.scalar(record_dict, type=OME_ARROW_STRUCT)
@@ -243,11 +249,123 @@ def _read_ngff_scale(zarr_path: Path) -> tuple[float, float, float, str | None]
     return psize_x, psize_y, psize_z, unit
 
 
+def _normalize_chunk_shape(
+    chunk_shape: Optional[Tuple[int, int, int]],
+    size_z: int,
+    size_y: int,
+    size_x: int,
+) -> Tuple[int, int, int]:
+    """Normalize a chunk shape against image bounds.
+
+    Args:
+        chunk_shape: Desired chunk shape as (Z, Y, X), or None.
+        size_z: Total Z size of the image.
+        size_y: Total Y size of the image.
+        size_x: Total X size of the image.
+
+    Returns:
+        Tuple[int, int, int]: Normalized (Z, Y, X) chunk shape.
+    """
+    if chunk_shape is None:
+        chunk_shape = (1, 512, 512)
+    if not isinstance(chunk_shape, (list, tuple)) or len(chunk_shape) != 3:
+        raise ValueError("chunk_shape must be a sequence of three integers (z,y,x)")
+    try:
+        cz_raw, cy_raw, cx_raw = (int(v) for v in chunk_shape)
+    except Exception as exc:
+        raise ValueError(
+            "chunk_shape must be a sequence of three integers (z,y,x)"
+        ) from exc
+    if cz_raw <= 0 or cy_raw <= 0 or cx_raw <= 0:
+        raise ValueError("chunk_shape values must be positive integers")
+    cz = max(1, min(cz_raw, int(size_z)))
+    cy = max(1, min(cy_raw, int(size_y)))
+    cx = max(1, min(cx_raw, int(size_x)))
+    return cz, cy, cx
+
+
+def _build_chunks_from_planes(
+    *,
+    planes: List[Dict[str, Any]],
+    size_t: int,
+    size_c: int,
+    size_z: int,
+    size_y: int,
+    size_x: int,
+    chunk_shape: Optional[Tuple[int, int, int]],
+    chunk_order: str = "ZYX",
+) -> List[Dict[str, Any]]:
+    """Build chunked pixels from a list of flattened planes.
+
+    Args:
+        planes: List of plane dicts with keys z, t, c, and pixels.
+        size_t: Total T size of the image.
+        size_c: Total C size of the image.
+        size_z: Total Z size of the image.
+        size_y: Total Y size of the image.
+        size_x: Total X size of the image.
+        chunk_shape: Desired chunk shape as (Z, Y, X).
+        chunk_order: Flattening order for chunk pixels (default "ZYX").
+
+    Returns:
+        List[Dict[str, Any]]: Chunk list with pixels stored as flat lists.
+
+    Raises:
+        ValueError: If an unsupported chunk_order is requested.
+    """
+    if str(chunk_order).upper() != "ZYX":
+        raise ValueError("Only chunk_order='ZYX' is supported for now.")
+
+    cz, cy, cx = _normalize_chunk_shape(chunk_shape, size_z, size_y, size_x)
+
+    plane_map: Dict[Tuple[int, int, int], np.ndarray] = {}
+    for p in planes:
+        z = int(p["z"])
+        t = int(p["t"])
+        c = int(p["c"])
+        pix = p["pixels"]
+        arr2d = np.asarray(pix).reshape(size_y, size_x)
+        plane_map[(t, c, z)] = arr2d
+
+    dtype = next(iter(plane_map.values())).dtype if plane_map else np.uint16
+
+    chunks: List[Dict[str, Any]] = []
+    for t in range(size_t):
+        for c in range(size_c):
+            for z0 in range(0, size_z, cz):
+                sz = min(cz, size_z - z0)
+                for y0 in range(0, size_y, cy):
+                    sy = min(cy, size_y - y0)
+                    for x0 in range(0, size_x, cx):
+                        sx = min(cx, size_x - x0)
+                        slab = np.zeros((sz, sy, sx), dtype=dtype)
+                        for zi in range(sz):
+                            plane = plane_map.get((t, c, z0 + zi))
+                            if plane is None:
+                                continue
+                            slab[zi] = plane[y0 : y0 + sy, x0 : x0 + sx]
+                        chunks.append(
+                            {
+                                "t": t,
+                                "c": c,
+                                "z": z0,
+                                "y": y0,
+                                "x": x0,
+                                "shape_z": sz,
+                                "shape_y": sy,
+                                "shape_x": sx,
+                                "pixels": slab.reshape(-1).tolist(),
+                            }
+                        )
+    return chunks
+
+
 def to_ome_arrow(
     type_: str = OME_ARROW_TAG_TYPE,
     version: str = OME_ARROW_TAG_VERSION,
     image_id: str = "unnamed",
     name: str = "unknown",
+    image_type: str | None = "image",
     acquisition_datetime: Optional[datetime] = None,
     dimension_order: str = "XYZCT",
     dtype: str = "uint16",
@@ -262,6 +380,10 @@ def to_ome_arrow(
     physical_size_unit: str = "µm",
     channels: Optional[List[Dict[str, Any]]] = None,
     planes: Optional[List[Dict[str, Any]]] = None,
+    chunks: Optional[List[Dict[str, Any]]] = None,
+    chunk_shape: Optional[Tuple[int, int, int]] = (1, 512, 512),  # (Z, Y, X)
+    chunk_order: str = "ZYX",
+    build_chunks: bool = True,
     masks: Any = None,
 ) -> pa.StructScalar:
     """
@@ -276,6 +398,9 @@ def to_ome_arrow(
         version: Specification version string.
         image_id: Unique image identifier.
         name: Human-friendly name.
+        image_type: Open-ended image kind (e.g., "image", "label"). Note that
+            from_* helpers pass image_type=None by default to preserve
+            "unspecified" vs explicitly set ("image").
         acquisition_datetime: Datetime of acquisition (defaults to now).
         dimension_order: Dimension order ("XYZCT" or "XYCT").
         dtype: Pixel data type string (e.g., "uint16").
@@ -284,6 +409,12 @@ def to_ome_arrow(
         physical_size_unit: Unit string, default "µm".
         channels: List of channel dicts. Autogenerates one if None.
         planes: List of plane dicts. Empty if None.
+        chunks: Optional list of chunk dicts. If None and build_chunks is True,
+            chunks are derived from planes using chunk_shape.
+        chunk_shape: Chunk shape as (Z, Y, X). Defaults to (1, 512, 512).
+        chunk_order: Flattening order for chunk pixels (default "ZYX").
+        build_chunks: If True, build chunked pixels from planes when chunks
+            is None.
         masks: Optional placeholder for future annotations.
 
     Returns:
@@ -299,6 +430,7 @@ def to_ome_arrow(
     version = str(version)
     image_id = str(image_id)
     name = str(name)
+    image_type = None if image_type is None else str(image_type)
     dimension_order = str(dimension_order)
     dtype = str(dtype)
     physical_size_unit = str(physical_size_unit)
@@ -328,11 +460,62 @@ def to_ome_arrow(
     if planes is None:
         planes = [{"z": 0, "t": 0, "c": 0, "pixels": [0] * (size_x * size_y)}]
 
+    if chunks is None and build_chunks:
+        chunks = _build_chunks_from_planes(
+            planes=planes,
+            size_t=size_t,
+            size_c=size_c,
+            size_z=size_z,
+            size_y=size_y,
+            size_x=size_x,
+            chunk_shape=chunk_shape,
+            chunk_order=chunk_order,
+        )
+
+    chunk_grid = None
+    if chunks is not None:
+        chunk_order = str(chunk_order).upper()
+        if chunk_order != "ZYX":
+            raise ValueError("Only chunk_order='ZYX' is supported for now.")
+        if len(chunks) == 0:
+            raise ValueError("chunks must not be an empty list")
+        first = chunks[0]
+        try:
+            derived_shape = (
+                int(first["shape_z"]),
+                int(first["shape_y"]),
+                int(first["shape_x"]),
+            )
+        except Exception as exc:
+            raise ValueError(
+                "chunks entries must include shape_z/shape_y/shape_x"
+            ) from exc
+        if derived_shape[0] <= 0 or derived_shape[1] <= 0 or derived_shape[2] <= 0:
+            raise ValueError("chunk shapes must be positive integers")
+        if chunk_shape is not None:
+            norm_shape = _normalize_chunk_shape(chunk_shape, size_z, size_y, size_x)
+            if norm_shape != derived_shape:
+                raise ValueError(
+                    "chunk_shape does not match provided chunks "
+                    f"(chunk_shape={norm_shape}, chunks_shape={derived_shape})"
+                )
+        cz, cy, cx = _normalize_chunk_shape(derived_shape, size_z, size_y, size_x)
+        chunk_grid = {
+            "order": "TCZYX",
+            "chunk_t": 1,
+            "chunk_c": 1,
+            "chunk_z": cz,
+            "chunk_y": cy,
+            "chunk_x": cx,
+            "chunk_order": str(chunk_order),
+        }
+
     record = {
         "type": type_,
         "version": version,
         "id": image_id,
         "name": name,
+        "image_type": image_type,
         "acquisition_datetime": acquisition_datetime or datetime.now(timezone.utc),
         "pixels_meta": {
             "dimension_order": dimension_order,
@@ -350,6 +533,8 @@ def to_ome_arrow(
             "physical_size_z_unit": physical_size_unit,
             "channels": channels,
         },
+        "chunk_grid": chunk_grid,
+        "chunks": chunks,
         "planes": planes,
         "masks": masks,
     }
@@ -363,9 +548,13 @@ def from_numpy(
     dim_order: str = "TCZYX",
     image_id: Optional[str] = None,
     name: Optional[str] = None,
+    image_type: Optional[str] = None,
     channel_names: Optional[Sequence[str]] = None,
     acquisition_datetime: Optional[datetime] = None,
     clamp_to_uint16: bool = True,
+    chunk_shape: Optional[Tuple[int, int, int]] = (1, 512, 512),
+    chunk_order: str = "ZYX",
+    build_chunks: bool = True,
     # meta
     physical_size_x: float = 1.0,
     physical_size_y: float = 1.0,
@@ -373,42 +562,39 @@ def from_numpy(
     physical_size_unit: str = "µm",
     dtype_meta: Optional[str] = None,  # if None, inferred from output dtype
 ) -> pa.StructScalar:
-    """
-    Build an OME-Arrow StructScalar from a NumPy array.
-
-    Parameters
-    ----------
-    arr : np.ndarray
-        Image data with axes described by `dim_order`.
-    dim_order : str, default "TCZYX"
-        Axis labels for `arr`. Must include "Y" and "X".
-        Supported examples: "YX", "ZYX", "CYX", "CZYX", "TYX", "TCYX", "TCZYX".
-    image_id, name : Optional[str]
-        Identifiers to embed in the record.
-    channel_names : Optional[Sequence[str]]
-        Names for channels; defaults to C0..C{n-1}.
-    acquisition_datetime : Optional[datetime]
-        Defaults to now (UTC) if None.
-    clamp_to_uint16 : bool, default True
-        If True, clamp/cast planes to uint16 before serialization.
-    physical_size_x/y/z : float
-        Spatial pixel sizes (µm), Z used if present.
-    physical_size_unit : str
-        Unit string for spatial axes (default "µm").
-    dtype_meta : Optional[str]
-        Pixel dtype string to place in metadata; if None, inferred from the
-        (possibly cast) array's dtype.
-
-    Returns
-    -------
-    pa.StructScalar
-        Typed OME-Arrow record (schema = OME_ARROW_STRUCT).
-
-    Notes
-    -----
-    - If Z is not in `dim_order`, `size_z` will be 1 and the meta
-      dimension_order becomes "XYCT"; otherwise "XYZCT".
-    - If T/C are absent in `dim_order`, they default to size 1.
+    """Build an OME-Arrow StructScalar from a NumPy array.
+
+    Args:
+        arr: Image data with axes described by `dim_order`.
+        dim_order: Axis labels for `arr`. Must include "Y" and "X".
+            Supported examples: "YX", "ZYX", "CYX", "CZYX", "TYX", "TCYX", "TCZYX".
+        image_id: Optional stable image identifier.
+        name: Optional human label.
+        image_type: Open-ended image kind (e.g., "image", "label").
+        channel_names: Names for channels; defaults to C0..C{n-1}.
+        acquisition_datetime: Defaults to now (UTC) if None.
+        clamp_to_uint16: If True, clamp/cast planes to uint16 before serialization.
+        chunk_shape: Chunk shape as (Z, Y, X). Defaults to (1, 512, 512).
+        chunk_order: Flattening order for chunk pixels (default "ZYX").
+        build_chunks: If True, build chunked pixels from planes.
+        physical_size_x: Spatial pixel size (µm) for X.
+        physical_size_y: Spatial pixel size (µm) for Y.
+        physical_size_z: Spatial pixel size (µm) for Z when present.
+        physical_size_unit: Unit string for spatial axes (default "µm").
+        dtype_meta: Pixel dtype string to place in metadata; if None, inferred
+            from the (possibly cast) array's dtype.
+
+    Returns:
+        pa.StructScalar: Typed OME-Arrow record (schema = OME_ARROW_STRUCT).
+
+    Raises:
+        TypeError: If `arr` is not a NumPy ndarray.
+        ValueError: If `dim_order` is invalid or dimensions are non-positive.
+
+    Notes:
+        - If Z is not in `dim_order`, `size_z` will be 1 and the meta
+          dimension_order becomes "XYCT"; otherwise "XYZCT".
+        - If T/C are absent in `dim_order`, they default to size 1.
     """
 
     if not isinstance(arr, np.ndarray):
@@ -496,6 +682,7 @@ def from_numpy(
     return to_ome_arrow(
         image_id=str(image_id or "unnamed"),
         name=str(name or "unknown"),
+        image_type=image_type,
         acquisition_datetime=acquisition_datetime or datetime.now(timezone.utc),
         dimension_order=meta_dim_order,
         dtype=dtype_str,
@@ -510,6 +697,9 @@ def from_numpy(
         physical_size_unit=str(physical_size_unit),
         channels=channels,
         planes=planes,
+        chunk_shape=chunk_shape,
+        chunk_order=chunk_order,
+        build_chunks=build_chunks,
         masks=None,
     )
 
@@ -518,6 +708,7 @@ def from_tiff(
     tiff_path: str | Path,
     image_id: Optional[str] = None,
     name: Optional[str] = None,
+    image_type: Optional[str] = None,
     channel_names: Optional[Sequence[str]] = None,
     acquisition_datetime: Optional[datetime] = None,
     clamp_to_uint16: bool = True,
@@ -532,6 +723,7 @@ def from_tiff(
         tiff_path: Path to a TIFF readable by bioio.
         image_id: Optional stable image identifier (defaults to stem).
         name: Optional human label (defaults to file name).
+        image_type: Optional image kind (e.g., "image", "label").
         channel_names: Optional channel names; defaults to C0..C{n-1}.
         acquisition_datetime: Optional acquisition time (UTC now if None).
         clamp_to_uint16: If True, clamp/cast planes to uint16.
@@ -601,6 +793,7 @@ def from_tiff(
     return to_ome_arrow(
         image_id=img_id,
         name=display_name,
+        image_type=image_type,
         acquisition_datetime=acquisition_datetime or datetime.now(timezone.utc),
         dimension_order=dim_order,
         dtype="uint16",
@@ -627,6 +820,7 @@ def from_stack_pattern_path(
     channel_names: Optional[List[str]] = None,
     image_id: Optional[str] = None,
     name: Optional[str] = None,
+    image_type: Optional[str] = None,
 ) -> pa.StructScalar:
     """Build an OME-Arrow record from a filename pattern describing a stack.
 
@@ -638,6 +832,7 @@ def from_stack_pattern_path(
         channel_names: Optional list of channel names to apply.
         image_id: Optional image identifier override.
         name: Optional display name override.
+        image_type: Optional image kind (e.g., "image", "label").
 
     Returns:
         A validated OME-Arrow StructScalar describing the stack.
@@ -907,6 +1102,7 @@ def from_stack_pattern_path(
     return to_ome_arrow(
         image_id=str(img_id),
         name=str(display_name),
+        image_type=image_type,
         acquisition_datetime=None,
         dimension_order=dim_order,
         dtype="uint16",
@@ -929,6 +1125,7 @@ def from_ome_zarr(
     zarr_path: str | Path,
     image_id: Optional[str] = None,
     name: Optional[str] = None,
+    image_type: Optional[str] = None,
     channel_names: Optional[Sequence[str]] = None,
     acquisition_datetime: Optional[datetime] = None,
     clamp_to_uint16: bool = True,
@@ -947,6 +1144,8 @@ def from_ome_zarr(
             Optional stable image identifier (defaults to directory stem).
         name:
             Optional display name (defaults to directory name).
+        image_type:
+            Optional image kind (e.g., "image", "label").
         channel_names:
             Optional list of channel names. Defaults to C0, C1, ...
         acquisition_datetime:
@@ -1028,6 +1227,7 @@ def from_ome_zarr(
     return to_ome_arrow(
         image_id=img_id,
         name=display_name,
+        image_type=image_type,
         acquisition_datetime=acquisition_datetime or datetime.now(timezone.utc),
         dimension_order=dim_order,
         dtype="uint16",

ome_arrow/meta.py

@@ -12,8 +12,10 @@ OME_ARROW_TAG_VERSION = ome_arrow_version
 # OME_ARROW_STRUCT: ome-arrow record (describes one image/value).
 #  - type/version: quick identity & evolution.
 #  - id/name/acquisition_datetime: identity & provenance.
+#  - image_type: open-ended image kind (e.g., "image", "label").
 #  - pixels_meta: pixels struct (sizes, units, channels).
 #  - planes: list of planes struct entries, one per (t,c,z).
+#  - chunk_grid/chunks: optional chunked pixels (TCZYX-aware), stored as Arrow lists.
 #  - masks: reserved for future labels/ROIs (placeholder).
 OME_ARROW_STRUCT: pa.StructType = pa.struct(
     [
@@ -21,6 +23,7 @@ OME_ARROW_STRUCT: pa.StructType = pa.struct(
         pa.field("version", pa.string()),  # e.g., "1.0.0"
         pa.field("id", pa.string()),  # stable image identifier
         pa.field("name", pa.string()),  # human label
+        pa.field("image_type", pa.string()),  # open-ended (e.g., "image", "label")
         pa.field("acquisition_datetime", pa.timestamp("us")),
         # PIXELS: OME-like "Pixels" header summarizing shape & scale.
         #  - dimension_order: hint like "XYZCT" (or "XYCT" when Z==1).
@@ -68,6 +71,44 @@ OME_ARROW_STRUCT: pa.StructType = pa.struct(
                 ]
             ),
         ),
+        # CHUNK GRID: optional chunking metadata for random access.
+        #  - order: axis order for the full array, e.g., "TCZYX".
+        #  - chunk_*: chunk sizes for each axis (defaults to 1 for T/C).
+        #  - chunk_order: order used to flatten chunk pixels (default "ZYX").
+        pa.field(
+            "chunk_grid",
+            pa.struct(
+                [
+                    pa.field("order", pa.string()),
+                    pa.field("chunk_t", pa.int32()),
+                    pa.field("chunk_c", pa.int16()),
+                    pa.field("chunk_z", pa.int32()),
+                    pa.field("chunk_y", pa.int32()),
+                    pa.field("chunk_x", pa.int32()),
+                    pa.field("chunk_order", pa.string()),
+                ]
+            ),
+        ),
+        # CHUNKS: list of chunk entries (Arrow-native, no binary payloads).
+        #  - pixels flattened in chunk_order (default "ZYX").
+        pa.field(
+            "chunks",
+            pa.list_(
+                pa.struct(
+                    [
+                        pa.field("t", pa.int32()),
+                        pa.field("c", pa.int16()),
+                        pa.field("z", pa.int32()),
+                        pa.field("y", pa.int32()),
+                        pa.field("x", pa.int32()),
+                        pa.field("shape_z", pa.int32()),
+                        pa.field("shape_y", pa.int32()),
+                        pa.field("shape_x", pa.int32()),
+                        pa.field("pixels", pa.list_(pa.uint16())),
+                    ]
+                )
+            ),
+        ),
         # PLANES: one 2D image plane for a specific (t, c, z).
         #  - pixels: flattened numeric list (Y*X) for analysis-ready computation.
         pa.field(

ome_arrow/transform.py

@@ -8,6 +8,7 @@ from typing import Any, Dict, Iterable, List, Optional, Tuple
 import numpy as np
 import pyarrow as pa
 
+from ome_arrow.ingest import _build_chunks_from_planes, _normalize_chunk_shape
 from ome_arrow.meta import OME_ARROW_STRUCT
 
 
@@ -179,4 +180,37 @@ def slice_ome_arrow(
     rec_out["pixels_meta"] = pm_out
     rec_out["planes"] = planes_out
 
+    chunk_grid_in = row.get("chunk_grid") or {}
+    if chunk_grid_in or row.get("chunks"):
+        chunk_shape = (
+            int(chunk_grid_in.get("chunk_z", 1)),
+            int(chunk_grid_in.get("chunk_y", 512)),
+            int(chunk_grid_in.get("chunk_x", 512)),
+        )
+        chunk_order = str(chunk_grid_in.get("chunk_order") or "ZYX")
+        chunks_out = _build_chunks_from_planes(
+            planes=planes_out,
+            size_t=new_st,
+            size_c=new_sc,
+            size_z=new_sz,
+            size_y=new_sy,
+            size_x=new_sx,
+            chunk_shape=chunk_shape,
+            chunk_order=chunk_order,
+        )
+        cz, cy, cx = _normalize_chunk_shape(chunk_shape, new_sz, new_sy, new_sx)
+        rec_out["chunk_grid"] = {
+            "order": "TCZYX",
+            "chunk_t": 1,
+            "chunk_c": 1,
+            "chunk_z": cz,
+            "chunk_y": cy,
+            "chunk_x": cx,
+            "chunk_order": chunk_order,
+        }
+        rec_out["chunks"] = chunks_out
+    else:
+        rec_out["chunk_grid"] = row.get("chunk_grid")
+        rec_out["chunks"] = row.get("chunks")
+
     return pa.scalar(rec_out, type=OME_ARROW_STRUCT)

ome_arrow/view.py

@@ -23,6 +23,8 @@ except ImportError:  # pragma: no cover - exercised when viz extra missing
 if TYPE_CHECKING:
     import pyvista
 
+from ome_arrow.export import plane_from_chunks
+
 
 def view_matplotlib(
     data: dict[str, object] | pa.StructScalar,
@@ -50,29 +52,8 @@ def view_matplotlib(
     Raises:
         ValueError: If the requested plane is missing or pixel sizes mismatch.
     """
-    if isinstance(data, pa.StructScalar):
-        data = data.as_py()
-
-    pm = data["pixels_meta"]
-    sx, sy = int(pm["size_x"]), int(pm["size_y"])
     t, c, z = (int(x) for x in tcz)
-
-    plane = next(
-        (
-            p
-            for p in data["planes"]
-            if int(p["t"]) == t and int(p["c"]) == c and int(p["z"]) == z
-        ),
-        None,
-    )
-    if plane is None:
-        raise ValueError(f"plane (t={t}, c={c}, z={z}) not found")
-
-    pix = plane["pixels"]
-    if len(pix) != sx * sy:
-        raise ValueError(f"pixels len {len(pix)} != size_x*size_y ({sx * sy})")
-
-    img = np.asarray(pix, dtype=np.uint16).reshape(sy, sx).copy()
+    img = plane_from_chunks(data, t=t, c=c, z=z, dtype=np.uint16).copy()
 
     if (vmin is None or vmax is None) and autoscale:
         lo, hi = int(img.min()), int(img.max())

{ome_arrow-0.0.5.dist-info → ome_arrow-0.0.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ome-arrow
-Version: 0.0.5
+Version: 0.0.6
 Summary: Using OME specifications with Apache Arrow for fast, queryable, and language agnostic bioimage data.
 Author: Dave Bunten
 Classifier: Programming Language :: Python :: 3 :: Only

ome_arrow-0.0.6.dist-info/RECORD

@@ -0,0 +1,14 @@
+ome_arrow/__init__.py,sha256=WWenJP9XxLZNGQPVOEFBDlDM1kSvj_QdHssrET6UuNQ,644
+ome_arrow/_version.py,sha256=7MyqQ3iPP2mJruPfRYGCNCq1z7_Nk7c-eyYecYITxsY,704
+ome_arrow/core.py,sha256=K1-jfojhqYkn3h-0AdmBQYFza0wtFqduJs6K7aw4Kuc,21303
+ome_arrow/export.py,sha256=XbKVIeMLbPshgo_OGO3e0PRqtZ3vEx_JAGyF9oUmZJw,26024
+ome_arrow/ingest.py,sha256=CptjVXXL8YzfHKlKqyoA-ani5SLbFlQSUVPqOXlPhXA,46931
+ome_arrow/meta.py,sha256=peIx6NLriaFpGBx9Y3NyTHLfGAg91v9YQpoBzrveKFQ,6031
+ome_arrow/transform.py,sha256=X3gKZkgTDNQSBcU3_YmJRav8JIBrDdYJci3PbFZ4t38,7200
+ome_arrow/utils.py,sha256=XHovcqmjqoiBpKvXY47-_yUwf07f8zVE_F9BR_VKaPU,2383
+ome_arrow/view.py,sha256=j9dpmSnVbiukwH6asFhCJ_WVRxwyCAdTeLiUnv_xvcE,10187
+ome_arrow-0.0.6.dist-info/licenses/LICENSE,sha256=9-2Pyhu3vTt2RJU8DorHQtHeNO_e5RLeFJTyOU4hOi4,1508
+ome_arrow-0.0.6.dist-info/METADATA,sha256=VWirz2ueYrPLOrsNj1EC2BGcsPtLpJU6Jay_NW_irZ8,6110
+ome_arrow-0.0.6.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+ome_arrow-0.0.6.dist-info/top_level.txt,sha256=aWOtkGXo_pfU-yy82guzGhz8Zh2h2nFl8Kc5qdzMGuE,10
+ome_arrow-0.0.6.dist-info/RECORD,,

{ome_arrow-0.0.5.dist-info → ome_arrow-0.0.6.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

ome_arrow-0.0.5.dist-info/RECORD

@@ -1,14 +0,0 @@
-ome_arrow/__init__.py,sha256=WWenJP9XxLZNGQPVOEFBDlDM1kSvj_QdHssrET6UuNQ,644
-ome_arrow/_version.py,sha256=YRV1ohn6CdKEhsUOmFFMmr5UTjMv4Ydw3WJGxF2BHBs,704
-ome_arrow/core.py,sha256=fgEFOwckYi3asosEUhGB8UL9Q93hO56H6qw9fUczFO8,19946
-ome_arrow/export.py,sha256=e9Nx25bD2K51gQng-4rUXM4v1l8-K1YkxGjWKImFrJ4,16972
-ome_arrow/ingest.py,sha256=Vt9hljI718vR-qpJXH4jk4Shs1OtFPfIVhmsILkbNxQ,38714
-ome_arrow/meta.py,sha256=qeD0e_ItAQyZDT7ypkBU0rBh9oHIu2ziz9MCfPpPp9g,4199
-ome_arrow/transform.py,sha256=0275_Mn1mlGXSWJ86llch8JoJyvqEOfvG-ub1dUWFNI,5997
-ome_arrow/utils.py,sha256=XHovcqmjqoiBpKvXY47-_yUwf07f8zVE_F9BR_VKaPU,2383
-ome_arrow/view.py,sha256=B2ZEE8LWlYzTBk0Fa19GHC1seEN_IdgOkfmJXcLRG2U,10691
-ome_arrow-0.0.5.dist-info/licenses/LICENSE,sha256=9-2Pyhu3vTt2RJU8DorHQtHeNO_e5RLeFJTyOU4hOi4,1508
-ome_arrow-0.0.5.dist-info/METADATA,sha256=l_CqAdgv7NFsNT48eDaC3s2uvKpg9g2FDgA3TAtricI,6110
-ome_arrow-0.0.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ome_arrow-0.0.5.dist-info/top_level.txt,sha256=aWOtkGXo_pfU-yy82guzGhz8Zh2h2nFl8Kc5qdzMGuE,10
-ome_arrow-0.0.5.dist-info/RECORD,,