graphics: Rendering using OpenGL

View

class View(drawing, *, window_size=(256, 256), trigger_set=None)

Bases: object

A View is the graphics windows that shows 3-dimensional drawings. It manages the camera and renders the drawing when needed.

property camera

The Camera controlling the vantage shown in the graphics window.

draw(camera=None, drawings=None, check_for_changes=True, swap_buffers=True)

Experimental API . Draw the scene.

property background_color

Background color as R, G, B, A values in 0-1 range.

property highlight_color

Highlight outline color as R, G, B, A values in 0-1 range.

property highlight_thickness

Highlight outline thickness in pixels.

property lighting

Lighting parameters.

property material

Material reflectivity parameters.

property silhouette

Silhouette parameters.

add_overlay(overlay)

Experimental API . Overlays are Drawings rendered after the normal scene is shown. They are used for effects such as motion blur or cross fade that blend the current rendered scene with a previous rendered scene.

overlays()

Experimental API . The current list of overlay Drawings.

remove_overlays(overlays=None, delete=True)

Experimental API . Remove the specified overlay Drawings.

image(width=None, height=None, supersample=None, transparent_background=False, camera=None, drawings=None)

Experimental API . Capture an image of the current scene. A PIL image is returned.

image_rgba(width=None, height=None, supersample=None, transparent_background=False, camera=None, drawings=None)

Experimental API . Capture an image of the current scene. A numpy uint8 rgba array is returned.

frame_buffer_rgba()

Experimental API . Return a numpy array of R, G, B, A values of the currently rendered scene. This is used for blending effects such as motion blur and cross fades.

resize(width, height)

Experimental API . This is called when the graphics window was resized by the user and causes the OpenGL rendering to use the specified new window size.

report_framerate(report_rate, monitor_period=1.0, _minimum_render_time=None)

Experimental API . Report a status message giving the current rendering rate in frames per second. This is computed without the vertical sync which normally limits the frame rate to typically 60 frames per second. The minimum drawing time used over a one second interval is used. The report_rate function is called with the frame rate in frames per second.

finish_rendering()

Experimental API . Force the graphics pipeline to complete all requested drawing. This can slow down rendering but is used by display devices such as Oculus Rift goggles to reduce latency time between head tracking and graphics update.

drawing_bounds(clip=False, cached_only=False, allow_drawing_changes=True)

Experimental API . Return bounds of drawing, displayed part only.

initial_camera_view(pad=0.05, set_pivot=True)

Experimental API . Set the camera position to show all displayed drawings, looking down the z axis.

view_all(bounds=None, pad=0)

Experimental API . Adjust the camera to show all displayed drawings using the current view direction. If bounds is given then view is adjusted to show those bounds instead of the current drawing bounds. If pad is specified the fit is to a window size reduced by this fraction.

set_rotation_depth(point)

Experimental API . Set center of rotation in middle of window at depth matching the depth along camera axis of the specified point.

picked_object(win_x, win_y, exclude=<function View.<lambda>>, beyond=None, max_transparent_layers=3)

Experimental API . Return a Pick object for the frontmost object below the given screen window position (specified in pixels). This Pick object will have an attribute position giving the point where the intercept occurs. This is used when hovering the mouse over an object (e.g. an atom) to get a description of that object. Beyond is minimum distance as fraction from front to rear clip plane.

picked_object_on_segment(xyz1, xyz2, exclude=<function View.<lambda>>, beyond=None, max_transparent_layers=3)

Experimental API . Return a Pick object for the first object along line segment from xyz1 to xyz2 in specified in scene coordinates. This Pick object will have an attribute position giving the point where the intercept occurs. Beyond is minimum distance as fraction (0-1) along the segment.

rectangle_pick(win_x1, win_y1, win_x2, win_y2, exclude=<function View.<lambda>>)

Experimental API . Return a Pick object for the objects in the rectangle having corners at the given screen window position (specified in pixels).

near_far_distances(camera, view_num, include_clipping=True)

Experimental API . Near and far scene bounds as distances from camera.

clip_plane_points(window_x, window_y, camera=None, view_num=None, include_scene_clipping=True)

Experimental API . Return two scene points at the near and far clip planes at the specified window pixel position. The points are in scene coordinates.

win_coord(pt, camera=None, view_num=None)

Experimental API . Convert world coordinate to window coordinate

rotate(axis, angle, drawings=None)

Experimental API . Move camera to simulate a rotation of drawings about current rotation center. Axis is in scene coordinates and angle is in degrees.

translate(shift, drawings=None, move_near_far_clip_planes=False)

Experimental API . Move camera to simulate a translation of drawings. Translation is in scene coordinates.

move(tf, drawings=None)

Experimental API . Move camera to simulate a motion of drawings. Transform is in scene coordinates.

pixel_size(p=None)

Experimental API . Return the pixel size in scene length units at point p in the scene.

stereo_scaling(delta_z)

Experimental API . If in stereo camera mode change eye separation so that when models moved towards camera by delta_z, their center of bounding box appears to stay at the same depth, giving the appearance that the models were simply scaled in size. Another way to understand this is the models are scaled when measured as a multiple of stereo eye separation.

Camera

class Camera

Bases: object

A Camera has a position in the scene and viewing direction given by a Place object. The -z axis of the coordinate frame given by the Place object is the view direction. The x and y axes are the horizontal and vertical axes of the camera frame. Different cameras handle perspective projection, orthographic projection, 360 degree equirectangular projection, sequential stereo with shutter glasses, ….

redraw_needed

Experimental API . Indicates whether a camera change has been made which requires the graphics to be redrawn.

name = 'unknown'

Experimental API . Name indicating the type of camera, for example, “mono”, “stereo”, “orthographic”.

property position

Place object giving location and orientation of the camera in scene coordinates. Camera points along -z axis.

view_direction(view_num=None)

Experimental API . The view direction of the camera in scene coordinates.

number_of_views()

Experimental API . TODO: Rename views to something clearer like “axis”. Number of view points for this camera. For example, sequential stereo has 2 views for left and right eyes, and 360 stereo renders the 6 faces of a cube and has 6 views.

view(camera_position, view_num)

Experimental API . Return the Place coordinate frame for a specific camera view number. As a transform it maps camera coordinates to scene coordinates.

view_pixel_shift(view_num)

Experimental API . Per view pixel shift of center away from center of render target. This is used for example to shift left/right eye images in sequential stereo camera.

set_fixed_pixel_shift(shift)

Experimental API . Set per view pixel shift of center away from center of render target. Used for supersampled image capture.

view_all(bounds, window_size=None, pad=0)

Experimental API . Return the shift that makes the camera completely show models having specified bounds. If the window size is given (width, height) in pixels then the models are fit in both height and width, otherwise just the width is fit. If pad is specified the fit is to a window size reduced by this fraction. The camera view direction is not changed.

view_width(point)

Experimental API . Return the full width of the view at the distance of point. The point is in scene coordinates.

projection_matrix(near_far_clip, view_num, window_size)

Experimental API . The 4 by 4 OpenGL projection matrix for rendering the scene.

ray(window_x, window_y, window_size)

Experimental API . Return origin and direction in scene coordinates of sight line for the specified window pixel position.

rectangle_bounding_planes(corner1, corner2, window_size)

Experimental API . Planes as 4-vectors bounding the view through a window rectangle. Rectangle diagonally opposite corners are given by corner1 and corner2 in pixels, and window size is in pixels.

set_special_render_modes(render)

Experimental API . Set any special rendering options needed by this camera. Called when this camera becomes the active camera.

clear_special_render_modes(render)

Experimental API . Clear any special rendering options needed by this camera. Done when another camera becomes the active camera.

set_render_target(view_num, render)

Experimental API . Set the OpenGL drawing buffer render the given view number. For quad-buffered stereo this code would switch between left and right eye buffers.

draw_background(view_num, render)

Experimental API . Draw background. May only draw it on the first view if multiple views render to portions of the same texture.

combine_rendered_camera_views(render)

Experimental API . Combine camera views into a single image.

class MonoCamera

Bases: Camera

Perspective projection camera has an angular field of view measured in degrees.

name = 'mono'

Experimental API . Name indicating the type of camera, for example, “mono”, “stereo”, “orthographic”.

field_of_view

Experimental API . Horizontal field of view in degrees.

view_all(bounds, window_size=None, pad=0)

Experimental API . Return the shift that makes the camera completely show models having specified bounds. The camera view direction is not changed.

view_width(center)

Experimental API . Return the width of the view at position center which is in scene coordinates.

ray(window_x, window_y, window_size)

Experimental API . Return origin and direction in scene coordinates of sight line for the specified window pixel position.

perspective_view_all(bounds, position, field_of_view, window_size=None, pad=0)

Experimental API . Return the camera position that shows the specified bounds. Camera has perspective projection.

perspective_view_width(point, origin, field_of_view)

Experimental API . Return the visible width at the distance to the given point in scene coordinates.

perspective_projection_matrix(field_of_view, window_size, near_far_clip, pixel_shift)

Experimental API . 4x4 perspective projection matrix viewing along -z axis.

perspective_direction(window_x, window_y, window_size, field_of_view)

Experimental API . Return points in camera coordinates at a given window pixel position at specified z depths. Field of view is in degrees.

class OrthographicCamera(field_width=None)

Bases: Camera

Orthographic projection camera.

name = 'orthographic'

Experimental API . Name indicating the type of camera, for example, “mono”, “stereo”, “orthographic”.

field_width

Experimental API . Horizontal field width in scene coordinate units.

view_all(bounds, window_size=None, pad=0)

Experimental API . Return the shift that shifts the camera to show the bounding box. The camera view direction is not changed.

view_width(center)

Experimental API . Return the width of the view at position center which is in scene coordinates.

projection_matrix(near_far_clip, view_num, window_size)

Experimental API . The 4 by 4 OpenGL projection matrix for rendering the scene.

ray(window_x, window_y, window_size)

Experimental API . Return origin and direction in scene coordinates of sight line for the specified window pixel position.

class StereoCamera(eye_separation_pixels=200)

Bases: Camera

Sequential stereo camera mode. Uses two parameters, the eye spacing in scene units, and also the eye spacing in pixels in the window. The two eyes are considered 2 views that belong to one camera.

name = 'stereo'

Experimental API . Name indicating the type of camera, for example, “mono”, “stereo”, “orthographic”.

field_of_view

Experimental API . Horizontal field of view in degrees.

eye_separation_scene

Experimental API . Stereo eye separation in scene units.

eye_separation_pixels

Experimental API . Separation of the user’s eyes in screen pixels used for stereo rendering.

view(camera_position, view_num)

Experimental API . Return the Place coordinate frame of the camera. As a transform it maps camera coordinates to scene coordinates.

number_of_views()

Experimental API . Number of views rendered by camera mode.

view_all(bounds, window_size=None, pad=0)

Experimental API . Return the shift that makes the camera completely show models having specified bounds. The camera view direction is not changed.

ray(window_x, window_y, window_size)

Experimental API . Return origin and direction in scene coordinates of sight line for the specified window pixel position. Uses the right eye.

view_width(center)

Experimental API . Return the width of the view at position center which is in scene coordinates.

view_pixel_shift(view_num)

Experimental API . Shift of center away from center of render target.

set_render_target(view_num, render)

Experimental API . Set the OpenGL drawing buffer and viewport to render the scene.

combine_rendered_camera_views(render)

Experimental API . Combine camera views into a single image.

class SplitStereoCamera(layout='side-by-side', eye_separation_scene=5.0, swap_eyes=False, convergence=0)

Bases: Camera

Side-by-side and top-bottom stereo.

name = 'split stereo'

Experimental API . Name indicating the type of camera, for example, “mono”, “stereo”, “orthographic”.

view(camera_position, view_num)

Experimental API . Return the Place coordinate frame for a specific camera view number. As a transform it maps camera coordinates to scene coordinates.

number_of_views()

Experimental API . Number of views rendered by camera mode.

view_all(bounds, window_size=None, pad=0)

Experimental API . Return the shift that makes the camera completely show models having specified bounds. The camera view direction is not changed.

ray(window_x, window_y, window_size)

Experimental API . Return origin and direction in scene coordinates of sight line for the specified window pixel position. Uses the right eye.

view_width(point)

Experimental API . Return the full width of the view at the distance of point. The point is in scene coordinates.

set_render_target(view_num, render)

Experimental API . Set the OpenGL drawing buffer and viewport to render the scene.

combine_rendered_camera_views(render)

Experimental API . Render the cube map using a projection.

frustum(left, right, bottom, top, z_near, z_far, xshift=0, yshift=0)

Experimental API . Return a 4 by 4 perspective projection matrix. It includes a shift along x used to superpose offset left and right eye views in sequential stereo mode.

ortho(left, right, bottom, top, z_near, z_far, xshift=0, yshift=0)

Experimental API . Return a 4 by 4 orthographic projection matrix. It includes a shift along x used to superpose offset left and right eye views in sequential stereo mode.

camera_framing_drawings(drawings)

Experimental API . Create a Camera object for viewing the specified models. This is used for capturing thumbnail images.

Drawing

class Drawing(name)

Bases: object

A Drawing represents a tree of objects each consisting of a set of triangles in 3 dimensional space. Drawings are used to draw molecules, density maps, geometric shapes and other models. A Drawing has a name, a unique id number which is a positive integer, it can be displayed or hidden, has a placement in space, or multiple copies can be placed in space, and a drawing can be highlighted. The coordinates, colors, normal vectors and other geometric and display properties are managed by the Drawing objects.

A drawing can have child drawings. The purpose of child drawings is for convenience in adding, removing, displaying and highlighting parts of a scene. Child drawings are created by the new_drawing() method.

Multiple copies of a drawing be drawn with specified positions and colors. Copy positions can be specified by a shift and scale factor but no rotation, useful for copies of spheres. Each copy can be displayed or hidden, highlighted or unhighlighted.

The basic data defining the triangles is an N by 3 array of vertices (float32 numpy array) and an array that defines triangles as 3 integer index values into the vertex array which define the 3 corners of a triangle. The triangle array is of shape T by 3 and is a numpy int32 array. The filled triangles or a mesh consisting of just the triangle edges can be shown. The vertices can be individually colored with linear interpolation of colors across triangles, or all triangles can be given the same color, or a 2-dimensional texture can be used to color the triangles with texture coordinates assigned to the vertices. Transparency values can be assigned to the vertices. Individual triangles or triangle edges in mesh display style can be hidden. An N by 3 float array gives normal vectors, one normal per vertex, for lighting calculations.

Rendering of drawings is done with OpenGL.

name

Experimental API . Name of this drawing.

texture

Experimental API . Texture to use in coloring the surface, a graphics.Texture object. Only 2-dimensional textures are supported. Can be None.

multitexture

Experimental API . List of N textures to use, each applying to 1/N of the triangles. This is used for volumetric rendering by texturing a stack of rectangles. Only 2-dimensional textures are supported. Can be None.

multitexture_reverse_order

Experimental API . Whether to draw multitextured geometry in reverse order for handling transparency. Used by grayscale rendering for depth ordering.

texture_coordinates

Experimental API . Texture coordinates, an N by 2 numpy array of float32 values in range 0-1

colormap

Experimental API . Maps 2D and 3D texture values to colors.

colormap_range

Experimental API . Data value range corresponding to ends of colormap.

ambient_texture

Experimental API . A 3-dimensional texture that modulates the brightness of surface vertex colors. Used for fast rendering of ambient occlusion lighting.

ambient_texture_transform

Experimental API . Transformation mapping vertex coordinates to ambient_texture coordinates, a geometry.Place object.

opaque_texture

Experimental API . Whether the texture for surface coloring is opaque or transparent.

use_lighting

Experimental API . Whether to use lighting when rendering. If false then a flat unshaded color will be shown.

allow_depth_cue

Experimental API . False means not show depth cue on this Drawing even if global depth cueing is on.

allow_clipping

Experimental API . False means not to clip this Drawing even if global clipping is on.

accept_shadow

Experimental API . False means not to show shadow on this Drawing even if global shadow is on.

accept_multishadow

Experimental API . False means not to show multishadow on this Drawing even if global multishadow is on.

inherit_graphics_exemptions

Experimental API . Whether disabled lighting and clipping in parent will be copied to child when drawing is added.

on_top

Experimental API . Whether to draw on top of everything else. Used for text labels.

was_deleted

Experimental API . Indicates whether this Drawing has been deleted.

pickable = True

Experimental API . Whether this drawing can be picked by View.picked_object().

casts_shadows = True

Experimental API . Whether this drawing creates shadows when shadows are enabled.

skip_bounds = False

Experimental API . Whether this drawing is included in calculation by bounds().

redraw_needed(**kw)

Experimental API . Function called when the drawing has been changed to indicate that the graphics needs to be redrawn.

property vertices

Vertices of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

property normals

Normal vectors of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

property triangles

Vertex indices for the corners of each triangle making up the rendered geometry, a numpy M by 3 array of int32 values. Read-only. Set using set_geometry() method.

property shape_changed

Did this drawing or any drawing in the same tree change shape since the last redraw.

Solid = 'solid'

Experimental API . Display style showing filled triangles.

Mesh = 'mesh'

Experimental API . Display style showing only edges of triangles.

Dot = 'dot'

Experimental API . Display style showing only dots at triangle vertices.

property display_style

Display style can be Drawing.Solid, Drawing.Mesh or Drawing.Dot. Only one style can be used for a single Drawing instance.

child_drawings()

Experimental API . Return the list of surface pieces.

all_drawings(displayed_only=False)

Experimental API . Return all drawings including self and children at all levels.

new_drawing(name, *, subclass=None)

Experimental API . Create a new empty child drawing.

add_drawing(d)

Experimental API . Add a child drawing.

remove_drawing(d, delete=True)

Experimental API . Remove a specified child drawing.

remove_drawings(drawings, delete=True)

Experimental API . Remove specified child drawings.

remove_all_drawings(delete=True)

Experimental API . Remove all child drawings.

property drawing_lineage

Return a sequence of drawings from the root down to the current drawing.

property display

Whether or not the surface is drawn.

property display_positions

Mask specifying which copies are displayed.

property highlighted

Whether or not the drawing is highlighted. Does not include or effect children.

property highlighted_positions

Mask specifying which drawing positions are highlighted. Does not include or effect children.

property highlighted_triangles_mask

Mask specifying which triangles are highlighted.

any_part_highlighted()

Experimental API . Is any part of this Drawing or its children highlighted.

clear_highlight(include_children=True)

Experimental API . Unhighlight this drawing and child drawings in if include_children is True.

property position

Position and orientation of the surface in space.

property scene_position

Position in scene coordinates.

property positions

Copies of the surface piece are placed using a 3 by 4 matrix with the first 3 columns giving a linear transformation, and the last column specifying a shift.

number_of_positions(displayed_only=False)

Experimental API . Number of positions the Drawing is placed at.

property color

Single color of drawing used when per-vertex coloring is not specified, 0-255 red, green, blue, alpha values.

property colors

Color for each position used when per-vertex coloring is not specified.

property vertex_colors

R, G, B, A color and transparency for each vertex, a numpy N by 4 array of uint8 values, can be None in which case a single color (attribute color) is used for the object.

set_transparency(alpha)

Experimental API . Set transparency to alpha (0-255). Applies to per-vertex colors if currently showing per-vertex colors otherwise single color. Does not effect child drawings.

showing_transparent(include_children=True)

Experimental API . Are any transparent objects being displayed. Includes all children.

set_geometry(vertices, normals, triangles, edge_mask=None, triangle_mask=None)

Experimental API . Set vertices, normals and triangles defining the shape to be drawn.

empty_drawing()

Experimental API . Does this drawing have no geometry? Does not consider child drawings.

number_of_triangles(displayed_only=False)

Experimental API . Return the number of triangles including all child drawings and all positions.

OPAQUE_DRAW_PASS = 'opaque'

Experimental API . Draw pass to render only opaque drawings.

TRANSPARENT_DRAW_PASS = 'transparent'

Experimental API . Draw pass to render only transparent drawings.

TRANSPARENT_DEPTH_DRAW_PASS = 'transparent depth'

Experimental API . Draw pass to render only the depth of transparent drawings.

HIGHLIGHT_DRAW_PASS = 'highlight'

Experimental API . Draw pass to render only the highlighted parts of drawings.

LAST_DRAW_PASS = 'last'

Experimental API . Draw pass to render after everything else for showing labels on top.

draw(renderer, draw_pass)

Experimental API . Draw this drawing using the given draw pass. Does not draw child drawings

draw_self(renderer, draw_pass)

Experimental API . Draw this drawing without children using the given draw pass.

bounds()

Experimental API . The bounds of all displayed parts of a drawing and its children and all descendants, including instance positions, in scene coordinates. Drawings with an attribute skip_bounds = True are not included. The bounds are in the scene coordinate system.

geometry_bounds()

Experimental API . Return the bounds of this drawing’s geometry not including positions and not including children. Bounds are in this drawing’s coordinate system. These bounds are cached for speed.

first_intercept(mxyz1, mxyz2, exclude=None)

Experimental API . Find the first intercept of a line segment with the displayed part of this drawing and its children. The end points are in the parent drawing coordinates and do not take account of this Drawings positions. If the exclude option is given it is a function that takes a drawing and returns true if this drawing should be excluded, ‘all’ if this drawing and its children should be excluded, or false to include this drawing and chidren. Returns a Pick object for the intercepted item. The Pick object has a distance attribute giving the fraction (0-1) along the segment where the intersection occurs. For no intersection None is returned. This routine is used for highlighting objects, for identifying objects during mouse-over, and to determine the front-most point in the center of view to be used as the interactive center of rotation.

first_intercept_children(child_drawings, mxyz1, mxyz2, exclude=None)

Experimental API . Like first_intercept() but check for intercepts with just the specified children.

bounds_intercept_copies(bounds, mxyz1, mxyz2)

Experimental API . Return indices of positions where line segment intercepts displayed bounds. This is to optimize picking so that positions where no intercept occurs do not need to be checked to see what is picked.

planes_pick(planes, exclude=None)

Experimental API . Find the displayed drawing instances bounded by the specified planes for this drawing and its children. Each plane is a 4-vector v with points in the pick region v0*x + v1*y + v2*z + v3 >= 0 using coordinate system of the parent drawing. If a drawing has instances then only the center of each instance is considered and the whole instance is picked if the center is within the planes. If a drawing has only one instance (self.positions has length 1) then the pick lists the individual triangles which have at least one vertex within all of the planes. If exclude is not None then it is a function called with a Drawing argument that returns ‘all’ if this drawing and its children should be excluded from the pick, or true if just this drawing should be excluded. Return a list of Pick objects for the contained items. This routine is used for highlighting objects in a frustum.

delete()

Experimental API . Delete drawing and all child drawings.

ALL_EDGES_DISPLAY_MASK = 7

Experimental API . Edge mask for displaying all three triangle edges (bits 0, 1, 2).

property triangle_mask

The triangle mask is a 1-dimensional bool numpy array of length equal to the number of triangles used to control display of individual triangles.

property highlighted_displayed_triangles_mask

Mask of highlighted and displayed triangles.

property edge_mask

The edge mask is a 1-dimensional uint8 numpy array of length equal to the number of triangles. The lowest 3 bits are used to control display of the 3 triangle edges in mesh mode.

custom_x3d(stream, x3d_scene, indent, place)

Experimental API . Override this function for custom X3D

This is a generic version and assumes that positions are orthogonal.

draw_opaque(renderer, drawings)

Experimental API . Draws the specified drawings but not their children.

draw_transparent(renderer, drawings)

Experimental API . Draws the specified drawings but not their children.

draw_depth(renderer, drawings, opaque_only=True)

Experimental API . Render only the depth buffer (not colors). Draws the specified drawings but not their children.

draw_overlays(drawings, renderer, scale=(1, 1))

Experimental API . Render drawings using an identity projection matrix with no depth test. Draws the specified drawings but not their children.

draw_highlight_outline(renderer, drawings, color=(0, 1, 0, 1), pixel_width=1)

Experimental API . Draw the outlines of highlighted parts of the specified drawings. Draws the specified drawings but not their children.

draw_on_top(renderer, drawings)

Experimental API . Draws the specified drawings but not their children.

draw_xor_rectangle(renderer, x1, y1, x2, y2, color, drawing=None)

Experimental API . Draw rectangle outline on front buffer using xor mode.

class PickedTriangle(distance, triangle_number, copy_number, drawing)

Bases: Pick

A picked triangle of a drawing.

description()

Experimental API . Text description of the picked object.

property id_string

A text identifier that can be used in commands to specified the picked Model. The id number is not a standard attribute of Drawing, only of Model which is a subclass of Drawing, and is a tuple of integers.

select(mode='add')

Experimental API . Cause this picked object to be highlighted (‘add’ mode), unhighlighted (‘subtract’ mode) or toggle highlighted (‘toggle’ mode).

class PickedTriangles(tmask, drawing)

Bases: Pick

Picked triangles of a drawing.

description()

Experimental API . Text description of the picked object.

select(mode='add')

Experimental API . Cause this picked object to be highlighted (‘add’ mode), unhighlighted (‘subtract’ mode) or toggle highlighted (‘toggle’ mode).

class PickedInstance(pmask, drawing)

Bases: Pick

A picked triangle of a drawing.

description()

Experimental API . Text description of the picked object.

select(mode='add')

Experimental API . Cause this picked object to be highlighted (‘add’ mode), unhighlighted (‘subtract’ mode) or toggle highlighted (‘toggle’ mode).

rgba_drawing(drawing, rgba, pos=(-1, -1), size=(2, 2), opaque=True, clamp_to_edge=True)

Experimental API . Make a drawing that is a single rectangle with a texture to show an RGBA image on it.

position_rgba_drawing(drawing, pos, size)

Experimental API . Use specified position and size for rgba drawing, values in fractional window size.

text_image_rgba(text, color, size, font, background_color=None, xpad=0, ypad=0, pixels=False, italic=False, bold=False, outline_width=0, outline_color=None)

Experimental API . Size argument is in points (1/72 inch) if pixels is False and the returned image has size to fit the specified text plus padding on each edge, xpad and ypad specified in pixels. If pixels is True then size is the image height in pixels and the font is chosen to fit within this image height minus ypad pixels at top and bottom.

concatenate_geometry(geom)

Experimental API . Combine list of (vertices, normals, triangles) triples into a single vertex, normal and triangle array triple. Also can combine pairs (vertices, triangles), or 4-tuples (vertices, normals, texcoords, triangles). All list entries must be tuples of the same length.

Pick

class Pick(distance=None)

A picked object returned by first_intercept() method of the Drawing class.

description()

Experimental API . Text description of the picked object.

select(mode='add')

Experimental API . Cause this picked object to be highlighted (‘add’ mode), unhighlighted (‘subtract’ mode) or toggle highlighted (‘toggle’ mode).

specifier()

Experimental API . Command specifier for the picked object.

Lighting

class Lighting

Lighting parameters specifying colors and directions of two lights: a key (main) light, and a fill light, as well as ambient light color. Directions are unit vectors in camera coordinates (x right, y up, z opposite camera view). Colors are R, G, B float values in the range 0-1.

Variables:

• key_light_direction – (.577, -.577, -.577)

• key_light_color – (1, 1, 1)

• key_light_intensity – 1

• fill_light_direction – (-.2, -.2, -.959)

• fill_light_color – (1, 1, 1)

• fill_light_intensity – 0.5

• ambient_light_color – (1, 1, 1)

• ambient_light_intensity – 0.4

• move_lights_with_camera – True

set_default_parameters(background_color=None)

Experimental API . Reset the lighting parameters to default values.

Material

class Material

Surface properties that control the reflection of light.

set_default_parameters()

Experimental API . Reset the material parameters to default values.

Texture

class Texture(data=None, dimension=2, cube_map=False, linear_interpolation=True, clamp_to_edge=False)

Create an OpenGL 1d, 2d, or 3d texture from a numpy array. For a N dimensional texture the data array can be N or N+1 dimensional. For example, for 2d shape (h, w, c) or (h, w) where w and h are the texture width and height and c is the number of color components. If the data array is 2-dimensional, the values must be 32-bit RGBA8. If the data array is 3 dimensional the texture format is GL_RED, GL_RG, GL_RGB, or GL_RGBA depending on whether c is 1, 2, 3 or 4 and only value types of uint8 or float32 are allowed and texture of type GL_UNSIGNED_BYTE or GL_FLOAT is created. Clamp to edge mode and nearest interpolation is set. The c = 2 mode uses the second component as alpha and the first componet for red, green, blue. The OpenGL texture is only created when the bind_texture() method is called. A reference to the array data is held until the OpenGL texture is created.

bind_texture(tex_unit=None)

Experimental API . Bind the OpenGL texture.

delete_texture()

Experimental API . Delete the OpenGL texture.

normalization()

Experimental API . Scale factor for converting texture values to normalized values, 0-1 for unsigned integer, -1 to 1 for signed integer.

read_texture_data(numpy_data_type=None)

Experimental API . The data is read back to a numpy array as uint8 values using the same array shape used to fill the texture.

reload_texture(data, now=False)

Experimental API . Replace the texture values in texture with OpenGL id using numpy array data. The data is interpreted the same as for the Texture constructor data argument.

set_linear_interpolation(linear)

Experimental API . Has side effect of binding texture.

texture_format(data)

Experimental API . Return the OpenGL texture format, internal format, and texture value type that will be used by the glTexImageNd() function when creating a texture from a numpy array of colors.

unbind_texture(tex_unit=None)

Experimental API . Unbind the OpenGL texture.

CrossFade

class CrossFade(session, frames)

Fade between one rendered scene and the next scene. This is a Drawing overlay that is added to the View to cause the cross-fade to be rendered. It is automatically added to the View when constructed and removes itself from the View when the fade is complete.

MotionBlur

class MotionBlur(viewer)

Leave faint images of previous rendered frames as the camera is moved through a scene. This is a Drawing overlay that is added to the View to render the motion blur. It is added to the View by the constructor and it can be removed from the View to stop the motion blur effect.

attenuate

Experimental API . All preceding frames are additionally dimmed by this factor.

decay_factor

Experimental API . The Nth previous rendered frame is dimmed by the decay factor to the Nth power. The dimming is achieved by fading to the current background color.

delete()

Experimental API . Delete drawing and all child drawings.

draw(renderer, draw_pass)

Experimental API . Draw this drawing using the given draw pass. Does not draw child drawings