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 rendering Nifti overlay types which represent directional data (and which are described by a VectorOpts instance). The GLVectorBase class is a sub-class of GLImageObject.

The GLVectorBase class is a base class which is not intended to be instantiated directly. The GLRGBVector, GLLineVector, GLTensor, and GLSH subclasses should be used instead. These subclasses share the functionality provided by this class. See also the GLVector 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 the xyz directions) to form the final fragment colour. The colours for each component are specified by the VectorOpts.xColour, VectorOpts.yColour, and VectorOpts.zColour properties. If the image being displayed contains directional data (e.g. is a X*Y*Z*3 vector image), you should use the GLVector 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 and VectorOpts.cmap properties.

In either case, the brightness or transparency of each vector colour may be modulated by another image, specified by the VectorOpts.modulateImage and VectorOpts.modulateMode properties. This modulation image is stored as a 3D single-channel ImageTexture.

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-channel ImageTexture, and the clipping thresholds specified by the VectorOpts.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 and VectorOpts 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 this GLVectorBase have been initialised.

• preinit – An optional functiono be called after this GLVectorBase has configured itself, but before init is called. Used by GLVector.

destroy()

Must be called when this GLVectorBase is no longer needed. Deletes the GL textures, and deregisters the listeners configured in __init__().

property modulateTexture

Returns the ImageTexture for the VectorOpts.modulateImage.

property clipTexture

Returns the ImageTexture for the VectorOpts.clipImage.

property colourTexture

Returns the ImageTexture for the VectorOpts.colourImage.

ready()

Returns True if this GLVectorBase is ready to be drawn, False otherwise.

texturesReady()

Calls AuxImageTextureManager.texturesReady().

addListeners()

Called by __init__(). Adds listeners to properties of the Display and VectorOpts instances, so that the GL representation can be updated when the display properties change.

removeListeners()

Called by destroy(). Removes all property listeners added by the addListeners() method.

compileShaders()

This method must be provided by subclasses (e.g.g the GLRGBVector and GLLineVector classes), and must compile the vertex/fragment shaders used to render this GLVectorBase. .

updateShaderState()

This method must be provided by subclasses (e.g. the GLRGBVector and GLLineVector classes), and must update the state of the vertex/fragment shader programs. It must return True if the shader state was updated, False otherwise.

asyncUpdateShaderState(*args, **kwargs)

Calls updateShaderState() and then Notifier.notify(), using idle.idleWhen() function to make sure that it is only called when ready() returns True.

refreshColourMapTexture(colourRes=256)

Called when the component colour maps need to be updated, when one of the VectorOpts.xColour, yColour, zColour, cmap, suppressX, suppressY, or suppressZ 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 the x, y, and z 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.

__cmapPropChanged(*a)

Called when a Display or VectorOpts property affecting the vector colour map settings changes. Calls refreshColourMapTexture() and asyncUpdateShaderState().

registerAuxImage(which, image, onReady=None, **kwargs)

Registers the given auxillary image with the AuxImageTextureManager.

__colourImageChanged(*a)

Called when the VectorOpts.colourImage changes. Registers with the new image, and refreshes textures as needed.

__modImageChanged(*a)

Called when the VectorOpts.modulateImage changes. Registers with the new image, and refreshes textures as needed.

__clipImageChanged(*a)

Called when the VectorOpts.clipImage changes. Registers with the new image, and refreshes textures as needed.

__textureChanged(*a)

Called when any of the ImageTexture instances containing clipping, modulation or colour data, are refreshed. Notifies listeners of this GLVectorBase (via the Notifier 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 of GLVectorBase, which contains some additional logic for rendering Image overlays with a shape X*Y*Z*3, or of type NIFTI_TYPE_RGB24, and which contain directional data.

By default , the image overlay passed to __init__() is assumed to be an Image instance which contains vector data. If this is not the case, the vectorImage parameter may be used to pass in the Image that contains the vector data.

This vector image is stored on the GPU as a 3D RGB ImageTexture, where the R channel contains the x vector values, the G channel the y values, and the B channel the z values.

This texture is bound to texture unit gl.GL_TEXTURE4 in the preDraw() 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 to GLVectorBase.__init__().

The image, (or vectorImage) argument is assumed to be an Image instance of shape (X, Y, Z, 3), or of type NIFTI_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, the image is assumed to be an Image instance which contains the vector data. If this is not the case, the vectorImage parameter can be used to specify an Image 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 this GLVector is no longer needed. Calls GLVectorBase.destroy(), and destroys the vector image texture.

texturesReady()

Overrides GLVectorBase.texturesReady(). Returns True if all of the textures managed by this GLVector are ready to be used, False otherwise.

refreshImageTexture(interp=<MagicMock name='mock.GL.GL_NEAREST' id='4058093072'>)

Called by __init__(), and when the ImageTexture needs to be updated. (Re-)creates the ImageTexture, using the resources module so that the texture can be shared by other users.

Parameters

interp – Interpolation method (GL_NEAREST or GL_LINEAR). Used by sub-class implementations (see GLRGBVector).

preDraw(xform=None, bbox=None)

Overrides GLVectorBase(). Binds the vector image texture.

postDraw(xform=None, bbox=None)

Overrides GLVectorBase(). Unbinds the vector image texture.

__textureChanged(*a)

Called when the ImageTexture instance containing the vector data is are refreshed. Notifies listeners of this GLVector (via the Notifier base class).

__module__ = 'fsleyes.gl.glvector'