Spacelab 0.28.0__py3-none-any.whl

spacelab/prep_spatialdata.py

@@ -0,0 +1,700 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["zarr>=3", "numcodecs", "numpy", "pillow", "pyarrow", "shapely>=2"]
+# ///
+"""Make a SpatialData store fast to open in the app.
+
+The app reads SpatialData stores (manifest `dataSourceType: "spatialData"`)
+without conversion, but cell outlines (GeoParquet WKB) and transcripts (one
+unsorted table of every detection) are slow to read in a browser. This adds
+sidecars next to the SpatialData files, in the same layouts the app's own
+format uses, and leaves every SpatialData file untouched:
+
+  images/<image>/                checked: must be a multiscale pyramid viv tiles
+  images/thumbnail.png           landing-page card preview
+  shapes/<shapes>/shapes.zarr    polygon_vertices + polygon_offset attr (zarr v3 group)
+  points/<points>/points.zarr    Hilbert LOD store (spacelab.hlod), streamed by viewport
+  tables/<table>/X               checked: must be dense or CSC (reported, never rewritten)
+  ../tissue-set-manifest.json    default entry for this store, added if its key is absent
+
+    uv run data/prep_spatialdata.py <name>.zarr     # one store
+    uv run data/prep_spatialdata.py <directory>     # every SpatialData .zarr in it
+
+Sidecar coordinates stay in each element's own units (µm for Xenium), as the
+standard format's do; the app maps them to image pixels with the element's
+SpatialData transform. Cells are written in the order the app indexes them
+(table order when the table joins the shapes; see src/spatialdata/cells.ts).
+
+Standalone (not part of prep_xenium_data.py) because SpatialData writes zarr v3
+and the prep environment pins zarr<3. shapes.zarr and points.zarr are zarr v3; points.zarr
+uses sharding.
+"""
+
+import argparse
+import json
+import math
+import os
+import shutil
+import sys
+
+import numpy as np
+import pyarrow as pa
+import pyarrow.parquet as pq
+import shapely
+import zarr
+from PIL import Image
+from zarr.codecs import BloscCodec
+
+
+class PrepError(Exception):
+    pass
+
+
+# --- shared helpers ---
+
+def _ome(attrs) -> dict:
+    """NGFF 0.5 (zarr v3) nests image metadata under `ome`; 0.4 has it top-level."""
+    return attrs.get("ome", attrs)
+
+
+def _replace_dir(tmp: str, final: str):
+    """Swap a finished sidecar in, so a failed run never leaves a half-written
+    one where the app would read it."""
+    if os.path.exists(final):
+        shutil.rmtree(final)
+    os.rename(tmp, final)
+
+
+# --- 1. image: a pyramid viv can tile ---
+
+# zarrita's codec registry (node_modules/zarrita/dist/src/codecs.js).
+ZARRITA_CODECS = {
+    "blosc", "lz4", "zstd", "gzip", "zlib", "transpose", "bytes", "crc32c", "sharding_indexed",
+}
+# viv's DTYPE_LOOKUP, in numpy names.
+VIV_DTYPES = {"uint8", "uint16", "uint32", "int8", "int16", "int32", "float32", "float64"}
+VIV_AXES = {"t", "c", "z", "y", "x"}
+# viv's tile edge is level 0's chunk edge; bigger tiles still render, but every
+# fetch moves a whole tile (4096² uint16 is 32 MB per channel).
+LARGE_TILE = 1024
+
+
+def _codec_names(arr) -> list[str]:
+    meta = arr.metadata.to_dict()
+    if meta.get("zarr_format") == 2:
+        comp = meta.get("compressor")
+        return [comp["id"]] if comp else []
+    names = []
+    for codec in meta.get("codecs", []):
+        names.append(codec["name"])
+        if codec["name"] == "sharding_indexed":
+            names += [c["name"] for c in codec["configuration"].get("codecs", [])]
+    return names
+
+
+def check_viv_image(image) -> dict:
+    """Raise PrepError unless `image` is a multiscale OME-Zarr that viv's
+    loadOmeZarr opens and MultiscaleImageLayer tiles at more than one level.
+    Mirrors @vivjs/loaders: datasets from multiscales[0], labels from axes, tile
+    size = prevPowerOf2(min(level-0 y/x chunk)), and a last dim of 3 or 4
+    read as interleaved RGB."""
+    ms_list = _ome(dict(image.attrs)).get("multiscales")
+    if not ms_list:
+        raise PrepError("no `multiscales` metadata: not an OME-Zarr image")
+    ms = ms_list[0]
+    paths = [d["path"] for d in ms.get("datasets", [])]
+    if len(paths) < 2:
+        raise PrepError(f"{len(paths)} resolution level(s): viv needs a pyramid to tile zoom levels")
+
+    axes = [a if isinstance(a, str) else a.get("name") for a in ms.get("axes", [])]
+    if not axes:
+        raise PrepError("multiscales has no `axes`")
+    if len(set(axes)) != len(axes) or not set(axes) <= VIV_AXES:
+        raise PrepError(f"axes {axes} are not unique names from {sorted(VIV_AXES)}")
+    if axes[-2:] != ["y", "x"]:
+        raise PrepError(f"axes {axes} must end in y, x")
+
+    levels = []
+    for p in paths:
+        if p not in image:
+            raise PrepError(f"level '{p}' listed in multiscales is missing")
+        arr = image[p]
+        if arr.ndim != len(axes):
+            raise PrepError(f"level '{p}' has {arr.ndim} dims for {len(axes)} axes")
+        if str(arr.dtype) not in VIV_DTYPES:
+            raise PrepError(f"level '{p}' dtype {arr.dtype} is not one viv renders")
+        bad = [c for c in _codec_names(arr) if c not in ZARRITA_CODECS]
+        if bad:
+            raise PrepError(f"level '{p}' uses codecs {bad} the browser reader can't decode")
+        if arr.shape[-1] in (3, 4):
+            raise PrepError(f"level '{p}' is {arr.shape[-1]} px wide; viv would read it as RGB")
+        levels.append(arr)
+
+    for k in range(1, len(levels)):
+        for dim, name in ((-2, "height"), (-1, "width")):
+            prev, cur = levels[k - 1].shape[dim], levels[k].shape[dim]
+            if abs(cur - prev / 2) > 1:
+                raise PrepError(
+                    f"level '{paths[k]}' {name} {cur} is not half of '{paths[k - 1]}' ({prev}); "
+                    "viv assumes each level downsamples by 2"
+                )
+        for i, name in enumerate(axes[:-2]):
+            if levels[k].shape[i] != levels[0].shape[i]:
+                raise PrepError(f"level '{paths[k]}' changes the size of non-spatial axis '{name}'")
+
+    chunk_y, chunk_x = levels[0].chunks[-2:]
+    tile = 2 ** math.floor(math.log2(min(chunk_y, chunk_x)))
+    warnings = []
+    if tile > LARGE_TILE:
+        warnings.append(
+            f"level-0 chunks are {chunk_y}x{chunk_x}, so viv fetches {tile}px tiles; "
+            f"rechunking to <= {LARGE_TILE} would make zooming faster"
+        )
+    if chunk_y != chunk_x or chunk_y != tile:
+        warnings.append(
+            f"level-0 chunks {chunk_y}x{chunk_x} aren't square powers of 2; each {tile}px tile "
+            "read spans several chunks"
+        )
+    return {
+        "levels": [{"path": p, "shape": list(a.shape)} for p, a in zip(paths, levels)],
+        "axes": axes,
+        "dtype": str(levels[0].dtype),
+        "tile_size": tile,
+        "warnings": warnings,
+    }
+
+
+# --- 2. thumbnail ---
+
+THUMB_OUT_DIM = 512
+THUMB_MIN_DIM = 512
+THUMB_MAX_DIM = 2048
+THUMB_MAX_CHANNELS = 4
+THUMB_LO_PCT = 25.0
+THUMB_HI_PCT = 99.9
+THUMB_TARGET_LUM = 0.22
+THUMB_GAMMA_RANGE = (0.7, 2.2)
+THUMB_MIN_REL_SIGNAL = 0.02
+# CHANNEL_DEFAULT_COLORS in src/config/constants.ts
+THUMB_TINTS = np.array(
+    [[0, 26, 255], [0, 255, 0], [255, 0, 255], [255, 255, 0], [0, 255, 255], [255, 0, 0]],
+    dtype=np.float32,
+) / 255.0
+
+
+def _pick_thumb_level(image) -> str:
+    """Smallest pyramid level still >= THUMB_MIN_DIM across, skipping any larger
+    than THUMB_MAX_DIM so a shallow pyramid can't make us decompress a whole slide."""
+    paths = [d["path"] for d in _ome(dict(image.attrs))["multiscales"][0]["datasets"]]
+    levels = [(p, max(image[p].shape[-2:])) for p in paths]
+    usable = [lv for lv in levels if lv[1] <= THUMB_MAX_DIM] or [min(levels, key=lambda lv: lv[1])]
+    big_enough = [lv for lv in usable if lv[1] >= THUMB_MIN_DIM]
+    if big_enough:
+        return min(big_enough, key=lambda lv: lv[1])[0]
+    return max(usable, key=lambda lv: lv[1])[0]
+
+
+def render_thumbnail(image) -> Image.Image:
+    """Follows prep_xenium_data._render_thumbnail: tinted channels max-composited
+    rather than summed (summing saturates co-stained tissue to white), a
+    per-channel percentile stretch, and an auto-gamma that puts median tissue
+    brightness at a fixed target. Tints are the app's default channel colors, so
+    the card matches what the viewer opens with."""
+    arr = image[_pick_thumb_level(image)]
+    planes = np.asarray(arr[...]).reshape(-1, *arr.shape[-2:])  # [c, y, x], any leading axes
+    layers = []
+    for i in range(min(planes.shape[0], THUMB_MAX_CHANNELS)):
+        plane = planes[i].astype(np.float32)
+        lo = float(np.percentile(plane, THUMB_LO_PCT))
+        hi = float(np.percentile(plane, THUMB_HI_PCT))
+        if hi <= lo:
+            hi = lo + 1.0
+        layers.append((plane, lo, hi, THUMB_TINTS[i % len(THUMB_TINTS)]))
+
+    # A blank channel's noise floor, stretched to full range, washes the frame in
+    # its tint; drop channels whose range is negligible next to the widest.
+    if len(layers) > 1:
+        widest = max(hi - lo for _, lo, hi, _ in layers)
+        layers = [lay for lay in layers if lay[2] - lay[1] >= THUMB_MIN_REL_SIGNAL * widest] or layers
+
+    h, w = planes.shape[-2:]
+    rgb = np.zeros((h, w, 3), dtype=np.float32)
+    for plane, lo, hi, tint in layers:
+        norm = np.clip((plane - lo) / (hi - lo), 0.0, 1.0)
+        np.maximum(rgb, norm[:, :, None] * tint[None, None, :], out=rgb)
+
+    signal = rgb.max(axis=2)
+    signal = signal[signal > 0.02]
+    if signal.size:
+        median = float(np.median(signal))
+        if 0.01 < median < 0.99:
+            rgb **= float(np.clip(np.log(THUMB_TARGET_LUM) / np.log(median), *THUMB_GAMMA_RANGE))
+
+    img = Image.fromarray(np.clip(rgb * 255.0, 0, 255).astype(np.uint8))
+    if max(img.size) > THUMB_OUT_DIM:
+        scale = THUMB_OUT_DIM / max(img.size)
+        img = img.resize((max(1, int(img.width * scale)), max(1, int(img.height * scale))),
+                         Image.LANCZOS)
+    return img
+
+
+# --- 3. shapes -> shapes.zarr ---
+
+# Same cap as MAX_RING_VERTICES in src/spatialdata/wkbPolygons.ts: every cell
+# pays for the longest ring, so dense outlines are resampled down to this.
+MAX_RING_VERTICES = 64
+POLYGON_COMPRESSOR = BloscCodec(cname="lz4", clevel=5, shuffle="shuffle")
+POLYGON_CHUNK = 259606  # floats, as the standard prep writes cells/uns/polygon_vertices
+
+
+def _pandas_index_column(schema: pa.Schema) -> str | None:
+    meta = json.loads((schema.metadata or {}).get(b"pandas", b"{}"))
+    cols = meta.get("index_columns") or []
+    return cols[0] if cols and isinstance(cols[0], str) else None
+
+
+def _as_str(values) -> np.ndarray:
+    # zarr 3 hands back numpy StringDType, which won't cast to fixed-width str.
+    return np.array([str(v) for v in values], dtype=object)
+
+
+def _read_string_column(obs, name: str) -> np.ndarray:
+    """An anndata obs column as strings: a plain string array, a categorical group
+    of categories + codes, or a nullable-string-array group of values + mask
+    (newer anndata). Missing entries become ""."""
+    node = obs[name]
+    if isinstance(node, zarr.Group):
+        if node.attrs.get("encoding-type") == "nullable-string-array":
+            values = _as_str(node["values"][...])
+            values[np.asarray(node["mask"][...], dtype=bool)] = ""
+            return values
+        cats = np.append(_as_str(node["categories"][...]), "")
+        return cats[np.asarray(node["codes"][...])]  # code -1 (missing) -> ""
+    return _as_str(node[...])
+
+
+def _column_length(node) -> int:
+    """Rows of an anndata column: an array, or a group encoding (categorical:
+    codes; nullable-*: values)."""
+    if isinstance(node, zarr.Array):
+        return node.shape[0]
+    for child in ("codes", "values"):
+        if child in node:
+            return node[child].shape[0]
+    raise PrepError(f"unsupported anndata column encoding {node.attrs.get('encoding-type')!r}")
+
+
+def _cell_order(root, shapes_index_col, shapes_ids, n_shapes, table):
+    """Destination slot for every shape row and the cell count, under the same
+    rules as resolveCellsLayout in src/spatialdata/cells.ts: join on the shapes'
+    index column when the table has it, by row order when only the lengths
+    match, else unjoined (cells are the shapes). Returns (dest | None, n_cells,
+    description, join); dest[i] = -1 drops shape i, None keeps shapes order. `join`
+    is the CellJoin the app would derive, recorded so it needn't read the parquet."""
+    if not table:
+        return None, n_shapes, "shapes order (no table)", {"mode": "none"}
+    tbl = root["tables"][table]
+    region = tbl.attrs.get("region")
+    if isinstance(region, list) and len(region) > 1:
+        return (None, n_shapes, f"shapes order (table '{table}' annotates {len(region)} regions)",
+                {"mode": "none"})
+    obs = tbl["obs"]
+    index_name = obs.attrs.get("_index", "_index")
+    n_obs = _column_length(obs[index_name]) if index_name in obs else 0
+    if n_obs == 0:
+        return None, n_shapes, "shapes order (empty table)", {"mode": "none"}
+    columns = obs.attrs.get("column-order", [])
+    if shapes_index_col and shapes_index_col in columns:
+        table_ids = _read_string_column(obs, shapes_index_col)
+        if n_shapes == n_obs and np.array_equal(shapes_ids, table_ids):
+            return (None, n_obs, f"table order (= shapes order, by '{shapes_index_col}')",
+                    {"mode": "column", "column": shapes_index_col})
+        row_of = {cid: r for r, cid in enumerate(table_ids)}
+        dest = np.fromiter((row_of.get(cid, -1) for cid in shapes_ids), np.int64, n_shapes)
+        return (dest, n_obs, f"table order (joined on '{shapes_index_col}')",
+                {"mode": "column", "column": shapes_index_col})
+    if n_obs == n_shapes:
+        return (None, n_obs, "table order (assumed = shapes order: no shared id column)",
+                {"mode": "order"})
+    return None, n_shapes, f"shapes order (table '{table}' doesn't match the shapes)", {"mode": "none"}
+
+
+def _ring_coords(geoms: np.ndarray):
+    """Outer ring of each Polygon, or of a MultiPolygon's first polygon (as
+    outerRing in wkbPolygons.ts). Returns xy [n_pts, 2] and per-ring start /
+    length; empty or unsupported geometry gets length 0."""
+    types = shapely.get_type_id(geoms)
+    polys = np.where(types == 6, shapely.get_geometry(geoms, 0), geoms)
+    polys = np.where(shapely.get_type_id(polys) == 3, polys, None)
+    rings = shapely.get_exterior_ring(polys)
+    xy, ring_of = shapely.get_coordinates(rings, return_index=True)
+    lengths = np.bincount(ring_of, minlength=len(geoms))
+    starts = np.zeros(len(geoms), dtype=np.int64)
+    np.cumsum(lengths[:-1], out=starts[1:])
+    return xy, starts, lengths
+
+
+def flatten_rings(xy, starts, lengths, dest, n_cells):
+    """The app's fixed-stride layout: every ring closed (shapely rings already
+    are) and padded to the longest by repeating its closing vertex, or evenly
+    resampled when longer than MAX_RING_VERTICES — writeRing in wkbPolygons.ts.
+    Cells nobody writes stay NaN, which the polygon worker skips."""
+    n_verts = int(min(max(lengths.max(initial=0), 4), MAX_RING_VERTICES))
+    out = np.full((n_cells, n_verts, 2), np.nan, dtype=np.float32)
+    slots = np.arange(len(lengths)) if dest is None else dest
+    keep = (lengths > 0) & (slots >= 0) & (slots < n_cells)
+    i = np.arange(n_verts)
+    for lo in range(0, len(lengths), 100_000):
+        sel = np.nonzero(keep[lo:lo + 100_000])[0] + lo
+        if sel.size == 0:
+            continue
+        ln = lengths[sel][:, None]
+        # Math.round(i * (len - 1) / (nVerts - 1)) for long rings, JS rounding.
+        resampled = np.floor(i[None, :] * (ln - 1) / (n_verts - 1) + 0.5).astype(np.int64)
+        src = np.where(ln <= n_verts, np.minimum(i[None, :], ln - 1), resampled)
+        out[slots[sel]] = xy[starts[sel][:, None] + src]
+    n_missing = int(n_cells - np.unique(slots[keep]).size)
+    return out.reshape(-1), n_verts * 2, n_missing
+
+
+def write_shapes_group(path: str, vertices: np.ndarray, attrs: dict) -> None:
+    """The shapes.zarr sidecar: a zarr v3 group whose zarr.json carries `attrs`
+    (polygon_offset among them) and whose one array, `polygon_vertices`, is the
+    flat float32 [x0, y0, x1, y1, ...] of every cell's ring."""
+    if os.path.exists(path):
+        shutil.rmtree(path)
+    g = zarr.open_group(path, mode="w", zarr_format=3, attributes=attrs)
+    g.create_array("polygon_vertices", data=vertices.astype(np.float32, copy=False),
+                   chunks=(POLYGON_CHUNK,), compressors=POLYGON_COMPRESSOR)
+
+
+def write_shapes_zarr(root, store_path: str, shapes: str, table: str | None) -> dict:
+    parquet = os.path.join(store_path, "shapes", shapes, "shapes.parquet")
+    if not os.path.exists(parquet):
+        raise PrepError(f"shapes/{shapes}/shapes.parquet not found")
+    pf = pq.ParquetFile(parquet) if os.path.isfile(parquet) else None
+    schema = pf.schema_arrow if pf else pq.read_schema(next(
+        os.path.join(parquet, f) for f in sorted(os.listdir(parquet)) if f.endswith(".parquet")))
+    geo = json.loads((schema.metadata or {}).get(b"geo", b"{}"))
+    geom_col = geo.get("primary_column", "geometry")
+    index_col = _pandas_index_column(schema)
+    cols = [geom_col] + ([index_col] if index_col else [])
+    tbl = pq.read_table(parquet, columns=cols)
+
+    geoms = shapely.from_wkb(tbl.column(geom_col).to_numpy(zero_copy_only=False))
+    ids = _as_str(tbl.column(index_col).to_pylist()) if index_col else None
+    dest, n_cells, order, join = _cell_order(root, index_col, ids, len(geoms), table)
+    xy, starts, lengths = _ring_coords(geoms)
+    vertices, polygon_offset, n_missing = flatten_rings(xy, starts, lengths, dest, n_cells)
+
+    final = os.path.join(store_path, "shapes", shapes, "shapes.zarr")
+    tmp = final + ".tmp"
+    write_shapes_group(tmp, vertices, {
+        "polygon_offset": polygon_offset,
+        "number_cells": n_cells,
+        "cell_order": order,
+        "source_element": f"shapes/{shapes}",
+        "table": table if join["mode"] != "none" else None,
+        # What resolveCellsLayout would otherwise read from the parquet footer, so
+        # the app can lay cells out without touching shapes.parquet at all.
+        "join": join,
+        "n_shapes": len(geoms),
+        "shapes_index_column": index_col,
+        "spatial_units": "element",
+    })
+    _replace_dir(tmp, final)
+    return {"path": final, "n_cells": n_cells, "n_shapes": len(geoms),
+            "polygon_offset": polygon_offset, "cells_without_outline": n_missing,
+            "cell_order": order}
+
+
+# --- 4. points -> points.zarr ---
+
+# The Hilbert LOD store (spacelab.hlod; format in py/src/spacelab/hlod/build.py):
+# every transcript once, sorted by (gene, level, Hilbert index), which the app
+# streams by viewport instead of reading whole genes. Co-sorted extras, when the
+# points have them.
+POINTS_COLUMNS = ("qv", "cell_id")
+
+
+def _load_hlod():
+    """spacelab.hlod.build, from the bundled package (this file sits in spacelab/
+    when installed) or from the repo (data/ next to py/src/spacelab)."""
+    import importlib.util
+
+    here = os.path.dirname(os.path.abspath(__file__))
+    for pkg in (os.path.join(here, "hlod"),
+                os.path.join(here, os.pardir, "py", "src", "spacelab", "hlod")):
+        init = os.path.join(pkg, "__init__.py")
+        if os.path.isfile(init):
+            spec = importlib.util.spec_from_file_location(
+                "spacelab_hlod", init, submodule_search_locations=[pkg])
+            mod = importlib.util.module_from_spec(spec)
+            sys.modules["spacelab_hlod"] = mod
+            spec.loader.exec_module(mod)
+            return importlib.import_module("spacelab_hlod.build")
+    raise PrepError("spacelab.hlod not found next to prep_spatialdata.py (broken install?)")
+
+
+def write_points_zarr(root, store_path: str, points: str) -> dict:
+    parquet = os.path.join(store_path, "points", points, "points.parquet")
+    if not os.path.exists(parquet):
+        raise PrepError(f"points/{points}/points.parquet not found")
+    sd_attrs = dict(root["points"][points].attrs).get("spatialdata_attrs", {})
+    feature = sd_attrs.get("feature_key")
+    schema = pq.read_schema(parquet if os.path.isfile(parquet) else next(
+        os.path.join(parquet, f) for f in sorted(os.listdir(parquet)) if f.endswith(".parquet")))
+    names_in_file = set(schema.names)
+    if not feature or feature not in names_in_file:
+        raise PrepError(f"points/{points} has no feature column (feature_key={feature!r})")
+    hlod = _load_hlod()
+    final = os.path.join(store_path, "points", points, "points.zarr")
+    try:
+        summary = hlod.build(
+            parquet, final, gene_col=feature, x_col="x", y_col="y",
+            id_col="transcript_id" if "transcript_id" in names_in_file else None,
+            columns=[c for c in POINTS_COLUMNS if c in names_in_file],
+            extra_attrs={"source_element": f"points/{points}"}, log=lambda _: None)
+    except hlod.BuildError as e:
+        raise PrepError(f"points/{points}: {e}") from None
+    return {"path": final, "n_genes": summary["genes"], "n_rnas": summary["rows"],
+            "Dmax": summary["Dmax"]}
+
+
+# --- 5. expression matrix: dense or CSC ---
+
+def check_expression_matrix(root, table: str | None) -> dict:
+    """The app reads a gene's per-cell column from tables/<table>/X; dense and
+    CSC store columns contiguously, CSR would mean reading the whole matrix.
+    Only reports — rewriting X is left to the user (e.g. in anndata:
+    `adata.X = adata.X.tocsc()` and write the table back)."""
+    if not table:
+        return {"table": None, "encoding": None, "ok": False, "message": "store has no table"}
+    tbl = root["tables"][table]
+    if "X" not in tbl:
+        return {"table": table, "encoding": None, "ok": False, "message": f"tables/{table} has no X"}
+    x = tbl["X"]
+    encoding = "dense" if isinstance(x, zarr.Array) else x.attrs.get("encoding-type")
+    ok = encoding in ("dense", "csc_matrix")
+    report = {"table": table, "encoding": encoding, "ok": ok}
+    if not ok:
+        report["message"] = (
+            f"tables/{table}/X is {encoding}; the app reads expression only from a dense or CSC "
+            "X, so Counts and Scores stay unavailable until X is rewritten as one"
+        )
+    return report
+
+
+# --- 5. tissue-set-manifest.json ---
+
+MANIFEST_NAME = "tissue-set-manifest.json"
+# Same 1%/99% start/end and ~66% bounds as prep_xenium_data's channel windows.
+CHANNEL_START_PCT, CHANNEL_END_PCT, CHANNEL_BOUND_FRAC = 1.0, 99.0, 0.66
+CHANNEL_HEX = ["%02X%02X%02X" % tuple(int(v) for v in (t * 255).round()) for t in THUMB_TINTS]
+
+
+def format_cell_count(n: int) -> str:
+    """The card's cell count, as prep_xenium_data.py writes it (xenium_utils, which
+    this standalone script can't import): 950, 170k, 162.2k, 1.2M."""
+    if n < 1000:
+        return str(n)
+    if n < 1_000_000:
+        return f"{int(n / 100) / 10.0:g}k"
+    return f"{int(n / 100000) / 10.0:g}M"
+
+
+def count_cells(root, table: str | None) -> int | None:
+    """Cells as the table counts them: the rows of its obs index, else of X (a
+    sparse X records its `shape` in the group attrs, a dense X is the array
+    itself). None without a table, so the caller can fall back to the outlines."""
+    if not table:
+        return None
+    tbl = root["tables"][table]
+    if "obs" in tbl:
+        obs = tbl["obs"]
+        index = obs.attrs.get("_index", "_index")
+        if index in obs:
+            return _column_length(obs[index])
+    if "X" not in tbl:
+        return None
+    x = tbl["X"]
+    shape = x.shape if isinstance(x, zarr.Array) else x.attrs.get("shape")
+    return int(shape[0]) if shape else None
+
+
+def default_channels(image) -> list[dict]:
+    """Manifest `channels` for the image: labels from omero when present, the
+    app's default tints, and contrast windows from the thumbnail level. The
+    first THUMB_MAX_CHANNELS start active, as in the thumbnail."""
+    arr = image[_pick_thumb_level(image)]
+    planes = np.asarray(arr[...]).reshape(-1, *arr.shape[-2:])
+    omero = _ome(dict(image.attrs)).get("omero", {}).get("channels", [])
+    channels = []
+    for i, plane in enumerate(planes):
+        label = omero[i].get("label") if i < len(omero) else None
+        lo, hi = float(plane.min()), float(plane.max())
+        start = float(np.percentile(plane, CHANNEL_START_PCT))
+        end = float(np.percentile(plane, CHANNEL_END_PCT))
+        if end <= start:
+            end = start + 1.0
+        channels.append({
+            "label": str(label) if label else f"Channel {i}",
+            "color": CHANNEL_HEX[i % len(CHANNEL_HEX)],
+            "active": i < THUMB_MAX_CHANNELS,
+            "window": {"min": int(lo * CHANNEL_BOUND_FRAC), "max": int(hi * CHANNEL_BOUND_FRAC),
+                       "start": start, "end": end},
+        })
+    return channels
+
+
+def ask_overwrite(key: str) -> bool:
+    """Y/n prompt (Enter = yes). No answer available (piped stdin) means keep the entry."""
+    try:
+        answer = input(f"'{key}' is already in {MANIFEST_NAME}. Overwrite it? [Y/n] ")
+    except EOFError:
+        return False
+    return answer.strip().lower() in ("", "y", "yes")
+
+
+def write_manifest(store_path: str, root, image, table: str | None, overwrite=ask_overwrite,
+                   n_shapes: int | None = None) -> dict:
+    """Add a default entry for this store to tissue-set-manifest.json in the
+    store's parent directory, keyed by the store name minus .zarr (the app opens
+    `<key>.zarr`). An existing entry may carry hand edits, so `overwrite(key)`
+    decides whether to replace it."""
+    store_path = os.path.abspath(store_path)
+    key = os.path.basename(store_path)
+    key = key[: -len(".zarr")] if key.endswith(".zarr") else key
+    path = os.path.join(os.path.dirname(store_path), MANIFEST_NAME)
+    manifest = {}
+    if os.path.exists(path):
+        with open(path) as f:
+            manifest = json.load(f)
+    if key in manifest and not overwrite(key):
+        return {"path": path, "key": key, "written": False}
+    # The card counts obs rows (cells QC kept), else the outlines.
+    n_cells = count_cells(root, table)
+    if n_cells is None:
+        n_cells = n_shapes
+    manifest[key] = {
+        "dataSourceType": "spatialData",
+        "majorLabel": key,
+        "description": "",
+        **({"nCells": format_cell_count(n_cells)} if n_cells is not None else {}),
+        "filterableMetadata": {"dataType": "SpatialData"},
+        "sampleInfo": [{"label": "Data type", "value": "SpatialData"}],
+        "channels": default_channels(image),
+    }
+    tmp = path + ".tmp"
+    with open(tmp, "w") as f:
+        json.dump(manifest, f, indent=2)
+    os.replace(tmp, path)
+    return {"path": path, "key": key, "written": True}
+
+
+# --- entry point ---
+
+def _pick(root, kind: str, requested: str | None) -> str | None:
+    """The element the app reads: the manifest's choice, else the first in
+    sorted order (pickElement in src/spatialdata/store.ts)."""
+    names = sorted(root[kind].group_keys()) if kind in root else []
+    if requested:
+        if requested not in names:
+            raise PrepError(f"no {kind}/{requested} (has: {', '.join(names) or 'none'})")
+        return requested
+    return names[0] if names else None
+
+
+def prep_spatialdata(store_path: str, image: str | None = "morphology_focus",
+                     shapes: str | None = None, points: str | None = None,
+                     table: str | None = None, overwrite=ask_overwrite) -> dict:
+    """Check the image, write the thumbnail and the shapes/points sidecars, and
+    report whether X is in a layout the app reads. Element names default as the app picks them, so pass the same names as the
+    manifest's `spatialDataElements` when it sets any. Raises PrepError (and
+    writes nothing) if the image won't tile in viv."""
+    root = zarr.open_group(store_path, mode="r")
+    image = _pick(root, "images", image)
+    if not image:
+        raise PrepError("store has no images")
+    img = root["images"][image]
+    try:
+        report = {"image": {"name": image, **check_viv_image(img)}}
+    except PrepError as e:
+        raise PrepError(f"images/{image}: {e}") from None
+
+    thumb = os.path.join(store_path, "images", "thumbnail.png")
+    render_thumbnail(img).save(thumb)
+    report["thumbnail"] = thumb
+
+    table = _pick(root, "tables", table)
+    shapes = _pick(root, "shapes", shapes)
+    if shapes:
+        report["shapes"] = write_shapes_zarr(root, store_path, shapes, table)
+    points = _pick(root, "points", points)
+    if points:
+        report["points"] = write_points_zarr(root, store_path, points)
+    report["expression"] = check_expression_matrix(root, table)
+    n_shapes = report["shapes"]["n_shapes"] if "shapes" in report else None
+    report["manifest"] = write_manifest(store_path, root, img, table, overwrite, n_shapes)
+    return report
+
+
+def is_spatialdata_store(path: str) -> bool:
+    return os.path.isdir(path) and any(
+        os.path.isdir(os.path.join(path, kind)) for kind in ("images", "shapes", "points", "tables")
+    )
+
+
+def find_stores(directory: str) -> list[str]:
+    return [
+        p for p in (os.path.join(directory, n) for n in sorted(os.listdir(directory)))
+        if p.endswith(".zarr") and is_spatialdata_store(p)
+    ]
+
+
+def prep_one(store: str, args) -> bool:
+    try:
+        report = prep_spatialdata(store, args.image, args.shapes, args.points, args.table)
+    except PrepError as e:
+        print(f"error: {store}: {e}", file=sys.stderr)
+        return False
+    for w in report["image"].pop("warnings"):
+        print(f"warning: images/{report['image']['name']}: {w}", file=sys.stderr)
+    if not report["expression"]["ok"]:
+        print(f"notice: {report['expression']['message']}", file=sys.stderr)
+    entry = "added to" if report["manifest"]["written"] else "left unchanged in"
+    print(f"✓ {os.path.basename(store)} prepped successfully; manifest entry {entry} {MANIFEST_NAME}")
+    return True
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    ap.add_argument("store", help="a <name>.zarr SpatialData store, or a directory of them "
+                    "(each is prepped in turn and added to the directory's tissue-set-manifest.json)")
+    ap.add_argument("--image", default="morphology_focus", help="images/<name> (default: %(default)s)")
+    ap.add_argument("--shapes", help="shapes/<name> for cells (default: first in sorted order)")
+    ap.add_argument("--points", help="points/<name> for transcripts (default: first in sorted order)")
+    ap.add_argument("--table", help="tables/<name> annotating the cells (default: first)")
+    args = ap.parse_args(argv)
+
+    if is_spatialdata_store(args.store):
+        return 0 if prep_one(args.store, args) else 1
+    if not os.path.isdir(args.store):
+        print(f"error: {args.store} is not a directory", file=sys.stderr)
+        return 1
+    stores = find_stores(args.store)
+    if not stores:
+        print(f"error: no SpatialData .zarr stores found in {args.store}", file=sys.stderr)
+        return 1
+    failed = []
+    for n, store in enumerate(stores, 1):
+        print(f"[{n}/{len(stores)}] {os.path.basename(store)}", file=sys.stderr)
+        if not prep_one(store, args):
+            failed.append(os.path.basename(store))
+    if failed:
+        print(f"failed: {', '.join(failed)}", file=sys.stderr)
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())