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

ome_arrow/__init__.py

@@ -4,10 +4,17 @@ Init file for ome_arrow package.
 
 from ome_arrow._version import version as ome_arrow_version
 from ome_arrow.core import OMEArrow
-from ome_arrow.export import to_numpy, to_ome_parquet, to_ome_tiff, to_ome_zarr
+from ome_arrow.export import (
+    to_numpy,
+    to_ome_parquet,
+    to_ome_tiff,
+    to_ome_vortex,
+    to_ome_zarr,
+)
 from ome_arrow.ingest import (
     from_numpy,
     from_ome_parquet,
+    from_ome_vortex,
     from_ome_zarr,
     from_tiff,
     to_ome_arrow,

ome_arrow/_version.py

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

ome_arrow/core.py

@@ -11,10 +11,17 @@ import matplotlib
 import numpy as np
 import pyarrow as pa
 
-from ome_arrow.export import to_numpy, to_ome_parquet, to_ome_tiff, to_ome_zarr
+from ome_arrow.export import (
+    to_numpy,
+    to_ome_parquet,
+    to_ome_tiff,
+    to_ome_vortex,
+    to_ome_zarr,
+)
 from ome_arrow.ingest import (
     from_numpy,
     from_ome_parquet,
+    from_ome_vortex,
     from_ome_zarr,
     from_stack_pattern_path,
     from_tiff,
@@ -52,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:
@@ -59,10 +67,12 @@ class OMEArrow:
         - a path/URL to an OME-TIFF (.tif/.tiff)
         - a path/URL to an OME-Zarr store (.zarr / .ome.zarr)
         - a path/URL to an OME-Parquet file (.parquet / .pq)
+        - a path/URL to a Vortex file (.vortex)
         - a NumPy ndarray (2D-5D; interpreted
             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
@@ -75,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 ---------------
@@ -90,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 {
@@ -99,12 +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(
@@ -117,6 +142,7 @@ class OMEArrow:
                     "  • Bio-Formats pattern string (contains '<', '>' or '*')\n"
                     "  • OME-Zarr path/URL ending with '.zarr' or '.ome.zarr'\n"
                     "  • OME-Parquet file ending with '.parquet' or '.pq'\n"
+                    "  • Vortex file ending with '.vortex'\n"
                     "  • OME-TIFF path/URL ending with '.tif' or '.tiff'"
                 )
 
@@ -125,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:
@@ -141,7 +172,19 @@ class OMEArrow:
                 "input data must be str, dict, pa.StructScalar, or numpy.ndarray"
             )
 
-    def export(
+    @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",
         dtype: np.dtype = np.uint16,
@@ -165,6 +208,8 @@ class OMEArrow:
         parquet_column_name: str = "ome_arrow",
         parquet_compression: str | None = "zstd",
         parquet_metadata: dict[str, str] | None = None,
+        vortex_column_name: str = "ome_arrow",
+        vortex_metadata: dict[str, str] | None = None,
     ) -> np.array | dict | pa.StructScalar | str:
         """
         Export the OME-Arrow content in a chosen representation.
@@ -178,6 +223,7 @@ class OMEArrow:
             "ome-tiff"  → write OME-TIFF via BioIO
             "ome-zarr"  → write OME-Zarr (OME-NGFF) via BioIO
             "parquet"   → write a single-row Parquet with one struct column
+            "vortex"    → write a single-row Vortex file with one struct column
         dtype:
             Target dtype for "numpy"/writers (default: np.uint16).
         strict:
@@ -194,11 +240,14 @@ 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_*:
             Options for Parquet export (column name, compression, file metadata).
+        vortex_*:
+            Options for Vortex export (column name, file metadata).
 
         Returns
         -------
@@ -209,6 +258,7 @@ class OMEArrow:
             - "ome-tiff": output path (str)
             - "ome-zarr": output path (str)
             - "parquet": output path (str)
+            - "vortex": output path (str)
 
         Raises
         ------
@@ -271,6 +321,18 @@ class OMEArrow:
             )
             return out
 
+        # Vortex (single row, single struct column)
+        if mode in {"ome-vortex", "omevortex", "vortex"}:
+            if not out:
+                raise ValueError("export(how='vortex') requires 'out' path.")
+            to_ome_vortex(
+                data=self.data,
+                out_path=out,
+                column_name=vortex_column_name,
+                file_metadata=vortex_metadata,
+            )
+            return out
+
         raise ValueError(f"Unknown export method: {how}")
 
     def info(self) -> Dict[str, Any]:
@@ -299,7 +361,7 @@ class OMEArrow:
         opacity: str | float = "sigmoid",
         clim: tuple[float, float] | None = None,
         show_axes: bool = True,
-        scaling_values: tuple[float, float, float] | None = (1.0, 0.1, 0.1),
+        scaling_values: tuple[float, float, float] | None = None,
     ) -> matplotlib.figure.Figure | "pyvista.Plotter":
         """
         Render an OME-Arrow record using Matplotlib or PyVista.
@@ -337,7 +399,10 @@ class OMEArrow:
         clim: Contrast limits (``(low, high)``) for PyVista rendering.
         show_axes: If ``True``, display axes in the PyVista scene.
         scaling_values: Physical scale multipliers for the (x, y, z) axes used by
-            PyVista, typically to express anisotropy. Defaults to ``(1.0, 0.1, 0.1)``.
+            PyVista, typically to express anisotropy. If ``None``, uses metadata
+            scaling from the OME-Arrow record (pixels_meta.physical_size_x/y/z).
+            These scaling values will default to 1µm if metadata is missing in
+            source image metadata.
 
         Returns:
         matplotlib.figure.Figure | pyvista.Plotter:

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
@@ -420,3 +655,62 @@ def to_ome_parquet(
         compression=compression,
         row_group_size=row_group_size,
     )
+
+
+def to_ome_vortex(
+    data: Dict[str, Any] | pa.StructScalar,
+    out_path: str,
+    column_name: str = "image",
+    file_metadata: Optional[Dict[str, str]] = None,
+) -> None:
+    """Export an OME-Arrow record to a Vortex file.
+
+    The file is written as a single-row, single-column Arrow table where the
+    column holds a struct with the OME-Arrow schema.
+
+    Args:
+        data: OME-Arrow dict or StructScalar.
+        out_path: Output path for the Vortex file.
+        column_name: Column name to store the struct.
+        file_metadata: Optional file-level metadata to attach.
+
+    Raises:
+        ImportError: If the optional `vortex-data` dependency is missing.
+    """
+
+    try:
+        import vortex.io as vxio
+    except ImportError as exc:
+        raise ImportError(
+            "Vortex export requires the optional 'vortex-data' dependency."
+        ) from exc
+
+    # 1) Normalize to a plain Python dict (works better with pyarrow builders,
+    #    especially when the struct has a `null`-typed field like "masks").
+    if isinstance(data, pa.StructScalar):
+        record_dict = data.as_py()
+    else:
+        # Validate by round-tripping through a typed scalar, then back to dict.
+        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
+
+    # 3) Wrap into a one-column table
+    table = pa.table({column_name: struct_array})
+
+    # 4) Attach optional file-level metadata
+    meta: Dict[bytes, bytes] = dict(table.schema.metadata or {})
+    try:
+        meta[b"ome.arrow.type"] = str(OME_ARROW_TAG_TYPE).encode("utf-8")
+        meta[b"ome.arrow.version"] = str(OME_ARROW_TAG_VERSION).encode("utf-8")
+    except Exception:
+        pass
+    if file_metadata:
+        for k, v in file_metadata.items():
+            meta[str(k).encode("utf-8")] = str(v).encode("utf-8")
+    table = table.replace_schema_metadata(meta)
+
+    # 5) Write Vortex (single row, single column)
+    vxio.write(table, str(out_path))