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:
volndarray

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

climstr | 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’.

thresholdfloat

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_sizefloat

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.

cmapstr

Colormap to use.

gammafloat

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

interpolationstr

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_formatnumpy.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_positionArrayLike

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_normalArrayLike

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_thicknessfloat

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:
volndarray

The 3D volume.

climtuple

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

copybool

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.