graphics: Rendering using OpenGL¶
View¶
-
class
View
(drawing, window_size, opengl_context, log, track=True)¶ A View is the graphics windows that shows 3-dimensional drawings. It manages the camera and renders the drawing when needed.
-
camera
= None¶ The camera controlling the vantage shown in the graphics window.
-
reset_state
()¶ Reset state to data-less state
-
opengl_version
()¶ Return the OpenGL version as a string.
-
draw_new_frame
()¶ Draw the scene if it has changed or camera or rendering options have changed. Before checking if the scene has changed call the “new frame” callbacks typically used by movie recording to animate such as rotating the view, fading models in and out, .... If the scene is drawn call the “rendered frame” callbacks after drawing. Return true if draw, otherwise false.
-
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.
-
enable_depth_cue
(enable)¶ Turn on or off dimming with depth.
-
depth_cue_enabled
()¶ Is depth cue enabled. Boolean value.
-
shadows
¶ Is a shadow cast by the key light enabled? Boolean value.
-
set_multishadow
(n)¶ Specify the number of shadows to use for ambient shadowing, for example, 64 or 128. To turn off ambient shadows specify 0 shadows. Shadows are cast from uniformly distributed directions. This is GPU intensive, each shadow requiring a texture lookup.
-
set_shadow_map_size
(size)¶ Set the size of the 2-d texture for casting shadows. Typical values are 1024, 2048, 4096. Larger sizes give shadows with smoother edges.
-
set_multishadow_map_size
(size)¶ Set the size of the 2-d texture for casting shadows. Small values (128, 256) give nicer smoother appearance.
-
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.
-
add_2d_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.
-
twod_overlays
()¶ The current list of overlay Drawings.
-
remove_2d_overlays
(overlays=None)¶ Remove the specified overlay Drawings.
-
image
(width=None, height=None, supersample=None, 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
(time=None, monitor_period=1.0)¶ 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 message is shown in the status line and log after the one second has elapsed.
-
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.
-
add_callback
(type, cb)¶ Add a function to be called before each redraw (type = “new frame”), before each redraw after new frame callbacks (type = “graphics update”), after each redraw (type = “rendered frame”), or before redrawing when the shape has changed (type = “shape changed”). The callback functions take no arguments.
-
remove_callback
(type, cb)¶ Remove a callback that was added with add_callback().
-
drawing_bounds
()¶ Return bounds of drawing, displayed part only.
-
any_drawing_selected
()¶ Is anything selected.
-
initial_camera_view
()¶ Set the camera position to show all displayed drawings, looking down the z axis.
-
view_all
()¶ Adjust the camera to show all displayed drawings using the current view direction.
-
first_intercept
(win_x, win_y)¶ 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.
-
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.
-
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.
-
Camera¶
-
class
Camera
¶ 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. A camera has an angular field of view measured in degrees. In stereo modes it uses two additional 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.
-
pixel_shift
= None¶ Shift the camera by this number of pixels in x and y from the geometric center of the window. This is used for supersampling where fractional pixel shifts are used and the resulting images are blended.
-
redraw_needed
= None¶ Indicates whether a camera change has been made which requires the graphics to be redrawn.
-
mode
¶ Set the camera mode to a CameraMode object.
-
position
¶ Location and orientation of the camera in scene coordinates. Camera points along -z axis.
-
initialize_view
(center, size)¶ Set the camera to completely show models having specified center and radius looking along the scene -z axis.
-
view_all
(center, size)¶ Return the shift that makes the camera completely show models having specified center and radius. The camera view direction is not changed.
-
view_width
(center)¶ Return the width of the view at position center which is in scene coordinates.
-
set_field_of_view_from_view_width
(center, width)¶ Set the field of field the match the particular width
-
pixel_size
(center, window_size)¶ Return the size of a pixel in scene units for a point at position center. Center is given in scene coordinates and perspective projection is accounted for.
-
view_direction
(view_num=None)¶ The view direction of the camera in scene coordinates.
-
projection_matrix
(near_far_clip, view_num, window_size)¶ The 4 by 4 OpenGL perspective projection matrix for rendering the scene using this camera view.
-
clip_plane_points
(window_x, window_y, window_size, z_distances, render)¶ Return two scene points at the near and far clip planes at the specified window pixel position. TODO: Only correct for mono camera.
-
number_of_views
()¶ Number of view points for this camera. Stereo modes have 2 views for left and right eyes.
-
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
StereoCameraMode
(eye_separation_pixels=200)¶ Sequential stereo camera mode.
-
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.
-
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.
-
-
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)¶ 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.
-
reverse_order_children
= None¶ Whether to render the children in reverse order for properly handling transparency.
-
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.
-
vertex_colors
= None¶ 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.
-
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.
-
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.
-
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
()¶ 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.
-
selected
¶ Whether or not the drawing is selected.
-
selected_positions
¶ Mask specifying which drawing positions are selected.
-
selected_triangles_mask
¶ Mask specifying which triangles are selected.
-
any_part_selected
()¶ Is any part of this Drawing or its children selected.
-
fully_selected
()¶ Is the entire Drawing including children selected.
-
clear_selection
()¶ Unselect this drawing. Child drawings may remain selected.
-
promote_selection
()¶ Select the next larger containing group. If one child is selected, then all become selected.
-
demote_selection
()¶ If the selection has previously been promoted, this returns it to the previous smaller selection.
-
clear_selection_promotion_history
()¶ Forget the selection history promotion history. This is used when the selection is changed manually.
-
position
¶ Position and orientation of the surface in space.
-
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.
-
colors
¶ Color for each position used when per-vertex coloring is not specified.
-
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.
-
first_intercept
(mxyz1, mxyz2, exclude=None)¶ Find the first intercept of a line segment with the displayed part of this drawing and its children. 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.
-
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.
-
-
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_2d_overlays
(drawings, renderer)¶ Render drawings using an identity projection matrix with no depth test.
-
draw_outline
(renderer, cvinv, drawings)¶ Draw the outlines of selected parts of the specified drawings.
-
class
TrianglePick
(distance, triangle_number, copy_number, drawing)¶ A picked triangle of a drawing.
-
rgba_drawing
(rgba, pos=(-1, -1), size=(2, 2), drawing=None)¶ Make a drawing that is a single rectangle with a texture to show an RGBA image on it.
Pick¶
-
class
Pick
(distance)¶ A picked object returned by first_intercept() method of the Drawing class.
-
description
()¶ Text description of the picked object.
-
drawing
()¶ The drawing immediately containing the picked object.
-
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
(toggle=False)¶ Cause this picked object to be marked as selected.
-
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
()¶ Reset the lighting parameters to default values.
Material¶
Texture¶
-
class
Texture
(data=None, dimension=2)¶ 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.
-
bind_texture
(tex_unit=None)¶ Bind the OpenGL texture.
-
reload_texture
(data)¶ 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
(viewer, 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.
-