ome-arrow 0.0.3__py3-none-any.whl → 0.0.5__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.3'
-__version_tuple__ = version_tuple = (0, 0, 3)
+__version__ = version = '0.0.5'
+__version_tuple__ = version_tuple = (0, 0, 5)
 
 __commit_id__ = commit_id = None

ome_arrow/core.py

@@ -5,17 +5,23 @@ Core of the ome_arrow package, used for classes and such.
 from __future__ import annotations
 
 import pathlib
-from typing import Any, Dict, Iterable, Optional, Tuple
+from typing import TYPE_CHECKING, Any, Dict, Iterable, Optional, Tuple
 
 import matplotlib
 import numpy as np
 import pyarrow as pa
-import pyvista
 
-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,
@@ -25,6 +31,10 @@ from ome_arrow.transform import slice_ome_arrow
 from ome_arrow.utils import describe_ome_arrow
 from ome_arrow.view import view_matplotlib, view_pyvista
 
+# if not in runtime, import pyvista for type hints
+if TYPE_CHECKING:
+    import pyvista
+
 
 class OMEArrow:
     """
@@ -47,6 +57,8 @@ class OMEArrow:
         self,
         data: str | dict | pa.StructScalar | "np.ndarray",
         tcz: Tuple[int, int, int] = (0, 0, 0),
+        column_name: str = "ome_arrow",
+        row_index: int = 0,
     ) -> None:
         """
         Construct an OMEArrow from:
@@ -54,6 +66,7 @@ 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
@@ -91,7 +104,15 @@ class OMEArrow:
                 ".parquet",
                 ".pq",
             }:
-                self.data = from_ome_parquet(s)
+                self.data = from_ome_parquet(
+                    s, column_name=column_name, row_index=row_index
+                )
+
+            # 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
+                )
 
             # TIFF
             elif path.suffix.lower() in {".tif", ".tiff"} or s.lower().endswith(
@@ -110,6 +131,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'"
                 )
 
@@ -134,7 +156,7 @@ class OMEArrow:
                 "input data must be str, dict, pa.StructScalar, or numpy.ndarray"
             )
 
-    def export(
+    def export(  # noqa: PLR0911
         self,
         how: str = "numpy",
         dtype: np.dtype = np.uint16,
@@ -158,6 +180,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.
@@ -171,6 +195,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:
@@ -192,6 +217,8 @@ class OMEArrow:
             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
         -------
@@ -202,6 +229,7 @@ class OMEArrow:
             - "ome-tiff": output path (str)
             - "ome-zarr": output path (str)
             - "parquet": output path (str)
+            - "vortex": output path (str)
 
         Raises
         ------
@@ -264,6 +292,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]:
@@ -292,8 +332,8 @@ 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),
-    ) -> matplotlib.figure.Figure | pyvista.Plotter:
+        scaling_values: tuple[float, float, float] | None = None,
+    ) -> matplotlib.figure.Figure | "pyvista.Plotter":
         """
         Render an OME-Arrow record using Matplotlib or PyVista.
 
@@ -330,7 +370,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

@@ -420,3 +420,61 @@ 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 = pa.scalar(data, 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))

ome_arrow/ingest.py

@@ -3,7 +3,9 @@ Converting to and from OME-Arrow formats.
 """
 
 import itertools
+import json
 import re
+import warnings
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Sequence, Tuple
@@ -19,6 +21,228 @@ from bioio_ome_zarr import Reader as OMEZarrReader
 from ome_arrow.meta import OME_ARROW_STRUCT, OME_ARROW_TAG_TYPE, OME_ARROW_TAG_VERSION
 
 
+def _ome_arrow_from_table(
+    table: pa.Table,
+    *,
+    column_name: Optional[str],
+    row_index: int,
+    strict_schema: bool,
+) -> pa.StructScalar:
+    """Extract a single OME-Arrow record from an Arrow table.
+
+    Args:
+        table: Source Arrow table.
+        column_name: Column to read; auto-detected when None or invalid.
+        row_index: Row index to extract.
+        strict_schema: Require the exact OME-Arrow schema if True.
+
+    Returns:
+        A typed OME-Arrow StructScalar.
+
+    Raises:
+        ValueError: If the row index is out of range or no suitable column exists.
+    """
+    if table.num_rows == 0:
+        raise ValueError("Table contains 0 rows; expected at least 1.")
+    if not (0 <= row_index < table.num_rows):
+        raise ValueError(f"row_index {row_index} out of range [0, {table.num_rows}).")
+
+    # 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}
+        col_fields = {f.name for f in t}
+        return ome_fields == col_fields
+
+    requested_name = column_name
+    candidate_col = None
+    autodetected_name = None
+
+    if column_name is not None and column_name in table.column_names:
+        arr = table[column_name]
+        if not pa.types.is_struct(arr.type):
+            raise ValueError(f"Column '{column_name}' is not a Struct; got {arr.type}.")
+        if strict_schema and arr.type != OME_ARROW_STRUCT:
+            raise ValueError(
+                f"Column '{column_name}' schema != OME_ARROW_STRUCT.\n"
+                f"Got:   {arr.type}\n"
+                f"Expect:{OME_ARROW_STRUCT}"
+            )
+        if not strict_schema and not _struct_matches_ome_fields(arr.type):
+            raise ValueError(
+                f"Column '{column_name}' does not have the expected OME-Arrow fields."
+            )
+        candidate_col = arr
+    else:
+        # Auto-detect a struct column that matches OME-Arrow fields
+        for name in table.column_names:
+            arr = table[name]
+            if pa.types.is_struct(arr.type):
+                if strict_schema and arr.type == OME_ARROW_STRUCT:
+                    candidate_col = arr
+                    autodetected_name = name
+                    column_name = name
+                    break
+                if not strict_schema and _struct_matches_ome_fields(arr.type):
+                    candidate_col = arr
+                    autodetected_name = name
+                    column_name = name
+                    break
+        if candidate_col is None:
+            if column_name is None:
+                hint = "no struct column with OME-Arrow fields was found."
+            else:
+                hint = f"column '{column_name}' not found and auto-detection failed."
+            raise ValueError(f"Could not locate an OME-Arrow struct column: {hint}")
+
+    # Emit warning if auto-detection was used
+    if autodetected_name is not None and autodetected_name != requested_name:
+        warnings.warn(
+            f"Requested column '{requested_name}' was not usable or not found. "
+            f"Auto-detected OME-Arrow column '{autodetected_name}'.",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    # 2) Extract the row as a Python dict
+    record_dict: Dict[str, Any] = candidate_col.slice(row_index, 1).to_pylist()[0]
+
+    # 3) Reconstruct a typed StructScalar using the canonical schema
+    scalar = pa.scalar(record_dict, type=OME_ARROW_STRUCT)
+
+    # Optional: soft validation via file-level metadata (if present)
+    try:
+        meta = table.schema.metadata or {}
+        meta.get(b"ome.arrow.type", b"").decode() == str(OME_ARROW_TAG_TYPE)
+        meta.get(b"ome.arrow.version", b"").decode() == str(OME_ARROW_TAG_VERSION)
+    except Exception:
+        pass
+
+    return scalar
+
+
+def _normalize_unit(unit: str | None) -> str | None:
+    if not unit:
+        return None
+    u = unit.strip().lower()
+    if u in {"micrometer", "micrometre", "micron", "microns", "um", "µm"}:
+        return "µm"
+    if u in {"nanometer", "nanometre", "nm"}:
+        return "nm"
+    return unit
+
+
+def _read_physical_pixel_sizes(
+    img: BioImage,
+) -> tuple[float, float, float, str | None, bool]:
+    pps = getattr(img, "physical_pixel_sizes", None)
+    if pps is None:
+        return 1.0, 1.0, 1.0, None, False
+
+    vx = getattr(pps, "X", None) or getattr(pps, "x", None)
+    vy = getattr(pps, "Y", None) or getattr(pps, "y", None)
+    vz = getattr(pps, "Z", None) or getattr(pps, "z", None)
+
+    if vx is None and vy is None and vz is None:
+        return 1.0, 1.0, 1.0, None, False
+
+    try:
+        psize_x = float(vx or 1.0)
+        psize_y = float(vy or 1.0)
+        psize_z = float(vz or 1.0)
+    except Exception:
+        return 1.0, 1.0, 1.0, None, False
+
+    unit = getattr(pps, "unit", None) or getattr(pps, "units", None)
+    unit = _normalize_unit(str(unit)) if unit is not None else None
+
+    return psize_x, psize_y, psize_z, unit, True
+
+
+def _load_zarr_attrs(zarr_path: Path) -> dict:
+    zarr_json = zarr_path / "zarr.json"
+    if zarr_json.exists():
+        try:
+            data = json.loads(zarr_json.read_text())
+            return data.get("attributes") or data.get("attrs") or {}
+        except Exception:
+            return {}
+    zattrs = zarr_path / ".zattrs"
+    if zattrs.exists():
+        try:
+            return json.loads(zattrs.read_text())
+        except Exception:
+            return {}
+    return {}
+
+
+def _extract_multiscales(attrs: dict) -> list[dict]:
+    if not isinstance(attrs, dict):
+        return []
+    ome = attrs.get("ome")
+    if isinstance(ome, dict) and isinstance(ome.get("multiscales"), list):
+        return ome["multiscales"]
+    if isinstance(attrs.get("multiscales"), list):
+        return attrs["multiscales"]
+    return []
+
+
+def _read_ngff_scale(zarr_path: Path) -> tuple[float, float, float, str | None] | None:
+    zarr_root = zarr_path
+    for parent in [zarr_path, *list(zarr_path.parents)]:
+        if parent.suffix.lower() in {".zarr", ".ome.zarr"}:
+            zarr_root = parent
+            break
+
+    for candidate in (zarr_path, zarr_root):
+        attrs = _load_zarr_attrs(candidate)
+        multiscales = _extract_multiscales(attrs)
+        if multiscales:
+            break
+    else:
+        return None
+
+    ms = multiscales[0]
+    axes = ms.get("axes") or []
+    datasets = ms.get("datasets") or []
+    if not axes or not datasets:
+        return None
+
+    ds = next((d for d in datasets if str(d.get("path")) == "0"), datasets[0])
+    cts = ds.get("coordinateTransformations") or []
+    scale_ct = next((ct for ct in cts if ct.get("type") == "scale"), None)
+    if not scale_ct:
+        return None
+
+    scale = scale_ct.get("scale") or []
+    if len(scale) != len(axes):
+        return None
+
+    axis_scale: dict[str, float] = {}
+    axis_unit: dict[str, str] = {}
+    for i, ax in enumerate(axes):
+        name = str(ax.get("name", "")).lower()
+        if name in {"x", "y", "z"}:
+            try:
+                axis_scale[name] = float(scale[i])
+            except Exception:
+                continue
+            unit = _normalize_unit(ax.get("unit"))
+            if unit:
+                axis_unit[name] = unit
+
+    if not axis_scale:
+        return None
+
+    psize_x = axis_scale.get("x", 1.0)
+    psize_y = axis_scale.get("y", 1.0)
+    psize_z = axis_scale.get("z", 1.0)
+
+    units = [axis_unit.get(a) for a in ("x", "y", "z") if axis_unit.get(a)]
+    unit = units[0] if units and len(set(units)) == 1 else None
+
+    return psize_x, psize_y, psize_z, unit
+
+
 def to_ome_arrow(
     type_: str = OME_ARROW_TAG_TYPE,
     version: str = OME_ARROW_TAG_VERSION,
@@ -337,13 +561,8 @@ def from_tiff(
     if size_x <= 0 or size_y <= 0:
         raise ValueError("Image must have positive Y and X dims.")
 
-    pps = getattr(img, "physical_pixel_sizes", None)
-    try:
-        psize_x = float(getattr(pps, "X", None) or 1.0)
-        psize_y = float(getattr(pps, "Y", None) or 1.0)
-        psize_z = float(getattr(pps, "Z", None) or 1.0)
-    except Exception:
-        psize_x = psize_y = psize_z = 1.0
+    psize_x, psize_y, psize_z, unit, _pps_valid = _read_physical_pixel_sizes(img)
+    psize_unit = unit or "µm"
 
     # --- NEW: coerce top-level strings --------------------------------
     img_id = str(image_id or p.stem)
@@ -393,7 +612,7 @@ def from_tiff(
         physical_size_x=psize_x,
         physical_size_y=psize_y,
         physical_size_z=psize_z,
-        physical_size_unit="µm",
+        physical_size_unit=psize_unit,
         channels=channels,
         planes=planes,
         masks=None,
@@ -409,6 +628,20 @@ def from_stack_pattern_path(
     image_id: Optional[str] = None,
     name: Optional[str] = None,
 ) -> pa.StructScalar:
+    """Build an OME-Arrow record from a filename pattern describing a stack.
+
+    Args:
+        pattern_path: Path or pattern string describing the stack layout.
+        default_dim_for_unspecified: Dimension to use when tokens lack a dim.
+        map_series_to: Dimension to map series tokens to (e.g., "T"), or None.
+        clamp_to_uint16: Whether to clamp pixel values to uint16.
+        channel_names: Optional list of channel names to apply.
+        image_id: Optional image identifier override.
+        name: Optional display name override.
+
+    Returns:
+        A validated OME-Arrow StructScalar describing the stack.
+    """
     path = Path(pattern_path)
     folder = path.parent
     line = path.name.strip()
@@ -740,13 +973,15 @@ def from_ome_zarr(
     if size_x <= 0 or size_y <= 0:
         raise ValueError("Image must have positive Y and X dimensions.")
 
-    pps = getattr(img, "physical_pixel_sizes", None)
-    try:
-        psize_x = float(getattr(pps, "X", None) or 1.0)
-        psize_y = float(getattr(pps, "Y", None) or 1.0)
-        psize_z = float(getattr(pps, "Z", None) or 1.0)
-    except Exception:
-        psize_x = psize_y = psize_z = 1.0
+    psize_x, psize_y, psize_z, unit, pps_valid = _read_physical_pixel_sizes(img)
+    psize_unit = unit or "µm"
+
+    if not pps_valid:
+        ngff_scale = _read_ngff_scale(p)
+        if ngff_scale is not None:
+            psize_x, psize_y, psize_z, unit = ngff_scale
+            if unit:
+                psize_unit = unit
 
     img_id = str(image_id or p.stem)
     display_name = str(name or p.name)
@@ -804,7 +1039,7 @@ def from_ome_zarr(
         physical_size_x=psize_x,
         physical_size_y=psize_y,
         physical_size_z=psize_z,
-        physical_size_unit="µm",
+        physical_size_unit=psize_unit,
         channels=channels,
         planes=planes,
         masks=None,
@@ -818,115 +1053,72 @@ def from_ome_parquet(
     row_index: int = 0,
     strict_schema: bool = False,
 ) -> pa.StructScalar:
-    """
-    Read an OME-Arrow record from a Parquet file and return a typed StructScalar.
-
-    Expected layout (as produced by `to_ome_parquet`):
-      - single Parquet file
-      - a single column (default name "ome_arrow") of `OME_ARROW_STRUCT` type
-      - one row (row_index=0)
+    """Read an OME-Arrow record from a Parquet file.
 
-    This function is forgiving:
-      - If `column_name` is None or not found, it will auto-detect a struct column
-        that matches the OME-Arrow field names.
-      - If the table has multiple rows, you can choose which record to read
-        via `row_index`.
+    Args:
+        parquet_path: Path to the Parquet file.
+        column_name: Column to read; auto-detected when None or invalid.
+        row_index: Row index to extract.
+        strict_schema: Require the exact OME-Arrow schema if True.
 
-    Parameters
-    ----------
-    parquet_path : str | Path
-        Path to the .parquet file.
-    column_name : Optional[str], default "ome_arrow"
-        Name of the column that stores the OME-Arrow struct. If None, auto-detect.
-    row_index : int, default 0
-        Which row to read if the table contains multiple rows.
-    strict_schema : bool, default False
-        If True, require the column's type to equal `OME_ARROW_STRUCT` exactly.
-        If False, we only require the column to be a Struct with the same field
-        names (order can vary).
+    Returns:
+        A typed OME-Arrow StructScalar.
 
-    Returns
-    -------
-    pa.StructScalar
-        A validated OME-Arrow struct scalar.
-
-    Raises
-    ------
-    FileNotFoundError
-        If the file does not exist.
-    ValueError
-        If a suitable column/row cannot be found or schema checks fail.
+    Raises:
+        FileNotFoundError: If the Parquet path does not exist.
+        ValueError: If the row index is out of range or no suitable column exists.
     """
     p = Path(parquet_path)
     if not p.exists():
         raise FileNotFoundError(f"No such file: {p}")
 
     table = pq.read_table(p)
+    return _ome_arrow_from_table(
+        table,
+        column_name=column_name,
+        row_index=row_index,
+        strict_schema=strict_schema,
+    )
 
-    if table.num_rows == 0:
-        raise ValueError("Parquet file contains 0 rows; expected at least 1.")
-    if not (0 <= row_index < table.num_rows):
-        raise ValueError(f"row_index {row_index} out of range [0, {table.num_rows}).")
-
-    # 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}
-        col_fields = {f.name for f in t}
-        return ome_fields == col_fields
 
-    candidate_col = None
+def from_ome_vortex(
+    vortex_path: str | Path,
+    *,
+    column_name: Optional[str] = "ome_arrow",
+    row_index: int = 0,
+    strict_schema: bool = False,
+) -> pa.StructScalar:
+    """Read an OME-Arrow record from a Vortex file.
 
-    if column_name is not None and column_name in table.column_names:
-        arr = table[column_name]
-        if not pa.types.is_struct(arr.type):
-            raise ValueError(f"Column '{column_name}' is not a Struct; got {arr.type}.")
-        if strict_schema and arr.type != OME_ARROW_STRUCT:
-            raise ValueError(
-                f"Column '{column_name}' schema != OME_ARROW_STRUCT.\n"
-                f"Got:   {arr.type}\n"
-                f"Expect:{OME_ARROW_STRUCT}"
-            )
-        if not strict_schema and not _struct_matches_ome_fields(arr.type):
-            raise ValueError(
-                f"Column '{column_name}' does not have the expected OME-Arrow fields."
-            )
-        candidate_col = arr
-    else:
-        # Auto-detect a struct column that matches OME-Arrow fields
-        for name in table.column_names:
-            arr = table[name]
-            if pa.types.is_struct(arr.type):
-                if strict_schema and arr.type == OME_ARROW_STRUCT:
-                    candidate_col = arr
-                    column_name = name
-                    break
-                if not strict_schema and _struct_matches_ome_fields(arr.type):
-                    candidate_col = arr
-                    column_name = name
-                    break
-        if candidate_col is None:
-            if column_name is None:
-                hint = "no struct column with OME-Arrow fields was found."
-            else:
-                hint = f"column '{column_name}' not found and auto-detection failed."
-            raise ValueError(f"Could not locate an OME-Arrow struct column: {hint}")
+    Args:
+        vortex_path: Path to the Vortex file.
+        column_name: Column to read; auto-detected when None or invalid.
+        row_index: Row index to extract.
+        strict_schema: Require the exact OME-Arrow schema if True.
 
-    # 2) Extract the row as a Python dict
-    #    (Using to_pylist() for the single element slice is simple & reliable.)
-    record_dict: Dict[str, Any] = candidate_col.slice(row_index, 1).to_pylist()[0]
+    Returns:
+        A typed OME-Arrow StructScalar.
 
-    # 3) Reconstruct a typed StructScalar using the canonical schema
-    #    (this validates field names/types and normalizes order)
-    scalar = pa.scalar(record_dict, type=OME_ARROW_STRUCT)
+    Raises:
+        FileNotFoundError: If the Vortex path does not exist.
+        ImportError: If the optional `vortex-data` dependency is missing.
+        ValueError: If the row index is out of range or no suitable column exists.
+    """
+    p = Path(vortex_path)
+    if not p.exists():
+        raise FileNotFoundError(f"No such file: {p}")
 
-    # Optional: soft validation via file-level metadata (if present)
     try:
-        meta = table.schema.metadata or {}
-        meta.get(b"ome.arrow.type", b"").decode() == str(
-            OME_ARROW_TAG_TYPE
-        ) and meta.get(b"ome.arrow.version", b"").decode() == str(OME_ARROW_TAG_VERSION)
-        # You could log/print a warning if tag_ok is False, but don't fail.
-    except Exception:
-        pass
-
-    return scalar
+        import vortex
+    except ImportError as exc:
+        raise ImportError(
+            "Vortex support requires the optional 'vortex-data' dependency."
+        ) from exc
+
+    table = vortex.open(str(p)).to_arrow().read_all()
+    return _ome_arrow_from_table(
+        table,
+        column_name=column_name,
+        row_index=row_index,
+        strict_schema=strict_schema,
+    )

ome_arrow/view.py

@@ -2,16 +2,27 @@
 Viewing utilities for OME-Arrow data.
 """
 
+from __future__ import annotations
+
 import contextlib
+import warnings
+from typing import TYPE_CHECKING
 
 import matplotlib.pyplot as plt
 import numpy as np
 import pyarrow as pa
-import pyvista as pv
 from matplotlib.axes import Axes
 from matplotlib.figure import Figure
 from matplotlib.image import AxesImage
 
+try:  # optional dependency
+    import pyvista as pv
+except ImportError:  # pragma: no cover - exercised when viz extra missing
+    pv = None  # type: ignore[assignment]
+
+if TYPE_CHECKING:
+    import pyvista
+
 
 def view_matplotlib(
     data: dict[str, object] | pa.StructScalar,
@@ -22,6 +33,23 @@ def view_matplotlib(
     cmap: str = "gray",
     show: bool = True,
 ) -> tuple[Figure, Axes, AxesImage]:
+    """Render a single (t, c, z) plane with Matplotlib.
+
+    Args:
+        data: OME-Arrow row or dict containing pixels_meta and planes.
+        tcz: (t, c, z) indices of the plane to render.
+        autoscale: If True, infer vmin/vmax from the image data.
+        vmin: Explicit lower display limit for intensity scaling.
+        vmax: Explicit upper display limit for intensity scaling.
+        cmap: Matplotlib colormap name.
+        show: Whether to display the plot immediately.
+
+    Returns:
+        A tuple of (figure, axes, image) from Matplotlib.
+
+    Raises:
+        ValueError: If the requested plane is missing or pixel sizes mismatch.
+    """
     if isinstance(data, pa.StructScalar):
         data = data.as_py()
 
@@ -63,6 +91,21 @@ def view_matplotlib(
     return fig, ax, im
 
 
+def _require_pyvista() -> "pyvista":
+    """
+    Ensure PyVista is available, raising a helpful error otherwise.
+    """
+    if pv is None:
+        msg = (
+            "PyVista-based visualization requires the optional 'viz' extras. "
+            "Install with `pip install ome-arrow[viz]` to enable 3D viewing."
+        )
+        warnings.warn(msg, RuntimeWarning)
+        raise RuntimeError(msg)
+
+    return pv
+
+
 def view_pyvista(
     data: dict | pa.StructScalar,
     c: int = 0,
@@ -77,16 +120,14 @@ def view_pyvista(
     percentile_clim: tuple[float, float] = (1.0, 99.9),  # robust contrast
     sampling_scale: float = 0.5,  # smaller = denser rays (sharper, slower)
     show: bool = True,
-) -> pv.Plotter:
+) -> "pyvista.Plotter":
     """
     Jupyter-inline interactive volume view using PyVista backends.
     Tries 'trame' → 'html' → 'static' when backend='auto'.
 
     sampling_scale controls ray step via the mapper after add_volume.
     """
-    import warnings
-
-    import numpy as np
+    pv = _require_pyvista()
 
     # ---- unwrap OME-Arrow row
     row = data.as_py() if isinstance(data, pa.StructScalar) else data

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ome-arrow
-Version: 0.0.3
+Version: 0.0.5
 Summary: Using OME specifications with Apache Arrow for fast, queryable, and language agnostic bioimage data.
 Author: Dave Bunten
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -16,25 +16,29 @@ Requires-Dist: bioio-ome-tiff>=1.4
 Requires-Dist: bioio-ome-zarr>=3.0.3
 Requires-Dist: bioio-tifffile>=1.3
 Requires-Dist: fire>=0.7
-Requires-Dist: ipywidgets>=8.1.8
-Requires-Dist: jupyterlab-widgets>=3.0.16
 Requires-Dist: matplotlib>=3.10.7
 Requires-Dist: numpy>=2.2.6
 Requires-Dist: pandas>=2.2.3
 Requires-Dist: pillow>=12
 Requires-Dist: pyarrow>=22
-Requires-Dist: pyvista>=0.46.4
-Requires-Dist: trame>=3.12
-Requires-Dist: trame-vtk>=2.10
-Requires-Dist: trame-vuetify>=3.1
+Provides-Extra: viz
+Requires-Dist: ipywidgets>=8.1.8; extra == "viz"
+Requires-Dist: jupyterlab-widgets>=3.0.16; extra == "viz"
+Requires-Dist: pyvista>=0.46.4; extra == "viz"
+Requires-Dist: trame>=3.12; extra == "viz"
+Requires-Dist: trame-vtk>=2.10; extra == "viz"
+Requires-Dist: trame-vuetify>=3.1; extra == "viz"
+Provides-Extra: vortex
+Requires-Dist: vortex-data>=0.56; extra == "vortex"
 Dynamic: license-file
 
-<img height="200" src="https://raw.githubusercontent.com/wayscience/ome-arrow/main/docs/src/_static/logo.png?raw=true">
+<img width="600" src="https://raw.githubusercontent.com/wayscience/ome-arrow/main/docs/src/_static/logo.png?raw=true">
 
 ![PyPI - Version](https://img.shields.io/pypi/v/ome-arrow)
 [![Build Status](https://github.com/wayscience/ome-arrow/actions/workflows/run-tests.yml/badge.svg?branch=main)](https://github.com/wayscience/ome-arrow/actions/workflows/run-tests.yml?query=branch%3Amain)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Software DOI badge](https://zenodo.org/badge/DOI/10.5281/zenodo.17664969.svg)](https://doi.org/10.5281/zenodo.17664969)
 
 # Open, interoperable, and queryable microscopy images with OME Arrow
 
@@ -52,6 +56,13 @@ OME Arrow enables image data to be stored alongside metadata or derived data suc
 Images in OME Arrow are composed of mutlilayer [structs](https://arrow.apache.org/docs/python/generated/pyarrow.struct.html) so they may be stored as values within tables.
 This means you can store, query, and build relationships on data from the same location using any system which is compatible with Apache Arrow (including Parquet) through common data interfaces (such as SQL and DuckDB).
 
+## Project focus
+
+This package is intentionally dedicated to work at a per-image level and not large batch handling (though it may be used for those purposes by users or in other projects).
+
+- For visualizing OME Arrow and OME Parquet data in Napari, please see the [`napari-ome-arrow`](https://github.com/WayScience/napari-ome-arrow) Napari plugin.
+- For more comprehensive handling of many images and features in the context of the OME Parquet format please see the [`CytoDataFrame`](https://github.com/cytomining/CytoDataFrame) project (and relevant [example notebook](https://github.com/cytomining/CytoDataFrame/blob/main/docs/src/examples/cytodataframe_at_a_glance.ipynb)).
+
 ## Installation
 
 Install OME Arrow from PyPI or from source:
@@ -89,12 +100,15 @@ oa_image.info()
 oa_image.view(how="matplotlib")
 
 # Display the image with pyvista
-# (great for ZYX 3D images).
+# (great for ZYX 3D images; install extras: `pip install 'ome-arrow[viz]'`).
 oa_image.view(how="pyvista")
 
 # Export to OME-Parquet.
 # We can also export OME-TIFF, OME-Zarr or NumPy arrays.
 oa_image.export(how="ome-parquet", out="your_image.ome.parquet")
+
+# Export to Vortex (install extras: `pip install 'ome-arrow[vortex]'`).
+oa_image.export(how="vortex", out="your_image.vortex")
 ```
 
 ## Contributing, Development, and Testing
@@ -107,5 +121,5 @@ OME Arrow is used or inspired by the following projects, check them out!
 
 - [`napari-ome-arrow`](https://github.com/WayScience/napari-ome-arrow): enables you to view OME Arrow and related images.
 - [`nViz`](https://github.com/WayScience/nViz): focuses on ingesting and visualizing various 3D image data.
-- [`CytoDataFrame`](https://github.com/cytomining/CytoDataFrame): provides a DataFrame-like experience for viewing feature and microscopy image data within Jupyter notebook interfaces.
+- [`CytoDataFrame`](https://github.com/cytomining/CytoDataFrame): provides a DataFrame-like experience for viewing feature and microscopy image data within Jupyter notebook interfaces and creating OME Parquet files.
 - [`coSMicQC`](https://github.com/cytomining/coSMicQC): performs quality control on microscopy feature datasets, visualized using CytoDataFrames.

ome_arrow-0.0.5.dist-info/RECORD

@@ -0,0 +1,14 @@
+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,,

ome_arrow-0.0.3.dist-info/RECORD

@@ -1,14 +0,0 @@
-ome_arrow/__init__.py,sha256=DfQsw8l0mx1Qt3YiiMv2SUljKETP3wS5hrD5eBbjMDM,583
-ome_arrow/_version.py,sha256=pBZsQt6tlL02W-ri--X_4JCubpAK7jjCSnOmUp_isjc,704
-ome_arrow/core.py,sha256=NUCV9KUH3yCOlpetRS5NNVG_phodutE1F2ujDBPhHgY,18351
-ome_arrow/export.py,sha256=CCTnEdHko4Z0i5LEHuNGFLznWSsPyAFcS42H5nHU22Q,14875
-ome_arrow/ingest.py,sha256=zZz94LaLOpmoxnryLeoPsaWV0EzkYkGFizYSVcbd5w8,33016
-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=DT8i56uV8Rw22KkqwjPPPKWJWNtfgR9OkI8Qj1WD8Ds,9355
-ome_arrow-0.0.3.dist-info/licenses/LICENSE,sha256=9-2Pyhu3vTt2RJU8DorHQtHeNO_e5RLeFJTyOU4hOi4,1508
-ome_arrow-0.0.3.dist-info/METADATA,sha256=VrhOZ3ENlUTdd3smTk_pCN8ptbuZJbhDwuCxdLu8UDc,4910
-ome_arrow-0.0.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ome_arrow-0.0.3.dist-info/top_level.txt,sha256=aWOtkGXo_pfU-yy82guzGhz8Zh2h2nFl8Kc5qdzMGuE,10
-ome_arrow-0.0.3.dist-info/RECORD,,