Files

• HBView_demo_OSX_SL.exe -- a pre-compiled binary version for Mac OSX Snow Leopard (v0.2)
• HBView_demo_win.exe -- a pre-compiled binary version for Windows (v0.2)
• HyperBallDemo_V0.2.tgz -- the current version corresponding to this README
• HyperBallDemo_V0.1_GLSL.tgz -- previous GLSL-only version. Use V0.2 instead.
• HyperBallDemo_V0.1_Cg.tgz -- previous Cg-only version. Use V0.2 instead.

HyperBallView demo v0.2 installation README

$Id: README.markdown 79 2011-11-22 20:46:24Z baaden $

HyperBallView is a demo program illustrating the HyperBalls representation (Chavent et al., 2011) designed to visualize molecular structures using GPU graphics card capabilities based on shaders (GLSL or Cg). It can read Protein Data Bank (PDB) files and a custom netCDF format.

The code is also intended as an example that can be re-used to implement the HyperBalls representation in other software. The performance of the code is not maximal, as this would require restructuring the program and it would become less readable.

More information on http://hyperballs.sourceforge.net

Features

• fast HyperBalls (Chavent et al., 2011) shaders for continuous representations including balls, sticks and intermediates
• interactively control HyperBalls parameters such as shrink factor and atom/bond radii
• navigate the sceen with a SpaceBall (for example the SpaceNavigator) or a joystick via GLUT
• choose among several color schemes; define background color
• read PDB files and netCDF files from the FvNano project. Read more about netCDF usage in the appendix.
• cross-platform application tested on MacOSX, Linux and Windows with shaders in GLSL and Cg languages

Installation

Dependencies

The demo uses CMake to facilitate cross-platform installations. Several graphics libraries are also needed.

Required

First, install the following dependencies: CMake, Cg Toolkit, freeglut/glut and a standard development environment (compiler and header files).

Optional

To install from the very latest source code version (recommended) you need the subversion svn utility. If you want to use the netCDF input files, you will also need the netCDF library and header files. In order to be able to rebuild the html version of this documentation you will need perl and MarkDown. The MarkDown software tool, written in Perl by John Gruber, is provided as part of this demo package source code.

Compilation

1. Download source code

   We advise you to get the latest version from svn, and put it in the ${HBDEMO_SRC} directory of your liking. In the next parts, we will refer to the absolute path of this directory as HBDEMO_SRC. So please replace it by your own path: for example it could be defined as /home/martin/hyperballdemo via the following command

   export HBDEMO_SRC=/home/martin/hyperballdemo (for bash)
   

   or

   setenv HBDEMO_SRC /home/martin/hyperballdemo (for csh)
   

   Now you can check out the latest version from the subversion repository using

   svn co https://hyperballs.svn.sourceforge.net/svnroot/hyperballs ${HBDEMO_SRC}
   

   This creates the demo source directory. You can also browse the subversion repository online at SourceForge.

2. Compile and install the demo

   mkdir HBDemoBuild
   cd HBDemoBuild
   cmake ${HBDEMO_SRC}
   make install (you may have to be root)
   

   This will install the demo in the default directory determined by the install prefix (/usr/local, be careful you might need to be root). You can also install the demo on your own install prefix (for example /home/martin) using this way :

   mkdir HBDemoBuild
   cd HBDemoBuild
   cmake ${HBDEMO_SRC} -DCMAKE_INSTALL_PREFIX:PATH=/home/martin
   make install
   

   Let's call the install prefix ${HBDEMO_EXE}. The above commands should generate and install an executable shell script called HBView_demo in ${HBDEMO_EXE}/bin.

Citation

• M. Chavent, A. Vanel, A. Tek, B. Levy, S. Robert, B. Raffin, M. Baaden: GPU-accelerated atom and dynamic bond visualization using HyperBalls, a unified algorithm for balls, sticks and hyperboloids; J Comput Chem (2011) 32, 2924.

Related work

• M. Chavent, B. Levy, M. Krone, K. Bidmon, J. P. Nomine, T. Ertl and M. Baaden: GPU-powered tools boost molecular visualization; Brief Bioinformatics (2011)

Troubleshooting

• please note that command line parsing is very basic. Wrong number/type of arguments will crash the software

Known Bugs and Issues

• on MacOSX, some artefacts may be visible in the renderings, in particular at joints between primitives
• right now, command line parsing is very primitive, and may well produce ugly bugs
• if you have both a Joystick and a Spaceball, you should deactivate Joystick support when compiling the demo for use with the SpaceBall. Actually GLUT sees the SpaceBall both as a SpaceBall and as a Joystick, which yields spurious results. You can use the GLUT_JOYSTICK_SUPPORT setting to do so.

Copyright and License

This program is under the CeCill licence, which is compatible with the GPL licence.

Appendix

Appendix 1: complementary installation instructions

(To be completed soon for Windows and Linux.)

In general, to ease source code compilation, we will provide some binary dependencies in the contrib subdirectory. Of course, you can always compile these packages from source.

MacOSX specific

• if you want to use Xcode, use cmake like this: cmake -G Xcode ${HBDEMO_SRC}
• if you get an error "CMake Error: The following variables are used in this project, but they are set to NOTFOUND." then you need to define some values on the cmake command line, In particular:
• for "GLUT_INCLUDE_DIR (ADVANCED)" add something like "-DGLUT_INCLUDE_DIR=/Developer/SDKs/MacOSX10.6.sdk/System/Library/Frameworks/GLUT.framework/Versions/A/Headers/"
• for "OPENGL_INCLUDE_DIR (ADVANCED)" add something like "-DOPENGL_INCLUDE_DIR=/Developer/SDKs/MacOSX10.6.sdk/System/Library/Frameworks/OpenGL.framework/Versions/A/Headers/"
• In the contrib subdirectory, we provide pre-compiled versions of the glew library. To use those, uncompress the version of your choice in a directory, for example in /opt/builds/
• for the library, add -DGLEW_LIBRARY:FILEPATH=/opt/builds/glew151_mac_SL/x86_64/libGLEW.a to the cmake command line
• for the includes, add -DGLEW_INCLUDE_DIR:PATH=/opt/builds/glew151_mac_SL to the cmake command line
• For example, in my case, the full line looks like this:
• cmake -G Xcode ${HBDEMO_SRC} -DCMAKE_INSTALL_PREFIX:PATH=/scratch/hbexe -DGLEW_INCLUDE_DIR:PATH=/opt/builds/glew151_mac_SL -DGLEW_LIBRARY:FILEPATH=/opt/builds/glew151_mac_SL/x86_64/libGLEW.a -DGLUT_INCLUDE_DIR=/Developer/SDKs/MacOSX10.6.sdk/System/Library/Frameworks/GLUT.framework/Versions/A/Headers/ -DOPENGL_INCLUDE_DIR=/Developer/SDKs/MacOSX10.6.sdk/System/Library/Frameworks/OpenGL.framework/Versions/A/Headers/

Appendix 2: debugging this demo

Debugging OpenGL-based shader implementations can be quite tricky, as there is no easy way to watch the value of variables or execute shader code step-by-step. We found the following tools very useful in our quest for bug-free shaders :)

• MacOSX OpenGL Shader Builder for checking the syntax and compilation of the GLSL shaders
• gDEBugger by graphicREMEDY for setting breakpoints and changing shaders on the fly in a running OpenGL application. The tool is now free and works on MacOSX, Linux and Windows