Read Me

<center>
![logo][]
</center>

[HyperBallView][hb] demo v0.2 README (under construction)
==========================

$Id$

HyperBallView is a demo program illustrating the HyperBalls representation ([Chavent et al., 2011][hbpaper])
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][hb]

Features
--------

* fast HyperBalls ([Chavent et al., 2011][hbpaper]) 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][fvnano]. Read more about netCDF usage in the appendix.
* cross-platform application tested on MacOSX, Linux and Windows with shaders in GLSL and Cg languages ; a set of internal shaders is hardcoded, but alternatively they can be read from disk

Installation
------------

### Dependencies

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

#### Required
First, install the following dependencies: [CMake][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][markdown]. The [MarkDown][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][svnweb] 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.


Usage
-----

The current demo is intentionally kept simple and only a subset of functionalities is available.
For the moment you can load a molecule and change some visualization parameters.
The atom color is fixed at startup. As the code is very simple, you can easily tune more colors and so on.
The main goal of this demo is to show how to use the shaders (code for the GPU) to display molecular representations.

To launch the viewer, use a pdb file. There is a molecule test provided in the file example.pdb. To visualize it, do:

	${HBDEMO_EXE}/bin/HBView_demo ${HBDEMO_SRC}/share/example.pdb

This should yield an image similar to the one below (eventually with different colors).

<center>
![hbex][]
</center>

### Command line options
* **-help**: Prints a short help text
* **-bcol (int)**: Change background color: 0=white (default), 1=black, 2=grey
* **-acol (int)**: Change atom color scheme: 0=CPK (default), 1=VMD-like, 3=test,... (more details in the appendix below)
* **-noinfo**: Disable on-screen information about radii etc.
* **-xtc <traj.xtc>**: load a Gromacs xtc-format trajectory for playback
* **-bondfshader <file.glsl>**: manually select specific shaders to be loaded

### Change the visual representation

You can interactively **change the shrink factor** (**s key**):

* increase shrink: S
* diminish shrink: s

You can interactively **change the atom radii** (**a key**):

* increase atom radii: A
* diminish atom radii: a

You can interactively **change the bond radii** (**b key**):

* increase bond radii: B
* diminish bond radii: b

You can interactively **change both atom and bond radii** (**w key**):

* increase atom and bond radii: W
* diminish atom and bond radii: w

You can see the values of these parameters on the screen (unless you have chosen the **-noinfo** command line option).

Just push the **esc key** to **quit** the demo.

You can also **switch between standard representations** (**number keys**):

* Ball & Stick rep. : 1
* Licorice rep. : 2
* VdW rep. : 3
* HyperBalls rep. (smooth links): 4

For debug reasons, the **m key** prints the mouse X and Y position to the console.
The **F6 key** prints the difference between current and previous mouse position.

### Trajectory playback

When an XTC trajectory was loaded, you can go forward/backward with **n key** and **N key**.
Automatic playback can be started with the **p key**. The speed can be changed with the
**f key** and the **F key**.

### Write out your current camera position

Just push the **= key** to **write a binary netCDF file** containing your
current camera position.

### Navigate in the scene

#### Mouse and keyboard
Rotation/translation:

* You can **rotate** the molecule with the **mouse** clicking on the **left button**.
* You can **translate** the molecule along x and y with the **mouse** clicking on the **right button**.
* You can also **translate** the molecule using **arrow (cursor) keys**.

**Zoom** in/Zoom out (**z key**):

* You can zoom in with z
* You can zoom out with Z.
* You can zoom the molecule with the **mouse** clicking on the **central button**.

#### SpaceBall
We tested the 3DConnexion SpaceNavigator on MacOSX and configured it such that you can simultaneously rotate and translate
the view along all three axes. The axis mapping may be machine-specific, so you may have to modify
it. Please let us know if this is the case. On MacOSX, you can control SpaceBall parameters in the GLUT preferences (command + comma key combination).

#### Joystick
We tested the Logitech Rumblepad on MacOSX for navigation in the scene. Button and stick mapping is
still being improved. Any suggestions and contributions are welcome.

Examples
--------

In the share/jcc\_figures subdirectory you will find example scenes that were used for preparing the
HyperBalls paper ([Chavent et al., 2011][hbpaper]). Those are in netCDF format and you need to compile
the demo with netCDF support to make them work. The file names include the figure number, so that you
can easily find a given scene.

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][hbpaper]; 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][gpupaper]; 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.

The end!
------------

We hope you enjoy interactive HyperBalls visualization via this demo.
Please let us know about your applications and discoveries!


Copyright and License
================================================
This program is under the [CeCill licence][cecill], 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: netCDF input files
------------------------------
In order to be able to prepare some more sophisticated scenes, a netCDF-based input file can be prepared for the viewer.
We provide the ${HBDEMO_SRC}/share/pdb2cdl.py Python script to setup a variety of graphical representations using HyperBalls.
The following options are supported:

        Usage : -f input.pdb/pqr -o output.cdl [-c colorfile] [-r radiifile] [-p paramfile] [-t] [--biospring]
                -c,--colortype : atomcolor.txt (default), chaincolor.txt, resnamecolor.txt, restypecolor.txt
				-r,--radii     : atomradii.txt (default), cgradii.txt (c-alpha grains), martiniradii.txt (martini grains), cgLewittradii.txt, cgZachariasradii.txt
                -p,--paramaters: %sparameters/parameters.txt (default), you can use your own also
                -t,--trace
                -b,--biospring : coarse-grains C-Alpha for BioSpring. Override all other options.
                -C,--conect : pdb CONECT parsing (no bonds besides those connection)

Below a few simple examples are listed. They generate an out.cdl file from a mol.pdb input structure.
The out.cdl file has to be converted to netCDF format using "ncgen -o mol.nc out.cdl":

* pdb2cdl.py -f mol.pdb -o out.cdl -- generates a default "thick licorice" representation
* pdb2cdl.py -c resnamecolor.txt -f mol.pdb -o out.cdl -- generates a model colored by residue name
* pdb2cdl.py -f mol.pdb -o out.cdl -t -- generate a carbon-alpha trace

Appendix 3: implemented atom color schemes
------------------------------------------
The command line option **-acol (int)** can be used to choose different atom coloring schemes.
We have implemented the following sets:

* **0** (default) - CPK colors as described on [Wikipedia][cpkwikip]
* **1** - a [VMD][vmd]-like color atom set
* **2** - a slightly different flavor of CPK colors
* **3** - the rasmol CPK color scheme
* **4** - a minimal element-based color scheme

Appendix 4: 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][gdbweb] 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


<!-- REFERENCES -->
[logo]: hblogo.jpg "HyperBalls logo"
[hbex]: hbex.jpg "HyperBalls example screen"
[hb]: http://hyperballs.sourceforge.net "http://hyperballs.sourceforge.net"
[svnweb]: http://hyperballs.svn.sourceforge.net/viewvc/hyperballs/ "http://hyperballs.svn.sourceforge.net/viewvc/hyperballs/"
[fvnano]: http://www.baaden.ibpc.fr/projects/fvnano "http://www.baaden.ibpc.fr/projects/fvnano"
[cecill]: http://www.cecill.info/index.en.html "CeCill licence"
[cmake]: http://www.cmake.org "http://www.cmake.org"
[vmd]: http://www.ks.uiuc.edu/Research/vmd/ "http://www.ks.uiuc.edu/Research/vmd/"
[hbpaper]: http://dx.doi.org/10.1002/jcc.21861 "http://dx.doi.org/10.1002/jcc.21861"
[gpupaper]: http://dx.doi.org/10.1093/bib/bbq089 "http://dx.doi.org/10.1093/bib/bbq089"
[markdown]: http://daringfireball.net/projects/markdown/ "http://daringfireball.net/projects/markdown/"
[cpkwikip]: http://en.wikipedia.org/wiki/CPK_coloring "http://en.wikipedia.org/wiki/CPK_coloring"
[gdbweb]: http://about.gremedy.com "http://about.gremedy.com"