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)

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 the LightBoxCanvas, a sub-class of SliceCanvas.

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 a wx.glcanvas.GLCanvas canvas.

The SliceCanvas creates a SliceCanvasOpts instance to manage its settings. The scene scene displayed on a SliceCanvas instance can be manipulated via the properties of its SliceCanvasOpts instnace, which is accessed via the opts attribute.

GL objects

The SliceCanvas draws GLObject instances. When created, a SliceCanvas creates a GLObject instance for every overlay in the OverlayList. When an overlay is added or removed, it creates/destroys GLObject instances accordingly. Furthermore, whenever the Display.overlayType for an existing overlay changes, the SliceCanvas destroys the old GLObject associated with the overlay, and creates a new one.

The SliceCanvas also uses an Annotations instance, for drawing simple annotations on top of the overlays. This Annotations instance can be accessed with the getAnnotations() method.

Performance optimisations

The SliceCanvasOpts.renderMode property controls the way in which the SliceCanvas renders GLObject 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 (a RenderTexture). This texture is then rendered to the canvas. One RenderTexture is used for every overlay in the OverlayList.
prerender	A stack of 2D slices for every GLObject instance is pre-generated off-screen, and cached, using a RenderTextureStack. When the SliceCanvas needs to display a particular Z location, it retrieves the appropriate slice from the stack, and renders it to the canvas. One RenderTextureStack is used for every overlay in the OverlayList.

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:

canvasToWorld	Given pixel x/y coordinates on this canvas, translates them into xyz display coordinates.
panDisplayBy	Pans the canvas display by the given x/y offsets (specified in display coordinates).
centreDisplayAt	Pans the display so the given x/y position is in the centre.
panDisplayToShow	Pans the display so that the given x/y position (in display coordinates) is visible.
zoomTo	Zooms the canvas to the given rectangle, specified in horizontal/vertical display coordinates.
resetDisplay	Resets the zoom to 100%, and sets the canvas display bounds to the overaly bounding box (from the DisplayContext.bounds)
getAnnotations	Returns an Annotations instance, which can be used to annotate the canvas.
getViewport	Return the current viewport, as two tuples containing the (xlo, ylo, zlo) and (xhi, yhi, zhi) bounds.

__init__(overlayList, displayCtx, zax=0, opts=None)

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

This method must be called when this SliceCanvas is no longer being used.

It removes listeners from all OverlayList, DisplayContext, and Display instances, and destroys OpenGL representations of all overlays.

property destroyed

Returns True if a call to destroy() has been made, False otherwise.

canvasToWorld(xpos, ypos, invertX=None, invertY=None)

Given pixel x/y coordinates on this canvas, translates them into xyz display coordinates.

Parameters

• invertX – If None, taken from invertX.

• invertY – If None, taken from invertY.

panDisplayBy(xoff, yoff)

Pans the canvas display by the given x/y offsets (specified in display coordinates).

centreDisplayAt(xpos, ypos)

Pans the display so the given x/y position is in the centre.

getDisplayCentre()

Returns the horizontal/vertical position, in display coordinates, of the current centre of the display bounds.

panDisplayToShow(xpos, ypos)

Pans the display so that the given x/y position (in display coordinates) is visible.

zoomTo(xlo, xhi, ylo, yhi)

Zooms the canvas to the given rectangle, specified in horizontal/vertical display coordinates.

resetDisplay()

Resets the zoom to 100%, and sets the canvas display bounds to the overaly bounding box (from the DisplayContext.bounds)

getAnnotations()

Returns an Annotations instance, which can be used to annotate the canvas.

getGLObject(overlay)

Returns the GLObject associated with the given overlay, or None if there isn’t one.

getViewport()

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

Call the _overlayListChanged() method - it will generate any necessary GL data for each of the overlays.

_updateRenderTextures()

Called when the renderMode changes, when the overlay list changes, or when the GLObject representation of an overlay changes.

If the renderMode property is onscreen, this method does nothing.

Otherwise, creates/destroys RenderTexture or RenderTextureStack instances for newly added/removed overlays.

_getPreRenderTexture(globj, overlay)

Creates/retrieves a RenderTextureStack for the given GLObject. A tuple containing the RenderTextureStack, and its name, as passed to the resources module, is returned.

Parameters

• globj – The GLObject instance.

• overlay – The overlay object.

_renderModeChange(*a)

Called when the renderMode property changes.

_highDpiChange(*a)

Called when the SliceCanvasOpts.highDpi property changes. Calls the GLCanvasTarget.EnableHighDPI() method.

_syncOverlayDisplayChanged(*a)

Called when the DisplayContext.syncOverlayDisplay property changes. If the current renderMode is prerender, the RenderTextureStack 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 separate RenderTextureStack is needed for the DisplayContext used by this SliceCanvas.

_zAxisChanged(*a)

Called when the zax property is changed. Notifies the Annotations instance, and calls resetDisplay().

_overlayListChanged(*args, **kwargs)

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

Called by _draw(). Builds a list of all GLObjects to be drawn.

Returns

A list of overlays, and a list of corresponding GLObjects to be drawn.

_overlayBoundsChanged(*args, **kwargs)

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), the zoom value is adjusted so that the effective zoom is preserved

_displaySpaceChanged(*a)

Called when the DisplayContext.displaySpace changes. Resets the display bounds and zoom.

_zoomChanged(*a)

Called when the zoom property changes. Updates the display bounds.

zoomToScale(zoom)

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)

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)

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)

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, the DisplayContext.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 this SliceCanvas - 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)

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.

_drawCursor()

Draws a green cursor at the current X/Y position.

_drawOffscreenTextures()

Draws all of the off-screen GLObjectRenderTexture instances to the canvas.

This method is called by _draw() if renderMode is set to offscreen.

_draw(*a)

Draws the current scene to the canvas.

_SliceCanvas__genGLObject(overlay, updateRenderTextures=True, refresh=True)

Creates a GLObject instance for the given overlay. Does nothing if a GLObject already exists for the given overlay.

If updateRenderTextures is True (the default), and the SliceCanvasOpts.renderMode is offscreen or prerender, any textures for the overlay are updated.

If refresh is True (the default), the Refresh() method is called after the GLObject has been created.

Note

If running in wx (i.e. via a WXGLSliceCanvas), the GLObject instnace will be created on the wx.EVT_IDLE lopp (via the idle module).

_SliceCanvas__onGLObjectUpdate(globj, *a)

Called when a GLObject has been updated, and needs to be redrawn.

_SliceCanvas__overlayTypeChanged(value, valid, display, name)

Called when the Display.overlayType setting for any overlay changes. Makes sure that an appropriate GLObject has been created for the overlay (see the __genGLObject() method).

_SliceCanvas__regenGLObject(overlay, updateRenderTextures=True, refresh=True)

Destroys any existing GLObject associated with the given overlay, and creates a new one (via the __genGLObject() method).

If updateRenderTextures is True (the default), and the SliceCanvasOpts.renderMode is offscreen or prerender, any render texture associated with the overlay is destroyed.

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

__module__ = 'fsleyes.gl.slicecanvas'

__weakref__

list of weak references to the object (if defined)