fsleyes.gl.glvolume
¶
This module provides the GLVolume
class, which creates and
encapsulates the data and logic required to render 2D slice of an
Image
instance.
- class fsleyes.gl.glvolume.GLVolume(image, overlayList, displayCtx, canvas, threedee)[source]¶
Bases:
fsleyes.gl.glimageobject.GLImageObject
The
GLVolume
class is aGLImageObject
which encapsulates the data and logic required to renderImage
overlays in 2D and 3D.A
GLVolume
instance may be used to render anImage
instance which has aDisplay.overlayType
equal tovolume
. It is assumed that thisImage
instance is associated with aDisplay
instance which, in turn, contains aVolumeOpts
instance, containing display options specific to volume rendering.Version dependent modules
The
GLVolume
class makes use of the functions defined in thegl14.glvolume_funcs
or thegl21.glvolume_funcs
modules, which provide OpenGL version specific details for creation/storage of vertex data, and for rendering.These version dependent modules must provide the following functions:
init(GLVolume)
Perform any necessary initialisation.
destroy(GLVolume)
Perform any necessary clean up.
compileShaders(GLVolume)
(Re-)Compile the shader programs.
updateShaderState(GLVolume)
Updates the shader program states when display parameters are changed.
preDraw(GLVolume, xform, bbox)
Initialise the GL state, ready for drawing.
draw2D(GLVolume, zpos, xform)
Draw a slice of the image at the given
zpos
. Ifxform
is notNone
, it must be applied as a transformation on the vertex coordinates.draw3D(GLVolume, xform, bbox)
Draw the image in 3D. If
xform
is notNone
, it must be applied as a transformation on the vertex coordinates.drawAll(Glvolume, zposes, xforms)
Draws slices at each of the specified
zposes
, applying the correspondingxforms
to each.postDraw(GLVolume, xform, bbox)
Clear the GL state after drawing.
2D rendering
Images are rendered in essentially the same way, regardless of which OpenGL version-specific module is used. The image data itself is stored as an
ImageTexture
. ThisImageTexture
is managed by theresources
module, so may be shared by manyGLVolume
instances. The current colour maps (defined by theVolumeOpts.cmap
andVolumeOpts.negativeCmap
properties) are stored asColourMapTexture
instances. A slice through the texture is rendered using six vertices, located at the respective corners of the image bounds.Image voxels may be clipped according to the
VolumeOpts.clippingRange
property. By default, the voxel value is compared against the clipping range, but theVolumeOpts.clipImage
property allows the data from a different image (of the same dimensions) to be used for clipping. If specified, this clipping image is stored as anotherImageTexture
.If the
ColourMapOpts.modulateAlpha
setting is active, the opacity of rendered voxels is modulated by the voxel intensity. IfVolumeOpts.modulateImage
is also set, the opacity is modulated by the values in a different image - in this case, this image is stored in anotherImageTexture
.An
AuxImageTextureManager
is used to manage the clip and modulate textures.3D rendering
In 3D, images are rendered using a ray-casting approach. The image bounding box is drawn as a cuboid. Then for each pixel, a ray is cast from the ‘camera’ through the image texture. The resulting colour is generated from sampling points along the ray.
The
glvolume_funcs
modules are expected to perform this rendering off-screen, using twoRenderTexture
instances, available as attributesrenderTexture1
and``renderTexture2``. After a call todraw3D
, the final result is assuemd to be contained inrenderTexture1
.Textures
The
GLVolume
class uses the following textures:An
ImageTexture
, a 3D texture which contains image data. This is bound to texture unit 0.A
ColourMapTexture
, a 1D texture which contains the colour map defined by theVolumeOpts.cmap
property. This is bound to texture unit 1.A
ColourMapTexture
, a 1D texture which contains the colour map defined by theVolumeOpts.negativeCmap
property. This is bound to texture unit 2.An
ImageTexture
which contains the clippimg image data. This is bound to texture unit 3. If theVolumeOpts.clipImage
property is not specified (i.e. it has a value ofNone
), this texture will not be bound - in this case, the image texture is used for clipping.Two
RenderTexture
instances which are used for 3D rendering. Both of these textures have depth buffers. When one of these textures is being drawn it is bound to texture units 4 (for RGBA) and 5 (for depth).
Attributes
The following attributes are available on a
GLVolume
instance:imageTexture
The
ImageTexture
which stores the image data.clipTexture
The
ImageTexture
which stores the clip image data.modulateTexture
The
ImageTexture
which stores the modulate image data.colourTexture
The
ColourMapTexture
used to store the colour map.negColourTexture
The
ColourMapTexture
used to store the negative colour map.renderTexture1
The first
RenderTexture
used for 3D rendering.renderTexture2
The first
RenderTexture
used for 3D rendering.texName
A name used for the
imageTexture
,colourTexture
, andnegColourTexture`. The name for the latter is suffixed with ``'_neg'
.- __init__(image, overlayList, displayCtx, canvas, threedee)[source]¶
Create a
GLVolume
object.- Parameters
image – An
Image
object.overlayList – The
OverlayList
displayCtx – The
DisplayContext
object managing the scene.canvas – The canvas doing the drawing.
threedee – Set up for 2D or 3D rendering.
- destroy()[source]¶
This must be called when this
GLVolume
object is no longer needed. It performs any needed clean up of OpenGL data (e.g. deleting texture handles), callsremoveDisplayListeners()
, and callsGLImageObject.destroy()
.
- texturesReady()[source]¶
Returns
True
if theimageTexture
andclipTexture
(if applicable) are both ready to be used,False
otherwise.
- property clipTexture¶
Returns the
ImageTexture
associated with theVolumeOpts.clipImage
.
- property modulateTexture¶
Returns the
ImageTexture
associated with theVolumeOpts.modulateImage
.
- addDisplayListeners()[source]¶
Called by
__init__()
.Adds a bunch of listeners to the
Display
object, and the associatedVolumeOpts
instance, which define how the image should be displayed.This is done so we can update the colour, vertex, and image data when display properties are changed.
- removeDisplayListeners()[source]¶
Called by
destroy()
. Removes all the property listeners that were added byaddDisplayListeners()
.
- testUnsynced()[source]¶
Used by the
refreshImageTexture()
method.Returns
True
if certain criticalVolumeOpts
properties have been unsynced from the parent instance, meaning that thisGLVolume
instance needs to create its own image texture; returnsFalse
otherwise.
- updateShaderState(*args, **kwargs)[source]¶
Calls
gl14.glvolume_funcs.updateShaderState()
orgl21.glvolume_funcs.updateShaderStatea()
, thenNotifier.notify()
. Uses theidle.idleWhen()
function to make sure that it is not called untilready()
returnsTrue
.- Parameters
alwaysNotify – Must be passed as a keyword argument. If
False
(the default),notify
is only called ifglvolume_funcs.updateShaderState
returnsTrue
. Otherwise,notify
is always called.
- refreshImageTexture(**kwargs)[source]¶
Refreshes the
ImageTexture
used to store theImage
data. This is performed through theresources
module, so the image texture can be shared between multipleGLVolume
instances.All keyword arguments are passed through to the
ImageTexture
constructor.
- registerAuxImage(which, image, onReady=None)[source]¶
Calls
AuxImageTextureManager.registerAuxImage()
, making sure that the texture interpolation is set appropriately.
- refreshColourTextures()[source]¶
Refreshes the
ColourMapTexture
instances used to colour image voxels.
- preDraw(*args, **kwargs)[source]¶
Binds the
ImageTexture
toGL_TEXTURE0
and theColourMapTexture
toGL_TEXTURE1, and calls the version-dependent ``preDraw
function.
- postDraw(*args, **kwargs)[source]¶
Unbinds the
ImageTexture
andColourMapTexture
, and calls the version-dependentpostDraw
function.
- getAuxTextureXform(which)[source]¶
Calculates a transformation matrix which will transform from the image coordinate system into the
VolumeOpts.clipImage
orVolumeOpts.modulateImage
coordinate system. If the property isNone
, it will be an identity transform.This transform is used by shader programs to find the auxillary image coordinates that correspond with specific image coordinates.
- getModulateValueXform()[source]¶
Returns an affine transform to normalise alpha modulation values.
The GL volume shaders need to normalise the modulate value by the modulation range to generate an opacity value. We calculate a suitable scale and offset by buildin an affine transform which transforms voxel values from the image/modulate image texture range to 0/1, where 0 corresponds to the low modulate range bound, and 1 to the high modulate range bound. The resulting scale/offset can be used by the shader to convert a modulate value directly into an opacity value.
- generateVertices2D(zpos, axes, bbox=None)[source]¶
Overrides
GLImageObject.generateVertices2D()
.Appliies the
ImageTextureBase.texCoordXform()
to the texture coordinates - this is performed to support 2D images/textures.
- generateVertices3D(bbox=None)[source]¶
Overrides
GLImageObject.generateVertices3D()
.Appliies the
ImageTextureBase.texCoordXform()
to the texture coordinates - this is performed to support 2D images/textures.
- _alphaChanged(*a)[source]¶
Called when the
Display.alpha
property changes.
- _lowClippingRangeChanged(*a)[source]¶
Called when the low
VolumeOpts.clippingRange
property changes. Separate listeners are used for the low and high clipping values to avoid unnecessary duplicate refreshes in the event that theVolumeOpts.linkLowRanges
orVolumeOpts.linkHighRanges
flags are set.
- _highClippingRangeChanged(*a)[source]¶
Called when the high
VolumeOpts.clippingRange
property changes (see_lowClippingRangeChanged()
).
- _clipImageChanged(*a)[source]¶
Called when the
VolumeOpts.clipImage
property changes.
- _modulateImageChanged(*a)[source]¶
Called when the
VolumeOpts.modulateImage
property changes.
- _cmapChanged(*a)[source]¶
Called when the
VolumeOpts.cmap
orVolumeOpts.negativeCmap
properties change.
- _modulateAlphaChanged(*a)[source]¶
Called when the
VolumeOpts.modulateAlpha
property changes. CallsupdateShaderState()
.
- _enableOverrideDataRangeChanged(*a)[source]¶
Called when the
VolumeOpts.enableOverrideDataRange
property changes. Calls_volumeChanged()
.
- _overrideDataRangeChanged(*a)[source]¶
Called when the
VolumeOpts.overrideDataRange
property changes. Calls_volumeChanged()
, but only ifVolumeOpts.enableOverrideDataRange
isTrue
.
- _volumeChanged(*a, **kwa)[source]¶
Called when the
NiftiOpts.volume
property changes Also called when other properties, which require a texture refresh, change.
- _channelChanged(*a, **kwa)[source]¶
Called when the
NiftiOpts.channel
changes. Refreshes the texture.
- _transformChanged(*a)[source]¶
Called when the
NiftiOpts.transform
property changes.
- _displayXformChanged(*a)[source]¶
Called when the
NiftiOpts.displayXform
property changes.
- _numStepsChanged(*a)[source]¶
Called when the
Volume3DOpts.numSteps
property changes.
- _numInnerStepsChanged(*a)[source]¶
Called when the
Volume3DOpts.numInnerSteps
property changes.
- _resolutionChanged(*a)[source]¶
Called when the
Volume3DOpts.resolution
property changes.
- _numClipPlanesChanged(*a)[source]¶
Called when the
Volume3DOpts.numClipPlanes
property changes.
- _clipModeChanged(*a)[source]¶
Called when the
Volume3DOpts.clipMode
property changes.
- _clipping3DChanged(*a)[source]¶
Called when any of the
Volume3DOpts.clipPosition
,Volume3DOpts.clipAzimuth
, orVolume3DOpts.clipInclination
properties change.
- _showClipPlanesChanged(*a)[source]¶
Called when the
Volume3DOpts.showClipPlanes
property changes.
- _blendPropertiesChanged(*a)[source]¶
Called when the
Volume3DOpts.showClipPlanes
property changes.
- _smoothingChanged(*a)[source]¶
Called when the
Volume3DOpts.smoothing
property changes.
- _imageSyncChanged(*a)[source]¶
Called when the synchronisation state of the
NiftiOpts.volume
orVolumeOpts.interpolation
properties change.
- __texturesChanged(*a)¶
Called when either the
imageTexture
or theclipTexture
changes. CallsupdateShaderState()
.
- __annotations__ = {}¶
- __module__ = 'fsleyes.gl.glvolume'¶