Add resample pipeline to @itk-wasm/downsample (transform + selectable interpolator)

[thewtex]

Summary

Adds a new resample pipeline to @itk-wasm/downsample / itkwasm-downsample. It wraps itk::ResampleImageFilter to resample a moving image onto a reference image's grid, with an optional transform and a selectable interpolator, across the full ITK-Wasm target matrix (WASI, Node, browser/Emscripten, and Python sync + async / WASI + Emscripten).

This was built in five phases: a working C++ prototype, VectorImage support + interpolator ctest coverage, regenerated TypeScript/Python bindings, test data + independent baselines, and the Node/browser/Python test suites.

What changed

C++ pipeline — packages/downsample/resample.cxx (new)

• Positional input (moving image), reference-image (geometry-only — an empty pixel buffer is accepted, since only origin/spacing/direction/size are read), and output.
• -t,--transform optional transform mapping output-grid points into moving-image space (defaults to identity).
• -i,--interpolator selectable from six methods: linear (default), nearest_neighbor, label_image, b_spline, windowed_sinc, gaussian.
• Supports 2D/3D/4D images over all scalar pixel types and itk::VectorImage (multi-component) types.

Build — packages/downsample/CMakeLists.txt

• Registers the resample executable and adds the required ITK modules (ITKImageFunction, ITKTransform) plus native transform IO (ITKIOTransformInsightLegacy, ITKIOTransformHDF5).
• Adds self-contained ctests: a baseline resample smoke test plus one per interpolator (identity resample of cthead1.png), and a label_image test on 2th_cthead1.png — all needing no new test data.

Bindings — regenerated TypeScript + Python

• TypeScript: resample / resampleNode with ResampleOptions (transform?: TransformList, interpolator?: string) and ResampleResult, exported from the package entry points.
• Python: sync + async resample across the wasi and emscripten sub-packages.

Test data & baselines

• New independent baselines and refreshed dam test-data-hash in package.json / test:data:download.

Tests

• Node: ava tests for the resample bindings.
• Browser: a demo-app controller + sample-input loader and a Playwright resample.spec.ts.
• Python: WASI test_resample.py.
• Adds @itk-wasm/transform-io (TS devDep) and itkwasm-transform-io (pixi) so transform inputs can be exercised in tests.

Why

The downsample package could shrink images but had no general way to map an image onto an arbitrary output grid with a transform and a chosen interpolation method — the standard "resample onto a reference geometry" operation. This adds that as a first-class, fully-bound pipeline.

Implementation notes

• Transform type: the option is read as itk::wasm::InputTransform<itk::AffineTransform<double, N>> rather than the abstract itk::Transform<double, N, N>. The abstract base won't compile — the memory-IO reader calls TTransform::New(), and itk::Transform has no itkNewMacro. The concrete double-precision AffineTransform is-a Transform<double, N, N> and still feeds SetTransform polymorphically.
• Geometry-only reference: the filter uses SetReferenceImage(...) + UseReferenceImageOn(), so the reference image contributes only its geometry.
• VectorImage path: ResampleImageFilter has no native multi-component support, so (mirroring downsample.cxx) each component is extracted (VectorIndexSelectionCastImageFilter), resampled through shared wiring, then recomposed (ComposeImageFilter). Per-component filters are kept alive until a single final compose update, because itk::DataObject only holds a weak pointer back to its producer.
• Shared wiring: reference-geometry / transform / interpolator setup lives in one MakeResampleFilter<TImage> helper reused by both the scalar and per-component vector paths.

[thewtex]

@sedghi @vboussot please take a look

This adds a pipeline to resample according to the sampling grid defined by a reference image. Another PR will add a pipeline to resample according to direct specification of the grid.

[sedghi]

I thought this would be a new /resample package, but it looks like you're putting it under downsample. Is that intentional?

---

These are the things Fable found

Findings (most severe first)

1. packages/downsample/resample-to-reference.cxx:170 — The --transform option is bound to InputTransform<itk::AffineTransform<double, N>> while the public API advertises a generic TransformList, and the deserializer never checks the transform parameterization. WasmTransformToTransformFilter's non-composite path validates only precision and dimensions, then raw-copies parameters into the affine. A Euler2DTransform from @itk-wasm/transform-io (3 params, dims 2→2, float64) passes every guard and silently produces a wrongly-resampled image; a BSpline transform (more params than the affine's N×(N+1)) makes std::copy write past the parameter buffer — wasm heap corruption; a composite list hits a null dynamic_cast and crashes; a multi-element non-composite list silently keeps only the last entry. Using itk::CompositeTransform<double, N> as the input type (as the core transform-read-write test pipeline does) would deserialize any factory-registered parameterization correctly and support chains.
2. packages/downsample/python/itkwasm-downsample-wasi/pyproject.toml:36 — All three Python packages keep itkwasm >= 1.0.b145, but the new bindings unconditionally do from itkwasm import ... TransformList at import time, and TransformList only exists in itkwasm ≥ 1.0b180. An environment holding itkwasm 1.0b145–b179 (which pip considers satisfied) gets ImportError on import itkwasm_downsample, breaking every pre-existing function, not just the new one. Same stale floor in itkwasm-downsample/pyproject.toml:37 and itkwasm-downsample-emscripten/pyproject.toml:36; bump to ≥ 1.0b180 (or transform-io's b185).
3. packages/downsample/python/itkwasm-downsample-wasi/itkwasm_downsample_wasi/resample_to_reference.py:73 — Interpolator validation is interpolator not in ('linear,nearest_neighbor,...') — a single comma-joined string, so in does substring matching, not membership. interpolator='near', 'sinc', or 'gauss' passes the check and dies deep in the wasm pipeline with an opaque CLI error instead of the intended ValueError. Root cause is in bindgen (wasi-function-module.js:237 splits choices on ', ' but they serialize without spaces) — this PR is the first artifact to hit that path, so fix the generator and regenerate.
4. packages/downsample/resample-to-reference.cxx:157 — The reference image is declared as InputImage using the moving image's exact pixel/component type, but the help text (propagated into every TS/Python docstring) promises "only the metadata is used, so an empty pixel buffer is acceptable." A routine cross-type call — float32 moving + uint8 reference — throws "Unexpected component type" at deserialization. The metadata-only claim is also never tested: the test-data tarball even packs cthead1-resample-reference-metadata-only.json "to exercise the empty-buffer path," yet nothing references it, and in Python data=None marshals through np.asarray(None).tobytes() into garbage bytes. Either relax the reference type, or fix the docs and exercise the fixture.
5. packages/downsample/resample-to-reference.cxx:90 — SelectInterpolator ends in a bare else that silently returns linear for unknown names, and the six-name interpolator list is hand-maintained in three places (the two CLI::IsMember lists at lines 183 and 254 plus this chain). Unreachable today because CLI11 gates input, but any future drift (a seventh name added to the CLI lists only) silently yields linear-interpolated output instead of an error — invisible to the run-success-only tests. Prefer a single name→factory table and an itkExceptionMacro on unknown names.
6. packages/downsample/typescript/README.md:26 — The bindgen-generated README (the published npm docs for @itk-wasm/downsample) was not regenerated: it documents the five pre-existing functions but has no resampleToReference/resampleToReferenceNode section, even though all other TS artifacts were regenerated. The new API ships invisible on npm, and the next full bindgen run will produce a surprise README diff.
7. packages/downsample/resample-to-reference.cxx:228 — The VectorImage functor re-declares the scalar functor's entire ~35-line option surface verbatim, including the duplicated CLI::IsMember list and multi-sentence help strings. Since dispatch picks a functor by input pixel type at runtime, drift between the copies would fork the CLI surface between scalar and vector inputs silently. This exceeds the package convention (downsample.cxx duplicates ~11 trivial lines with no enum constraint); hoist the declarations into a templated helper alongside MakeResampleFilter.
8. packages/downsample/CMakeLists.txt:80 — The resample-to-reference smoke ctest is argument-for-argument identical to resample-to-reference-linear (same executable, same inputs, same explicit --interpolator linear; only the output basename differs) — pure duplicate CI work. Additionally, none of the six per-interpolator tests compares output against anything (exit-code-0 only), so a broken interpolator that still writes an image passes the whole matrix. Drop the duplicate and consider a foreach() with a baseline comparison.