`fsleyes.gl.textures.texture3d`¶

This module provides the Texture3D class, which represents a 3D OpenGL texture.

class fsleyes.gl.textures.texture3d.Texture3D(name, nvals=1, notify=True, threaded=None, **kwargs)¶

Bases: fsleyes.gl.textures.texture.Texture, __main__.MockClass

The Texture3D class contains the logic required to create and manage a 3D texture.

A number of texture settings can be configured through the following methods:

`set`	Set any parameters on this `Texture3D`.
`refresh`	(Re-)configures the OpenGL texture.
`setData`	Sets the texture data - assumed to be a `numpy` array.
`setInterp`	Sets the texture interpolation - either `GL_NEAREST` or `GL_LINEAR`.
`setResolution`	Sets the texture data resolution - this value is passed to the `routines.subsample()` function, in the `__prepareTextureData()` method.
`setScales`	Sets scaling factors for each axis of the texture data.
`setPrefilter`	Sets the prefilter function - texture data is passed through this function before being uploaded to the GPU.
`setPrefilterRange`	Sets the prefilter range function - if the `prefilter` function changes the data range, this function must be provided.
`setNormalise`	Enable/disable normalisation.

`ready`	Returns `True` if this `Texture3D` is ready to be used, `False` otherwise.
`textureShape`	Return a tuple containing the texture data shape.
`voxValXform`	Return a transformation matrix that can be used to transform values read from the texture back to the original data range.
`invVoxValXform`	Return a transformation matrix that can be used to transform values in the original data range to values as read from the texture.

When a Texture3D is created, and when its settings are changed, it may need to prepare the data to be passed to OpenGL - for large textures, this can be a time consuming process, so this is performed on a separate thread using the idle module (unless the threaded parameter to __init__() is set to False). The ready() method returns True or False to indicate whether the Texture3D can be used.

Furthermore, the Texture3D class derives from Notifier, so listeners can register to be notified when an Texture3D is ready to be used.

__init__(name, nvals=1, notify=True, threaded=None, **kwargs)¶

Create a Texture3D.

Parameters:

name – A unique name for the texture.
nvals – Number of values per voxel. Currently must be either 1 or 3.
notify – Passed to the initial call to refresh().
threaded – If True, the texture data will be prepared on a separate thread (on calls to refresh()). If False, the texture data is prepared on the calling thread, and the refresh() call will block until it has been prepared.

All other keyword arguments are passed through to the set() method, and thus used as initial texture settings.

Note

The default value of the threaded parameter is set to the value of fsl.utils.platform.Platform.haveGui.

destroy()¶: Must be called when this Texture3D is no longer needed. Deletes the texture handle.

classmethod canUseFloatTextures(*args, **kwargs)¶

MagicMock is a subclass of Mock with default implementations of most of the magic methods. You can use MagicMock without having to configure the magic methods yourself.

If you use the spec or spec_set arguments then only magic methods that exist in the spec will be created.

Attributes and the return value of a MagicMock will also be MagicMocks.

classmethod oneChannelFormat(*args, **kwargs)¶

MagicMock is a subclass of Mock with default implementations of most of the magic methods. You can use MagicMock without having to configure the magic methods yourself.

If you use the spec or spec_set arguments then only magic methods that exist in the spec will be created.

Attributes and the return value of a MagicMock will also be MagicMocks.

classmethod getTextureType(*args, **kwargs)¶

MagicMock is a subclass of Mock with default implementations of most of the magic methods. You can use MagicMock without having to configure the magic methods yourself.

If you use the spec or spec_set arguments then only magic methods that exist in the spec will be created.

Attributes and the return value of a MagicMock will also be MagicMocks.

ready()¶: Returns True if this Texture3D is ready to be used, False otherwise.

setInterp(interp)¶: Sets the texture interpolation - either GL_NEAREST or GL_LINEAR.

setData(data)¶: Sets the texture data - assumed to be a numpy array.

setPrefilter(prefilter)¶

Sets the prefilter function - texture data is passed through this function before being uploaded to the GPU.

If this function changes the range of the data, you must also provide a prefilterRange function - see setPrefilterRange().

setPrefilterRange(prefilterRange)¶: Sets the prefilter range function - if the prefilter function changes the data range, this function must be provided. It is passed two parameters - the known data minimum and maximum, and must adjust these values so that they reflect the adjusted range of the data that was passed to the prefilter function.

setResolution(resolution)¶: Sets the texture data resolution - this value is passed to the routines.subsample() function, in the __prepareTextureData() method.

setScales(scales)¶: Sets scaling factors for each axis of the texture data. These values are solely used to calculate the sub-sampling rate if the resolution (as set by setResolution()) is in terms of something other than data indices (e.g. Image pixdims).

setNormalise(normalise)¶

Enable/disable normalisation.

If normalise=True, the data is normalised to lie in the range [0, 1] (or normalised to the full range, if being stored as integers) before being stored. The data is normalised according to the minimum/maximum of the data, or to a normalise range set via setNormaliseRange().

Set to False to disable normalisation.

Note

If the data is not of a type that can be stored natively as a texture, the data is automatically normalised, regardless of the value specified here.

setNormaliseRange(normaliseRange)¶

Enable/disable normalisation.

If normalisation is enabled (see setNormalise()), or necessary, the data is normalised according to either its minimum/maximum, or to the range specified via this method.

This parameter must be a sequence of two values, containing the (min, max) normalisation range. The data is then normalised to lie in the range [0, 1] (or normalised to the full range, if being stored as integers) before being stored.

If None, the data minimum/maximum are calculated and used.

voxValXform¶: Return a transformation matrix that can be used to transform values read from the texture back to the original data range.

invVoxValXform¶: Return a transformation matrix that can be used to transform values in the original data range to values as read from the texture.

textureShape¶: Return a tuple containing the texture data shape.

patchData(data, offset)¶

This is a shortcut method which can be used to replace part of the image texture data without having to regenerate the entire texture.

The set() and refresh() methods are quite heavyweight, and are written in such a way that partial texture updates are not possible. This method was added as a hacky workaround to allow small parts of the image texture to be quickly updated.

Note

Hopefully, at some stage, I will refactor the Texture3D class to be more flexible. Therefore, this method might disappear in the future.

set(**kwargs)¶

Set any parameters on this Texture3D. Valid keyword arguments are:

`interp`	See `setInterp()`.
`data`	See `setData()`.
`prefilter`	See `setPrefilter()`.
`prefilterRange`	See `setPrefilterRange()`
`resolution`	See `setResolution()`.
`scales`	See `setScales()`.
`normalise`	See `setNormalise.()`
`normaliseRange`	See `setNormaliseRange()`.
`refresh`	If `True` (the default), the `refresh()` function is called (but only if a setting has changed).
`callback`	Optional function which will be called (via `idle.idle()`) when the texture has been refreshed. Only called if `refresh` is `True`, and a setting has changed.
`notify`	Passed through to the `refresh()` method.

Returns:	`True` if any settings have changed and the `Texture3D` is to be refreshed, `False` otherwise.

refresh(*args, **kwargs)¶: (Re-)configures the OpenGL texture.

Note

This method is a wrapper around the __refresh() method, which does the real work, and which is not intended to be called from outside the Texture3D class.

_Texture3D__determineTextureType()¶

Figures out how the texture data should be stored as an OpenGL 3D texture. This method just figures out the data types which should be used to store the data as a texture. Any necessary data conversion/ transformation is performed by the __prepareTextureData() method.

The data can be stored as a GL texture as-is if:

it is of type uint8 or uint16

it is of type float32, and this GL environment has support for floating point textures. Support for floating point textures is determined by testing for the availability of the ARB_texture_float extension.

In all other cases, the data needs to be converted to a supported data type, and potentially normalised, before it can be used as texture data. If floating point textures are available, the data is converted to float32. Otherwise, the data is converted to uint16, and normalised to take the full uint16 data range (0-65535), and a transformation matrix is saved, allowing transformation of this normalised data back to its original data range.

Note

OpenGL does different things to 3D texture data depending on its type: unsigned integer types are normalised from [0, INT_MAX] to [0, 1].

Floating point texture data types are, by default, clamped (not normalised), to the range [0, 1]! We can overcome by this by using a true floating point texture, which is accomplished by using one of the data types provided by the ARB_texture_float extension. If this extension is not available, we have no choice but to normalise the data.

This method sets the following attributes on this Texture3D instance:

`__texFmt`	The texture format (e.g. `GL_RGB`, `GL_LUMINANCE`, etc).
`__texIntFmt`	The internal texture format used by OpenGL for storage (e.g. `GL_RGB16`, `GL_LUMINANCE8`, etc).
`__texDtype`	The raw type of the texture data (e.g. `GL_UNSIGNED_SHORT`)

_Texture3D__prepareTextureData()¶

This method is a wrapper around the __realPrepareTextureData() method.

This method passes the stored image data to realPrepareTextureData, and then stores references to its return valuesa as attributes on this ImageTexture instance:

`__preparedata`	A `numpy` array containing the image data, ready to be copied to the GPU.
`__voxValXform`	An affine transformation matrix which encodes an offset and a scale, which may be used to transform the texture data from the range `[0.0, 1.0]` to its raw data range.
`__invVoxValXform`	Inverse of `voxValXform`.

_Texture3D__realPrepareTextureData(data)¶

This method prepares and returns the given data, ready to be used as GL texture data.

This process potentially involves:

Resampling to a different resolution (see the routines.subsample() function).

Pre-filtering (see the prefilter parameter to __init__()).

Normalising (if the normalise parameter to __init__() was True, or if the data type cannot be used as-is).

Casting to a different data type (if the data type cannot be used as-is).

Returns:	A tuple containing: A `numpy` array containing the image data, ready to be copied to the GPU. An affine transformation matrix which encodes an offset and a scale, which may be used to transform the texture data from the range `[0.0, 1.0]` to its raw data range. Inverse of `voxValXform`.

_Texture3D__refresh(*args, **kwargs)¶

(Re-)configures the OpenGL texture.

Parameters:

refreshData – If True (the default), the texture data is refreshed.
notify – If True (the default), a notification is triggered via the Notifier base-class, when this Texture3D has been refreshed, and is ready to use. Otherwise, the notification is suppressed.
callback – Optional function which will be called (via idle.idle()) when the texture has been refreshed. Only called if refresh is True, and a setting has changed.

This method sets an attribute __textureShape on this Texture3D instance, containing the shape of the texture data.

Note

The texture data is generated on a separate thread, using the idle.run() function.

__module__ = 'fsleyes.gl.textures.texture3d'¶

fsleyes.gl.textures.texture3d¶

`fsleyes.gl.textures.texture3d`¶