fsleyes.gl.slicecanvas
¶
This module provides the SliceCanvas
class, which contains the
functionality to display a 2D slice from a collection of 3D overlays.
-
class
fsleyes.gl.slicecanvas.
SliceCanvas
(overlayList, displayCtx, zax=0, opts=None)[source]¶ Bases:
object
The
SliceCanvas
represents a canvas which may be used to display a single 2D slice from a collection of 3D overlays. See also theLightBoxCanvas
, a sub-class ofSliceCanvas
.Note
The
SliceCanvas
class is not intended to be instantiated directly - use one of these subclasses, depending on your use-case:OSMesaSliceCanvas
for static off-screen rendering of a scene using OSMesa.WXGLSliceCanvas
for interactive rendering on awx.glcanvas.GLCanvas
canvas.
The
SliceCanvas
creates aSliceCanvasOpts
instance to manage its settings. The scene scene displayed on aSliceCanvas
instance can be manipulated via the properties of itsSliceCanvasOpts
instnace, which is accessed via theopts
attribute.GL objects
The
SliceCanvas
drawsGLObject
instances. When created, aSliceCanvas
creates aGLObject
instance for every overlay in theOverlayList
. When an overlay is added or removed, it creates/destroysGLObject
instances accordingly. Furthermore, whenever theDisplay.overlayType
for an existing overlay changes, theSliceCanvas
destroys the oldGLObject
associated with the overlay, and creates a new one.The
SliceCanvas
also uses anAnnotations
instance, for drawing simple annotations on top of the overlays. ThisAnnotations
instance can be accessed with thegetAnnotations()
method.Performance optimisations
The
SliceCanvasOpts.renderMode
property controls the way in which theSliceCanvas
rendersGLObject
instances. It has three settings:onscreen
GLObject
instances are rendered directly to the canvas.offscreen
GLObject
instances are rendered off-screen to a fixed size 2D texture (aRenderTexture
). This texture is then rendered to the canvas. OneRenderTexture
is used for every overlay in theOverlayList
.prerender
A stack of 2D slices for every
GLObject
instance is pre-generated off-screen, and cached, using aRenderTextureStack
. When theSliceCanvas
needs to display a particular Z location, it retrieves the appropriate slice from the stack, and renders it to the canvas. OneRenderTextureStack
is used for every overlay in theOverlayList
.Attributes and methods
The following attributes are available on a
SliceCanvas
:name
A unique name for this
SliceCanvas
opts
Reference to the
SliceCanvasOpts
.overlayList
Reference to the
OverlayList
.displayCtx
Reference to the
DisplayContext
.The following convenience methods are available on a
SliceCanvas
:Given pixel x/y coordinates on this canvas, translates them into xyz display coordinates.
Pans the canvas display by the given x/y offsets (specified in display coordinates).
Pans the display so the given x/y position is in the centre.
Pans the display so that the given x/y position (in display coordinates) is visible.
Zooms the canvas to the given rectangle, specified in horizontal/vertical display coordinates.
Resets the
zoom
to 100%, and sets the canvas display bounds to the overaly bounding box (from theDisplayContext.bounds
)Returns an
Annotations
instance, which can be used to annotate the canvas.Return the current viewport, as two tuples containing the
(xlo, ylo, zlo)
and(xhi, yhi, zhi)
bounds.-
__init__
(overlayList, displayCtx, zax=0, opts=None)[source]¶ Create a
SliceCanvas
.- Parameters
overlayList – An
OverlayList
object containing a collection of overlays to be displayed.displayCtx – A
DisplayContext
object which describes how the overlays should be displayed.zax – Display coordinate system axis perpendicular to the plane to be displayed (the depth axis), default 0.
-
destroy
()[source]¶ This method must be called when this
SliceCanvas
is no longer being used.It removes listeners from all
OverlayList
,DisplayContext
, andDisplay
instances, and destroys OpenGL representations of all overlays.
-
canvasToWorld
(xpos, ypos, invertX=None, invertY=None)[source]¶ Given pixel x/y coordinates on this canvas, translates them into xyz display coordinates.
-
panDisplayBy
(xoff, yoff)[source]¶ Pans the canvas display by the given x/y offsets (specified in display coordinates).
-
getDisplayCentre
()[source]¶ Returns the horizontal/vertical position, in display coordinates, of the current centre of the display bounds.
-
panDisplayToShow
(xpos, ypos)[source]¶ Pans the display so that the given x/y position (in display coordinates) is visible.
-
zoomTo
(xlo, xhi, ylo, yhi)[source]¶ Zooms the canvas to the given rectangle, specified in horizontal/vertical display coordinates.
-
resetDisplay
()[source]¶ Resets the
zoom
to 100%, and sets the canvas display bounds to the overaly bounding box (from theDisplayContext.bounds
)
-
getAnnotations
()[source]¶ Returns an
Annotations
instance, which can be used to annotate the canvas.
-
getGLObject
(overlay)[source]¶ Returns the
GLObject
associated with the givenoverlay
, orNone
if there isn’t one.
-
getViewport
()[source]¶ Return the current viewport, as two tuples containing the
(xlo, ylo, zlo)
and(xhi, yhi, zhi)
bounds.This method will return
None
if_draw()
has not yet been called.
-
property
viewMatrix
¶ Returns the current model view matrix.
-
property
projectionMatrix
¶ Returns the current projection matrix.
-
_initGL
()[source]¶ Call the
_overlayListChanged()
method - it will generate any necessary GL data for each of the overlays.
-
_updateRenderTextures
()[source]¶ Called when the
renderMode
changes, when the overlay list changes, or when the GLObject representation of an overlay changes.If the
renderMode
property isonscreen
, this method does nothing.Otherwise, creates/destroys
RenderTexture
orRenderTextureStack
instances for newly added/removed overlays.
-
_getPreRenderTexture
(globj, overlay)[source]¶ Creates/retrieves a
RenderTextureStack
for the givenGLObject
. A tuple containing theRenderTextureStack
, and its name, as passed to theresources
module, is returned.- Parameters
globj – The
GLObject
instance.overlay – The overlay object.
-
_highDpiChange
(*a)[source]¶ Called when the
SliceCanvasOpts.highDpi
property changes. Calls theGLCanvasTarget.EnableHighDPI()
method.
-
_syncOverlayDisplayChanged
(*a)[source]¶ Called when the
DisplayContext.syncOverlayDisplay
property changes. If the currentrenderMode
isprerender
, theRenderTextureStack
instances for each overlay are re-created.This is done because, if all display properties for an overlay are synchronised, then a single
RenderTextureStack
can be shared across multiple displays. However, if any display properties are not synchronised, then a separateRenderTextureStack
is needed for theDisplayContext
used by thisSliceCanvas
.
-
_zAxisChanged
(*a)[source]¶ Called when the
zax
property is changed. Notifies theAnnotations
instance, and callsresetDisplay()
.
-
__overlayTypeChanged
(value, valid, display, name)¶ Called when the
Display.overlayType
setting for any overlay changes. Makes sure that an appropriateGLObject
has been created for the overlay (see the__genGLObject()
method).
-
__regenGLObject
(overlay, updateRenderTextures=True, refresh=True)¶ Destroys any existing
GLObject
associated with the givenoverlay
, and creates a new one (via the__genGLObject()
method).If
updateRenderTextures
isTrue
(the default), and theSliceCanvasOpts.renderMode
isoffscreen
orprerender
, any render texture associated with the overlay is destroyed.
-
__genGLObject
(overlay, updateRenderTextures=True, refresh=True)¶ Creates a
GLObject
instance for the givenoverlay
. Does nothing if aGLObject
already exists for the given overlay.If
updateRenderTextures
isTrue
(the default), and theSliceCanvasOpts.renderMode
isoffscreen
orprerender
, any textures for the overlay are updated.If
refresh
isTrue
(the default), theRefresh()
method is called after theGLObject
has been created.Note
If running in
wx
(i.e. via aWXGLSliceCanvas
), theGLObject
instnace will be created on thewx.EVT_IDLE
lopp (via theidle
module).
-
_overlayListChanged
(*args, **kwargs)[source]¶ This method is called every time an overlay is added or removed to/from the overlay list.
For newly added overlays, calls the
__genGLObject()
method, which initialises the OpenGL data necessary to render the overlay.
-
_getGLObjects
()[source]¶ Called by
_draw()
. Builds a list of allGLObjects
to be drawn.- Returns
A list of overlays, and a list of corresponding
GLObjects
to be drawn.
-
_overlayBoundsChanged
(*args, **kwargs)[source]¶ Called when the
DisplayContext.bounds
are changed. Initialises/resets the display bounds, and/or preserves the zoom level if necessary.- Parameters
preserveZoom – Must be passed as a keyword argument. If
True
(the default), thezoom
value is adjusted so that the effective zoom is preserved
-
_displaySpaceChanged
(*a)[source]¶ Called when the
DisplayContext.displaySpace
changes. Resets the display bounds and zoom.
-
zoomToScale
(zoom)[source]¶ Converts the given zoom value into a scaling factor that can be multiplied by the display bounds width/height.
Zoom is specified as a percentage. At 100% the full scene takes up the full display.
In order to make the zoom smoother at low levels, we re-scale the zoom value to be exponential across the range.
This is done by transforming the zoom from
[zmin, zmax]
into[0.0, 1.0]
, then turning it from linear[0.0, 1.0]
to exponential[0.0, 1.0]
, and then finally transforming it back to[zmin - zmax]
.However there is a slight hack in that, if the zoom value is less than 100%, it will be applied linearly (i.e. 50% will cause the width/height to be scaled by 50%).
-
scaleToZoom
(scale)[source]¶ Converts the given zoom scaling factor into a zoom percentage. This method performs the reverse operation to the
zoomToScale()
method.
-
_applyZoom
(xmin, xmax, ymin, ymax)[source]¶ Zooms in to the given rectangle according to the current value of the zoom property Returns a 4-tuple containing the updated bound values.
-
_updateDisplayBounds
(bbox=None, oldLoc=None)[source]¶ Called on canvas resizes, overlay bound changes, and zoom changes.
Calculates the bounding box, in display coordinates, to be displayed on the canvas. Stores this bounding box in the
displayBounds
property. If any of the parameters are not provided, theDisplayContext.bounds
are used.Note
This method is used internally, and also by the
WXGLSliceCanvas
class.Warning
This code assumes that, if the display coordinate system has changed, the display context location has already been updated. See the
DisplayContext.__displaySpaceChanged()
method.- Parameters
bbox –
Tuple containing four values:
Minimum x (horizontal) value to be in the display bounds.
Maximum x value to be in the display bounds.
Minimum y (vertical) value to be in the display bounds.
Maximum y value to be in the display bounds.
oldLoc – If provided, should be the
(x, y)
location shown on thisSliceCanvas
- the new display bounds will be adjusted so that this location remains the same, with respect to the new field of view.
-
_setViewport
(invertX=None, invertY=None)[source]¶ Sets up the GL canvas size, viewport, and projection.
- Parameters
invertX – Invert the X axis. If not provided, taken from
invertX
.invertY – Invert the Y axis. If not provided, taken from
invertY
.
- Returns
A sequence of three
(low, high)
values, defining the display coordinate system bounding box.
-
_drawOffscreenTextures
()[source]¶ Draws all of the off-screen
GLObjectRenderTexture
instances to the canvas.This method is called by
_draw()
ifrenderMode
is set tooffscreen
.
-
__dict__
= mappingproxy({'__module__': 'fsleyes.gl.slicecanvas', '__doc__': 'The ``SliceCanvas`` represents a canvas which may be used to display a\n single 2D slice from a collection of 3D overlays. See also the\n :class:`.LightBoxCanvas`, a sub-class of ``SliceCanvas``.\n\n\n .. note:: The :class:`SliceCanvas` class is not intended to be instantiated\n directly - use one of these subclasses, depending on your\n use-case:\n\n - :class:`.OSMesaSliceCanvas` for static off-screen rendering of\n a scene using OSMesa.\n\n - :class:`.WXGLSliceCanvas` for interactive rendering on a\n :class:`wx.glcanvas.GLCanvas` canvas.\n\n\n The ``SliceCanvas`` creates a :class:`.SliceCanvasOpts` instance to manage\n its settings. The scene scene displayed on a ``SliceCanvas`` instance can\n be manipulated via the properties of its ``SliceCanvasOpts`` instnace,\n which is accessed via the ``opts`` attribute.\n\n\n **GL objects**\n\n\n The ``SliceCanvas`` draws :class:`.GLObject` instances. When created, a\n ``SliceCanvas`` creates a :class:`.GLObject` instance for every overlay in\n the :class:`.OverlayList`. When an overlay is added or removed, it\n creates/destroys ``GLObject`` instances accordingly. Furthermore,\n whenever the :attr:`.Display.overlayType` for an existing overlay\n changes, the ``SliceCanvas`` destroys the old ``GLObject`` associated with\n the overlay, and creates a new one.\n\n\n The ``SliceCanvas`` also uses an :class:`.Annotations` instance, for\n drawing simple annotations on top of the overlays. This ``Annotations``\n instance can be accessed with the :meth:`getAnnotations` method.\n\n\n **Performance optimisations**\n\n\n The :attr:`.SliceCanvasOpts.renderMode` property controls the way in which\n the ``SliceCanvas`` renders :class:`.GLObject` instances. It has three\n settings:\n\n\n ============= ============================================================\n ``onscreen`` ``GLObject`` instances are rendered directly to the canvas.\n\n ``offscreen`` ``GLObject`` instances are rendered off-screen to a fixed\n size 2D texture (a :class:`.RenderTexture`). This texture\n is then rendered to the canvas. One :class:`.RenderTexture`\n is used for every overlay in the :class:`.OverlayList`.\n\n ``prerender`` A stack of 2D slices for every ``GLObject`` instance is\n pre-generated off-screen, and cached, using a\n :class:`.RenderTextureStack`. When the ``SliceCanvas`` needs\n to display a particular Z location, it retrieves the\n appropriate slice from the stack, and renders it to the\n canvas. One :class:`.RenderTextureStack` is used for every\n overlay in the :class:`.OverlayList`.\n ============= ============================================================\n\n\n **Attributes and methods**\n\n\n The following attributes are available on a ``SliceCanvas``:\n\n\n =============== ===========================================\n ``name`` A unique name for this ``SliceCanvas``\n ``opts`` Reference to the :class:`.SliceCanvasOpts`.\n ``overlayList`` Reference to the :class:`.OverlayList`.\n ``displayCtx`` Reference to the :class:`.DisplayContext`.\n =============== ===========================================\n\n\n The following convenience methods are available on a ``SliceCanvas``:\n\n .. autosummary::\n :nosignatures:\n\n canvasToWorld\n panDisplayBy\n centreDisplayAt\n panDisplayToShow\n zoomTo\n resetDisplay\n getAnnotations\n getViewport\n ', '__init__': <function SliceCanvas.__init__>, 'destroy': <function SliceCanvas.destroy>, 'destroyed': <property object>, 'canvasToWorld': <function SliceCanvas.canvasToWorld>, 'panDisplayBy': <function SliceCanvas.panDisplayBy>, 'centreDisplayAt': <function SliceCanvas.centreDisplayAt>, 'getDisplayCentre': <function SliceCanvas.getDisplayCentre>, 'panDisplayToShow': <function SliceCanvas.panDisplayToShow>, 'zoomTo': <function SliceCanvas.zoomTo>, 'resetDisplay': <function SliceCanvas.resetDisplay>, 'getAnnotations': <function SliceCanvas.getAnnotations>, 'getGLObject': <function SliceCanvas.getGLObject>, 'getViewport': <function SliceCanvas.getViewport>, 'viewMatrix': <property object>, 'projectionMatrix': <property object>, '_initGL': <function SliceCanvas._initGL>, '_updateRenderTextures': <function SliceCanvas._updateRenderTextures>, '_getPreRenderTexture': <function SliceCanvas._getPreRenderTexture>, '_renderModeChange': <function SliceCanvas._renderModeChange>, '_highDpiChange': <function SliceCanvas._highDpiChange>, '_syncOverlayDisplayChanged': <function SliceCanvas._syncOverlayDisplayChanged>, '_zAxisChanged': <function SliceCanvas._zAxisChanged>, '_SliceCanvas__overlayTypeChanged': <function SliceCanvas.__overlayTypeChanged>, '_SliceCanvas__regenGLObject': <function SliceCanvas.__regenGLObject>, '_SliceCanvas__genGLObject': <function SliceCanvas.__genGLObject>, '_SliceCanvas__onGLObjectUpdate': <function SliceCanvas.__onGLObjectUpdate>, '_overlayListChanged': <function SliceCanvas._overlayListChanged>, '_getGLObjects': <function SliceCanvas._getGLObjects>, '_overlayBoundsChanged': <function SliceCanvas._overlayBoundsChanged>, '_displaySpaceChanged': <function SliceCanvas._displaySpaceChanged>, '_zoomChanged': <function SliceCanvas._zoomChanged>, 'zoomToScale': <function SliceCanvas.zoomToScale>, 'scaleToZoom': <function SliceCanvas.scaleToZoom>, '_applyZoom': <function SliceCanvas._applyZoom>, '_updateDisplayBounds': <function SliceCanvas._updateDisplayBounds>, '_setViewport': <function SliceCanvas._setViewport>, '_drawCursor': <function SliceCanvas._drawCursor>, '_drawOffscreenTextures': <function SliceCanvas._drawOffscreenTextures>, '_draw': <function SliceCanvas._draw>, '__dict__': <attribute '__dict__' of 'SliceCanvas' objects>, '__weakref__': <attribute '__weakref__' of 'SliceCanvas' objects>, '__annotations__': {}})¶
-
__module__
= 'fsleyes.gl.slicecanvas'¶
-
__weakref__
¶ list of weak references to the object (if defined)