fsleyes.gl.textures.texture
¶
This module provides the Texture
class, which is the base classes
for all other FSLeyes texture types. See also the Texture2D
and
Texture3D
classes.
-
class
fsleyes.gl.textures.texture.
TextureBase
(name, ndims, nvals)¶ Bases:
object
Base mixin class used by the
Texture
class.This class provides logic for texture lifecycle management (creation/destruction) and usage.
Returns the name of this texture.
Returns the GL texture handle for this texture.
Return the number of dimensions of this texture - 1, 2, or 3.
Return the number of values stored at each point in this texture.
Returns
True
if this texture is currently bound,False
otherwise.Context manager which can be used to bind and unbind this texture, instead of manually calling
bindTexture()
andunbindTexture()
Activates and binds this texture.
Unbinds this texture.
The
bound()
method (which usesbindTexture()
andunbindTexture()
) method allows you to bind a texture object to a GL texture unit. For example, let’s say we have a texture object calledtex
, and we want to configure and use it:import OpenGL.GL as gl # When we want to use the texture in a # scene render, we need to bind it to # a texture unit. with tex.bound(gl.GL_TEXTURE0): # use linear interpolation tex.interp = gl.GL_LINEAR # ... # Do the render # ...
-
__init__
(name, ndims, nvals)¶ Create a
TextureBase
.- Parameters
name – The name of this texture - should be unique.
ndims – Number of dimensions - must be 1, 2 or 3.
nvals – Number of values stored in each texture element.
-
__del__
()¶ Prints a log message.
-
destroy
()¶ Must be called when this
TextureBase
is no longer needed. Deletes the texture handle.
-
property
name
¶ Returns the name of this texture. This is not the GL texture name, rather it is the unique name passed into
__init__()
.
-
property
handle
¶ Returns the GL texture handle for this texture.
-
property
ndim
¶ Return the number of dimensions of this texture - 1, 2, or 3.
-
property
nvals
¶ Return the number of values stored at each point in this texture.
-
isBound
()¶ Returns
True
if this texture is currently bound,False
otherwise.Note
This method assumes that the
bindTexture()
andunbindTexture()
methods are called in pairs.
-
bound
(textureUnit=None)¶ Context manager which can be used to bind and unbind this texture, instead of manually calling
bindTexture()
andunbindTexture()
- Parameters
textureUnit – The texture unit to bind this texture to, e.g.
GL_TEXTURE0
.
-
bindTexture
(textureUnit=None)¶ Activates and binds this texture.
- Parameters
textureUnit – The texture unit to bind this texture to, e.g.
GL_TEXTURE0
.
-
unbindTexture
()¶ Unbinds this texture.
-
__dict__
= mappingproxy({'__module__': 'fsleyes.gl.textures.texture', '__doc__': "Base mixin class used by the :class:`Texture` class.\n\n This class provides logic for texture lifecycle management\n (creation/destruction) and usage.\n\n\n .. autosummary::\n :nosignatures:\n\n name\n handle\n ndim\n nvals\n isBound\n bound\n bindTexture\n unbindTexture\n\n\n The :meth:`bound` method (which uses :meth:`bindTexture` and\n :meth:`unbindTexture`) method allows you to bind a texture object to a GL\n texture unit. For example, let's say we have a texture object called\n ``tex``, and we want to configure and use it::\n\n import OpenGL.GL as gl\n\n # When we want to use the texture in a\n # scene render, we need to bind it to\n # a texture unit.\n with tex.bound(gl.GL_TEXTURE0):\n\n # use linear interpolation\n tex.interp = gl.GL_LINEAR\n\n # ...\n # Do the render\n # ...\n ", '__init__': <function TextureBase.__init__>, '__del__': <function TextureBase.__del__>, 'destroy': <function TextureBase.destroy>, 'name': <property object>, 'handle': <property object>, 'ndim': <property object>, 'nvals': <property object>, 'isBound': <function TextureBase.isBound>, 'bound': <function TextureBase.bound>, 'bindTexture': <function TextureBase.bindTexture>, 'unbindTexture': <function TextureBase.unbindTexture>, '__dict__': <attribute '__dict__' of 'TextureBase' objects>, '__weakref__': <attribute '__weakref__' of 'TextureBase' objects>})¶
-
__module__
= 'fsleyes.gl.textures.texture'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
-
class
fsleyes.gl.textures.texture.
TextureSettingsMixin
(settings=None)¶ Bases:
object
Mixin class used by the
Texture
class.This class provides methods to get/set various settings which can be used to manipulate the texture. All of the logic which uses these settings is in the
Texture
class.The following settings can be changed:
Return the current texture interpolation setting - either
GL_NEAREST
orGL_LINEAR
.Return the current prefilter function - texture data is passed through this function before being uploaded to the GPU.
Return the current prefilter range function - if the
prefilter
function changes the data range, this function must be provided.Return the current normalisation state.
Return the current normalise range.
Return the texture border colour.
Return the scaling factors for each axis of the texture data.
Return the current texture data resolution - this value is passed to the
routines.subsample()
function, in theprepareData()
function.Additional settings can be added via the
settings
argument to__init__()
. All settings can be changed via theupdate()
method.-
__init__
(settings=None)¶ Create a
TextureSettingsMixin
.- Parameters
settings – Sequence of additional settings to make available.
-
property
interp
¶ Return the current texture interpolation setting - either
GL_NEAREST
orGL_LINEAR
.
-
property
prefilter
¶ Return the current 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 - seeprefilterRange()
.
-
property
prefilterRange
¶ Return the current 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.
-
property
normalise
¶ Return the current normalisation state.
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 thenormaliseRange()
.Set this 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.
-
property
normaliseRange
¶ Return the current normalise range.
If normalisation is enabled (see
normalise()
), 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.
-
property
border
¶ Return the texture border colour. Set this to a tuple of four values in the range 0 to 1, or
None
for no border (in which case the texture coordinates will be clamped to edges).
-
property
scales
¶ Return the 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
resolution()
) is in terms of something other than data indices (e.g.Image
pixdims).
-
property
resolution
¶ Return the current texture data resolution - this value is passed to the
routines.subsample()
function, in theprepareData()
function.
-
update
(**kwargs)¶ Set any parameters on this
TextureSettingsMixin
. Valid keyword arguments are:interp
See
interp()
.prefilter
See
prefilter()
.prefilterRange
See
prefilterRange()
normalise
See
normalise.()
normaliseRange
See
normaliseRange()
border
See
border()
scales
See
scales()
.resolution
See
resolution()
- Returns
A
dict
of{attr : changed}
mappings, indicating which properties have changed value.
-
__dict__
= mappingproxy({'__module__': 'fsleyes.gl.textures.texture', '__doc__': 'Mixin class used by the :class:`Texture` class.\n\n\n This class provides methods to get/set various settings which can\n be used to manipulate the texture. All of the logic which uses\n these settings is in the ``Texture`` class.\n\n\n The following settings can be changed:\n\n .. autosummary::\n :nosignatures:\n\n interp\n prefilter\n prefilterRange\n normalise\n normaliseRange\n border\n scales\n resolution\n\n Additional settings can be added via the ``settings`` argument to\n :meth:`__init__`. All settings can be changed via the :meth:`update`\n method.\n ', '__init__': <function TextureSettingsMixin.__init__>, 'interp': <property object>, 'prefilter': <property object>, 'prefilterRange': <property object>, 'normalise': <property object>, 'normaliseRange': <property object>, 'border': <property object>, 'scales': <property object>, 'resolution': <property object>, 'update': <function TextureSettingsMixin.update>, '__dict__': <attribute '__dict__' of 'TextureSettingsMixin' objects>, '__weakref__': <attribute '__weakref__' of 'TextureSettingsMixin' objects>})¶
-
__module__
= 'fsleyes.gl.textures.texture'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
-
class
fsleyes.gl.textures.texture.
Texture
(name, ndims, nvals, threaded=False, settings=None, **kwargs)¶ Bases:
__main__.MockClass
,fsleyes.gl.textures.texture.TextureBase
,fsleyes.gl.textures.texture.TextureSettingsMixin
The
Texture
class is the base class for all other texture types in FSLeyes. This class is not intended to be used directly - use one of the sub-classes instead.A texture can be bound and unbound via the methods of the
TextureBase
class. Various texture settings can be changed via the methods of theTextureSettingsMixin
class. In the majority of cases, in order to draw or configure a texture, it needs to be bound (although this depends on the sub-class).In order to use a texture, at the very least you need to provide some data, or specify a type and shape. This can be done either via the
data()
/shape()
/dtype()
methods, or by theset()
method. If you specify a shape and data type, any previously specified data will be lost, and vice versa.Calling
set()
will usually cause the texture to be reconfigured and refreshed, although you can also force a refresh by calling therefresh()
method directly.The following properties can be queried to retrieve information about the tetxure; some will return
None
until you have provided some data (or a shape and type):Return a transformation matrix that can be used to transform values read from the texture back to the original data range.
Return a transformation matrix that can be used to transform values in the original data range to values as read from the texture.
Return a tuple containing the texture data shape.
Return the
numpy
data type of the texture data.Return the texture data type, e.g.
Return the base texture format, e.g.
Return the sized/internal texture format, e.g.
Returns the data that has been passed to the
set()
method.Returns the prepared data, i.e.
When a
Texture
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 may be performed on a separate thread using theidle
module (unless thethreaded
parameter to__init__()
is set toFalse
). Theready()
method returnsTrue
orFalse
to indicate whether theTexture
is ready to be used.Furthermore, the
Texture
class derives fromNotifier
, so listeners can register to be notified when anTexture
is ready to be used.For textures with multiple values per voxel, it is assumed that these values are indexed with the first dimension of the texture data (as passed to
data()
orset()
).Texture
sub-classes (e.g.Texture2D
,Texture3D
,ColourMapTexture
) must override thedoRefresh()
method such that it performs the GL calls required to configure the textureb.See the
resources
module for a method of sharing texture resources.-
__init__
(name, ndims, nvals, threaded=False, settings=None, **kwargs)¶ Create a
Texture
.- Parameters
name – The name of this texture - should be unique.
ndims – Number of dimensions - must be 1, 2 or 3.
nvals – Number of values stored in each texture element.
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.settings – Additional settings to make available through the
TextureSettingsMixin
.
All other arguments are passed through to the initial call to
set()
.Note
All subclasses must accept a
name
as the first parameter to their__init__
method, and must pass saidname
through to the__init__()
method.
-
destroy
()¶ Must be called when this
Texture
is no longer needed.
-
ready
()¶ Returns
True
if thisTexture
is ready to be used,False
otherwise.
-
property
voxValXform
¶ Return a transformation matrix that can be used to transform values read from the texture back to the original data range.
-
property
invVoxValXform
¶ Return a transformation matrix that can be used to transform values in the original data range to values as read from the texture.
-
property
shape
¶ Return a tuple containing the texture data shape.
-
property
dtype
¶ Return the
numpy
data type of the texture data.
-
_Texture__determineTextureType
()¶ Figures out how the texture data should be stored as an OpenGL texture. See the
data.getTextureType()
function.This method sets the following attributes on this
Texture
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
)
-
_Texture__prepareTextureData
()¶ Prepare the texture data.
This method passes the stored data to the
data.prepareData()
function and then stores references to its return valuesa as attributes on thisTexture
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
.
-
__module__
= 'fsleyes.gl.textures.texture'¶
-
property
textureType
¶ Return the texture data type, e.g.
gl.GL_UNSIGNED_BYTE
.
-
property
baseFormat
¶ Return the base texture format, e.g.
gl.GL_ALPHA
.
-
property
internalFormat
¶ Return the sized/internal texture format, e.g.
gl.GL_ALPHA8
.
-
property
preparedData
¶ Returns the prepared data, i.e. the data as it has been copied to the GPU.
-
set
(**kwargs)¶ Set any parameters on this
Texture
. Valid keyword arguments are:interp
See
interp()
.data
See
data()
.shape
See
shape()
.dtype
See
dtype()
.prefilter
See
prefilter()
.prefilterRange
See
prefilterRange()
normalise
See
normalise.()
normaliseRange
See
normaliseRange()
.scales
See
scales()
.resolution
See
resolution()
.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 theTexture
is being/needs to be refreshed,False
otherwise.
-
refresh
(refreshData=True, notify=True, callback=None)¶ (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.
Note
The texture data may be generated on a separate thread, using the
idle.run()
function. This is controlled by thethreaded
parameter, passed to__init__()
.
-
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 allows small parts of the image texture to be quickly updated.
-
doRefresh
()¶ Must be overridden by sub-classes to configure the texture.
This method is not intended to be called externally - call
refresh()
instead.This method should use the
preparedData()
, or theshape()
, to configure the texture. Sub-classes can assume that at least one of these will not beNone
.If
preparedData
is notNone
, theshape
should be ignored, and inferred frompreparedData
.
-
doPatch
(offset)¶ Must be overridden by sub-classes to quickly update part of the texture data.
This method is not intended to be called externally - call
patchData()
instead.
-