✨ Add wk-* CLI suite for warp pipeline operations

[vanandrew]

Summary

Expand warpkit's CLI from medic + extract_field_from_maps to seven
purpose-built tools, all wk- prefixed to avoid colliding with namesakes
from FSL/ANTs/AFNI/etc.:

Command	Purpose
wk-medic	End-to-end MEDIC pipeline (renamed from medic).
wk-unwrap-phase	Stage 1: ROMEO multi-echo phase unwrapping → unwrapped phase + per-frame masks.
wk-compute-fieldmap	Stage 2: stage-1 outputs → native + displacement + undistorted-space field maps.
wk-apply-warp	Resample an image through a displacement map / field (single or per-frame series).
wk-convert-warp	maps ↔ fields, ITK/FSL/ANTs/AFNI conversion, frame extraction, --invert.
wk-convert-fieldmap	Convert between mm displacement maps/fields and Hz B0 field maps.
wk-compute-jacobian	Per-voxel Jacobian determinant (1 = no change, <1 = compression, >1 = expansion).

Closes #12 — wk-unwrap-phase exposes unwrapped phase as a first-class
output usable outside the distortion-correction pipeline (phase regression,
T2* estimation).

Changes

New CLIs / refactor:

• unwrap_and_compute_field_maps split into reusable unwrap_phases +
  compute_field_maps stages; the wrapper is kept so medic()'s Python
  API is unchanged.
• --invert on wk-convert-warp routes by frame count: N==1 uses the
  full 3D invert_displacement_field; N>1 runs invert_displacement_maps
  once on the stacked 4D series (faster per frame, requires --axis).
• Transform type is always declared explicitly: wk-convert-warp and
  wk-compute-jacobian require --from, wk-apply-warp requires
  --transform-type. Auto-classification was prototyped and then dropped
  (9164bcb) — silently misclassifying a 1-channel map as a 3-channel
  field (or vice versa) on a stripped intent code is worse than a clean
  argparse error.

Bug fix surfaced while wiring up wk-convert-warp --invert:

• invert_displacement_field was using np.pad(data, pad_width=1) which
  padded the channel axis as well as the spatial axes; the output array
  came back with last-dim = 5 instead of 3. Now padding is spatial-only
  (((1,1), (1,1), (1,1), (0,0))). The existing test that documented
  this as "out of scope" is updated to assert the full shape match.

Bindings:

• Romeo C++ class facade replaced with free functions in warpkit_cpp
  (romeo_unwrap3d, romeo_unwrap4d, romeo_voxelquality,
  calculate_weights). warpkit_cpp.pyi regenerated via
  scripts/regen-stub.sh.

Internal API:

• New displacement_field_to_map (inverse of displacement_map_to_field).
• Shared CLI IO helpers (frame splitting, bundle/per-frame write,
  intent normalization for scalar outputs) extracted into a private
  warpkit/scripts/_warp_io.py.

Tests + coverage:

• 80 → 206 tests; coverage 74% → 95%.
• Added per-CLI happy-path tests that actually run each script to
  completion against the bundled MEDIC fixture (or tiny synthetic NIfTIs)
  and assert on the output files. Previous suite was argparse-only.
• Added test_compute_jacobian_determinant_zero_field (zero field → J=1).

CI-relevant

• setup.py no longer auto-discovers warpkit/scripts/*.py; entry
  points are listed explicitly in [project.scripts] in pyproject.toml.
  No wheel-matrix change.
• Dockerfile ENTRYPOINT switched from medic → wk-medic.
• README CLI section restructured (added a CLI reference table and
  "Common follow-on workflows" with concrete examples for wk-apply-warp,
  wk-convert-warp, wk-convert-fieldmap, wk-compute-jacobian).
• CLAUDE.md tightened: corrected the cibuildwheel skip list (only
  cp314t-*, not also cp313t-*), added ubuntu-24.04-arm to the runner
  list, and added a coverage snippet to the dev workflow.

Test plan

• uv run pytest -q — 206/206 passing locally
• uv run coverage run && uv run coverage report — 95% total coverage
• uv run pre-commit run --all-files — ruff/format/pyright clean
• End-to-end smoke on the bundled MEDIC fixture for each new CLI
• Verify CI matrix builds wheels for cp311–cp314 on Linux x86/arm + macOS
• Sanity-check Docker entrypoint locally (docker run ... --help)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR expands warpkit’s command-line surface area to a wk-* tool suite for warp/MEDIC pipeline operations, while refactoring the Python/C++ bindings and internal APIs to support staged workflows (unwrap → fieldmap → apply/convert/jacobian) and modernizing packaging/entrypoints.

Changes:

• Introduces new wk-* CLIs (wk-unwrap-phase, wk-compute-fieldmap, wk-apply-warp, wk-convert-warp, wk-compute-jacobian) and updates docs/Docker to use wk-medic.
• Refactors MEDIC unwrap/fieldmap logic into reusable stages (unwrap_phases, compute_field_maps) and adds new warp utility conversion (displacement_field_to_map) plus a bugfix in invert_displacement_field.
• Replaces the ROMEO pybind class wrapper with module-level free functions and expands tests to include CLI happy paths.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
warpkit/warpkit_cpp.pyi	Updates type stubs for ROMEO bindings refactor (free functions, no Romeo class).
warpkit/utilities.py	Adds displacement_field_to_map and fixes spatial-only padding in invert_displacement_field.
warpkit/unwrap.py	Switches ROMEO usage from class instance to module-level binding functions; adds staged unwrap/fieldmap APIs.
warpkit/scripts/unwrap_phase.py	New CLI for phase unwrapping stage outputting per-echo unwrapped phase + masks.
warpkit/scripts/medic.py	Updates CLI metadata/epilog formatting (wk-prefixed usage in tests/docs).
warpkit/scripts/extract_field_from_maps.py	Removes legacy CLI superseded by wk-convert-warp.
warpkit/scripts/convert_warp.py	New CLI for map/field conversion, format conversion, and inversion with shared IO helpers.
warpkit/scripts/compute_jacobian.py	New CLI to compute Jacobian determinant per frame from map/field inputs.
warpkit/scripts/compute_fieldmap.py	New CLI for post-unwrap fieldmap/displacement-map computation mirroring MEDIC stage 2.
warpkit/scripts/apply_warp.py	New CLI to resample images through map/field transforms (single or per-frame).
warpkit/scripts/_warp_io.py	New shared IO: input classification/splitting and bundled/per-frame output writing.
tests/test_utilities.py	Updates inversion shape expectations and adds Jacobian determinant zero-field test.
tests/test_unwrap.py	Updates ROMEO binding smoke tests for free-function API.
tests/test_scripts.py	Expands CLI coverage: validation + happy-path execution for the new wk-* scripts.
tests/test_romeo.py	Updates ROMEO tests to use free-function bindings (no Romeo fixture).
tests/conftest.py	Adds fixture returning test-data file paths for CLI tests.
src/warpkit.cpp	Updates pybind11 module exports: removes Romeo class, registers ROMEO free functions.
setup.py	Removes console-script auto-discovery (entrypoints now owned by pyproject.toml).
pyproject.toml	Declares explicit [project.scripts] for wk-* CLI entry points (no longer dynamic).
include/romeo/romeo.h	Refactors ROMEO Python-facing API from a facade class to free functions.
README.md	Documents wk-* CLIs and adds follow-on workflow examples.
Dockerfile	Switches container entrypoint from medic to wk-medic.
CLAUDE.md	Updates contributor/CI guidance to match explicit wk-* scripts and CI/coverage workflow.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

❌ Patch coverage is 98.78049% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.44%. Comparing base (e1d202b) to head (a14a6c4).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
warpkit/unwrap.py	90.00%	3 Missing ⚠️
warpkit/utilities.py	88.88%	2 Missing ⚠️
warpkit/scripts/compute_fieldmap.py	98.36%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             main      #17       +/-   ##
===========================================
+ Coverage   83.54%   94.44%   +10.90%     
===========================================
  Files           9       15        +6     
  Lines         632     1081      +449     
===========================================
+ Hits          528     1021      +493     
+ Misses        104       60       -44     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated 6 comments.

Comments suppressed due to low confidence (1)

warpkit/unwrap.py:741

• unwrap_phases() converts 3D inputs to a single-frame 4D series, but it only forces frames=[0] when frames is None. If a caller passes frames=[1] (or any non-zero index) with 3D inputs, phase_iterator() will index dataobj[..., frame_idx] out of range and crash. Consider validating that all requested frame indices are within [0, phase[0].shape[-1]) after the 3D→4D promotion (and either raise a clear ValueError or coerce frames to [0]).

    # check if data is 4D or 3D
    if len(phase[0].shape) == 3:
        # convert data to 4D
        phase = [
            nib.Nifti1Image(p.get_fdata()[..., np.newaxis], p.affine, p.header)
            for p in phase
        ]
        mag = [
            nib.Nifti1Image(m.get_fdata()[..., np.newaxis], m.affine, m.header)
            for m in mag
        ]
        if frames is None:
            frames = [0]
    elif len(phase[0].shape) == 4:
        # if frames is None, set it to all frames
        if frames is None:
            frames = list(range(phase[0].shape[-1]))
    else:
        raise ValueError("Data must be 3D or 4D.")
    # frames should be a list at this point
    frames = cast(list[int], frames)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.