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.

camera

The Camera controlling the vantage shown in the graphics window.

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

Draw the scene.

background_color

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

lighting

Lighting parameters.

material

Material reflectivity parameters.

add_overlay(overlay)

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

The current list of overlay Drawings.

remove_overlays(overlays=None)

Remove the specified overlay Drawings.

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

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

frame_buffer_rgba()

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)

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)

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

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)

Return bounds of drawing, displayed part only.

any_drawing_selected()

Is anything selected.

initial_camera_view(pad=0.05)

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

view_all(bounds=None, pad=0)

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.

first_intercept(win_x, win_y, exclude=None, beyond=None)

Return a Pick object for the front-most 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.

rectangle_intercept(win_x1, win_y1, win_x2, win_y2, exclude=None)

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)

Near and far scene bounds as distances from camera.

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

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)

Convert world coordinate to window coordinate

rotate(axis, angle, drawings=None)

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 camera to simulate a translation of drawings. Translation is in scene coordinates.

move(tf, drawings=None)

Move camera to simulate a motion of drawings.

pixel_size(p=None)

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

stereo_scaling(delta_z)

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.

class ClipPlanes

Bases: object

Manage multiple clip planes and track when any change so that redrawing is done.

class ClipPlane(name, normal, plane_point, camera_normal=None)

Bases: object

Clip plane that is either fixed in scene coordinates or camera coordinates (near/far planes). Normal vector and plane point are given in scene coordinates. If clip plane is fixed in camera coordinates, then camera_normal is given in camera coordinates.

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 = None

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

name = 'unknown'

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

position

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

view_direction(view_num=None)

The view direction of the camera in scene coordinates.

number_of_views()

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)

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)

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)

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)

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)

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)

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

ray(window_x, window_y, window_size)

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

rectangle_bounding_planes(corner1, corner2, window_size)

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)

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

clear_special_render_modes(render)

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

set_render_target(view_num, render)

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

combine_rendered_camera_views(render)

Combine camera views into a single image.

class MonoCamera

Bases: chimerax.core.graphics.camera.Camera

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

field_of_view = None

Horizontal field of view in degrees.

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

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

view_width(center)

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

ray(window_x, window_y, window_size)

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)

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

perspective_view_width(point, origin, field_of_view)

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)

4x4 perspective projection matrix viewing along -z axis.

perspective_direction(window_x, window_y, window_size, field_of_view)

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: chimerax.core.graphics.camera.Camera

Orthographic projection camera.

field_width = None

Horizontal field width in scene coordinate units.

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

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

view_width(center)

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

projection_matrix(near_far_clip, view_num, window_size)

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

ray(window_x, window_y, window_size)

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

class StereoCamera(eye_separation_pixels=200)

Bases: chimerax.core.graphics.camera.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.

field_of_view = None

Horizontal field of view in degrees.

eye_separation_scene = None

Stereo eye separation in scene units.

eye_separation_pixels = None

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

view(camera_position, view_num)

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

number_of_views()

Number of views rendered by camera mode.

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

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

view_width(center)

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

view_pixel_shift(view_num)

Shift of center away from center of render target.

set_render_target(view_num, render)

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

class SplitStereoCamera(layout='side-by-side')

Bases: chimerax.core.graphics.camera.Camera

Side-by-side and top-bottom stereo.

view(camera_position, view_num)

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

number_of_views()

Number of views rendered by camera mode.

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

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

set_render_target(view_num, render)

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

combine_rendered_camera_views(render)

Render the cube map using a projection.

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

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)

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)

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 selected. 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 selecting 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, selected or unselected.

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 = None

Name of this drawing.

vertices = None

Vertices of the rendered geometry, a numpy N by 3 array of float32 values.

triangles = None

Vertex indices for the corners of each triangle making up the rendered geometry, a numpy M by 3 array of int32 values.

normals = None

Normal vectors of the rendered geometry, a numpy N by 3 array of float32 values.

display_style = None

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

texture = None

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

multitexture = None

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 = None

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

texture_coordinates = None

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

ambient_texture = None

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

ambient_texture_transform = None

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

opaque_texture = None

Whether the texture for surface coloring is opaque or transparent.

use_lighting = None

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

was_deleted = None

Indicates whether this Drawing has been deleted.

redraw_needed(**kw)

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

shape_changed

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

Solid = 'solid'

Display style showing filled triangles.

Mesh = 'mesh'

Display style showing only edges of triangles.

Dot = 'dot'

Display style showing only dots at triangle vertices.

child_drawings()

Return the list of surface pieces.

all_drawings(displayed_only=False)

Return all drawings including self and children at all levels.

new_drawing(name=None)

Create a new empty child drawing.

add_drawing(d)

Add a child drawing.

remove_drawing(d, delete=True)

Remove a specified child drawing.

remove_drawings(drawings, delete=True)

Remove specified child drawings.

remove_all_drawings(delete=True)

Remove all child drawings.

drawing_lineage

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

display

Whether or not the surface is drawn.

display_positions

Mask specifying which copies are displayed. Can be None meaning all positions displayed

selected

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

selected_positions

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

selected_triangles_mask

Mask specifying which triangles are selected.

any_part_selected()

Is any part of this Drawing or its children selected.

clear_selection(include_children=True)

Unselect this drawing and child drawings in if include_children is True.

position

Position and orientation of the surface in space.

scene_position

Position in scene coordinates.

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)

Number of positions the Drawing is placed at.

color

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

colors

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

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)

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

Are any transparent objects being displayed. Includes all children.

geometry

Geometry is the array of vertices and array of triangles.

all_geometries()

Return geometry of this drawing and all its chidren as a list of 3-tuples, each containing the vertices, triangles, and a Places object that contains all the scene locations of those vertices and triangles.

empty_drawing()

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

number_of_triangles(displayed_only=False)

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

OPAQUE_DRAW_PASS = 'opaque'

Draw pass to render only opaque drawings.

TRANSPARENT_DRAW_PASS = 'transparent'

Draw pass to render only transparent drawings.

TRANSPARENT_DEPTH_DRAW_PASS = 'transparent depth'

Draw pass to render only the depth of transparent drawings.

SELECTION_DRAW_PASS = 'selection'

Draw pass to render only the selected parts of drawings.

draw(renderer, place, draw_pass, selected_only=False)

Draw this drawing and children using the given draw pass.

draw_self(renderer, place, draw_pass, selected_only=False)

Draw this drawing without children using the given draw pass.

bounds(positions=True)

The bounds of drawing and displayed children and displayed positions in the parent model coordinate system.

first_intercept(mxyz1, mxyz2, exclude=None)

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 and its children should be excluded. Return 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 selecting 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)

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

bounds_intercept_copies(bounds, mxyz1, mxyz2)

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)

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 true if this drawing and its children should be excluded from the pick. Return a list of Pick objects for the contained items. This routine is used for selecting objects in a frustum.

delete()

Delete drawing and all child drawings.

ALL_EDGES_DISPLAY_MASK = 7

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

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.

selected_displayed_triangles_mask

Mask of selected and displayed triangles.

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)

Override this function for custom X3D

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

draw_drawings(renderer, cvinv, drawings, opaque_only=False)

Render opaque and transparent draw passes for a given set of drawings, and given camera view (inverse camera transform).

draw_depth(renderer, cvinv, drawings, opaque_only=True)

Render only the depth buffer (not colors).

draw_overlays(drawings, renderer)

Render drawings using an identity projection matrix with no depth test.

draw_selection_outline(renderer, cvinv, drawings)

Draw the outlines of selected parts of the specified drawings.

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

Draw rectangle outline on front buffer using xor mode.

class TrianglePick(distance, triangle_number, copy_number, drawing)

Bases: chimerax.core.graphics.drawing.Pick

A picked triangle of a drawing.

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.

class TrianglesPick(tmask, drawing)

Bases: chimerax.core.graphics.drawing.Pick

Picked triangles of a drawing.

class InstancePick(pmask, drawing)

Bases: chimerax.core.graphics.drawing.Pick

A picked triangle of a drawing.

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

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

position_rgba_drawing(drawing, pos, size)

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

Pick

class Pick(distance=None)

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

description()

Text description of the picked object.

select(mode='add')

Cause this picked object to be selected (‘add’ mode), unselected (‘subtract’ mode) or toggle selected (‘toggle’ mode).

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)

Reset the lighting parameters to default values.

Material

class Material

Surface properties that control the reflection of light.

set_default_parameters()

Reset the material parameters to default values.

Texture

class Texture(data=None, dimension=2, cube_map=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)

Bind the OpenGL texture.

delete_texture()

Delete the OpenGL texture.

reload_texture(data, now=False)

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.

texture_format(data)

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)

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 = None

All preceding frames are additionally dimmed by this factor.

decay_factor = None

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.