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)[source]

Bases: object

Base mixin class used by the Texture class.

This class provides logic for texture lifecycle management (creation/destruction) and usage.

name

Returns the name of this texture.

handle

Returns the GL texture handle for this texture.

target

Returns the type of this texture - GL_TEXTURE_1D, GL_TEXTURE_2D or GL_TEXTURE_3D.

ndim

Return the number of dimensions of this texture - 1, 2, or 3.

nvals

Return the number of values stored at each point in this texture.

isBound

Returns True if this texture is currently bound, False otherwise.

bound

Context manager which can be used to bind and unbind this texture, instead of manually calling bindTexture() and unbindTexture()

bindTexture

Activates and binds this texture.

unbindTexture

Unbinds this texture.

The bound() method (which uses bindTexture() and unbindTexture()) method allows you to bind a texture object to a GL texture unit. For example, let’s say we have a texture object called tex, 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)[source]

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__()[source]

Prints a log message.

destroy()[source]

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 target

Returns the type of this texture - GL_TEXTURE_1D, GL_TEXTURE_2D or GL_TEXTURE_3D.

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()[source]

Returns True if this texture is currently bound, False otherwise.

Note

This method assumes that the bindTexture() and unbindTexture() methods are called in pairs.

bound(textureUnit=None)[source]

Context manager which can be used to bind and unbind this texture, instead of manually calling bindTexture() and unbindTexture()

Parameters

textureUnit – The texture unit to bind this texture to, e.g. GL_TEXTURE0.

bindTexture(textureUnit=None)[source]

Activates and binds this texture.

Parameters

textureUnit – The texture unit to bind this texture to, e.g. GL_TEXTURE0.

unbindTexture()[source]

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 target\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>, 'target': <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)[source]

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:

interp

Return the current texture interpolation setting - either GL_NEAREST or GL_LINEAR.

prefilter

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

prefilterRange

Return the current prefilter range function - if the prefilter function changes the data range, this function must be provided.

normalise

Return the current normalisation state.

normaliseRange

Return the current normalise range.

border

Return the texture border colour.

scales

Return the scaling factors for each axis of the texture data.

resolution

Return the current texture data resolution - this value is passed to the routines.subsample() function, in the prepareData() function.

Additional settings can be added via the settings argument to __init__(). All settings can be changed via the update() method.

__init__(settings=None)[source]

Create a TextureSettingsMixin.

Parameters

settings – Sequence of additional settings to make available.

property interp

Return the current texture interpolation setting - either GL_NEAREST or GL_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 - see prefilterRange().

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 the prefilter 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 the normaliseRange().

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 the prepareData() function.

update(**kwargs)[source]

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, textureFormat=None, internalFormat=None, **kwargs)[source]

Bases: __main__.docbuilder.run.<locals>.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 the TextureSettingsMixin 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 the set() 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 the refresh() 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):

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.

shape

Return a tuple containing the texture data shape.

dtype

Return the numpy data type of the texture data.

textureType

Return the texture data type, e.g.

baseFormat

Return the base texture format, e.g.

internalFormat

Return the sized/internal texture format, e.g.

data

Returns the data that has been passed to the set() method.

preparedData

Returns the prepared data, i.e. the data as it has been copied to the GPU.

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 the idle module (unless the threaded parameter to __init__() is set to False). The ready() method returns True or False to indicate whether the Texture is ready to be used.

Furthermore, the Texture class derives from Notifier, so listeners can register to be notified when an Texture 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() or set()).

Texture sub-classes (e.g. Texture2D, Texture3D, ColourMapTexture) must override the doRefresh() 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, textureFormat=None, internalFormat=None, **kwargs)[source]

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 to refresh()). If False, the texture data is prepared on the calling thread, and the refresh() call will block until it has been prepared.

  • settings – Additional settings to make available through the TextureSettingsMixin.

  • textureFormat – Texture format to use - if not specified, this is automatically determined. If specified, an internalFormat must also be specified.

  • internalFormat – Internal texture format to use - if not specified, this is automatically determined.

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 said name through to the __init__() method.

Note

In normal cases, the textureFormat and internalFormat do not need to be specified - they will be automatically determined using the data.getTextureType() function. However, there can be instances where a specific texture type needs to be used. In these instances, it is up to the calling code to ensure that the texture data can be coerced into the correct GL data type.

destroy()[source]

Must be called when this Texture is no longer needed.

ready()[source]

Returns True if this Texture 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.

texCoordXform(origShape)[source]

Returns a transformation matrix which can be used to adjust a set of 3D texture coordinates so they can index the underlying texture, which may be 2D.

This implementation returns an identity matrix, but it is overridden by the .Texture2D sub-class, which is sometimes used to store 3D image data.

Parameters

origShape – Original data shape.

invTexCoordXform(origShape)[source]

Returns the inverse of texCoordXform().

property shape

Return a tuple containing the texture data shape.

property dtype

Return the numpy data type of the texture data.

property textureType

Return the texture data type, e.g. gl.GL_UNSIGNED_BYTE.

__module__ = 'fsleyes.gl.textures.texture'
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 data

Returns the data that has been passed to the set() method.

property preparedData

Returns the prepared data, i.e. the data as it has been copied to the GPU.

shapeData(data, oldShape=None)[source]

Shape the data so that it is ready for use as texture data.

This implementation returns the data unchanged, but it is overridden by the Texture2D class, which is sometimes used to store 3D image data.

Parameters
  • datanumpy array containing the data to be shaped

  • oldShape – Original data shape, if this is a sub-array. If not provided, taken from data.

set(**kwargs)[source]

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), 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 Texture is being/needs to be refreshed, False otherwise.

refresh(refreshData=True, notify=True, callback=None)[source]

(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.

Note

The texture data may be generated on a separate thread, using the idle.run() function. This is controlled by the threaded parameter, passed to __init__().

patchData(data, offset)[source]

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 allows small parts of the image texture to be quickly updated.

doRefresh()[source]

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 the shape(), to configure the texture. Sub-classes can assume that at least one of these will not be None.

If preparedData is not None, the shape should be ignored, and inferred from preparedData.

doPatch(data, offset)[source]

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.

__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)

__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 this Texture 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.