Consolidate Python tooling into a publishable spatialdata-js-util

.cursor/settings.json

@@ -10,7 +10,7 @@
   },
   "python.analysis.extraPaths": [
     "${workspaceFolder}/python",
-    "${workspaceFolder}/python/spatialdata-codec-writer/scripts"
+    "${workspaceFolder}/python/spatialdata-js-util/scripts"
   ]
 }
 

.github/workflows/test.yml

@@ -105,7 +105,7 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
-      - name: Vendor OpenJPH for spatialdata-codec-writer
+      - name: Vendor OpenJPH for spatialdata-js-util
         run: node scripts/vendor-openjph-for-python.mjs
 
       - name: Build packages
@@ -128,8 +128,8 @@ jobs:
         if: steps.cache-fixtures.outputs.cache-hit != 'true'
         run: pnpm test:fixtures:generate
 
-      - name: Run spatialdata-codec-writer tests
-        run: uv run --directory python/spatialdata-codec-writer pytest
+      - name: Run spatialdata-js-util tests
+        run: uv run --directory python/spatialdata-js-util --extra write --extra tui pytest
 
       - name: Run unit tests
         run: pnpm test:unit

.gitignore

@@ -21,8 +21,8 @@ python/v0.5.0/.venv/
 python/v0.6.1/.venv/
 python/v0.7.2/.venv/
 
-# Vendored from @cornerstonejs/codec-openjph (see scripts/vendor-openjph-for-python.mjs)
-python/spatialdata-codec-writer/src/spatialdata_codec_writer/vendor/openjph/
+# Vendored from openjph-wasm (see scripts/vendor-openjph-for-python.mjs)
+python/spatialdata-js-util/src/spatialdata_js_util/codecs/vendor/openjph/
 
 **/__pycache__/
 *.egg-info/

.vscode/settings.json

@@ -10,7 +10,7 @@
   },
   "python.analysis.extraPaths": [
     "${workspaceFolder}/python",
-    "${workspaceFolder}/python/spatialdata-codec-writer/scripts"
+    "${workspaceFolder}/python/spatialdata-js-util/scripts"
   ],
   "typescript.tsdk": "node_modules/typescript/lib",
   "js/ts.experimental.useTsgo": false

docs/adr/0002-spatially-aware-vector-loading.md

@@ -113,7 +113,7 @@ silently swap sort order under the existing `morton-points` format id.
 Generate comparable permutations with:
 
 ```bash
-spatialdata-experimental-writer write-index-permutations SOURCE_ZARR DEST_ZARR
+spatialdata-js-util points index-permutations SOURCE_ZARR DEST_ZARR
 ```
 
 The derivative store includes sibling `points/<condition>/` elements and

docs/docs/vis/codec-fixtures.mdx

@@ -52,15 +52,15 @@ The vis dev script starts the fixture server on port `38473` and proxies
 
 ## Python reference writer
 
-The **publishable** package (`spatialdata-codec-writer`) exposes recompression
+The **publishable** package (`spatialdata-js-util`) exposes recompression
 only. Codec test fixtures are generated by repo-local scripts under
-`python/spatialdata-codec-writer/scripts/`.
+`python/spatialdata-js-util/scripts/`.
 
 Useful commands:
 
 ```bash
 pnpm test:fixtures:generate:codecs
-uv run --directory python/spatialdata-codec-writer spatialdata-codec-writer inspect ../../test-fixtures/codecs/jpeg2k.manifest.json
+uv run --directory python/spatialdata-js-util spatialdata-js-util images inspect ../../test-fixtures/codecs/jpeg2k.manifest.json
 ```
 
 ### Fixture provenance
@@ -91,13 +91,13 @@ SpatialData store, rewrites configured image rasters with JP2K or experimental
 HTJ2K, and writes labels with Blosc/zstd by default.
 
 ```bash
-uv run --directory python/spatialdata-codec-writer spatialdata-codec-writer recompress input.sdata.zarr output-jp2k.zarr --image-key morphology_focus --preset balanced --chunks auto --overwrite
+uv run --directory python/spatialdata-js-util spatialdata-js-util images recompress input.sdata.zarr output-jp2k.zarr --image-key morphology_focus --preset balanced --chunks auto --overwrite
 ```
 
 Custom HTJ2K quality (instead of a preset name):
 
 ```bash
-uv run --directory python/spatialdata-codec-writer spatialdata-codec-writer recompress \
+uv run --directory python/spatialdata-js-util spatialdata-js-util images recompress \
   input.sdata.zarr output-htj2k.zarr \
   --image-key morphology_focus \
   --codec experimental.openjph_htj2k \
@@ -139,7 +139,7 @@ uses OpenJPH WASM (`experimental.openjph_htj2k`) via
 `HTJ2KEncoder.setQuality(reversible, quality)`. The quality argument is a float
 quantization factor (lower = higher fidelity, larger output) — not JP2K-style
 0–100. Presets map to `balanced: 0.0002`, `small: 0.001` (calibrated roughly on
-Xenium morphology; see `python/spatialdata-codec-writer/docs/htj2k-wasm-encode-design.md`).
+Xenium morphology; see `python/spatialdata-js-util/docs/htj2k-wasm-encode-design.md`).
 Override with CLI `--quality 0.001` or per-image JSON `"quality": 0.001` (implies
 lossy unless `"reversible": true`). A future codec-demo UI may add interactive `q`
 exploration on sample regions.
@@ -162,7 +162,7 @@ considered supported by the current JavaScript decoder paths.
 Useful Xenium morphology experiment:
 
 ```bash
-uv run --directory python/spatialdata-codec-writer spatialdata-codec-writer recompress /path/to/input.zarr /path/to/output.zarr --image-key morphology_focus --preset balanced --chunks auto --overwrite
+uv run --directory python/spatialdata-js-util spatialdata-js-util images recompress /path/to/input.zarr /path/to/output.zarr --image-key morphology_focus --preset balanced --chunks auto --overwrite
 ```
 
 When serving recompressed stores for browser experiments, disable HTTP caching

docs/plans/shapes-nonblocking-tiled-loading.md

@@ -83,7 +83,7 @@ a *consequence* of moving the load into the layer, not a feature bolted on.
 | Worker decode + transferables | `core/src/workers/points-worker.ts`, `pointsWorkerClient.ts` (`decodeGeometryWithFeaturesInWorker`), `pointsWorkerProtocol.ts` | add a `decode-shapes-wkb` request + handler + client, or a `shapes-worker.ts` |
 | Row-group range reads (INHERITED — reuse as-is) | `core/src/models/VTableSource.ts` | — |
 | Tiling metadata + real bounds loader | `core/src/pointsTiling.ts`, `VPointsSource.loadPointsInBounds` (morton bisect) | `ShapesTilingMetadata`, `VShapesSource.loadShapesInBounds` (bbox bisect) |
-| Python spatial writer | `python/spatialdata-experimental-writer/src/.../points.py` (morton sort, sentinels, row groups) | shapes GeoParquet writer under `shapes.experimental/<key>/` |
+| Python spatial writer | `python/spatialdata-js-util/src/.../points.py` (morton sort, sentinels, row groups) | shapes GeoParquet writer under `shapes.experimental/<key>/` |
 
 Note: the live vis points path currently sets `experimentalOptimizations: 'off'`
 (`PointsRendererAdapter.ts`), so even the points `TileLayer` is test-exercised but
@@ -299,7 +299,7 @@ artifact (Phase 2); renaming the worker (future).
 
 ### Phase 2 — the tiled artifact + tiled loader
 
-8. **Python writer** under `python/spatialdata-experimental-writer/`, a
+8. **Python writer** under `python/spatialdata-js-util/`, a
    `shapes` subcommand cloning `points.py` but: DuckDB Hilbert sort on geometry,
    GeoParquet 1.1 bbox covering column, zstd, sized row groups. Target
    `shapes.experimental/<key>/` (ADR 0002 — standard readers can't consume a

package.json

@@ -21,9 +21,9 @@
     "test:fixtures:generate:0.5.0": "uv run python/scripts/generate_fixtures.py --version 0.5.0",
     "test:fixtures:generate:0.6.1": "uv run python/scripts/generate_fixtures.py --version 0.6.1",
     "test:fixtures:generate:0.7.2": "uv run python/scripts/generate_fixtures.py --version 0.7.2",
-    "test:fixtures:generate:codecs": "node scripts/vendor-openjph-for-python.mjs && UV_CACHE_DIR=.tmp/uv-cache uv run --directory python/spatialdata-codec-writer python scripts/generate_codec_fixtures.py --output-dir ../../test-fixtures/codecs --experimental-htj2k --overwrite",
-    "write-synthetic": "node scripts/vendor-openjph-for-python.mjs && uv run --directory python/spatialdata-codec-writer spatialdata-codec-writer-write-synthetic",
-    "test:codec-writer": "node scripts/vendor-openjph-for-python.mjs && UV_CACHE_DIR=.tmp/uv-cache uv run --directory python/spatialdata-codec-writer pytest",
+    "test:fixtures:generate:codecs": "node scripts/vendor-openjph-for-python.mjs && UV_CACHE_DIR=.tmp/uv-cache uv run --directory python/spatialdata-js-util --extra write python scripts/generate_codec_fixtures.py --output-dir ../../test-fixtures/codecs --experimental-htj2k --overwrite",
+    "write-synthetic": "node scripts/vendor-openjph-for-python.mjs && uv run --directory python/spatialdata-js-util --extra write python scripts/write_synthetic.py",
+    "test:python": "node scripts/vendor-openjph-for-python.mjs && UV_CACHE_DIR=.tmp/uv-cache uv run --directory python/spatialdata-js-util --extra write --extra tui pytest",
     "test:server": "node scripts/test-server.js",
     "test:proxy": "node scripts/cors-proxy.js",
     "validate:datasets:js": "node scripts/validate-datasets-js.js",

packages/core/tests/mortonPointsTiling.spec.ts

@@ -8,7 +8,7 @@ import SpatialDataPointsSource from '../src/models/VPointsSource.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const projectRoot = join(__dirname, '../../..');
-const writerRoot = join(projectRoot, 'python/spatialdata-experimental-writer');
+const writerRoot = join(projectRoot, 'python/spatialdata-js-util');
 
 async function writeSyntheticPointsZarr(root: string) {
   const elementDir = join(root, 'points', 'transcripts');
@@ -52,7 +52,7 @@ PY`,
   );
 
   execSync(
-    `uv run spatialdata-experimental-writer morton-points-from-zarr ${JSON.stringify(root)} --points-key transcripts --row-group-size 100`,
+    `uv run spatialdata-js-util points morton-from-zarr ${JSON.stringify(root)} --points-key transcripts --row-group-size 100`,
     { cwd: writerRoot, stdio: 'pipe' }
   );
 }

packages/core/tests/parquetFooterStats.spec.ts

@@ -11,7 +11,7 @@ import {
 } from '../src/parquetFooterStats.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const writerRoot = join(__dirname, '../../../python/spatialdata-experimental-writer');
+const writerRoot = join(__dirname, '../../../python/spatialdata-js-util');
 
 /** Slice the Thrift `FileMetaData` bytes out of a full parquet file. */
 function footerMetaData(fileBytes: Uint8Array): Uint8Array {

packages/core/tests/pointsFeatures.spec.ts

@@ -8,7 +8,7 @@ import SpatialDataPointsSource from '../src/models/VPointsSource.js';
 import * as pointsWorkerClient from '../src/workers/pointsWorkerClient.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const writerRoot = join(__dirname, '../../../python/spatialdata-experimental-writer');
+const writerRoot = join(__dirname, '../../../python/spatialdata-js-util');
 
 async function writePointsFeatureFixture(root: string) {
   const elementDir = join(root, 'points', 'transcripts');

packages/core/tests/vtableDirectoryResponse.spec.ts

@@ -21,7 +21,7 @@ import SpatialDataTableSource from '../src/models/VTableSource.js';
  * the directory path does (return null vs. throw), and both must find the parts.
  */
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const writerRoot = join(__dirname, '../../../python/spatialdata-experimental-writer');
+const writerRoot = join(__dirname, '../../../python/spatialdata-js-util');
 
 async function writeMultipartParquetFixture(root: string, partRows: [number, number]) {
   execSync(

packages/core/tests/vtableMultipart.spec.ts

@@ -7,7 +7,7 @@ import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import SpatialDataTableSource from '../src/models/VTableSource.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const writerRoot = join(__dirname, '../../../python/spatialdata-experimental-writer');
+const writerRoot = join(__dirname, '../../../python/spatialdata-js-util');
 
 async function writeMultipartParquetFixture(root: string, partRows: [number, number]) {
   execSync(

packages/zarrextra/README.md

@@ -82,7 +82,7 @@ chunk's `[..., z, y, x]` layout. The `mandelbulb` test fixture exercises this:
 each chunk is a single codestream spanning 4 z-planes (`(1, 1, 4, 128, 128)`).
 
 For offline encode (fixtures, recompress), use `encodeHtj2kPlane()` or
-`createOpenJphEncoder()` from the same package. Python `spatialdata-codec-writer`
+`createOpenJphEncoder()` from the same package. Python `spatialdata-js-util`
 uses vendored OpenJPH WASM with a persistent Node worker pool; new stores use
 codec id `experimental.openjph_htj2k`.