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=None, method='mip', threshold=None, relative_step_size=0.8, cmap='grays', gamma=1.0, clim_range_threshold=0.2, emulate_texture=False, interpolation='linear')

Bases: vispy.visuals.visual.Visual

Displays a 3D Volume

Parameters

volndarray

The volume to display. Must be ndim==3.

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

thresholdfloat

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

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.

clim_range_thresholdfloat

When changing the clims, if the new clim range is smaller than this fraction of the last-used texture data range, then it will trigger a rescaling of the texture data. For instance: if the texture data was last scaled from 0-1, and the clims are set to 0.4-0.5, then a texture rescale will be triggered if clim_range_threshold < 0.1. To prevent rescaling, set this value to 0. To always rescale, set the value to >= 1. By default, 0.2

emulate_texturebool

Use 2D textures to emulate a 3D texture. OpenGL ES 2.0 compatible, but has lower performance on desktop platforms.

interpolation{‘linear’, ‘nearest’}

Selects method of image interpolation.

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 clim_normalized

Normalize current clims between 0-1 based on last-used texture data range.

In set_data(), the data is normalized (on the CPU) to 0-1 using clim. During rendering, the frag shader will apply the final contrast adjustment based on the current clim.

property cmap

property gamma

The gamma used when rendering the image.

property interpolation

The interpolation method to use

Current options are:

• linear: this method is appropriate for most volumes as it creates nice looking visuals.

• nearest: this method is appropriate for volumes with discrete data where additional interpolation does not make sense.

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.

rescale_data()

Force rescaling of data to the current contrast limits and texture upload.

Because Textures are currently 8-bits, and contrast adjustment is done during rendering by scaling the values retrieved from the texture on the GPU (provided that the new contrast limits settings are within the range of the clims used when the last texture was uploaded), posterization may become visible if the contrast limits become too small of a fraction of the clims used to normalize the texture. This function is a convenience to “force” rescaling of the Texture data to the current contrast limits range.

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

Set the volume data.

Parameters

volndarray

The 3D volume.

climtuple | None

Colormap limits to use. None will use the min and max values.

copybool | True

Whether to copy the input volume prior to applying clim normalization.

property texture_is_inverted

property threshold

The threshold value to apply for the isosurface render method.

vispy.visuals.visual module vispy.visuals.windbarb module