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')[source]¶ 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 currentclim
.
-
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
()[source]¶ 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)[source]¶ 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.