Graphics API

The Chimera 2 graphics API enables rendering of molecules and density maps. Here is some info on how Hydra is providing these interfaces.

Current ​Hydra API documentation produced by Sphinx from code comments. Includes graphics module.

Here are the Python classes in the Hydra graphics module (taken from graphics/init.py) that are used by other modules:

• Drawing
• View
• OpenGLContext
• Camera
• Lighting
• Material
• Texture
• Pick
• CrossFade
• MotionBlur

These classes handle representing the scene, rendering it, and selecting parts of it. The "scene graph" is the geometric shapes, colors and transparency including hierarchy and instancing, also including the concept of selected part, all handled by the Drawing class. A Drawing can have any number of child Drawings, to any depth, in a tree. Some classes handle the rendering (View, Camera, Lighting, CrossFade, MotionBlur) including effects like silhouette edges, shadows, ambient occlusion, depth cuing, cross fades, and also camera modes like mono, shutter glasses stereo, or oculus rift. Also image save including supersampling, the graphics redraw loop, and interactive center of rotation are managed by View. Selecting objects using a mouse click is handled by View and Drawing.

Differences between Chimera 1 graphics APIs and Chimera 2 graphics APIs

Chimera 1	Chimera 2
All in C++	All in Python
2 levels of models	N levels of models
Instancing atoms	Instancing any object
Legacy OpenGL 2.1	Core OpenGL 3.3
Rotation moves models	Rotation moves camera
Point, Vector, Xform in C++	Numpy arrays
Change notifications	Change status flags
Dome mode	Oculus Rift, ambient occlusion
Slow multipass silhouettes/selection outline	Fast single-pass silhouette/selection

How the Graphical User Interface uses a View

The View class handles OpenGL rendering. To use the View class a graphical user interface needs to create an opengl context and instruct View to draw periodically. Here are the relevant APIs.

• OpenGLContext instance - passed to the View constructor, subclassed to provide make_current() and swap_buffers() methods that are window-system specific operations.
• draw() - called on a window system exposure event, for example when the graphics window is deiconified.
• draw(only_if_changed=True) - called 60 times per second using a window system timer event.
• resize(width,height) - called when the user resizes the graphics window, for example using the mouse.

The OpenGL context is provided by the window toolkit and passed to the View constructor as an argument. The last three View methods are called by the GUI code. The user interface mouse modes code uses additional member of the View class, namely the Camera (v.camera), the window size (v.window_size), the pixel size in Angstroms (v.pixel_size()), and the object under the mouse (v.first_intercept()).

What Graphics APIs are Useful to Outside Developers?

Developing a new type of rendering is rare. In Chimera 1 we have molecule, density map, surface, vrml models, and maybe 2d labels. I don't know of any case where an outside developer tried to add a different type of rendering. This seems a very advanced programming task. So maybe the API for Drawing which is what all model types use for rendering does not need to be public. Instead a much simpler single level (no hierarchy) Surface model could be made a public API. The View and Camera classes control rendering and probably are of use to many outside developers.

Private OpenGL classes

The Hydra graphics module also has many private classes like Render, Shader, Framebuffer, Bindings, ... that are lower level OpenGL Python classes. Those are not used outside the graphics module currently. All the OpenGL is in one file graphics/opengl.py wrapped to make the OpenGL use more object oriented. No other code directly makes OpenGL calls.

WebGL

The Hydra graphics API does not address retargeting to WebGL with a client (web browser) / server model.

Dependencies

The Hydra graphics module depends on matrix and vector math provided by the geometry module. The main geometry object is a Place which is a coordinate frame (origin position and 3 axis vectors). Points and vectors are simply numpy arrays. The graphics module depends on numpy, pyopengl, math, but no Hydra modules besides geometry and map_cpp. The map_cpp module is C++ used to accelerate some numpy operations, currently just 3, what is hit by a mouse click for picking, hiding mesh edges, and blending images. These routines are in map_cpp which has about 100 routines for density map operations because I was too lazy to make a separate C++ module for these graphics operations.

Complexity

The public API classes above have a total of about 120 public methods and attributes and about 170 private methods and attributes. So this graphics module is pretty complex (3400 lines of Python, 280 lines of OpenGL shader code).

Some decision should be made about when public class attributes (or properties) are used and when methods are used. It is a mish mash in Hydra.

Clean-up and Issues with Hydra graphics module

• Should the frame drawing loop be outside the View class? Checks if graphics update needed. The View class should perhaps only take care of rendering effects (shadows, silhouettes, depth cue, background color) and know about the Camera and Models. Currently it handles "new frame" callbacks.
• Need an API to switch the graphics into stereo mode which requires that the GUI replace the OpenGL context with stereo-capable one.
• Make sphinx documentation group attributes and methods of classes.