#
# glvector.py - The GLVectorBase and GLVector classes.
#
# Author: Paul McCarthy <pauldmccarthy@gmail.com>
#
"""This module provides the :class:`GLVectorBase` and :class:`GLVector`
classes. The ``GLVectorBase`` class encapsulate the logic for rendering
overlays which contain directional data, and the ``GLVector`` class
specifically conatins logic for displaying :class:`.Image` overlays with
shape ``X*Y*Z*3``, or of type ``NIFTI_TYPE_RGB24``.
"""
import functools as ft
import numpy as np
import OpenGL.GL as gl
import fsl.data.image as fslimage
import fsl.utils.idle as idle
import fsl.transform.affine as affine
import fsleyes.colourmaps as fslcm
from . import resources as glresources
from . import textures
from . import glimageobject
[docs]class GLVectorBase(glimageobject.GLImageObject):
"""The :class:`GLVectorBase` class encapsulates the logic for rendering
:class:`.Nifti` overlay types which represent directional data (and which
are described by a :class:`.VectorOpts` instance). The ``GLVectorBase``
class is a sub-class of :class:`.GLImageObject`.
The ``GLVectorBase`` class is a base class which is not intended to be
instantiated directly. The :class:`.GLRGBVector`, :class:`.GLLineVector`,
:class:`.GLTensor`, and :class:`.GLSH` subclasses should be used instead.
These subclasses share the functionality provided by this class. See also
the :class:`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 :attr:`.VectorOpts.xColour`,
:attr:`.VectorOpts.yColour`, and :attr:`.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
:class:`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
:attr:`.VectorOpts.colourImage` and :attr:`.VectorOpts.cmap` properties.
In either case, the brightness of each vector colour may be modulated by
another image, specified by the :attr:`.VectorOpts.modulateImage`
property. This modulation image is stored as a 3D single-channel
:class:`.ImageTexture`.
Finally, vector voxels may be clipped according to the values of another
image, specified by the :attr:`.VectorOpts.clipImage` property. This
clipping image is stored as a 3D single-channel :class:`.ImageTexture`, and
the clipping thresholds specified by the :attr:`.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``
=================== ==================
"""
[docs] def __init__(self,
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 :class:`.Display` and :class:`.VectorOpts`
instances, so the textures and geometry can be updated when
necessary.
:arg overlay: A :class:`.Nifti` object.
:arg overlayList: The :class:`.OverlayList`
:arg displayCtx: A :class:`.DisplayContext` object which describes
how the overlay is to be displayed.
:arg canvas: The canvas doing the drawing.
:arg threedee: 2D or 3D rendering.
:arg init: An optional function to be called when all of the
:class:`.ImageTexture` instances associated with
this ``GLVectorBase`` have been initialised.
:arg preinit: An optional functiono be called after this
``GLVectorBase`` has configured itself, but
*before* ``init`` is called. Used by
:class:`GLVector`.
"""
glimageobject.GLImageObject.__init__(self,
overlay,
overlayList,
displayCtx,
canvas,
threedee)
name = self.name
opts = self.opts
self.cmapTexture = textures.ColourMapTexture('{}_cm'.format(name))
self.shader = None
self.auxmgr = glimageobject.AuxImageTextureManager(
self, colour=None, modulate=None, clip=None)
self.registerAuxImage('colour', opts.colourImage)
self.registerAuxImage('modulate', opts.modulateImage)
self.registerAuxImage('clip', opts.clipImage)
self.addListeners()
self.refreshColourMapTexture()
def initWrapper():
if init is not None:
init()
self.notify()
if preinit is not None:
preinit()
idle.idleWhen(initWrapper, self.texturesReady)
[docs] def destroy(self):
"""Must be called when this ``GLVectorBase`` is no longer needed.
Deletes the GL textures, and deregisters the listeners configured in
:meth:`__init__`.
"""
self.cmapTexture.destroy()
self.auxmgr.destroy()
self.removeListeners()
self.cmapTexture = None
self.auxmgr = None
glimageobject.GLImageObject.destroy(self)
@property
def modulateTexture(self):
"""Returns the :class:`.ImageTexture` for the
:attr:`.VectorOpts.modulateImage`.
"""
return self.auxmgr.texture('modulate')
@property
def clipTexture(self):
"""Returns the :class:`.ImageTexture` for the
:attr:`.VectorOpts.clipImage`.
"""
return self.auxmgr.texture('clip')
@property
def colourTexture(self):
"""Returns the :class:`.ImageTexture` for the
:attr:`.VectorOpts.colourImage`.
"""
return self.auxmgr.texture('colour')
[docs] def ready(self):
"""Returns ``True`` if this ``GLVectorBase`` is ready to be drawn,
``False`` otherwise.
"""
return self.shader is not None and self.texturesReady()
[docs] def texturesReady(self):
"""Calls :meth:`.AuxImageTextureManager.texturesReady`. """
return self.auxmgr.texturesReady()
[docs] def addListeners(self):
"""Called by :meth:`__init__`. Adds listeners to properties of the
:class:`.Display` and :class:`.VectorOpts` instances, so that the GL
representation can be updated when the display properties change.
"""
display = self.display
opts = self.opts
name = self.name
display.addListener('alpha', name, self.__cmapPropChanged)
display.addListener('brightness', name, self.__cmapPropChanged)
display.addListener('contrast', name, self.__cmapPropChanged)
opts .addListener('xColour', name, self.asyncUpdateShaderState)
opts .addListener('yColour', name, self.asyncUpdateShaderState)
opts .addListener('zColour', name, self.asyncUpdateShaderState)
opts .addListener('suppressX', name, self.asyncUpdateShaderState)
opts .addListener('suppressY', name, self.asyncUpdateShaderState)
opts .addListener('suppressZ', name, self.asyncUpdateShaderState)
opts .addListener('suppressMode', name, self.asyncUpdateShaderState)
opts .addListener('cmap', name, self.__cmapPropChanged)
opts .addListener('modulateImage', name, self.__modImageChanged)
opts .addListener('clipImage', name, self.__clipImageChanged)
opts .addListener('colourImage', name, self.__colourImageChanged)
opts .addListener('clippingRange', name, self.asyncUpdateShaderState)
opts .addListener('modulateRange', name, self.asyncUpdateShaderState)
opts .addListener('transform', name, self.notify)
[docs] def removeListeners(self):
"""Called by :meth:`destroy`. Removes all property listeners added
by the :meth:`addListeners` method.
"""
display = self.display
opts = self.opts
name = self.name
display.removeListener('alpha', name)
display.removeListener('brightness', name)
display.removeListener('contrast', name)
opts .removeListener('xColour', name)
opts .removeListener('yColour', name)
opts .removeListener('zColour', name)
opts .removeListener('cmap', name)
opts .removeListener('suppressX', name)
opts .removeListener('suppressY', name)
opts .removeListener('suppressZ', name)
opts .removeListener('suppressMode', name)
opts .removeListener('modulateImage', name)
opts .removeListener('clipImage', name)
opts .removeListener('colourImage', name)
opts .removeListener('clippingRange', name)
opts .removeListener('modulateRange', name)
opts .removeListener('transform' , name)
[docs] def compileShaders(self):
"""This method must be provided by subclasses (e.g.g the
:class:`.GLRGBVector` and :class:`.GLLineVector` classes), and must
compile the vertex/fragment shaders used to render this
``GLVectorBase``.
."""
raise NotImplementedError('compileShaders must be implemented by '
'{} subclasses'.format(type(self).__name__))
[docs] def updateShaderState(self):
"""This method must be provided by subclasses (e.g. the
:class:`.GLRGBVector` and :class:`.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.
"""
raise NotImplementedError('updateShaderState must be implemented by '
'{} subclasses'.format(type(self).__name__))
[docs] def asyncUpdateShaderState(self, *args, **kwargs):
"""Calls :meth:`updateShaderState` and then :meth:`.Notifier.notify`, using
:func:`.idle.idleWhen` function to make sure that it is only called
when :meth:`ready` returns ``True``.
"""
alwaysNotify = kwargs.pop('alwaysNotify', None)
def func():
if self.updateShaderState() or alwaysNotify:
self.notify()
idle.idleWhen(func,
self.ready,
name=self.name,
skipIfQueued=True)
[docs] def refreshColourMapTexture(self, colourRes=256):
"""Called when the component colour maps need to be updated, when one
of the :attr:`.VectorOpts.xColour`, ``yColour``, ``zColour``, ``cmap``,
``suppressX``, ``suppressY``, or ``suppressZ`` properties change.
Regenerates the colour map texture.
"""
display = self.display
opts = self.opts
if opts.colourImage is not None:
dmin, dmax = opts.colourImage.dataRange
else:
dmin, dmax = 0.0, 1.0
dmin, dmax = fslcm.briconToDisplayRange(
(dmin, dmax),
display.brightness / 100.0,
display.contrast / 100.0)
self.cmapTexture.set(cmap=opts.cmap,
alpha=display.alpha / 100.0,
displayRange=(dmin, dmax))
[docs] def getVectorColours(self):
"""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.
"""
display = self.display
opts = self.opts
bri = display.brightness / 100.0
con = display.contrast / 100.0
alpha = display.alpha / 100.0
colours = np.array([opts.xColour, opts.yColour, opts.zColour])
colours[:, 3] = alpha
if opts.suppressMode == 'white': suppress = [1, 1, 1, alpha]
elif opts.suppressMode == 'black': suppress = [0, 0, 0, alpha]
elif opts.suppressMode == 'transparent': suppress = [0, 0, 0, 0]
# Transparent suppression
if opts.suppressX: colours[0, :] = suppress
if opts.suppressY: colours[1, :] = suppress
if opts.suppressZ: colours[2, :] = suppress
# Scale/offset for brightness/contrast.
# Note: This code is a duplicate of
# that found in ColourMapTexture.
lo, hi = fslcm.briconToDisplayRange((0, 1), bri, con)
if hi == lo: scale = 0.0000000000001
else: scale = hi - lo
xform = np.identity(4, dtype=np.float32)
xform[0, 0] = 1.0 / scale
xform[0, 3] = -lo * xform[0, 0]
return colours, xform
[docs] def getClippingRange(self):
"""Returns the :attr:`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.
"""
opts = self.opts
clipLow, clipHigh = opts.clippingRange
xform = self.clipTexture.invVoxValXform
if opts.clipImage is not None:
clipLow = clipLow * xform[0, 0] + xform[0, 3]
clipHigh = clipHigh * xform[0, 0] + xform[0, 3]
else:
clipLow = -0.1
clipHigh = 1.1
return clipLow, clipHigh
[docs] def getModulateRange(self):
"""Returns the :attr:`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.
"""
opts = self.opts
modLow, modHigh = opts.modulateRange
xform = self.modulateTexture.invVoxValXform
if opts.modulateImage is not None:
modLow = modLow * xform[0, 0] + xform[0, 3]
modHigh = modHigh * xform[0, 0] + xform[0, 3]
else:
modLow = 0
modHigh = 1
return modLow, modHigh
[docs] def getAuxTextureXform(self, 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'``).
"""
return self.auxmgr.textureXform(which)
[docs] def preDraw(self, 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.
"""
self.modulateTexture.bindTexture(gl.GL_TEXTURE0)
self.clipTexture .bindTexture(gl.GL_TEXTURE1)
self.colourTexture .bindTexture(gl.GL_TEXTURE2)
self.cmapTexture .bindTexture(gl.GL_TEXTURE3)
[docs] def postDraw(self, xform=None, bbox=None):
"""Must be called by subclass implementations.
Unbinds all of the textures managed by this ``GLVectorBase``.
"""
self.modulateTexture.unbindTexture()
self.clipTexture .unbindTexture()
self.colourTexture .unbindTexture()
self.cmapTexture .unbindTexture()
def __cmapPropChanged(self, *a):
"""Called when a :class:`.Display` or :class:`.VectorOpts` property
affecting the vector colour map settings changes. Calls
:meth:`refreshColourMapTexture` and :meth:`asyncUpdateShaderState`.
"""
self.refreshColourMapTexture()
self.asyncUpdateShaderState(alwaysNotify=True)
[docs] def registerAuxImage(self, which, image, onReady=None, **kwargs):
"""Registers the given auxillary image with the
``AuxImageTextureManager``.
"""
self.auxmgr.texture(which).deregister(self.name)
self.auxmgr.registerAuxImage(which, image, **kwargs)
self.auxmgr.texture(which).register(self.name, self.__textureChanged)
if onReady is not None:
idle.idleWhen(onReady, self.auxmgr.texturesReady)
def __colourImageChanged(self, *a):
"""Called when the :attr:`.VectorOpts.colourImage` changes. Registers
with the new image, and refreshes textures as needed.
"""
def onReady():
self.compileShaders()
self.refreshColourMapTexture()
self.asyncUpdateShaderState(alwaysNotify=True)
self.registerAuxImage('colour', self.opts.colourImage, onReady)
def __modImageChanged(self, *a):
"""Called when the :attr:`.VectorOpts.modulateImage` changes.
Registers with the new image, and refreshes textures as needed.
"""
onReady = ft.partial(self.asyncUpdateShaderState, alwaysNotify=True)
self.registerAuxImage('modulate', self.opts.modulateImage, onReady)
def __clipImageChanged(self, *a):
"""Called when the :attr:`.VectorOpts.clipImage` changes.
Registers with the new image, and refreshes textures as needed.
"""
onReady = ft.partial(self.asyncUpdateShaderState, alwaysNotify=True)
self.registerAuxImage('clip', self.opts.clipImage, onReady)
def __textureChanged(self, *a):
"""Called when any of the :class:`.ImageTexture` instances containing
clipping, modulation or colour data, are refreshed. Notifies
listeners of this ``GLVectorBase`` (via the :class:`.Notifier` base
class).
"""
self.asyncUpdateShaderState(alwaysNotify=True)
[docs]class GLVector(GLVectorBase):
"""The ``GLVector`` class is a sub-class of :class:`GLVectorBase`, which
contains some additional logic for rendering :class:`.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 :meth:`__init__` is assumed
to be an :class:`.Image` instance which contains vector data. If this is
not the case, the ``vectorImage`` parameter may be used to pass in the
:class:`.Image` that contains the vector data.
This vector image is stored on the GPU as a 3D RGB :class:`.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
:meth:`preDraw` method.
"""
[docs] def __init__(self, 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 :meth:`GLVectorBase.__init__`.
The ``image``, (or ``vectorImage``) argument is assumed to be an
:class:`.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]``.
:arg vectorImage: If ``None``, the ``image`` is assumed to be an
:class:`.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.
:arg prefilter: An optional function which filters the data before
it is stored as a 3D texture. See
:class:`.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.
:arg 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.
"""
def defaultPrefilter(d):
return d
vectorImage = kwargs.pop('vectorImage', image)
prefilter = kwargs.pop('prefilter', defaultPrefilter)
prefilterRange = kwargs.pop('prefilterRange', None)
# Must be an image of shape (X, Y, Z, 3),
# or of type RGB24. If the latter, the
# test below will accept any numpy
# structured array with three values per
# voxel, but we assume elsewhere that
# those values are all of type np.uint8
# (and thus correspond to the
# NIFTI_TYPE_RGB24 type)
shape = vectorImage.shape
ndims = len(shape)
nvals = vectorImage.nvals
isRGB = (((ndims == 4) and (nvals == 1) and (shape[3] == 3)) or
((ndims == 3) and (nvals == 3)))
if not isRGB:
raise ValueError('Image must be 4 dimensional with 3 volumes '
'representing the XYZ vector angles, or of '
'type RGB24')
self.vectorImage = vectorImage
self.imageTexture = None
self.prefilter = prefilter
self.prefilterRange = prefilterRange
# Using the preinit hook to overcome a slight
# chicken-and-egg problem. We need to create
# the image texture before shaders are created
# (which are done via the init hook, as defined
# in sub-classes, e.g. GLRGBVector). But we
# need access to the display/displayopts objects
# in order to configure the image texture.
# So pre-init ensures that the GLObject refs
# (display/displayOpts) are set up, then the
# image texture is refreshed, then the init hook
# is called.
preinit = kwargs.pop('preinit', None)
def preinitWrapper():
self.refreshImageTexture()
if preinit is not None:
preinit()
GLVectorBase.__init__(self,
image,
*args,
preinit=preinitWrapper,
**kwargs)
[docs] def destroy(self):
"""Overrides :meth:`GLVectorBase.destroy`. Must be called when this
``GLVector`` is no longer needed. Calls :meth:`GLVectorBase.destroy`,
and destroys the vector image texture.
"""
GLVectorBase.destroy(self)
self.imageTexture.deregister(self.name)
glresources.delete(self.imageTexture.name)
self.imageTexture = None
[docs] def texturesReady(self):
"""Overrides :meth:`GLVectorBase.texturesReady`. Returns ``True`` if
all of the textures managed by this ``GLVector`` are ready to be used,
``False`` otherwise.
"""
return (self.imageTexture is not None and
self.imageTexture.ready() and
GLVectorBase.texturesReady(self))
[docs] def refreshImageTexture(self, interp=gl.GL_NEAREST):
"""Called by :meth:`__init__`, and when the :class:`.ImageTexture`
needs to be updated. (Re-)creates the ``ImageTexture``, using the
:mod:`.resources` module so that the texture can be shared by other
users.
:arg interp: Interpolation method (``GL_NEAREST`` or ``GL_LINEAR``).
Used by sub-class implementations (see
:class:`.GLRGBVector`).
"""
prefilter = self.prefilter
prefilterRange = self.prefilterRange
vecImage = self.vectorImage
texName = '{}_{}'.format(type(self).__name__, id(vecImage))
if self.imageTexture is not None:
self.imageTexture.deregister(self.name)
glresources.delete(self.imageTexture.name)
self.imageTexture = glresources.get(
texName,
textures.ImageTexture,
texName,
vecImage,
nvals=3,
interp=interp,
normaliseRange=vecImage.dataRange,
prefilter=prefilter,
prefilterRange=prefilterRange,
notify=False)
self.imageTexture.register(self.name, self.__textureChanged)
[docs] def preDraw(self, xform=None, bbox=None):
"""Overrides :meth:`GLVectorBase`. Binds the vector image texture.
"""
GLVectorBase.preDraw(self, xform, bbox)
self.imageTexture.bindTexture(gl.GL_TEXTURE4)
[docs] def postDraw(self, xform=None, bbox=None):
"""Overrides :meth:`GLVectorBase`. Unbinds the vector image texture.
"""
GLVectorBase.postDraw(self, xform, bbox)
self.imageTexture.unbindTexture()
def __textureChanged(self, *a):
"""Called when the :class:`.ImageTexture` instance containing the vector
data is are refreshed. Notifies listeners of this ``GLVector`` (via the
:class:`.Notifier` base class).
"""
self.asyncUpdateShaderState(alwaysNotify=True)