21. canvas — This implements an OpenGL drawing widget for painting 3D scenes. — pyFormex v0.8.6 documentation

### Navigation

- index
- modules |
- next |
- previous |
- pyFormex v0.8.6 documentation >
- pyFormex reference manual >

# 21. `canvas` — This implements an OpenGL drawing widget for painting 3D scenes.

`Classes defined in module canvas`

class `canvas.` `CanvasSettings`(**kargs)

  A collection of settings for an OpenGL Canvas.

  The canvas settings are a collection of settings and default values affecting the rendering in an individual viewport. There are two type of settings:

  - mode settings are set during the initialization of the canvas and can/should not be changed during the drawing of actors and decorations;
  - default settings can be used as default values but may be changed during the drawing of actors/decorations: they are reset before each individual draw instruction.

  Currently the following mode settings are defined:

  - bgmode: the viewport background mode. Should be one of ‘solid’, ‘vertical gradient’, ‘horizontal gradient’
  - bgcolor: the viewport background color (left/top color for graded modes)
  - bgcolor2: right/bottom color for a grade background
  - slcolor: the highlight color
  - rendermode: the rendering mode
  - shading: True is smooth, False is flat
  - lighting: True or False

  The list of default settings includes:

  - fgcolor: the default drawing color
  - bkcolor: the default backface color
  - colormap: the default color map to be used if color is an index
  - bklormap: the default color map to be used if bkcolor is an index
  - pointsize: the default size for drawing points
  - marksize: the default size for drawing markers
  - linewidth: the default width for drawing lines

  Any of these values can be set in the constructor using a keyword argument. All items that are not set, will get their value from the configuration file(s).

  `reset`(d={})

    Reset the CanvasSettings to its defaults.

    The default values are taken from the configuration files. An optional dictionary may be specified to override (some of) these defaults.

  `update`(d, strict=True)

    Update current values with the specified settings

    Returns the sanitized update values.

  classmethod `checkDict`(clas, dict, strict=True)

    Transform a dict to acceptable settings.

  `setMode`()

    Activate the mode canvas settings in the GL machine.

  `setDefault`()

    Activate the default canvas settings in the GL machine.

  `get`(key, default)

    Return the value for key or a default.

    This is the equivalent of the dict get method, except that it returns only the default value if the key was not found in self, and there is no _default_ method or it raised a KeyError.

  `setdefault`(key, default)

    Replaces the setdefault function of a normal dictionary.

    This is the same as the get method, except that it also sets the default value if get found a KeyError.

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

  A canvas for OpenGL rendering.

  The Canvas is a class holding all global data of an OpenGL scene rendering. This includes colors, line types, rendering mode. It also keeps lists of all the actors and decorations in the scene. It always has a Camera object holding import viewing parameters. And finally it stores the lighting information.

  It does not however contain the viewport size and position.

  `do_lighting`(onoff)

    Toggle lights on/off.

  `has_lighting`()

    Return the status of the lighting.

  `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

  `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.lighting. If the canvas was already initialized (it has a camera), and one of the specified settings is fdifferent 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.

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

  `setBgColor`(color1, color2=None, mode='solid')

    Set the background color.

    If one color is specified, a solid background is set. If two colors are specified, a graded background is set and an object is created to display the background.

  `createBackground`()

    Create the background object.

  `setFgColor`(color)

    Set the default foreground color.

  `setSlColor`(color)

    Set the highlight color.

  `setTriade`(on=None, pos='lb', siz=100)

    Toggle the display of the global axes on or off.

    If on is True, a triade of global axes is displayed, if False it is removed. The default (None) toggles between on and off.

  `glinit`()

    Initialize the rendering machine.

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

  `glupdate`()

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

  `clear`()

    Clear the canvas to the background color.

  `setDefaults`()

    Activate the canvas settings in the GL machine.

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

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

  `setBbox`(bbox=None)

    Set the bounding box of the scene you want to be visible.

  `addActor`(actor)

    Add a 3D actor to the 3D scene.

  `removeActor`(actor)

    Remove a 3D actor from the 3D scene.

  `addHighlight`(actor)

    Add a 3D actor highlight to the 3D scene.

  `removeHighlight`(actor)

    Remove a 3D actor highlight from the 3D scene.

  `addAnnotation`(actor)

    Add an annotation to the 3D scene.

  `removeAnnotation`(actor)

    Remove an annotation from the 3D scene.

  `addDecoration`(actor)

    Add a 2D decoration to the canvas.

  `removeDecoration`(actor)

    Remove a 2D decoration from the canvas.

  `remove`(itemlist)

    Remove a list of any actor/highlights/annotation/decoration items.

    This will remove the items from any of the canvas lists in which the item appears. itemlist can also be a single item instead of a list.

  `removeActors`(actorlist=None)

    Remove all actors in actorlist (default = all) from the scene.

  `removeHighlights`(actorlist=None)

    Remove all highlights in actorlist (default = all) from the scene.

  `removeAnnotations`(actorlist=None)

    Remove all annotations in actorlist (default = all) from the scene.

  `removeDecorations`(actorlist=None)

    Remove all decorations in actorlist (default = all) from the scene.

  `removeAll`()

    Remove all actors and decorations

  `redrawAll`()

    Redraw all actors in the scene.

  `setCamera`(bbox=None, angles=None)

    Sets the camera looking under angles at bbox.

    This function sets the camera angles and adjusts the zooming. The camera distance remains unchanged.

    If a bbox is specified, the camera will be zoomed to make the whole bbox visible. If no bbox is specified, the current scene bbox will be used. If no current bbox has been set, it will be calculated as the bbox of the whole scene.

    If no camera angles are given, the camera orientation is kept. angles can be a set of 3 angles, or a string

  `project`(x, y, z, locked=False)

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

  `unProject`(x, y, z, locked=False)

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

    Rectangle zoom to make full scene visible.

  `saveBuffer`()

    Save the current OpenGL buffer

  `showBuffer`()

    Show the saved buffer

  `draw_focus_rectangle`(width=2)

    Draw the focus rectangle.

    The specified width is HALF of the line width

  `draw_cursor`(x, y)

    draw the cursor

`Functions defined in module canvas`

`canvas.` `gl_pickbuffer`()

  Return a list of the 2nd numbers in the openGL pick buffer.

`canvas.` `glLineStipple`(factor, pattern)

  Set the line stipple pattern.

  When drawing lines, OpenGl can use a stipple pattern. The stipple is defined by two values: a pattern (on/off) of maximum 16 bits, used on the pixel level, and a multiplier factor for each bit.

  If factor <= 0, the stippling is disabled.

`canvas.` `glSmooth`()

  Enable smooth shading

`canvas.` `glFlat`()

  Disable smooth shading

`canvas.` `onOff`(onoff)

  Convert On/Off strings to a boolean

`canvas.` `glEnable`(facility, onoff)

  Enable/Disable an OpenGL facility, depending on onoff value

  facility is an OpenGL facility. onoff can be True or False to enable, resp. disable the facility, or None to leave it unchanged.

### Navigation

- index
- modules |
- next |
- previous |
- pyFormex v0.8.6 documentation >
- pyFormex reference manual >