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
orGL_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 thisTexture3D
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 theidle
module (unless thethreaded
parameter to__init__()
is set toFalse
). Theready()
method returnsTrue
orFalse
to indicate whether theTexture3D
can be used.Furthermore, the
Texture3D
class derives fromNotifier
, so listeners can register to be notified when anTexture3D
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
or3
. - notify – Passed to the initial call to
refresh()
. - threaded – If
True
, the texture data will be prepared on a separate thread (on calls torefresh()
). IfFalse
, the texture data is prepared on the calling thread, and therefresh()
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 offsl.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 thisTexture3D
is ready to be used,False
otherwise.
-
setInterp
(interp)¶ Sets the texture interpolation - either
GL_NEAREST
orGL_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 - seesetPrefilterRange()
.
-
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 theprefilter
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 viasetNormaliseRange()
.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()
andrefresh()
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), therefresh()
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 ifrefresh
isTrue
, and a setting has changed.notify
Passed through to the refresh()
method.Returns: True
if any settings have changed and theTexture3D
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 theTexture3D
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
oruint16
- 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 theARB_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 fulluint16
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 theARB_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
)- it is of type
-
_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 thisImageTexture
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__()
wasTrue
, 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.
- A
- 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
.
- Resampling to a different resolution (see the
-
_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 theNotifier
base-class, when thisTexture3D
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 ifrefresh
isTrue
, and a setting has changed.
This method sets an attribute
__textureShape
on thisTexture3D
instance, containing the shape of the texture data.Note
The texture data is generated on a separate thread, using the
idle.run()
function.- refreshData – If
-
__module__
= 'fsleyes.gl.textures.texture3d'¶
-