---

name: visualization-interop description: "Plot, render, convert channels/RGB, matrix/image data, and interoperate with NumPy, nibabel, and SimpleITK in ANTsPy." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Visualization and Interop

Use this sub-skill when a task asks for ANTsPy plotting, saved figures, headless rendering, image grids, orthographic views, movies, channel/RGB/vector handling, image-to-matrix conversion, n-dimensional image splitting/merging, or conversion to/from nibabel and SimpleITK objects.

Start Here

1. Import the public package as import ants; the installable distribution is antspyx.
2. For CI, servers, notebooks without display access, or scripts that save figures, set a non-interactive Matplotlib backend before importing ants; see workflows.
3. Use API reference for verified plotting signatures, conversion signatures, optional dependency notes, and known unsupported aliases.
4. Pick a recipe from workflows: saved plots, overlays, grids, histograms, movies, channels/RGB/vector images, matrix/image round trips, n-dimensional image lists, nibabel, or SimpleITK.
5. Check troubleshooting for backend failures, optional import failures, overlay mismatch, channel axis confusion, and mask/matrix ordering issues.
6. For a deterministic runtime check, run scripts/antspy_plotting_smoke.py in an environment with antspyx, numpy, and matplotlib installed.

Core Rules

• Pass filename= to ants.plot, ants.plot_ortho, ants.plot_ortho_stack, and ants.plot_grid for non-interactive rendering; otherwise these functions call Matplotlib display behavior.
• Validate physical space before display or conversion with ants.image_physical_space_consistency(a, b). Some plotting helpers resample mismatched overlays automatically, but explicit validation prevents silent interpolation mistakes.
• Plotting helpers expect scalar images for base display and overlays. Split component images, choose a scalar component, or make an RGB/vector image intentionally before plotting.
• ants.scalar_to_rgb is present in the namespace but is not a working scalar colorizer in current ANTsPy; use Matplotlib colormaps on arrays or explicit RGB image construction when scalar-to-RGB display is needed.
• ANTsPy component arrays use a trailing component axis. Move channel-first arrays to channel-last before ants.from_numpy(..., has_components=True) or ants.from_numpy(..., is_rgb=True).
• Matrix rows follow the order of the input image list; matrix columns follow the voxel order selected by mask >= epsilon. Reuse the exact same mask and epsilon when converting back.

Route Elsewhere

• Image creation, IO, metadata setters, pixel types, NumPy views/copies, and physical-space primitives: image-core.
• Filtering, masks, thresholding, resampling, cropping, padding, denoising, morphology, histogram matching, and display preprocessing: image-ops-math.
• Registration, transform application, warped grids, transform ordering, interpolation for registration outputs, and deformation-field interpretation: registration-transforms.
• Segmentation overlays when label semantics, label ordering, or label-specific metrics matter: segmentation-labels.
• Deep-learning patch tensors, augmentation, one-hot arrays, and learning-specific channel conventions: learning-deeplearn.

References

• API reference: plotting, channel/RGB, matrix/image, n-dimensional list, nibabel, and SimpleITK signatures plus behavior notes.
• Workflows: self-contained recipes for headless figures, overlays, grids, histograms, movies, channels/RGB, matrix round trips, and optional interop.
• Troubleshooting: display backend errors, optional dependency failures, physical-space mismatches, vector/RGB pitfalls, and mask ordering problems.