Skip to main content
`Ctrl`+`K`

# vispy.visuals.volume module

## About this technique

In Python, we define the six faces of a cuboid to draw, as well as texture cooridnates corresponding with the vertices of the cuboid. The back faces of the cuboid are drawn (and front faces are culled) because only the back faces are visible when the camera is inside the volume.

In the vertex shader, we intersect the view ray with the near and far clipping planes. In the fragment shader, we use these two points to compute the ray direction and then compute the position of the front cuboid surface (or near clipping plane) along the view ray.

Next we calculate the number of steps to walk from the front surface to the back surface and iterate over these positions in a for-loop. At each iteration, the fragment color or other voxel information is updated depending on the selected rendering method.

It is important for the texture interpolation is ‘linear’ for most volumes, since with ‘nearest’ the result can look very ugly; however for volumes with discrete data ‘nearest’ is sometimes appropriate. The wrapping should be clamp_to_edge to avoid artifacts when the ray takes a small step outside the volume.

The ray direction is established by mapping the vertex to the document coordinate frame, adjusting z to +/-1, and mapping the coordinate back. The ray is expressed in coordinates local to the volume (i.e. texture coordinates).

class vispy.visuals.volume.VolumeVisual(vol, clim='auto', method='mip', threshold=None, attenuation=1.0, relative_step_size=0.8, cmap='grays', gamma=1.0, interpolation='linear', texture_format=None, raycasting_mode='volume', plane_position=None, plane_normal=None, plane_thickness=1.0, clipping_planes=None, clipping_planes_coord_system='scene', mip_cutoff=None, minip_cutoff=None)

  Bases: `Visual`

  Displays a 3D Volume

  Parameters:
    vol ndarray

      The volume to display. Must be ndim==3. Array is assumed to be stored as `(z, y, x)`.

    clim str | tuple

      Limits to use for the colormap. I.e. the values that map to black and white in a gray colormap. Can be ‘auto’ to auto-set bounds to the min and max of the data. If not given or None, ‘auto’ is used.

    method{‘mip’, ‘attenuated_mip’, ‘minip’, ‘translucent’, ‘additive’,

      ‘iso’, ‘average’} The render method to use. See corresponding docs for details. Default ‘mip’.

    threshold float

      The threshold to use for the isosurface render method. By default the mean of the given volume is used.

    attenuation: float

      The attenuation rate to apply for the attenuated mip render method. Default: 1.0.

    relative_step_size float

      The relative step size to step through the volume. Default 0.8. Increase to e.g. 1.5 to increase performance, at the cost of quality.

    cmap str

      Colormap to use.

    gamma float

      Gamma to use during colormap lookup. Final color will be cmap(val**gamma). by default: 1.

    interpolation str

      Selects method of texture interpolation. Makes use of the two hardware interpolation methods and the available interpolation methods defined in vispy/gloo/glsl/misc/spatial_filters.frag

      > - ‘nearest’: Default, uses ‘nearest’ with Texture interpolation.

      > - ‘linear’: uses ‘linear’ with Texture interpolation.

      > - ‘hanning’, ‘hamming’, ‘hermite’, ‘kaiser’, ‘quadric’, ‘cubic’,

      >     ‘catrom’, ‘mitchell’, ‘spline16’, ‘spline36’, ‘gaussian’, ‘bessel’, ‘sinc’, ‘lanczos’, ‘blackman’

    texture_format numpy.dtype | str | None

      How to store data on the GPU. OpenGL allows for many different storage formats and schemes for the low-level texture data stored in the GPU. Most common is unsigned integers or floating point numbers. Unsigned integers are the most widely supported while other formats may not be supported on older versions of OpenGL or with older GPUs. Default value is `None` which means data will be scaled on the CPU and the result stored in the GPU as an unsigned integer. If a numpy dtype object, an internal texture format will be chosen to support that dtype and data will not be scaled on the CPU. Not all dtypes are supported. If a string, then it must be one of the OpenGL internalformat strings described in the table on this page: https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/glTexImage2D.xhtml The name should have GL_ removed and be lowercase (ex. GL_R32F becomes `'r32f'`). Lastly, this can also be the string `'auto'` which will use the data type of the provided volume data to determine the internalformat of the texture. When this is specified (not `None`) data is scaled on the GPU which allows for faster color limit changes. Additionally, when 32-bit float data is provided it won’t be copied before being transferred to the GPU. Note this visual is limited to “luminance” formatted data (single band). This is equivalent to GL_RED format in OpenGL 4.0.

    raycasting_mode{‘volume’, ‘plane’}

      Whether to cast a ray through the whole volume or perpendicular to a plane through the volume defined.

    plane_position ArrayLike

      A (3,) array containing a position on a plane of interest in the volume. The position is defined in data coordinates. Only relevant in raycasting_mode = ‘plane’.

    plane_normal ArrayLike

      A (3,) array containing a vector normal to the plane of interest in the volume. The normal vector is defined in data coordinates. Only relevant in raycasting_mode = ‘plane’.

    plane_thickness float

      A value defining the total length of the ray perpendicular to the plane interrogated during rendering. Defined in data coordinates. Only relevant in raycasting_mode = ‘plane’.

    .. versionchanged: 0.7

      Deprecate ‘emulate_texture’ keyword argument.

  property attenuation

    The attenuation rate to apply for the attenuated mip render method.

  property clim

    The contrast limits that were applied to the volume data.

    Volume display is mapped from black to white with these values. Settable via set_data() as well as @clim.setter.

  property clipping_planes: ndarray

    The set of planes used to clip the volume. Values on the negative side of the normal are discarded.

    Each plane is defined by a position and a normal vector (magnitude is irrelevant). Shape: (n_planes, 2, 3). The order is xyz, as opposed to data’s zyx (for consistency with the rest of vispy)

    Example: one plane in position (0, 0, 0) and with normal (0, 0, 1), and a plane in position (1, 1, 1) with normal (0, 1, 0):

        >>> volume.clipping_planes = np.array([
        >>>     [[0, 0, 0], [0, 0, 1]],
        >>>     [[1, 1, 1], [0, 1, 0]],
        >>> ])

  property clipping_planes_coord_system: str

    Coordinate system used by the clipping planes (see visuals.transforms.transform_system.py)

  property cmap
  property gamma

    The gamma used when rendering the image.

  property interpolation

    Get interpolation algorithm name.

  property interpolation_methods
  property method

    The render method to use

    Current options are:

    > - translucent: voxel colors are blended along the view ray until the result is opaque.

    > - mip: maxiumum intensity projection. Cast a ray and display the maximum value that was encountered.

    > - minip: minimum intensity projection. Cast a ray and display the minimum value that was encountered.

    > - attenuated_mip: attenuated maximum intensity projection. Cast a ray and display the maximum value encountered. Values are attenuated as the ray moves deeper into the volume.

    > - additive: voxel colors are added along the view ray until the result is saturated.

    > - iso: isosurface. Cast a ray until a certain threshold is encountered. At that location, lighning calculations are performed to give the visual appearance of a surface.

    > - average: average intensity projection. Cast a ray and display the average of values that were encountered.

  property minip_cutoff

    The upper cutoff value for minip.

    When using the minip rendering method, fragments with values above the cutoff will be discarded.

  property mip_cutoff

    The lower cutoff value for mip and attenuated_mip.

    When using the mip or attenuated_mip rendering methods, fragments with values below the cutoff will be discarded.

  property plane_normal

    Direction normal to a plane through the volume.

    A (3,) array containing a vector normal to the plane of interest in the volume. The normal vector is defined in data coordinates. Only relevant in raycasting_mode = ‘plane’.

  property plane_position

    Position on a plane through the volume.

    A (3,) array containing a position on a plane of interest in the volume. The position is defined in data coordinates. Only relevant in raycasting_mode = ‘plane’.

  property plane_thickness

    Thickness of a plane through the volume.

    A value defining the total length of the ray perpendicular to the plane interrogated during rendering. Defined in data coordinates. Only relevant in raycasting_mode = ‘plane’.

  property raycasting_mode

    The raycasting mode to use.

    This defines whether to cast a ray through the whole volume or perpendicular to a plane through the volume. must be in {‘volume’, ‘plane’}

  property raycasting_modes
  property relative_step_size

    The relative step size used during raycasting.

    Larger values yield higher performance at reduced quality. If set > 2.0 the ray skips entire voxels. Recommended values are between 0.5 and 1.5. The amount of quality degredation depends on the render method.

  property rendering_methods
  set_data(vol, clim=None, copy=True)

    Set the volume data.

    Parameters:
      vol ndarray

        The 3D volume.

      clim tuple

        Colormap limits to use (min, max). None will use the min and max values. Defaults to `None`.

      copy bool

        Whether to copy the input volume prior to applying clim normalization on the CPU. Has no effect if visual was created with ‘texture_format’ not equal to None as data is not modified on the CPU and data must already be copied to the GPU. Data must be 32-bit floating point data to completely avoid any data copying when scaling on the CPU. Defaults to `True` for CPU scaled data. It is forced to `False` for GPU scaled data.

  property threshold

    The threshold value to apply for the isosurface render method.