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)

Bases: vispy.visuals.visual.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.

interpolation{‘linear’, ‘nearest’}

Selects method of image interpolation.

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, WebGL (without enabling some extensions), 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.

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

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

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.

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