VolumeVisual

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’, since with nearest the result look very ugly. 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 VolumeVisual(vol, clim=None, method='mip', threshold=None, relative_step_size=0.8, cmap='grays', emulate_texture=False)[source]

Bases: vispy.visuals.visual.Visual

Displays a 3D Volume

Parameters

  • vol (ndarray) – The volume to display. Must be ndim==3.

  • clim (tuple of two floats | None) – The contrast limits. The values in the volume are mapped to black and white corresponding to these values. Default maps between min and max.

  • method ({'mip', 'translucent', 'additive', 'iso'}) – 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.

  • 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.

  • emulate_texture (bool) – Use 2D textures to emulate a 3D texture. OpenGL ES 2.0 compatible, but has lower performance on desktop platforms.

set_data(vol, clim=None)[source]

Set the volume data.

Parameters

  • vol (ndarray) – The 3D volume.

  • clim (tuple | None) – Colormap limits to use. None will use the min and max values.

property clim

The contrast limits that were applied to the volume data. Settable via set_data().

property cmap
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.

  • 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.

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 threshold

The threshold value to apply for the isosurface render method.