fsleyes.gl.glsh

This module provides the GLSH class, a GLObject for rendering Image overlays which contain spherical harmonic (SH) coefficients which represent fibre orientation distributions (FODs). The GLSH class uses functions defined in the gl21.glsh_funcs module.

GLSH instances can only be rendered in OpenGL 2.1 and above.

class fsleyes.gl.glsh.GLSH(*args, **kwargs)

Bases: GLVectorBase

The GLSH class is a GLVectorBase for rendering Image overlays which contain spherical harmonic (SH) coefficients that represent fibre orientation distributions (FOD).

This class manages listeners on Display and SHOpts instances, and also manages two textures (described below). The rendering logic is implemented in the gl21.glsh_funcs module.

Each voxel in a FOD image contains coefficients which describe a linear combination of spherical harmonic functions. The SHOpts.getSHParameters() method returns a numpy array which may be used to transform these coefficients into a set of radii that can be applied to the vertices of a sphere to visualise the spherical function. Pre-calculated vertices of tessellated spheres are used, and are retrieved via the SHOpts.getVertices() and SHOpts.getIndices() methods.

These radii are calculated on every call to draw() (via the updateRadTexture() method), and stored in a Texture3D instance, which is available as an attribute called radTexture. This texture is only 3D out of necessity - it is ultimately interpreted by the glsh vertex shader as a 1D sequence of values, ordered by voxel then vertex.

The radius texture managed by a GLSH instance is bound to GL texture unit GL_TEXTURE4.

The following attributes are available on a GLSH instance (and are assumed to be present by the functions in the glsh_funcs module`):

radTexture	Texture3D containing radius values for each vertex to be displayed in the current draw call.
vertices	numpy array of shape (N, 3) which comprise a tessellated sphere. The vertex shader will apply the radii to the vertices contained in this array, to form the FODs at every voxel.
indices	Indices into vertices defining the faces of the sphere.
nVertices	Total number of rendered vertices (equal to len(indices)).
vertIdxs	Indices for each vertex (equal to np.arange(vertices.shape[0])).

__init__(image, overlayList, displayCtx, threedee)

Create a GLSH object.

Creates a Texture3D instance to store vertex radii, adds property listeners to the Display and SHOpts instances, and sets up shaders.

Parameters:

• image – The Image instance

• overlayList – The OverlayList

• displayCtx – The DisplayContext managing the scene.

• threedee – Set up for 2D or 3D rendering.

destroy()

Removes property listeners, destroys textures, and calls glsh_funcs.destroy().

ready()

Overrides GLVectorBase.ready. Returns True when this GLSH is ready to be drawn.

getDataResolution(xax, yax, width, height)

Overrides GLVector.getDataResolution(). Returns a pixel resolution suitable for off-screen rendering of this GLSH.

addListeners()

Overrides GLVectorBase.addListeners().

Called by __init__(). Adds listeners to properties of the Display and SHOpts instanecs associated with the image.

removeListeners()

Overrides GLVectorBase.removeListeners(). Called by destroy(). Removes listeners added by addListeners().

compileShaders(*a)

Overrides GLVectorBase.compileShaders(). Calls glsh_funcs.compileShaders().

updateShaderState(*a, **kwa)

Overrides GLVectorBase.updateShaderState(). Calls glsh_funcs.updateShaderState().

__shStateChanged(*a)

Called when the SHOpts.shResolution property changes. Re-loads the SH parameters from disk, and attaches them as an attribute called __shParams.

__coefVolumeMask()

Figures out which volumes from the image need to be included in the SH radius calculation. If an image has been generated with a particular maximum SH function order, but is being displayed at a reduced order, a sub-set of the volumes need to be used in the calculation.

:returns A slice object which can be used to select a subset of

volumes from the SH image.

For a symmetric SH image (which only contains SH functions of even order), each volume corresponds to

Volume	Maximum order	Order
0	0	0
1	2	-2
2	2	-1
3	2	0
4	2	1
5	2	2
6	4	-4
7	4	-3
8	4	-2
9	4	-1
10	4	0
11	4	1
12	4	2
13	4	3
14	4	4
15	6	-6
…	…	…

Asymmetric images (containing SH functions of both even and odd order) follow the same pattern:

Volume	Maximum order	Order
0	0	0
1	1	-1
2	1	0
3	1	1
4	2	-2
5	2	-1
6	2	0
7	2	1
8	2	2
9	3	-3
10	3	-2
11	3	-1
12	3	0
13	3	1
14	3	2
15	3	3
16	4	-4
…	…	…

updateRadTexture(voxels)

Called by glsh_funcs.draw(). Updates the radius texture to contain radii for the given set of voxels (assumed to be an (N, 3) numpy array).

If SHOpts.radiusThreshold is greater than 0, any voxels for which all radii are less than the threshold are removed from the voxels array.

If SHOpts.normalise is True, the radii within each voxel are normalised to lie between 0 and 0.5, so that they fit within the voxel.

This function returns a tuple containing:

• The voxels array. If SHOpts.radiusThreshold == 0, this will be the same as the input. Otherwise, this will be a new array with sub-threshold voxels removed. If no voxels are to be rendered (all out of bounds, or below the radius threshold), this will be an empty list.

• The adjusted shape of the radius texture.

texturesReady()

Overrides GLVectorBase.texturesReady(). Returns True if all textures used by this GLSH instance are ready to be used, False otherwise.

preDraw()

Overrides GLVectorBase.preDraw(). Binds textures, and calls glsh_funcs.preDraw().

draw2D(*args, **kwargs)

Overrides GLObject.draw2D(). Calls glsh_funcs.draw2D().

draw3D(*args, **kwargs)

Does nothing.

drawAll(*args, **kwargs)

Overrides GLObject.draw2D(). Calls glsh_funcs.drawAll().

__annotations__ = {}

__module__ = 'fsleyes.gl.glsh'

postDraw()

Overrides GLVectorBase.postDraw(). Unbinds textures, and calls glsh_funcs.postDraw().