Add animate CLI subcommand

Author: fepegar

docs/how-to/tta.md

@@ -83,6 +83,8 @@ restored = tio.apply_inverse_transform(data)
 | `Affine` | ✅ | Uses the inverse affine matrix |
 | `ElasticDeformation` | ✅ | Negates the sampled displacement field |
 | `Spatial` | ✅ | Inverts resampling, affine, and elastic parts together |
+| `Normalize` | ✅ | Reverses the linear rescaling |
+| `Standardize` | ✅ | Multiplies by std and adds mean |
 | `Noise` | ❌ | Skipped silently when ``ignore_intensity=True`` |
 
 Non-invertible transforms are **skipped with a warning** (not

docs/how-to/visualization.md

@@ -206,3 +206,31 @@ The data is flipped and transposed as needed so these directions are
 always in the same screen positions. The axis labels show which tensor
 axis (I, J, K) maps to each direction, making it easy to relate what
 you see to the underlying data layout.
+
+## Animated GIFs and videos
+
+You can export an animation sweeping through slices along any
+anatomical direction:
+
+<!-- pytest-codeblocks:skip -->
+```python
+image.to_gif("brain.gif", seconds=5, direction="I")
+image.to_video("brain.mp4", seconds=5, direction="S")
+```
+
+The ``direction`` parameter accepts ``"I"`` (inferior), ``"S"``
+(superior), ``"A"`` (anterior), ``"P"`` (posterior), ``"R"`` (right),
+or ``"L"`` (left). The image is automatically reoriented so slices
+appear in the correct anatomical view.
+
+From the command line:
+
+```bash
+torchio animate brain.nii.gz brain.gif
+torchio animate brain.nii.gz brain.mp4 --seconds 10 --direction S
+```
+
+!!! note "Optional dependencies"
+    GIFs require ``Pillow`` (included in the ``[plot]`` extra).
+    Videos require ``ffmpeg-python`` (``pip install torchio[video]``)
+    and a working ``ffmpeg`` installation.

docs/reference/cli.md

@@ -5,7 +5,7 @@ TorchIO includes a `torchio` command with several subcommands.
 ## Usage
 
 ```
-torchio [plot|info|convert|transform|cache] [options]
+torchio [plot|animate|info|convert|transform|cache] [options]
 ```
 
 ## Reference
@@ -18,6 +18,11 @@ Help text for each subcommand is generated from the source code.
       show_root_heading: true
       heading_level: 3
 
+::: torchio.cli.Animate
+    options:
+      show_root_heading: true
+      heading_level: 3
+
 ::: torchio.cli.Info
     options:
       show_root_heading: true

src/torchio/cli.py

@@ -48,6 +48,53 @@ def run(self) -> None:
         )
 
 
+@dataclass
+class Animate:
+    """Create an animated GIF or MP4 sweeping through slices.
+
+    The output format is inferred from the file extension:
+    ``.gif`` produces an animated GIF, ``.mp4`` produces a video.
+
+    Examples::
+
+        torchio animate brain.nii.gz brain.gif
+        torchio animate brain.nii.gz brain.mp4 --seconds 10 --direction S
+    """
+
+    path: Annotated[Path, tyro.conf.Positional]
+    """Path to the input image."""
+
+    output: Annotated[Path, tyro.conf.Positional]
+    """Output path (.gif or .mp4)."""
+
+    seconds: float = 5.0
+    """Duration of the animation in seconds."""
+
+    direction: str = "I"
+    """Anatomical sweep direction (I, S, A, P, R, or L)."""
+
+    def run(self) -> None:
+        image = tio.ScalarImage(self.path)
+        suffix = self.output.suffix.lower()
+        if suffix == ".gif":
+            image.to_gif(
+                self.output,
+                seconds=self.seconds,
+                direction=self.direction,
+            )
+        elif suffix == ".mp4":
+            image.to_video(
+                self.output,
+                seconds=self.seconds,
+                direction=self.direction,
+            )
+        else:
+            msg = f"Unsupported output format {self.output.suffix!r}. Use .gif or .mp4."
+            print(msg, file=sys.stderr)
+            sys.exit(1)
+        print(f"Created {self.output}")
+
+
 @dataclass
 class Info:
     """Print image metadata to stdout."""
@@ -162,7 +209,7 @@ def run(self) -> None:
         self.command.run()
 
 
-Command = Union[Plot, Info, Convert, Transform, Cache]  # noqa: UP007 (tyro needs Union)
+Command = Union[Plot, Animate, Info, Convert, Transform, Cache]  # noqa: UP007 (tyro needs Union)
 
 
 # ---------------------------------------------------------------------------

tests/test_cli.py

@@ -13,6 +13,7 @@
 import numpy as np
 import pytest
 
+from torchio.cli import Animate
 from torchio.cli import Cache
 from torchio.cli import Convert
 from torchio.cli import Dir
@@ -90,3 +91,20 @@ def test_plot_to_file(self, nii_path: Path, tmp_path: Path) -> None:
         Plot(path=nii_path, output=output).run()
         assert output.exists()
         assert output.stat().st_size > 0
+
+
+class TestAnimate:
+    def test_animate_gif(self, nii_path: Path, tmp_path: Path) -> None:
+        output = tmp_path / "anim.gif"
+        Animate(path=nii_path, output=output, seconds=1.0, direction="I").run()
+        assert output.exists()
+        assert output.stat().st_size > 0
+
+    def test_animate_unsupported_format(
+        self,
+        nii_path: Path,
+        tmp_path: Path,
+    ) -> None:
+        output = tmp_path / "bad.avi"
+        with pytest.raises(SystemExit):
+            Animate(path=nii_path, output=output).run()