101. opengl.canvas — This implements an OpenGL drawing widget for painting 3D scenes.

101.1. Classes defined in module opengl.canvas

class opengl.canvas.Canvas(settings={})

A canvas for OpenGL rendering.

The Canvas is a class holding all global data of an OpenGL scene rendering. It always contains a Scene with the actors and decorations that are drawn on the canvas. The canvas has a Camera holding the viewing parameters needed to project the scene on the canvas. Settings like colors, line types, rendering mode and the lighting information are gathered in a CanvasSettings object. There are attributes for some special purpose decorations (Triade, Grid) that can not be handled by the standard drawing and Scene changing functions.

The Canvas class does not however contain the viewport size and position. The class is intended as a mixin to be used by some OpenGL widget class that will hold this information (such as the QtCanvas class).

Important note: the Camera object is not initalized by the class initialization. The derived class initialization should therefore explicitely call the initCamera method before trying to draw anything to the canvas. This is because initializing the camera requires a working OpenGL format, which is only established by the derived OpenGL widget.

sceneBbox()

Return the bbox of all actors in the scene

resetDefaults(dict={})

Return all the settings to their default values.

setAmbient(ambient)

Set the global ambient lighting for the canvas

setMaterial(matname)

Set the default material light properties for the canvas

resetLighting()

Change the light parameters

resetOptions()

Reset the Drawing options to default values

setOptions(d)

Set the Drawing options to some values

setRenderMode(mode, lighting=None)

Set the rendering mode.

This sets or changes the rendermode and lighting attributes. If lighting is not specified, it is set depending on the rendermode.

If the canvas has not been initialized, this merely sets the attributes self.rendermode and self.settings.lighting. If the canvas was already initialized (it has a camera), and one of the specified settings is different from the existing, the new mode is set, the canvas is re-initialized according to the newly set mode, and everything is redrawn with the new mode.

setWireMode(state=None, mode=None)

Set the wire mode.

This toggles the drawing of edges on top of 2D and 3D geometry. State is either True or False, mode is 1, 2 or 3 to switch:

1: all edges 2: feature edges 3: border edges

If no mode is specified, the current wiremode is used. A negative value inverses the state.

getToggle(attr)

Get the value of a toggle attribute

setToggle(attr, state)

Set or toggle a boolean settings attribute

Furthermore, if a Canvas method do_ATTR is defined, it will be called with the old and new toggle state as a parameter.

do_wiremode(state, oldstate)

Change the wiremode

do_alphablend(state, oldstate)

Toggle alphablend on/off.

do_lighting(state, oldstate)

Toggle lights on/off.

setLineWidth(lw)

Set the linewidth for line rendering.

setLineStipple(repeat, pattern)

Set the linestipple for line rendering.

setPointSize(sz)

Set the size for point drawing.

setBackground(color=None, image=None)

Set the color(s) and image.

Change the background settings according to the specified parameters and set the canvas background accordingly. Only (and all) the specified parameters get a new value.

Parameters:

• color: either a single color, a list of two colors or a list of four colors.

• image: an image to be set.

createBackground()

Create the background object.

setFgColor(color)

Set the default foreground color.

setSlColor(color)

Set the highlight color.

setTriade(pos='lb', siz=100, triade=None)

Set the Triade for this canvas.

Display the Triade on the current viewport. The Triade is a reserved Actor displaying the orientation of the global axes. It has special methods to show/hide it. See also: removeTriade(), hasTriade()

Parameters:

• pos: string of two characters. The characters define the horizontal (one of ‘l’, ‘c’, or ‘r’) and vertical (one of ‘t’, ‘c’, ‘b’) position on the camera’s viewport. Default is left-bottom.

• siz: float: intended size (in pixels) of the triade.

• triade: None or Geometry: defines the Geometry to be used for representing the global axes.

  If None, use the previously set triade, or set a default if no previous.

  If Geometry, use this to represent the axes. To be useful and properly displayed, the Geometry’s bbox should be around [(-1,-1,-1),(1,1,1)]. Drawing attributes may be set on the Geometry to influence the appearance. This allows to fully customize the Triade.

removeTriade()

Remove the Triade from the canvas.

Remove the Triade from the current viewport. The Triade is a reserved Actor displaying the orientation of the global axes. It has special methods to draw/undraw it. See also: setTriade(), hasTriade()

hasTriade()

Check if the canvas has a Triade displayed.

Return True if the Triade is currently displayed. The Triade is a reserved Actor displaying the orientation of the global axes. See also: setTriade(), removeTriade()

setGrid(grid=None)

Set the canvas Grid for this canvas.

Display the Grid on the current viewport. The Grid is a 2D grid fixed to the canvas. See also: removeGrid(), hasGrid()

Parameters:

• grid: None or Actor: The Actor to be displayed as grid. This will normall be a Grid2D Actor.

removeGrid()

Remove the Grid from the canvas.

Remove the Grid from the current viewport. The Grid is a 2D grid fixed to the canvas. See also: setGrid(), hasGrid()

hasGrid()

Check if the canvas has a Grid displayed.

Return True if the Grid is currently displayed. The Grid is a 2D grid fixed to the canvas. See also: setGrid(), removeGrid()

initCamera(camera=None)

Initialize the current canvas camera

If a camera is provided, that camera is set. Else a new default camera is constructed.

clearCanvas()

Clear the canvas to the background color.

drawit(a)

_Perform the drawing of a single item

setDefaults()

Activate the canvas settings in the GL machine.

overrideMode(mode)

Override some settings

reset()

Reset the rendering engine.

The rendering machine is initialized according to self.settings: - self.rendermode: one of - self.lighting

glinit()

Initialize the rendering engine.

glFinish()

Flush all OpenGL commands, making sure the display is updated.

draw_sorted_objects(objects, alphablend)

Draw a list of sorted objects through the fixed pipeline.

If alphablend is True, objects are separated in opaque and transparent ones, and the opaque are drawn first. Inside each group, ordering is preserved. Else, the objects are drawn in the order submitted.

display()

(Re)display all the actors in the scene.

This should e.g. be used when actors are added to the scene, or after changing camera position/orientation or lens.

renderpick(obj_type)

Show rendering for picking

begin_2D_drawing()

Set up the canvas for 2D drawing on top of 3D canvas.

The 2D drawing operation should be ended by calling end_2D_drawing. It is assumed that you will not try to change/refresh the normal 3D drawing cycle during this operation.

end_2D_drawing()

Cancel the 2D drawing mode initiated by begin_2D_drawing.

addHighlight(itemlist)

Add a highlight or a list thereof to the 3D scene

setCamera(bbox=None, angles=None, orient='xy')

Sets the camera looking under angles at bbox.

This function sets the camera parameters to view the specified bbox volume from the specified viewing direction.

Parameters:

• bbox: the bbox of the volume looked at

• angles: the camera angles specifying the viewing direction. It can also be a string, the key of one of the predefined camera directions

If no angles are specified, the viewing direction remains constant. The scene center (camera focus point), camera distance, fovy and clipping planes are adjusted to make the whole bbox viewed from the specified direction fit into the screen.

If no bbox is specified, the following remain constant: the center of the scene, the camera distance, the lens opening and aspect ratio, the clipping planes. In other words the camera is moving on a spherical surface and keeps focusing on the same point.

If both are specified, then first the scene center is set, then the camera angles, and finally the camera distance.

In the current implementation, the lens fovy and aspect are not changed by this function. Zoom adjusting is performed solely by changing the camera distance.

project(x, y, z)

Map the object coordinates (x,y,z) to window coordinates.

unproject(x, y, z)

Map the window coordinates (x,y,z) to object coordinates.

zoom(f, dolly=True)

Dolly zooming.

Zooms in with a factor f by moving the camera closer to the scene. This does not change the camera’s FOV setting. It will change the perspective view though.

zoomRectangle(x0, y0, x1, y1)

Rectangle zooming.

Zooms in/out by changing the area and position of the visible part of the lens. Unlike zoom(), this does not change the perspective view.

x0,y0,x1,y1 are pixel coordinates of the lower left and upper right corners of the area of the lens that will be mapped on the canvas viewport. Specifying values that lead to smaller width/height will zoom in.

zoomCentered(w, h, x=None, y=None)

Rectangle zooming with specified center.

This is like zoomRectangle, but the zoom rectangle is specified by its center and size, which may be more appropriate when using off-center zooming.

zoomAll()

Zoom to make full scene visible.

saveBuffer()

Save the current OpenGL buffer

showBuffer()

Show the saved buffer

add_focus_rectangle(color=(1.0, 0.2, 0.4))

Draw the focus rectangle.

highlightSelection(K)

Highlight a selection of items on the canvas.

K is Collection of actors/items as returned by the pick() method.

removeHighlight()

Remove a highlight or a list thereof from the 3D scene.

Without argument, removes all highlights from the scene.

101.2. Functions defined in module opengl.canvas

opengl.canvas.drawDot(x, y)

Draw a dot at canvas coordinates (x,y).

opengl.canvas.drawLine(x1, y1, x2, y2)

Draw a straight line from (x1,y1) to (x2,y2) in canvas coordinates.

opengl.canvas.drawRect(x1, y1, x2, y2)

Draw the circumference of a rectangle.

opengl.canvas.drawGrid(x1, y1, x2, y2, nx, ny)

Draw a rectangular grid of lines

The rectangle has (x1,y1) and and (x2,y2) as opposite corners. There are (nx,ny) subdivisions along the (x,y)-axis. So the grid has (nx+1) * (ny+1) lines. nx=ny=1 draws a rectangle. nx=0 draws 1 vertical line (at x1). nx=-1 draws no vertical lines. ny=0 draws 1 horizontal line (at y1). ny=-1 draws no horizontal lines.