fsleyes.gl.glvector
¶
This module provides the GLVectorBase
and GLVector
classes. The GLVectorBase
class encapsulate the logic for rendering
overlays which contain directional data, and the GLVector
class
specifically conatins logic for displaying Image
overlays with
shape X*Y*Z*3
, or of type NIFTI_TYPE_RGB24
.
-
class
fsleyes.gl.glvector.
GLVectorBase
(overlay, overlayList, displayCtx, canvas, threedee, init=None, preinit=None)¶ Bases:
fsleyes.gl.glimageobject.GLImageObject
The
GLVectorBase
class encapsulates the logic for renderingNifti
overlay types which represent directional data (and which are described by aVectorOpts
instance). TheGLVectorBase
class is a sub-class ofGLImageObject
.The
GLVectorBase
class is a base class which is not intended to be instantiated directly. TheGLRGBVector
,GLLineVector
,GLTensor
, andGLSH
subclasses should be used instead. These subclasses share the functionality provided by this class. See also theGLVector
class, which is also a base class.Colouring
A
GLVectorBase
can be coloured in one of two ways:Each voxel is coloured according to the orientation of the vector. A custom fragment shader program looks up the
xyz
vector values, and combines three colours (corresponding to thexyz
directions) to form the final fragment colour. The colours for each component are specified by theVectorOpts.xColour
,VectorOpts.yColour
, andVectorOpts.zColour
properties. If the image being displayed contains directional data (e.g. is aX*Y*Z*3
vector image), you should use theGLVector
class.Each voxel is coloured according to the values contained in another image, which are used to look up a colour in a colour map. The image and colour map are respectively specified by the
VectorOpts.colourImage
andVectorOpts.cmap
properties.
In either case, the brightness of each vector colour may be modulated by another image, specified by the
VectorOpts.modulateImage
property. This modulation image is stored as a 3D single-channelImageTexture
.Finally, vector voxels may be clipped according to the values of another image, specified by the
VectorOpts.clipImage
property. This clipping image is stored as a 3D single-channelImageTexture
, and the clipping thresholds specified by theVectorOpts.clippingRange
property.Textures
The
GLVectorBase
class configures its textures in the following manner:modulateTexture
gl.GL_TEXTURE0
clipTexture
gl.GL_TEXTURE1
colourTexture
gl.GL_TEXTURE2
cmapTexture
gl.GL_TEXTURE3
-
__init__
(overlay, overlayList, displayCtx, canvas, threedee, init=None, preinit=None)¶ Create a
GLVectorBase
object bound to the given overlay and display.Initialises the OpenGL data required to render the given vector overlay. This method does the following:
Creates the modulate, clipping and colour image textures.
Adds listeners to the
Display
andVectorOpts
instances, so the textures and geometry can be updated when necessary.
- Parameters
overlay – A
Nifti
object.overlayList – The
OverlayList
displayCtx – A
DisplayContext
object which describes how the overlay is to be displayed.canvas – The canvas doing the drawing.
threedee – 2D or 3D rendering.
init – An optional function to be called when all of the
ImageTexture
instances associated with thisGLVectorBase
have been initialised.preinit – An optional functiono be called after this
GLVectorBase
has configured itself, but beforeinit
is called. Used byGLVector
.
-
destroy
()¶ Must be called when this
GLVectorBase
is no longer needed. Deletes the GL textures, and deregisters the listeners configured in__init__()
.
-
ready
()¶ Returns
True
if thisGLVectorBase
is ready to be drawn,False
otherwise.
-
texturesReady
()¶ Returns
True
if all of the textures are ready,False
otherwise.
-
addListeners
()¶ Called by
__init__()
. Adds listeners to properties of theDisplay
andVectorOpts
instances, so that the GL representation can be updated when the display properties change.
-
removeListeners
()¶ Called by
destroy()
. Removes all property listeners added by theaddListeners()
method.
-
compileShaders
()¶ This method must be provided by subclasses (e.g.g the
GLRGBVector
andGLLineVector
classes), and must compile the vertex/fragment shaders used to render thisGLVectorBase
. .
-
updateShaderState
()¶ This method must be provided by subclasses (e.g. the
GLRGBVector
andGLLineVector
classes), and must update the state of the vertex/fragment shader programs. It must returnTrue
if the shader state was updated,False
otherwise.
-
asyncUpdateShaderState
(*args, **kwargs)¶ Calls
updateShaderState()
and thenNotifier.notify()
, usingidle.idleWhen()
function to make sure that it is only called whenready()
returnsTrue
.
-
registerAuxImage
(which)¶ Called when the
VectorOpts.modulateImage
,VectorOpts.clipImage
, orVectorOpts.colourImage
properties change. Registers a listener with theNiftiOpts.volume
property of the modulate/clip/colour image, so the modulate/clip/colour textures can be updated when the image volume changes.
-
deregisterAuxImage
(which)¶ Called when the
VectorOpts.modulateImage
,VectorOpts.clipImage
orVectorOpts.colourImage
properties change. Deregisters theNiftiOpts.volume
listener that was registered inregisterAuxImage()
.
-
refreshAuxTexture
(which, interp=<MagicMock name='mock.GL.GL_NEAREST' id='140736131267664'>)¶ Called when the :attr`.VectorOpts.modulateImage`, :attr`.VectorOpts.clipImage`, or :attr`.VectorOpts.colourImage` properties changes. Reconfigures the modulation/clip/colour
ImageTexture
. If no image is selected, a ‘dummy’ texture is creatad, which contains all white values (and which result in the auxillary textures having no effect).The
interp
argument can be used to set the initial interpolation type (GL_NEAREST
orGL_LINEAR
).
-
refreshColourMapTexture
(colourRes=256)¶ Called when the component colour maps need to be updated, when one of the
VectorOpts.xColour
,yColour
,zColour
,cmap
,suppressX
,suppressY
, orsuppressZ
properties change.Regenerates the colour map texture.
-
getVectorColours
()¶ Prepares the colours that represent each direction.
- Returns:
a
numpy
array of size(3, 4)
containing the RGBA colours that correspond to thex
,y
, andz
vector directions.A
numpy
array of shape(4, 4)
which encodes a scale and offset to be applied to the vector value before it is combined with the colours, encoding the current brightness and contrast settings.
-
getClippingRange
()¶ Returns the
clippingRange
, suitable for use in the fragment shader. The returned values are transformed into the clip image texture value range, so the fragment shader can compare texture values directly to it.
-
getModulateRange
()¶ Returns the
modulateRange
, suitable for use in the fragment shader. The returned values are transformed into the modulate image texture value range, so the fragment shader can compare texture values directly to it.
-
getAuxTextureXform
(which)¶ Generates and returns a transformation matrix which can be used to transform texture coordinates from the vector image to the specified auxillary image (
'clip'
,'modulate'
or'colour'
).
-
preDraw
(xform=None, bbox=None)¶ Must be called by subclass implementations.
Ensures that all of the textures managed by this
GLVectorBase
are bound to their corresponding texture units.
-
postDraw
(xform=None, bbox=None)¶ Must be called by subclass implementations.
Unbinds all of the textures managed by this
GLVectorBase
.
-
_GLVectorBase__clipImageChanged
(*a)¶ Called when the
VectorOpts.clipImage
changes. Registers with the new image, and refreshes textures as needed.
-
_GLVectorBase__cmapPropChanged
(*a)¶ Called when a
Display
orVectorOpts
property affecting the vector colour map settings changes. CallsrefreshColourMapTexture()
andasyncUpdateShaderState()
.
-
_GLVectorBase__colourImageChanged
(*a)¶ Called when the
VectorOpts.colourImage
changes. Registers with the new image, and refreshes textures as needed.
-
_GLVectorBase__modImageChanged
(*a)¶ Called when the
VectorOpts.modulateImage
changes. Registers with the new image, and refreshes textures as needed.
-
_GLVectorBase__textureChanged
(*a)¶ Called when any of the
ImageTexture
instances containing clipping, modulation or colour data, are refreshed. Notifies listeners of thisGLVectorBase
(via theNotifier
base class).
-
__module__
= 'fsleyes.gl.glvector'¶
-
class
fsleyes.gl.glvector.
GLVector
(image, *args, **kwargs)¶ Bases:
fsleyes.gl.glvector.GLVectorBase
The
GLVector
class is a sub-class ofGLVectorBase
, which contains some additional logic for renderingImage
overlays with a shapeX*Y*Z*3
, or of typeNIFTI_TYPE_RGB24
, and which contain directional data.By default , the
image
overlay passed to__init__()
is assumed to be anImage
instance which contains vector data. If this is not the case, thevectorImage
parameter may be used to pass in theImage
that contains the vector data.This vector image is stored on the GPU as a 3D RGB
ImageTexture
, where theR
channel contains thex
vector values, theG
channel they
values, and theB
channel thez
values.This texture is bound to texture unit
gl.GL_TEXTURE4
in thepreDraw()
method.-
__init__
(image, *args, **kwargs)¶ Create a
GLVector
. All of the arguments documented here are optional, but if provided, must be passed as keyword arguments. All other arguments are passed through toGLVectorBase.__init__()
.The
image
, (orvectorImage
) argument is assumed to be anImage
instance of shape(X, Y, Z, 3)
, or of typeNIFTI_TYPE_RGB24
, which contains the vector data. If the former, the vector data is assumed to be in the range[-1, 1]
. If the latter, the vector data is, by definition, in the range[0, 255]
- this is assumed to map directly to the range[-1, 1]
.- Parameters
vectorImage – If
None
, theimage
is assumed to be anImage
instance which contains the vector data. If this is not the case, thevectorImage
parameter can be used to specify anImage
instance which does contain the vector data.prefilter – An optional function which filters the data before it is stored as a 3D texture. See
Texture3D
. Regardless of whether this function is provided, the data is always transposed so that the fourth dimension is the fastest changing, before being transferred to the GPU.prefilterRange – If the provided
prefilter
function will cause the range of the data to change, this function must be provided, and must, given the original data range, return a suitably adjusted adjust data range.
-
destroy
()¶ Overrides
GLVectorBase.destroy()
. Must be called when thisGLVector
is no longer needed. CallsGLVectorBase.destroy()
, and destroys the vector image texture.
-
texturesReady
()¶ Overrides
GLVectorBase.texturesReady()
. ReturnsTrue
if all of the textures managed by thisGLVector
are ready to be used,False
otherwise.
-
refreshImageTexture
(interp=<MagicMock name='mock.GL.GL_NEAREST' id='140736131267664'>)¶ Called by
__init__()
, and when theImageTexture
needs to be updated. (Re-)creates theImageTexture
, using theresources
module so that the texture can be shared by other users.- Parameters
interp – Interpolation method (
GL_NEAREST
orGL_LINEAR
). Used by sub-class implementations (seeGLRGBVector
).
-
preDraw
(xform=None, bbox=None)¶ Overrides
GLVectorBase()
. Binds the vector image texture.
-
postDraw
(xform=None, bbox=None)¶ Overrides
GLVectorBase()
. Unbinds the vector image texture.
-
_GLVector__textureChanged
(*a)¶ Called when the
ImageTexture
instance containing the vector data is are refreshed. Notifies listeners of thisGLVector
(via theNotifier
base class).
-
__module__
= 'fsleyes.gl.glvector'¶
-