spatialdata-js-util 0.1.0__tar.gz → 0.2.0__tar.gz

{spatialdata_js_util-0.1.0 → spatialdata_js_util-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatialdata-js-util
-Version: 0.1.0
+Version: 0.2.0
 Summary: Read/write utilities for browser-oriented SpatialData stores (image codecs, Morton-indexed points, CSC tables)
 Author: SpatialData.js contributors
 License: MIT
@@ -14,7 +14,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
-Requires-Dist: imagecodecs>=2025.8.2
+Requires-Dist: imagecodecs>=2026.6.26
 Requires-Dist: numcodecs>=0.16
 Requires-Dist: numpy>=2.0
 Requires-Dist: pandas>=2.2
@@ -111,7 +111,8 @@ The flow is the same for every command: **guided form → confirm → run → re
 - **Runs stream their JSON output** to a log pane, so a long recompression shows
   progress rather than appearing to hang.
 - The recompress form carries the [pyramid](#multiscale-pyramids) controls, so
-  single-resolution input can be made browser-ready without leaving the UI.
+  single-resolution or shallow-pyramid input can be made browser-ready without
+  leaving the UI.
 - **Writes are verified afterwards** and the report screen shows a pass/fail
   table. For Morton writes that means:
 
@@ -238,18 +239,43 @@ spatial axis is `--pyramid-min-size` (1024) or smaller, so the coarsest level is
 roughly one chunk. Override with `--pyramid-levels N` (a *total* count including
 full resolution) and `--pyramid-downscale K`.
 
-Images that already have more than one level are **skipped**, and the manifest
-says so; `--pyramid-force` rebuilds them anyway. Pass `--labels` to
+An image gets levels only when its coarsest existing level is still larger than
+`--pyramid-min-size` (with `--pyramid-levels N`, when it has fewer than N
+levels). Existing levels are kept and new ones are coarsened from the coarsest
+level (full resolution, for a single-resolution image), so only that level is
+read. Others are **skipped**, and the manifest says
+why; `--pyramid-force` rebuilds every image from full resolution anyway. Pass `--labels` to
 `add-pyramid` to include label elements — they are downsampled by the label
 model, so ids are never averaged into values that identify no object.
 
-Full resolution is copied through unchanged; only the added levels are new.
-Levels are generated through SpatialData's own parsers, which get the per-level
-scale *and* half-pixel translation right — hand-written `multiscales` metadata
-tends to misalign every level against the full-resolution image.
+Existing levels are copied through unchanged; only the added levels are new.
+Levels are generated through SpatialData's own parsers and the per-level
+transforms are derived from level shapes, which gets the scale *and* half-pixel
+translation right — hand-written `multiscales` metadata tends to misalign every
+level against the full-resolution image.
 
-Pyramids are always written to a **different** store than the source. SpatialData
-refuses to delete the files backing a live element, so there is no in-place mode.
+`add-pyramid` and `recompress --pyramid` write to a **different** store than the
+source, because SpatialData refuses to delete the files backing a live element.
+Adding levels deletes nothing, though, so there are two ways to skip the copy:
+
+```bash
+spatialdata-js-util images add-pyramid store.zarr --in-place
+```
+
+`--in-place` appends the missing levels to the store itself. Existing arrays are
+not read back, rewritten or recompressed; the new arrays are written first and
+then declared in the element's `zarr.json` and the store's consolidated metadata,
+so an interrupted run leaves a store that still reads as before and that a rerun
+completes. New levels use the coarsest level's codecs when those are plain zarr
+codecs, and zarr's defaults (zstd) when it uses an image codec, so they never add
+JPEG 2000 or HTJ2K. It cannot replace levels, so `--pyramid-force` and
+`--overwrite` do not apply, and it stops rather than append to levels whose
+transforms do not follow their shapes. Do not run it while anything else writes
+the store.
+
+To avoid even that when you are about to write a `SpatialData` object anyway, call
+`ensure_pyramids(sdata)`: it replaces the elements that need levels in memory and
+writes nothing.
 
 ### Other image notes
 
@@ -364,9 +390,12 @@ csc = to_csc(adata.X)                         # or just a matrix
 ## Python API
 
 ```python
+import spatialdata as sd
 from spatialdata_js_util import (
     recompress_spatialdata,
     add_pyramids,
+    add_pyramids_in_place,
+    ensure_pyramids,
     has_pyramid,
     write_morton_points_parquet,
     convert_store_tables_to_csc,
@@ -377,7 +406,7 @@ result = recompress_spatialdata(
     "input.zarr", "output-htj2k.zarr",
     codec="experimental.openjph_htj2k",
     preset="balanced",
-    pyramid=True,          # add levels to single-resolution images first
+    pyramid=True,          # add levels to images whose coarsest level is too large
     overwrite=True,
 )
 print(result.manifest_path)
@@ -385,6 +414,12 @@ print(result.manifest_path)
 # Or pyramids on their own
 has_pyramid("input.zarr", "images", "morphology")   # -> False
 add_pyramids("input.zarr", "output.zarr", levels=4)
+add_pyramids_in_place("input.zarr")   # append levels to the store itself
+
+# Or in memory, before a write you were doing anyway
+sdata = sd.read_zarr("input.zarr")
+ensure_pyramids(sdata, include_labels=True)
+sdata.write("output.zarr")
 ```
 
 ## Monorepo development

{spatialdata_js_util-0.1.0 → spatialdata_js_util-0.2.0}/README.md

@@ -78,7 +78,8 @@ The flow is the same for every command: **guided form → confirm → run → re
 - **Runs stream their JSON output** to a log pane, so a long recompression shows
   progress rather than appearing to hang.
 - The recompress form carries the [pyramid](#multiscale-pyramids) controls, so
-  single-resolution input can be made browser-ready without leaving the UI.
+  single-resolution or shallow-pyramid input can be made browser-ready without
+  leaving the UI.
 - **Writes are verified afterwards** and the report screen shows a pass/fail
   table. For Morton writes that means:
 
@@ -205,18 +206,43 @@ spatial axis is `--pyramid-min-size` (1024) or smaller, so the coarsest level is
 roughly one chunk. Override with `--pyramid-levels N` (a *total* count including
 full resolution) and `--pyramid-downscale K`.
 
-Images that already have more than one level are **skipped**, and the manifest
-says so; `--pyramid-force` rebuilds them anyway. Pass `--labels` to
+An image gets levels only when its coarsest existing level is still larger than
+`--pyramid-min-size` (with `--pyramid-levels N`, when it has fewer than N
+levels). Existing levels are kept and new ones are coarsened from the coarsest
+level (full resolution, for a single-resolution image), so only that level is
+read. Others are **skipped**, and the manifest says
+why; `--pyramid-force` rebuilds every image from full resolution anyway. Pass `--labels` to
 `add-pyramid` to include label elements — they are downsampled by the label
 model, so ids are never averaged into values that identify no object.
 
-Full resolution is copied through unchanged; only the added levels are new.
-Levels are generated through SpatialData's own parsers, which get the per-level
-scale *and* half-pixel translation right — hand-written `multiscales` metadata
-tends to misalign every level against the full-resolution image.
+Existing levels are copied through unchanged; only the added levels are new.
+Levels are generated through SpatialData's own parsers and the per-level
+transforms are derived from level shapes, which gets the scale *and* half-pixel
+translation right — hand-written `multiscales` metadata tends to misalign every
+level against the full-resolution image.
 
-Pyramids are always written to a **different** store than the source. SpatialData
-refuses to delete the files backing a live element, so there is no in-place mode.
+`add-pyramid` and `recompress --pyramid` write to a **different** store than the
+source, because SpatialData refuses to delete the files backing a live element.
+Adding levels deletes nothing, though, so there are two ways to skip the copy:
+
+```bash
+spatialdata-js-util images add-pyramid store.zarr --in-place
+```
+
+`--in-place` appends the missing levels to the store itself. Existing arrays are
+not read back, rewritten or recompressed; the new arrays are written first and
+then declared in the element's `zarr.json` and the store's consolidated metadata,
+so an interrupted run leaves a store that still reads as before and that a rerun
+completes. New levels use the coarsest level's codecs when those are plain zarr
+codecs, and zarr's defaults (zstd) when it uses an image codec, so they never add
+JPEG 2000 or HTJ2K. It cannot replace levels, so `--pyramid-force` and
+`--overwrite` do not apply, and it stops rather than append to levels whose
+transforms do not follow their shapes. Do not run it while anything else writes
+the store.
+
+To avoid even that when you are about to write a `SpatialData` object anyway, call
+`ensure_pyramids(sdata)`: it replaces the elements that need levels in memory and
+writes nothing.
 
 ### Other image notes
 
@@ -331,9 +357,12 @@ csc = to_csc(adata.X)                         # or just a matrix
 ## Python API
 
 ```python
+import spatialdata as sd
 from spatialdata_js_util import (
     recompress_spatialdata,
     add_pyramids,
+    add_pyramids_in_place,
+    ensure_pyramids,
     has_pyramid,
     write_morton_points_parquet,
     convert_store_tables_to_csc,
@@ -344,7 +373,7 @@ result = recompress_spatialdata(
     "input.zarr", "output-htj2k.zarr",
     codec="experimental.openjph_htj2k",
     preset="balanced",
-    pyramid=True,          # add levels to single-resolution images first
+    pyramid=True,          # add levels to images whose coarsest level is too large
     overwrite=True,
 )
 print(result.manifest_path)
@@ -352,6 +381,12 @@ print(result.manifest_path)
 # Or pyramids on their own
 has_pyramid("input.zarr", "images", "morphology")   # -> False
 add_pyramids("input.zarr", "output.zarr", levels=4)
+add_pyramids_in_place("input.zarr")   # append levels to the store itself
+
+# Or in memory, before a write you were doing anyway
+sdata = sd.read_zarr("input.zarr")
+ensure_pyramids(sdata, include_labels=True)
+sdata.write("output.zarr")
 ```
 
 ## Monorepo development

{spatialdata_js_util-0.1.0 → spatialdata_js_util-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spatialdata-js-util"
-version = "0.1.0"
+version = "0.2.0"
 description = "Read/write utilities for browser-oriented SpatialData stores (image codecs, Morton-indexed points, CSC tables)"
 requires-python = ">=3.12"
 readme = "README.md"
@@ -15,7 +15,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Bio-Informatics",
 ]
 dependencies = [
-    "imagecodecs>=2025.8.2",
+    "imagecodecs>=2026.6.26",
     "numcodecs>=0.16",
     "numpy>=2.0",
     "pandas>=2.2",

{spatialdata_js_util-0.1.0 → spatialdata_js_util-0.2.0}/src/spatialdata_js_util/__init__.py

@@ -40,7 +40,10 @@ from .images import (
 from .pyramids import (
     PyramidResult,
     add_pyramids,
+    add_pyramids_in_place,
+    ensure_pyramids,
     has_pyramid,
+    needs_pyramid,
     resolve_scale_factors,
 )
 from .points import (
@@ -84,16 +87,19 @@ __all__ = [
     "RecompressedSpatialData",
     "add_points_zarr_to_store",
     "add_pyramids",
+    "add_pyramids_in_place",
     "anndata_to_csc",
     "backend_report",
     "build_spatialdata_multiscale_metadata",
     "convert_store_tables_to_csc",
     "dtype_quantum",
+    "ensure_pyramids",
     "has_pyramid",
     "htj2k_available",
     "htj2k_preset_quality",
     "is_htj2k_codec",
     "morton_sort_points",
+    "needs_pyramid",
     "plan_column_encodings",
     "recompress_spatialdata",
     "register_codecs",

{spatialdata_js_util-0.1.0 → spatialdata_js_util-0.2.0}/src/spatialdata_js_util/cli.py

@@ -128,8 +128,10 @@ def _add_pyramid_args(parser: argparse.ArgumentParser, *, with_flag: bool) -> No
             "--pyramid",
             action="store_true",
             help=(
-                "Build a multiscale pyramid for any image that has only one resolution "
-                "level, before recompressing. Implied by the other --pyramid-* options."
+                "Before recompressing, add pyramid levels to any image whose coarsest "
+                "level is larger than --pyramid-min-size: a single-resolution image is "
+                "built from full resolution, a shallow pyramid is extended from its "
+                "coarsest level. Implied by the other --pyramid-* options."
             ),
         )
     parser.add_argument(
@@ -159,18 +161,36 @@ def _add_pyramid_args(parser: argparse.ArgumentParser, *, with_flag: bool) -> No
     parser.add_argument(
         "--pyramid-force",
         action="store_true",
-        help="Rebuild pyramids for images that already have more than one level",
+        help="Rebuild every pyramid from full resolution, including ones already deep enough",
     )
 
 
 def _images_add_pyramid(args: argparse.Namespace) -> None:
-    from .pyramids import add_pyramids
+    from .pyramids import add_pyramids, add_pyramids_in_place
 
     def command() -> dict[str, Any]:
+        image_keys = args.image_key.split(",") if args.image_key else None
+        if args.in_place:
+            if args.dest is not None:
+                raise WriterCommandError("--in-place takes no destination; omit DEST.")
+            if args.overwrite or args.pyramid_force:
+                raise WriterCommandError(
+                    "--in-place only adds levels, so --overwrite and --pyramid-force do not apply."
+                )
+            return add_pyramids_in_place(
+                args.source,
+                image_keys=image_keys,
+                include_labels=args.labels,
+                levels=args.pyramid_levels,
+                downscale=args.pyramid_downscale,
+                min_size=args.pyramid_min_size,
+            ).manifest
+        if args.dest is None:
+            raise WriterCommandError("Give a destination store, or pass --in-place.")
         return add_pyramids(
             args.source,
             args.dest,
-            image_keys=args.image_key.split(",") if args.image_key else None,
+            image_keys=image_keys,
             include_labels=args.labels,
             levels=args.pyramid_levels,
             downscale=args.pyramid_downscale,
@@ -265,16 +285,31 @@ def _add_images_commands(subparsers: argparse._SubParsersAction) -> None:
 
     add_pyramid = image_commands.add_parser(
         "add-pyramid",
-        help="give single-resolution rasters a multiscale pyramid",
+        help="give rasters the overview levels they lack",
         description=(
-            "Copy a store and add multiscale pyramids to rasters that have only one "
-            "resolution level, so a zoomed-out browser view does not have to read "
-            "full-resolution chunks. Codecs are left unchanged; use "
-            "'images recompress --pyramid' to do both in one pass."
+            "Copy a store and add pyramid levels to rasters whose coarsest level is "
+            "larger than --pyramid-min-size (or that have fewer than --pyramid-levels "
+            "levels), keeping any levels they already have, so a zoomed-out browser "
+            "view does not have to read full-resolution chunks. Codecs are left "
+            "unchanged; use 'images recompress --pyramid' to do both in one pass. "
+            "With --in-place the levels are appended to SOURCE itself and nothing is "
+            "copied or rewritten."
         ),
     )
     add_pyramid.add_argument("source", help="Existing SpatialData Zarr store")
-    add_pyramid.add_argument("dest", help="Output SpatialData Zarr store")
+    add_pyramid.add_argument(
+        "dest",
+        nargs="?",
+        help="Output SpatialData Zarr store (omit with --in-place)",
+    )
+    add_pyramid.add_argument(
+        "--in-place",
+        action="store_true",
+        help=(
+            "Append the missing levels to SOURCE instead of writing a copy. Existing "
+            "arrays are not touched; new levels use plain zarr codecs."
+        ),
+    )
     add_pyramid.add_argument(
         "--image-key",
         metavar="KEYS",

{spatialdata_js_util-0.1.0 → spatialdata_js_util-0.2.0}/src/spatialdata_js_util/codecs/backends.py

@@ -35,6 +35,7 @@ from __future__ import annotations
 
 import json
 import os
+import warnings
 from functools import lru_cache
 from pathlib import Path
 from typing import Any, Protocol
@@ -205,6 +206,17 @@ def resolve_backend() -> Htj2kBackend | None:
         # so it is trusted on availability; every other backend must prove it.
         if name == BACKEND_OPENJPH_WASM:
             if _BACKENDS[name].available():
+                if not requested:
+                    # Reaching here means `imagecodecs` failed, usually because the
+                    # installed release has no HTJ2K for this platform. Encoding
+                    # still works, but only while Node.js is on PATH.
+                    warnings.warn(
+                        "imagecodecs has no usable HTJ2K; falling back to the openjph-wasm "
+                        "backend, which needs Node.js. Upgrade imagecodecs to the version "
+                        "spatialdata-js-util requires to encode without Node.",
+                        RuntimeWarning,
+                        stacklevel=2,
+                    )
                 return _BACKENDS[name]
         elif backend_passes_probe(name):
             return _BACKENDS[name]
@@ -212,9 +224,12 @@ def resolve_backend() -> Htj2kBackend | None:
 
 
 def reset_backend_cache() -> None:
-    """Clear memoized backend selection (used by tests that flip the env var)."""
+    """Clear memoized backend selection (used by tests that flip the env var or PATH)."""
+    from .htj2k_wasm import wasm_encode_available
+
     resolve_backend.cache_clear()
     backend_passes_probe.cache_clear()
+    wasm_encode_available.cache_clear()
 
 
 def require_backend() -> Htj2kBackend:

{spatialdata_js_util-0.1.0 → spatialdata_js_util-0.2.0}/src/spatialdata_js_util/images.py

@@ -614,7 +614,7 @@ def _stage_pyramids(
 ) -> tuple[list[dict[str, Any]], dict[str, Path]]:
     """Build pyramids for *image_keys* into a staging store.
 
-    Returns the per-raster reports and, for each key that was actually rebuilt,
+    Returns the per-raster reports and, for each key that was given levels,
     the root to read its levels from.
     """
     import spatialdata as sd
@@ -635,7 +635,7 @@ def _stage_pyramids(
     roots = {
         report["path"].split("/", 1)[1]: staging_path
         for report in reports
-        if report.get("action") == "rebuilt"
+        if report.get("action") in ("rebuilt", "extended")
     }
     return reports, roots
 
@@ -675,10 +675,11 @@ def recompress_spatialdata(
     shapes, points, and unconfigured rasters intact without loading the whole
     object.
 
-    With *pyramid*, any configured image that has only one resolution level is
-    given a multiscale pyramid before it is recompressed, so single-resolution
-    acquisition output becomes browser-ready in one pass. Images that already
-    have a pyramid are left alone unless *pyramid_force* is set. See
+    With *pyramid*, any configured image whose coarsest level is larger than
+    *pyramid_min_size* is given the levels it lacks before it is recompressed,
+    so single-resolution or shallow-pyramid acquisition output becomes
+    browser-ready in one pass. Images whose pyramid is already deep enough are
+    left alone, and *pyramid_force* rebuilds them from full resolution. See
     `spatialdata_js_util.pyramids` for how levels are chosen.
     """