Skip to content

CornucopiaAdapter

Bases: Transform

Wrap a Cornucopia transform for use in TorchIO pipelines.

Cornucopia <https://cornucopia.readthedocs.io/>_ transforms operate on (C, I, J, K) tensors and support passing multiple tensors to share spatial parameters (e.g., the same elastic deformation is applied to an image and its segmentation).

The adapter extracts image tensors from the subject, passes them to the Cornucopia transform as positional arguments (scalar images first, then label maps), and writes the results back.

Parameters:

Name Type Description Default
cornucopia_transform Callable

A Cornucopia transform (any callable accepting one or more (C, I, J, K) tensors). Requires cornucopia to be installed: pip install cornucopia.

 required
**kwargs Any

See Transform.

 {}

Examples:

>>> import torchio as tio
>>> import cornucopia as cc
>>> adapter = tio.CornucopiaAdapter(
...     cc.ElasticTransform(),
... )
>>> result = adapter(subject)
Note

CornucopiaAdapter does not record itself in the subject's transform history, because Cornucopia transform objects are not guaranteed to be serializable.

Source code in src/torchio/transforms/cornucopia_adapter.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
class CornucopiaAdapter(Transform):
    """Wrap a Cornucopia transform for use in TorchIO pipelines.

    `Cornucopia <https://cornucopia.readthedocs.io/>`_ transforms
    operate on `(C, I, J, K)` tensors and support passing multiple
    tensors to share spatial parameters (e.g., the same elastic
    deformation is applied to an image and its segmentation).

    The adapter extracts image tensors from the subject, passes them
    to the Cornucopia transform as positional arguments (scalar images
    first, then label maps), and writes the results back.

    Args:
        cornucopia_transform: A Cornucopia transform (any callable
            accepting one or more `(C, I, J, K)` tensors).
            Requires `cornucopia` to be installed:
            `pip install cornucopia`.
        **kwargs: See [`Transform`][torchio.Transform].

    Examples:
        >>> import torchio as tio
        >>> import cornucopia as cc  # doctest: +SKIP
        >>> adapter = tio.CornucopiaAdapter(
        ...     cc.ElasticTransform(),
        ... )  # doctest: +SKIP
        >>> result = adapter(subject)  # doctest: +SKIP

    Note:
        `CornucopiaAdapter` does **not** record itself in the
        subject's transform history, because Cornucopia transform
        objects are not guaranteed to be serializable.
    """

    def __init__(
        self,
        cornucopia_transform: Callable,
        **kwargs: Any,
    ) -> None:
        super().__init__(**kwargs)
        if not callable(cornucopia_transform):
            msg = (
                "cornucopia_transform must be callable, "
                f"got {type(cornucopia_transform).__name__}"
            )
            raise TypeError(msg)
        self.cornucopia_transform = cornucopia_transform

    def forward(self, data: Any) -> Any:
        """Apply without recording history."""
        batch, unwrap = self._wrap(data)
        if self.copy:
            batch = _copy.deepcopy(batch)
        if torch.rand(1).item() > self.p:
            return unwrap(batch)
        subjects = batch.unbatch()
        for subject in subjects:
            _apply_cornucopia(subject, self.cornucopia_transform, self)
        from ..data.batch import SubjectsBatch

        result = SubjectsBatch.from_subjects(subjects)
        result.adopt_history(batch, subjects)
        return unwrap(result)

    def apply_transform(
        self,
        batch: SubjectsBatch,
        params: dict[str, Any],
    ) -> SubjectsBatch:
        """Not used: CornucopiaAdapter overrides forward directly."""
        return batch

    def add_transform_to_subject_history(self, *args: Any) -> None:
        """No-op: Cornucopia transforms are opaque."""

    @property
    def invertible(self) -> bool:
        """Cornucopia transforms are not invertible through TorchIO."""
        return False

supports_per_instance_params property

Whether this transform can sample parameters per batch element.

Defaults to False. Transforms that implement per-instance parameter sampling override this to return True. When False, the transform always uses batch-shared parameters regardless of the per_instance flag, preserving the legacy behavior.

supports_per_instance_p property

Whether this transform can gate each batch element independently.

Defaults to False. Shape-preserving transforms that implement per-element probability override this to return True. Shape-changing transforms must leave it False because masked and unmasked elements would have incompatible shapes.

invertible property

Cornucopia transforms are not invertible through TorchIO.

make_params(batch)

Sample random parameters for this transform.

Override in subclasses that have random behavior.

Parameters:

Name Type Description Default
batch SubjectsBatch

A SubjectsBatch.

 required

Returns:

Type Description
dict[str, Any]

Dict of sampled parameters.
Source code in src/torchio/transforms/transform.py 
382
383
384
385
386
387
388
389
390
391
392
393
def make_params(self, batch: SubjectsBatch) -> dict[str, Any]:
    """Sample random parameters for this transform.

    Override in subclasses that have random behavior.

    Args:
        batch: A `SubjectsBatch`.

    Returns:
        Dict of sampled parameters.
    """
    return {}

inverse(params)

Return a transform that undoes this one.

Override in invertible subclasses. The returned transform, when applied, reverses the effect of the forward pass with the given parameters.

Parameters:

Name Type Description Default
params dict[str, Any]

The parameters recorded in the forward pass.

 required

Returns:

Type Description
Transform

A new Transform instance that inverts this one.
Source code in src/torchio/transforms/transform.py 
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
def inverse(self, params: dict[str, Any]) -> Transform:
    """Return a transform that undoes this one.

    Override in invertible subclasses. The returned transform,
    when applied, reverses the effect of the forward pass with
    the given parameters.

    Args:
        params: The parameters recorded in the forward pass.

    Returns:
        A new `Transform` instance that inverts this one.
    """
    msg = f"{type(self).__name__} is not invertible"
    raise NotImplementedError(msg)

to_hydra()

Export as a Hydra-compatible config dict.

Returns a dict with _target_ set to the fully qualified class name and only non-default field values included.

Returns:

Type Description
dict[str, Any]

Dict suitable for hydra.utils.instantiate().
Source code in src/torchio/transforms/transform.py 
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
def to_hydra(self) -> dict[str, Any]:
    """Export as a Hydra-compatible config dict.

    Returns a dict with `_target_` set to the fully qualified
    class name and only non-default field values included.

    Returns:
        Dict suitable for `hydra.utils.instantiate()`.
    """
    from .parameter_range import _ParameterRange

    cls = type(self)
    target = f"torchio.{cls.__qualname__}"
    cfg: dict[str, Any] = {"_target_": target}

    for name, default in _collect_init_params(cls).items():
        value = getattr(self, name, default)
        if isinstance(value, _ParameterRange):
            if value._original == default:
                continue
            value = _hydra_value(value._original)
        elif value == default:
            continue
        else:
            value = _hydra_value(value)
        cfg[name] = value
    return cfg

forward(data)

Apply without recording history.

Source code in src/torchio/transforms/cornucopia_adapter.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
def forward(self, data: Any) -> Any:
    """Apply without recording history."""
    batch, unwrap = self._wrap(data)
    if self.copy:
        batch = _copy.deepcopy(batch)
    if torch.rand(1).item() > self.p:
        return unwrap(batch)
    subjects = batch.unbatch()
    for subject in subjects:
        _apply_cornucopia(subject, self.cornucopia_transform, self)
    from ..data.batch import SubjectsBatch

    result = SubjectsBatch.from_subjects(subjects)
    result.adopt_history(batch, subjects)
    return unwrap(result)

apply_transform(batch, params)

Not used: CornucopiaAdapter overrides forward directly.

Source code in src/torchio/transforms/cornucopia_adapter.py 
82
83
84
85
86
87
88
def apply_transform(
    self,
    batch: SubjectsBatch,
    params: dict[str, Any],
) -> SubjectsBatch:
    """Not used: CornucopiaAdapter overrides forward directly."""
    return batch

add_transform_to_subject_history(*args)

No-op: Cornucopia transforms are opaque.

Source code in src/torchio/transforms/cornucopia_adapter.py 
90
91
def add_transform_to_subject_history(self, *args: Any) -> None:
    """No-op: Cornucopia transforms are opaque."""