Skip to content

snapshots

voxel.snapshot(volume=None, label=None, view='axial', num_slices=1, coord=None, res=256, square=False, resample='nearest', label_colors=None, alpha=0.5, outline=False, pool=4) -> torch.Tensor | list[torch.Tensor]

Render a volume (or stack of overlaid volumes) into one or more 2D RGB snapshot images, optionally blending label masks on top.

Slices are taken along the view direction and returned as channels-last \((H, W, 3)\) uint8 image tensors: a single tensor for one slice, else a list.

Parameters:

  • volume (Volume or list[Volume], default: None ) –

    Volume(s) to render, each with 1 (grayscale) or 3 (RGB) channels. The first defines the base geometry; the rest are composited on top wherever they have in-bounds data. Grayscale channels are contrast-normalized to \([0, 1]\); RGB values must already lie within \([0, 1]\).

  • label (Volume or list[Volume], default: None ) –

    Label overlay(s). A volume with values greater than one is treated as a discrete labelmap: values are conformed to integers, each unique nonzero value becomes a class, resampled with nearest-neighbor interpolation and colored from the volume's labels lookup when it defines a color. A volume within \([0, 1]\) holds soft mask(s), blending softly for fractional values, with each channel a separate class.

  • view (str, default: 'axial' ) –

    View plane: 'axial', 'coronal', or 'sagittal' (or their first letters). Defaults to 'axial'.

  • num_slices (int, default: 1 ) –

    Number of evenly spaced slices along the view direction. Ignored when coord is given. Defaults to 1.

  • coord (Tensor, default: None ) –

    World-space (x, y, z) coordinate. If given, a single slice through this point is rendered and num_slices ignored.

  • res (int, default: 256 ) –

    Pixel height of the rendered images. Slices are resampled to the isotropic in-plane spacing that yields this height, preserving the physical aspect ratio. Defaults to 256.

  • square (bool, default: False ) –

    If True, center-crop or pad the image width to match its height, yielding square (res, res) images. Defaults to False.

  • resample (str, default: 'nearest' ) –

    Interpolation mode used when resampling volumes and labels onto the snapshot grid, either 'linear' or 'nearest'. Defaults to 'nearest'.

  • label_colors (Tensor or list, default: None ) –

    RGB color(s) in \([0, 1]\) for the labels, cycled to match the number of label classes. Overrides any lookup-defined colors. Defaults to a categorical palette.

  • alpha (float, default: 0.5 ) –

    Opacity of the label overlays. Defaults to 0.5.

  • outline (bool, default: False ) –

    If True, draw a fully opaque one-pixel outline just inside the boundary of each label in its color, unaffected by alpha. Defaults to False.

  • pool (int, default: 4 ) –

    Pooling window used to make grayscale normalization robust to outlier voxels. Set to 1 or None to disable. Defaults to 4.

Returns:

  • Tensor or list[Tensor] –

    A single \((H, W, 3)\) uint8 RGB image, or a list of them.

voxel.pca(volumes, n_components=3, mask=None, center=True, standardize=False, whiten=False, normalize='quantile', quantile=0.01, return_basis=False) -> vx.Volume | list[vx.Volume] | tuple

Project the feature channels of one or more volumes onto their principal components using PCA.

Given a list of volumes, a single shared basis is fit across all of them so the resulting colormaps are comparable.

Parameters:

  • volumes (Volume or list[Volume]) –

    Volume(s) to project.

  • n_components (int, default: 3 ) –

    Number of components to keep, i.e. the output channel count. Defaults to 3 (RGB).

  • mask (Volume or list[Volume], default: None ) –

    Foreground mask(s) restricting which voxels are used to fit the basis and normalization. The basis is still applied to every voxel. A single mask is applied to all inputs, a list must match the number of inputs.

  • center (bool, default: True ) –

    Subtract the per-channel mean before fitting.

  • standardize (bool, default: False ) –

    Scale each input channel to unit variance before fitting (correlation-based PCA).

  • whiten (bool, default: False ) –

    Scale each output component to unit variance, balancing their contribution to the colormap.

  • normalize (str, default: 'quantile' ) –

    Per-component output normalization: 'minmax' (rescale to \([0, 1]\)), 'quantile' (robust rescaling that clips the quantile tails), or None. Stats are computed from foreground voxels. Defaults to 'quantile'.

  • quantile (float, default: 0.01 ) –

    Tail fraction clipped when using 'quantile` normalization. Defaults to 0.01.

  • return_basis (bool, default: False ) –

    If True, also return the fit basis dict.

Returns:

  • Volume or list[Volume] –

    The projected volume(s) with n_components channels, matching the single-vs-list structure of the input. If return_basis is True, an (output, basis) tuple is returned instead.