Add partial-volume-aware label resampling mode

[fepegar]

[Partially generated by a coding agent]

---

---

Summary

Adds an opt-in label_interpolation="label" mode to the spatial transforms (Spatial, Resample, Affine, ElasticDeformation) for proper, partial-volume-aware resampling of label maps.

Nearest-neighbor interpolation (the default) produces staircase artifacts, biases label volumes, and erodes small structures under strong downsampling. The new mode instead:

1. one-hot encodes the label map using the unique label values present (robust to non-contiguous labels such as {0, 2, 5});
2. optionally Gaussian-smooths each channel before downsampling when antialias=True (reusing the existing Cardoso et al., MICCAI 2015 sigma);
3. resamples every channel with linear interpolation; and
4. takes the per-voxel argmax, remapping back to the original label values.

Out-of-bounds voxels use default_pad_label. Multi-channel (already one-hot) label inputs are resampled linearly without re-encoding.

Behavior / compatibility

• Defaults unchanged: label_interpolation stays "nearest" everywhere; this is purely opt-in.
• image_interpolation="label" raises a clear ValueError (the mode is label-only).
• The mode never produces label values absent from the input.

Example

import torchio as tio

transform = tio.Resample(2, label_interpolation="label", antialias=True)

Tests

New TestLabelInterpolation in tests/test_spatial.py: no invalid labels (up/downsampling), non-contiguous round-trip, default_pad_label fill, image_interpolation="label" raises, antialias path, multi-channel input, and a round-trip Dice check showing "label" beats "nearest".

uv run pytest tests/test_spatial.py tests/test_one_hot.py -q -> 99 passed. ruff and ty clean.

Notes

• For extreme downsampling of highly convoluted multi-tissue maps, nearest can occasionally match/beat "label" on Dice because argmax correctly drops sub-voxel-thin structures; "label" wins clearly at moderate-to-strong factors and on small structures.
• A separate, pre-existing bug was observed during testing: copy.deepcopy of a CropOrPad output reverts the image to its original (pre-crop) shape, which makes Resample compute the wrong output grid (since forward deepcopies inputs). Not addressed here; can file separately.

[github-actions]

📖 Docs Preview

Preview of the documentation for this PR:

🔗 https://smokeshow.helpmanual.io/3g5j630h1v1y5e513r4t/

_{Built from c112917}

[Copilot]

Pull request overview

Adds an opt-in label_interpolation="label" mode to TorchIO’s unified spatial transform pipeline to resample discrete label maps in a partial-volume-aware way (one-hot → linear resample → argmax), with optional antialiasing, plus tests covering core behaviors.

Changes:

• Extend interpolation parsing/support to include a new "label" mode for LabelMap resampling.
• Implement _resample_label_partial_volume() and route label batches through it when requested.
• Add TestLabelInterpolation coverage for validity, padding, antialias, and multi-channel label behavior.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
src/torchio/transforms/spatial/spatial.py	Adds "label" interpolation option, validation, and the partial-volume label resampling helper integrated into the spatial batch application path.
tests/test_spatial.py	Adds tests validating parsing/validation and functional behavior of the new label interpolation mode.

---

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

src/torchio/transforms/spatial/spatial.py:89

• _parse_interpolation() and the docstring state that integer interpolation orders 0–7 are supported, and tests already pass image_interpolation=3. However, the public type aliases/signatures use TypeImageInterpolation/TypeLabelInterpolation that only accept string literals, so static type checkers will flag valid usage (e.g. tio.Affine(image_interpolation=3)). Consider extending the type aliases to include the allowed integer orders to keep the public typing consistent with runtime behavior and docs.

TypeImageInterpolation: TypeAlias = Literal[
    "nearest",
    "linear",
    "quadratic",
    "cubic",

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

[romainVala]

Hi there

This is a cool add on !
I use a 'home made' version of this interpolation, which is indeed very useful especially when you want to upsample a label file

Just a small comment about step 3
3 .resamples every channel with linear interpolation;

It would be nice to add an extra parametre (let call it one_hot_label_interpolation=linear by default ) but the user could then also use other interpolation (bspline, sinc ect ...)

Cheers

Romain

(may be a note to add in the documentation: this can be extremely memory demanding as the number of labels augments)
I work now with more thant 300 labels, and this is a typical use case where applying this transform patch by patch with a gridSampler would help to adjust this process to available memory

[fepegar]

Thanks, @romainVala. Your suggestions have been addressed in e7f8e0f.