fsleyes.gl.glmesh
¶
This module provides the GLMesh
class, a GLObject
used
to render Mesh
overlays.
-
class
fsleyes.gl.glmesh.
GLMesh
(overlay, overlayList, displayCtx, canvas, threedee)[source]¶ Bases:
fsleyes.gl.globject.GLObject
The
GLMesh
class is aGLObject
which encapsulates the logic required to draw 2D slices, and 3D renderings, of aMesh
overlay. TheGLMesh
class assumes that theDisplay
instance associated with theMesh
overlay holds a reference to aMeshOpts
instance, which containsGLMesh
specific display settings.2D rendering
A
GLMesh
is rendered in one of two different ways, depending upon the value of theMeshOpts.outline
andMeshOpts.vertexData
properties.Cross-sections
If
outline is False and vertexData is None
, a filled cross-section of the mesh is drawn. This is accomplished using a three-pass technique, roughly following that described at http://glbook.gamedev.net/GLBOOK/glbook.gamedev.net/moglgp/advclip.html:The front face of the mesh is rendered to the stencil buffer.
The back face is rendered to the stencil buffer, and subtracted from the front face.
This intersection (of the mesh with a plane at the slice Z location) is then rendered to the canvas.
This cross-section is filled with the
MeshOpts.colour
property.Outlines
If
outline is True or vertexData is not None
, the intersection of the mesh triangles with the viewing plane is calculated. These lines are then rendered asGL_LINES
primitives.When a mesh outline is drawn on a canvas, the calculated line vertices, and corresponding mesh faces (triangles) are cached via the
OverlayList.setData()
method. This is so that other parts of FSLeyes can access this information if necessary (e.g. theOrthoViewProfile
provides mesh-specific interaction). For a canvas which is showing a plane orthogonal to display axis X, Y or Z, this data will be given a key of'crosssection_0'
,'crosssection_1'
, or'crosssection_2'
respectively.Colouring
These lines will be coloured in one of the following ways:
With the
MeshOpts.colour
.According to the
MeshOpts.vertexData
if it is set, in which case the properties of theColourMapOpts
class (from which theMeshOpts
class derives) come into effect.Or, if
vertexData
is set, and theMeshOpts.useLut
property isTrue
, theMeshOpts.lut
is used.
When
MeshOpts.vertexData is not None
, theGLMesh
class makes use of theglmesh
vertex and fragment shaders. These shaders are managed by two OpenGL version-specific modules -gl14.glmesh_funcs
, andgl21.glmesh_funcs
. These version specific modules must provide the following functions:compileShaders(GLMesh)
: Compiles vertex/fragment shaders.updateShaderState(GLMesh, **kwargs)
: Updates vertex/fragment shaders. Should expect the following keyword arguments:useNegCmap
: Boolean which isTrue
if a negative colour mapshould be used
cmapXform
: Transformation matrix which transforms from vertexdata into colour map texture coordinates.
flatColour
: Colour to use for fragments which are outsideof the clipping range.
lightPos
Light position in display coordinates.
preDraw(GLMesh)
: Prepare for drawing (e.g. load shaders)draw(GLMesh, glType, vertices, indices=None, normals=None, vdata=None)
: # noqaDraws mesh using shaders.
postDraw(GLMesh)
: Clean up after drawing
3D rendering
3D mesh rendering is much simpler than 2D rendering. The mesh is simply rendered to the canvas, and coloured in the same way as described above. Whether the 3D mesh is coloured with a flat colour, or according to vertex data, shader programs are used which colour the mesh, and also apply a simple lighting effect.
Flat shading
When the
MeshOpts.flatShading
property is active (only possible when 3D rendering), the mesh vertices and indices need to be modified. In order to achive flat shading, each vertex of a triangle must be given the same vertex data value. This means that vertices cannot be shared by different triangles. So when theflatShading
property changes, theupdateVertices()
method will re-generate the vertices and indices accordingly. ThegetVertexData()
method will modify the vertex data that gets passed to the shader accordingly too.-
__init__
(overlay, overlayList, displayCtx, canvas, threedee)[source]¶ Create a
GLMesh
.- Parameters
overlay – A
Mesh
overlay.overlayList – The
OverlayList
displayCtx – The
DisplayContext
managing the scene.canvas – The canvas drawing this
GLMesh
.threedee – 2D or 3D rendering.
-
destroy
()[source]¶ Must be called when this
GLMesh
is no longer needed. Removes some property listeners and destroys the colour map textures and off-screenRenderTexture
.
-
ready
()[source]¶ Overrides
GLObject.ready()
. Always returnsTrue
.
-
addListeners
()[source]¶ Called by
__init__()
. Adds some property listeners to theDisplay
andMeshOpts
instances so the OpenGL representation can be updated when the display properties are changed..
-
removeListeners
()[source]¶ Called by
destroy()
. Removes all of the listeners added by theaddListeners()
method.
-
registerLut
()[source]¶ Registers property listeners with the currently registered
LookupTable
(theMeshOpts.lut
property).
-
deregisterLut
()[source]¶ De-registers property listeners from the currently registered
LookupTable
.
-
updateVertices
(*a)[source]¶ Called by
__init__()
, and when certain display properties change. (Re-)generates the mesh vertices, indices and normals (if being displayed in 3D). They are stored as attributes calledvertices
,indices
, andnormals
respectively.
-
frontFace
()[source]¶ Returns the face of the mesh triangles which which will be facing outwards, either
GL_CCW
orGL_CW
. This will differ depending on the mesh-to-display transformation matrix.This method is only used in 3D rendering.
-
getDisplayBounds
()[source]¶ Overrides
GLObject.getDisplayBounds()
. Returns a bounding box which contains the mesh vertices.
-
draw2DOutlineEnabled
()[source]¶ Only relevent for 2D rendering. Returns
True
if outline mode should be used,False
otherwise.
-
needShader
()[source]¶ Returns
True
if a shader should be loaded,False
otherwise. Relevant for both 2D and 3D rendering.
-
preDraw
(xform=None, bbox=None)[source]¶ Overrides
GLObject.preDraw()
. Performs some pre-drawing configuration, which might involve loading shaders, and/or setting the size of the backingRenderTexture
instance based on the current viewport size.
-
draw2D
(zpos, axes, xform=None, bbox=None)[source]¶ Overrids
GLObject.draw2D()
. Draws a 2D slice of theMesh
, at the specified Z location.
-
draw3D
(xform=None, bbox=None)[source]¶ Overrides
GLObject.draw3D()
. Draws a 3D rendering of the mesh.
-
postDraw
(xform=None, bbox=None)[source]¶ Overrides
GLObject.postDraw()
. May call thegl14.glmesh_funcs.postDraw()
orgl21.glmesh_funcs.postDraw()
function.
-
drawOutline
(zpos, axes, xform=None, bbox=None)[source]¶ Called by
draw2D()
whenMeshOpts.outline is True or MeshOpts.vertexData is not None
. Calculates the intersection of the mesh with the viewing plane, and renders it as a set ofGL_LINES
. IfMeshOpts.vertexData is None
, the draw is performed using immediate mode OpenGL.Otherwise, the
gl14.glmesh_funcs.draw()
orgl21.glmesh_funcs.draw()
function is used, which performs shader-based rendering.
-
draw2DMesh
(xform=None, bbox=None)[source]¶ Not to be confused with
draw2D()
. Called bydraw2D()
forMesh
overlays which are actually 2D (with a flat third dimension).
-
drawCrossSection
(zpos, axes, lo, hi, dest)[source]¶ Renders a filled cross-section of the mesh to an off-screen
RenderTexture
. See:http://glbook.gamedev.net/GLBOOK/glbook.gamedev.net/moglgp/advclip.html
- Parameters
zpos – Position along the z axis
axes – Tuple containing
(x, y, z)
axis indices.lo – Tuple containing the low bounds on each axis.
hi – Tuple containing the high bounds on each axis.
dest – The
RenderTexture
to render to.
-
calculateViewport
(lo, hi, axes, bbox=None)[source]¶ Called by
draw2D()
. Calculates an appropriate viewport (the horizontal/vertical minimums/maximums in display coordinates) given thelo
andhi
GLMesh
display bounds, and a displaybbox
.
-
calculateIntersection
(zpos, axes, bbox=None)[source]¶ Uses the
Mesh.planeIntersection()
method to calculate the intersection of the mesh with the viewing plane at the givenzpos
.- Parameters
zpos – Z axis coordinate at which the intersection is to be calculated
axes – Tuple containing the
(x, y, z)
axis indices.bbox – A tuple containing a
([xlo, ylo, zlo], [xhi, yhi, zhi])
bounding box to which the calculation can be restricted.
- Returns
A tuple containing:
A
(n, 2, 3)
array which contains the two vertices of a line for every intersected face (triangle) in the mesh.A
(n, 3)
array containing the intersected faces (indices into theMesh.vertices
array).A
(n, 2, 3)
array containing the barycentric coordinates of the intersection line vertices.A
(4, 4)
array containing a transformation matrix for transforming the line vertices into the display coordinate system. May beNone
, indicating that no transformation is necessary.
Note
The line vertices, and corresponding mesh triangle face indices, which make up the cross section are saved via the
OverlayList.setData()
method, with a key'crosssection_[zax]'
, where[zax]
is set to the index of the display Z axis.
-
getVertexData
(vdtype, faces=None, dists=None)[source]¶ If
MeshOpts.vertexData
(orMeshOpts.modulateData
) is notNone
, this method returns the vertex data to use for the current vertex data index.faces
anddists
are used by thedrawOutline()
method, which draws a cross-section of the mesh. Thedists
array contains barycentric coordinates for each line vertex, and is used to linearly interpolate between the values of the vertices of the intersected triangles (defined infaces
).If
MeshOpts.vertexData is None
, this method returnsNone
.- Parameters
vdtype – Use
'vertex'
forMeshOpts.vertexData
, or'modulate'
forMeshOpts.modulateData
.
-
refreshCmapTextures
(*a, **kwa)[source]¶ Called when various
Display
orMeshOpts`
properties change. Refreshes theColourMapTexture
instances corresponding to theMeshOpts.cmap
andMeshOpts.negativeCmap
properties, and theLookupTableTexture
corresponding to theMeshOpts.lut
property.- Parameters
notify – Must be passed as a keyword argument. If
True
(the default)GLObject.notify()
is called after the textures have been updated.
-
compileShaders
()[source]¶ (Re)Compiles the vertex/fragment shader program(s), via a call to the GL-version specific
compileShaders
function.
-
updateShaderState
()[source]¶ Updates the vertex/fragment shader program(s) state, via a call to the GL-version specific
updateShaderState
function.
-
__module__
= 'fsleyes.gl.glmesh'¶