103. opengl.decors — Decorations for the OpenGL canvas.

This module contains a collection of predefined decorations that can be useful additions to a geometry scene rendering.

103.1. Classes defined in module opengl.decors

class opengl.decors.BboxActor(bbox, **kargs)

Create a bounding box actor.

A bounding box is a hexaeder in global axes. The hexaeder is drawn in wireframe mode with default color black.

Parameters:

• bbox (coords_like) – A Coords with two points: the minimal and maximal coordinates of the bounding box to be drawn.

• **kargs (keyword parameters) – Keyword parameters like in the draw() funnction. The mode, lighting, opak parameters are fixed and can not be used.

Returns:

Actor – An Actor representing a bounding box.

class opengl.decors.Rectangle(x1, y1, x2, y2, **kargs)

A 2D-rectangle on the canvas.

class opengl.decors.Line(x1, y1, x2, y2, **kargs)

A 2D-line on the canvas.

Parameters:

• x1, y1, x2, y2: floats: the viewport coordinates of the endpoints of the line

• kargs: keyword arguments to be passed to the Actor.

class opengl.decors.Lines(data, color=None, linewidth=None, **kargs)

A collection of straight lines on the canvas.

Parameters:

• data: data that can initialize a 2-plex Formex: the viewport coordinates of the 2 endpoints of the n lines. The third coordinate is ignored.

• kargs: keyword arguments to be passed to the Actor.

class opengl.decors.Grid2D(x1, y1, x2, y2, nx=1, ny=1, lighting=False, rendertype=2, **kargs)

A 2D-grid on the canvas.

class opengl.decors.ColorLegend(colorscale, ncolors, x, y, w, h, ngrid=0, linewidth=None, nlabel=-1, size=18, font=None, textcolor=None, dec=2, scale=0, lefttext=False, **kargs)

A labeled colorscale legend.

When showing the distribution of some variable over a domain by means of a color encoding, the viewer expects some labeled colorscale as a guide to decode the colors. The ColorLegend decoration provides such a color legend. This class only provides the visual details of the scale. The conversion of the numerical values to the matching colors is provided by the ColorScale class.

Parameters:

• colorscale: a ColorScale instance providing conversion between numerical values and colors

• ncolors: int: the number of different colors to use.

• x,y,w,h: four integers specifying the position and size of the color bar rectangle

• ngrid: int: number of intervals for the grid lines to be shown. If > 0, grid lines are drawn around the color bar and between the ngrid intervals. If = 0, no grid lines are drawn. If < 0 (default), the value is set equal to the number of colors or to 0 if this number is higher than 50.

• linewidth: float: width of the grid lines. If not specified, the current canvas line width is used.

• nlabel: int: number of intervals for the labels to be shown. If > 0, labels will be displayed at nlabel interval borders, if possible. The number of labels displayed thus will be nlabel+1, or less if the labels would otherwise be too close or overlapping. If 0, no labels are shown. If < 0 (default), a default number of labels is shown.

• size: font size to be used for the labels

• font: font to be used for the labels. It can be a FontTexture or a string with the path to a monospace .ttf font. If unspecified, the default font is used.

• dec: int: number of decimals to be used in the labels

• scale: int: exponent of 10 for the scaling factor of the label values. The displayed values will be equal to the real values multiplied with 10**scale.

• lefttext: bool: if True, the labels will be drawn to the left of the color bar. The default is to draw the labels at the right.

Some practical guidelines:

• Large numbers of colors result in a quasi continuous color scheme.

• With a high number of colors, grid lines disturb the image, so either use ngrid=0 or ngrid= to only draw a border around the colors.

• With a small number of colors, set ngrid = len(colorlegend.colors) to add gridlines between each color. Without it, the individual colors in the color bar may seem to be not constant, due to an optical illusion. Adding the grid lines reduces this illusion.

• When using both grid lines and labels, set both ngrid and nlabel to the same number or make one a multiple of the other. Not doing so may result in a very confusing picture.

• The best practice is to either use a low number of colors (<=20) and the default ngrid and nlabel, or to use a high number of colors (>=200) and the default values or a low value for nlabel.

The ColorScale example script provides opportunity to experiment with different settings.

103.2. Functions defined in module opengl.decors

opengl.decors.Grid(nx=(1, 1, 1), ox=(0.0, 0.0, 0.0), dx=(1.0, 1.0, 1.0), planes='b', lines='b', planecolor=(1.0, 1.0, 1.0), linecolor=(0.0, 0.0, 0.0), alpha=0.3, name='_grid_', **kargs)

Creates a (set of) grid(s) in (some of) the coordinate planes.

Parameters:

• nx (tuple of int) – A tuple of three ints, specifying the number of divisions of the grid in the three coordinate directions. A zero value may be specified to avoid the grid to extend in that direction. Thus, setting the last value to zero will result in a planar grid in the xy-plane.

• ox (tuple of float) – The coordinates of the origin of the grid.

• dx (tuple of float) – The step size in each coordinate direction.

• plane (str) – One of ‘first’, ‘box’, ‘all’, ‘no’. The string can be shortened to the first character. Specifies how many planes to draw in each direction: ‘first’ only draws the first, ‘box’ draws the first and the last, ‘all’ draws all planes, ‘no’ draws no planes.

• lines (str) – One of ‘first’, ‘box’, ‘all’, ‘no’. The string can be shortened to the first character. Specifies how many lines to draw in each direction: ‘first’ only draws the first, ‘box’ draws the first and the last, ‘all’ draws all lines, ‘no’ draws no lines.

• plane_color (color_like) – The color to use for drawing the planes

• line_color (color_like) – The color to use for drawing the lines

• alpha (float) – Alpha transparency value (0.0 <= alpha <= 1.0)

• name (str) – Base name for the attributes set on the items in the returned List.

Returns:

List – A List with up to two Meshes: the planes and the lines. The Meshes come with the following Attributes set:

• name: the provided name with ‘_planes_’ or ‘_lines_’ appended.

• color: the provided plane or line color

• alpha: the provided alpha value for the planes, 0.6 for the lines.

• mode: ‘flat’

• lighting: False

The user can of course change these before drawing the List.