UnityMol  0.9.6-875
UnityMol viewer / In developement
User Guide - Quickstart

post-R676 (Nov. 2014)

umollogo

Introduction

Caution about evolving program versions

This part of the user guide is based on an initial user manual from November 2014 for the SweetUnityMol version of our software. It is currently being adapted and updated to match the current development builds of the 0.9.5 series. In the meantime, several descriptions and screen captures may still pertain to previous versions of the software and may be inaccurate for the current builds. Please be aware of this limitation.

Warning
Screenshots and examples in this document may differ from the current UnityMol version
Todo:
Complete user and developer guide(s) with data from internship reports.

Installing the software

The software described below has been initially developed based on revision 676 of UnityMol and version4.5.2f1 of Unity3D. All source code was implemented using C# and Cg languages built into Unity 3D and is available along with executables for Mac, Windows and Linux platforms on the sourceforge project website. Current UnityMol versions run within version 5.3.2f1 of Unity3D.

https://sourceforge.net/projects/unitymol/files/

Further documentation, input files, and series of illustrations can be found at

http://glycopedia.eu/IMG/pdf/unitymol-user-manual.pdf

and in the online UnityMol doxygen documentation available from:

http://www.baaden.ibpc.fr/umol/Doc/manual/html/pages.html

Windows version (date: 2014 10 02)

  • 32 bits
    • umol-win32-20141002_Data
    • Run_SweetUmol_32.bat
    • umol-win32-20141002.exe
  • 64 bits
    • umol-win64-20141002_Data
    • Run_SweetUmol_64.bat
    • umol-win64-20141002.exe
Note
This part and the following need to be updated to version 0.9.5

Mac version (date: 2014 10 02)

  • umol-macosx-universal-20141002.app

Linux version (data: 2014 10 02)

  • umol-linux-20141002_Data
  • umol-linux-20141002.x86
  • umol-linux-20141002.x86_64

Running the 32 and 64 bits Windows version

splashconfig
Warning
If you encounter issues running UnityMol, try to NOT USE THE FULL SCREEN MODE (check Windowed in the “UnityMol Configuration” menu (this menu is the menu where you set the resolution and click on Play!).

UnityMol's main menu bar

mainmenu1

The menu bar sits on the top and groups several submenus together that are described hereafter.

Some of these options offering advanced visualization and manipulations (haptic arm) are being implemented and are not functional at this time: November 2014.

1 - File menu (PDB Loading)

filemenu1

By default the visualization of UnityMol is the Particle mode. This mode uses the particle system of Unity3D to display the molecule. This may not be the most appropriate visualization. Changing to SmoothHyperballs mode offers a better visualization (this setting is the default in more recent builds of UnityMol).

2 - Atom Menu

atomappmenu1

Different types of representations are available, by Atom (1) or by Bond (2).

The preselected visualization is called Hyperballs (3) (the most interesting one).

hballex1

The Renderer (4) and Panels (5) menus are made to change the color and the texture of either the entire molecule, or a selection.

Hide: Hide the molecule (This option is activated when some visualization option (like secondary structures) is activated. Uncheck this box to display both the secondary structure and the molecule.

Radius: Change the radius of atom spheres.

LOD mode : when in the Hyperballs mode and this option is checked (and upon changing the orientation of the camera) the molecule will be displayed in the particle mode prior recreating the Hyperball representation. This is to be used for large macromolecular systems for which the Hyperballs representation reduces frame rate too much. FPS: Frame Per Second.

Automove (or SPACE key): the camera will turn around the molecule.

Lock Camera: The camera will not be able to move when this option is checked.

Brightness : adjust the brightness of Hyperballs. This is useful for some dark textures, or when using texture grayscale plus added colors.

A – HyperBall Style menu.

hballstylemenu1

Shrink : to adjust the shape of the bond.

Scale : to adjust the scale of the bond.

DFactor : only for Biological Networks.

Metaphor : pre-configured style (CPK, Licorice, VdW, Smooth Hyperballs)

metaphorex1

Above: example rendering of Ball & Sticks, Licorice, VdW, Smooth Hyperballs metaphors

Interactive mode : use spring forces to make an interactive molecule (an atom can be dragged and it will go back to its original position).

Drag/Spring : spring parameters for interactive mode.

Velocity Colors : colors each atom in interactive mode from white (slow) to black (very fast) based on the velocity of each particle.

Measure dist : activate and click on 2 atoms to display their distance.

Dist. Cueing : adjust the light according to the distance of the camera.

B - Render Menu (4)

rendermenu1

The whole molecule is selected by default. The selection can be changed by:

  • Atom Type (A)
  • Atom name (B)
  • Residue name (C)
  • By chain (D)

The selection can be combined.

Pre-configured coloration is on the Panels menu (E). Another color can be selected by clicking on the Color Button (F).

A texture can be selected and applied to the selection (G). Several textures are available on other pages (you can switch pages by clicking << and >>).

C – Panels Menu (3)

panelsmenu1

This menu contains pre-configured colors. You can switch by clicking on the buttons.

Color Panels:

  • All white: make the molecule all white.
  • Goodsell: make the color softer.
  • WaterColor: color carbons in blue.
  • Pastel: default colors.
  • CPK : color with the CPK color code.
  • Basic : color carbon in green.
  • IUPAC : color with the IUPAC color code.
  • Chains : color by chain
  • Sugar : color by sugar Type (the molecule must contain sugar).
  • ADN/ARN : coloration for DNA and RNA.

Texture Panels:

  • Default : default texture
  • CPK : CPK coloration with adapted texture.
  • Acid-Basic : coloration and texture according to the acid-basic status of amino acids.

3 – Secondary Structures

ssmenu1

4 – Surface

surfacemenu1

T : Density threshold used to generate the iso-surface

Generate : generate the surface.

BFactor : adjust the shape of the surface according to the B-factor value.

Volumetric : show the volumetric space of the protein with a particle system.

Toggle surface : hide surface representation (when you change a parameter, you have to hide the surface and press the Generate button again).

HetAtoms / Sugars : show surface for HetAtoms or/and Sugars molecules.

Upon selecting the Generate button, the following window will appear.

surfacemenu2

Color : change the color of the surface (external face).

Inside color : change the inside color.

Use atom color : Color the surface according to the type of atom under each portion of it.

Use chain color : use the color of the chains.

Hydrophobic scale : Color the surface according to different hydrophobic scale of residues.

Use properties color : Color the surface according to the properties of amino acids (basic, acids etc...)

Use BFactor color: Color the surface according to the B-factor value of the surface atoms.

Texture : apply a texture on the surface.

Static cut : cut the surface (you can control the cutting by a pad that will appear in the upper right corner).

Mobile cut : cut the surface and the cut will remain the same upon changing the orientation of the camera.

Brightness : adjust the brightness of the surface

Color weight : adjust the color concentration on the surface.

5 – Electrostat.

To use this menu, the following files have to be in the same folder: the PDB file and (with the same name) a file with extension .dx and .apf generated with softwares such as APBS (a wide-spread software for evaluating the electrostatic properties of biomolecular systems).

electrostmenu1

Transparency : Add transparency to the mesh generated upon loading the negative and positive electrostatic visualization.

T : Threshold value used to generate the electrostatic isosurface.

Load Neg/Pos : load electrostatic visualization.

Toggle Neg/Pos : show or hide the electrostatic visualization.

Volumetric Fields : volume rendering of the electrostatic fields.

Field Lines : show the Field Lines visualization (examine the local intensity of electric fields).

6 – Display

This menu is made to take screenshots, change the background and add special effects.

displaymenu1

Screenshot (or P key) : take a screenshot (prefer the P key or you will get all menus included with the screen capture).

ScreenShot Sequence : doesn't work yet.

Background : add a picture in the background (switch between yes/no)

White/Gray/Black : quick selection of background color

Background Color : choose your background color with a color panel.

Effects : add special effect.

Infos : show/hide FPS info and Atom/Bond number.

List of all visual effects:

  • SSAO : Screen Space Ambient Occlusion. Works on spheres, cubes, surfaces and secondary structures
  • DOF : focus on a point and make fuzzy all atoms far away from this point. This effect requires selecting (by clicking) an atom. It works better for large molecules.
  • EDGE : the edge of every atom is black.
  • CREASE : add a thick contour to the molecule.
  • SEPIA : use a SEPIA coloration.
  • GRAYS : make the molecule black and white.
  • GLOW : make all atoms shiny.
  • BLUR : add a blur effect upon moving the camera.
  • NOISE : add noise on the screen
  • BLUR2 : constant blur.
  • VORTEX : twist the molecule around the center.
  • TWIRL : similar to VORTEX

7 – Advanced

This menu offers advanced options (only some are fully implemented and functional).

advancedmenu1

GUI Scale : change the size of the GUI (buggy).

Orto/Persp : doesn't work fully yet.

Best Textures : switch between a moderate and large selection of lit sphere textures.

Depth Cueing : doesn't work yet.

Volumectric Depth Cueing: Doesn't work yet.

Ambient Occlusion : darkens the densest parts of the molecule to improve depth perception.

8 – Guided Navigation

guidednavmenu1

This menu is used to enable a "guided navigation" feature, but for now it works only with the pdb 3EI0 (GLIC ion channel) as part of work in progress. See the following paper by Trellet in IEEE VR 2015 for more detail.

Symmetry origin : X,Y,Z coordinates of the center of symmetry.

Symmetry direction : vector of the symmetry direction.

Send : activate the guided navigation mode.

9 – Sugar

This menu is made to deal with the specific features of sugar visualization (the atomic coordinate file can be generated (pdb format) by several molecular builders, but the POLYS 2.0 software is the most appropriate). The visualization mode called Ring Blending works with all molecules.

sugarmenu1

Enable Ring Blending : enable the filling of all rings (aromatic, sugar, or other rings) with a semi-transparent color.

Enable SugarRibbons : enable the SugarRibbons visualization (to transform a sugar into a "schematic" representation like secondary structures, but adapted for sugars).

Hide Hydrogens : hide hydrogens atoms. Sugar: hide sugar atoms.

Non Sugar : hide non sugar atoms.

Tune submenu

sugarmenu2

Show Oxygens : to display the intracyclic oxygen atom as a sphere.

Sugar Only : apply the sugar Ribbons visualization only on “sugar residues” (will detect the 3 letter sugar codes in the PDB file. List of recognized 3 letters code is given below).

Change Coloration : open the Color Tune Menu to change color of: sphere, rings and outer ring.

Oxygen Sphere size : To adjust the size of the radius of the sphere.

Ribbons Thickness : to adjust the thickness of the ribbon.

Inner Ring Thickness : to adjust the thickness of the ring.

Outer Ring Thickness : to adjust the thickness of the ring.

Pyranose : to adjust the thickness of the glycosidic bond (for pyranose).

Pyranose : to adjust the thickness of other bonds (for pyranose).

Furanose : to adjust the thickness of bonds for Furanose.

Note
Do not forget to click on Apply changes to apply the selected new parameters.

Color Tune submenu

sugarmenu3

For Oxygen Sphere, Outer Rings and Bond:

  • Sugar : use the sugar color to color Oxygen/Outer Rings or Bonds.
  • Chain : use the chain color to color Oxygen/Outer Rings or Bonds
  • Custom color : open a color picker windows to choose a custom color for Oxygen/Outer Rings or Bonds.
  • The color can be made darker or lighter with the Light Color Factor slider.
Note
Apply Changes button not needed for this feature.

10 – VRPN

This menu is used to connect a haptic arm, but a VRPN server needs to be installed on the computer. Work in progress.

11 – MDDriver

This menu is meant to visualize a real-time molecular simulation. Work in progress.

12 – Reset

Reset the view.

Key Bindings

Todo:
Verify the key bindings and check against Edit > Project Settings > Input

General

Key to press Action to carry out
LEFT Arrow – A Move LEFT
RIGHT Arrow – D Move RIGHT
DOWN arrow - S Move DOWN
UP arrow – W Move UP
Q Rotation DOWN
E Rotation UP
Z Rotation LEFT
X Rotation Right
N ZOOM +
B ZOOM –
P Screenshot (only on local pdb; doesn't work yet on fetched PDB)
BACKSPACE Hide GUI
SPACE Automove (rotation right)
R Reset to center
C Center to one or several atoms (select an atom/group with the selection mode first).

Guided Navigation (only for 3EI0)

These controls are only available when Guided Navigation mode is activated. The actual version is specific to pentameric channels (especially the PDB file 3EI0).

Constrained navigation

Key to press Action to carry out
U Enable/Disable automatic Constrained Navigation UP (panoramic mode)
J Enable/Disable automatic Constrained Navigation DOWN (panoramic mode)
UP ARROW - W Constrained Navigation Up
DOWN ARROW - S Constrained Navigation Down
RIGHT ARROW - D move RIGHT
LEFT ARROW - A move LEFT

Spreading

This mode doesn't work for particles and cubes. Second step is only available by fetching PDB 3EI0.

Key to press Action to carry out
Numpad + or B Spreading chains
Numpad – or V Narrowing chains
Numpad \* or T Reset chains
L Enable/Disable spreading near the structure (active by default)

Panoramic mode

Key to press Action to carry out
I Enable/Disable panoramic mode
LEFT ARROW - A turn LEFT
RIGHT ARROW - D turn RIGHT
DOWN ARROW - S move DOWN
UP ARROW - W move UP

Monomer jump mode

Key to press Action to carry out
M Enable/Disable monomer jump mode
LEFT ARROW - A Next monomer on left
RIGHT ARROW - D Next monomer on right

Appendix

Description of the PDB coordinate input file

Input File generated by SWEET

pdbsweet1
1 ATOM 1 C1 FUC 1 2.387 -19.488 -11.522 0.00 0.00 C1
2 ATOM 2 C2 FUC 1 3.248 -19.891 -12.734 0.00 0.00 C2
3 ATOM 3 C3 FUC 1 4.696 -19.417 -12.550 0.00 0.00 C3
4 ATOM 4 C4 FUC 1 5.229 -19.916 -11.196 0.00 0.00 C4
5 ATOM 5 C5 FUC 1 4.278 -19.476 -10.072 0.00 0.00 C5
6 ATOM 6 C6 FUC 1 4.703 -19.967 -8.682 0.00 0.00 C6
7 ATOM 7 OR FUC 1 2.950 -19.963 -10.295 0.00 0.00 O7
8 ATOM 8 OW FUC 1 2.124 -18.089 -11.437 0.00 0.00 O8
9 ATOM 9 O2H FUC 1 2.615 -19.391 -13.909 0.00 0.00 OH2
10 ATOM 10 O3H FUC 1 5.479 -19.850 -13.659 0.00 0.00 OH3
11 ATOM 11 O4H FUC 1 5.336 -21.339 -11.160 0.00 0.00 OH4
12 ATOM 12 H5 FUC 1 4.272 -18.370 -10.039 0.00 0.00 H5
13 ATOM 13 H1 FUC 1 1.402 -19.965 -11.595 0.00 0.00 H1
14 ATOM 14 H2 FUC 1 3.255 -20.998 -12.784 0.00 0.00 H2
15 ---------------------------------------------------------------------
16 ATOM 23 C1 GAL 2 1.456 -16.523 -9.755 0.00 0.00 C1
17 ATOM 24 C2 GAL 2 1.018 -17.688 -10.638 0.00 0.00 C2
18 ATOM 25 C3 GAL 2 -0.154 -17.316 -11.531 0.00 0.00 C3
19 ATOM 26 C4 GAL 2 -1.262 -16.689 -10.717 0.00 0.00 C4
20 ATOM 27 C5 GAL 2 -0.709 -15.522 -9.900 0.00 0.00 C5
21 ATOM 28 C6 GAL 2 -1.722 -14.822 -9.021 0.00 0.00 C6
22 ---------------------------------------------------------------------
23 ATOM 44 C1 XYL 3 2.801 -16.388 -6.544 0.00 0.00 C1
24 ATOM 45 C2 XYL 3 3.027 -16.035 -8.001 0.00 0.00 C2
25 ATOM 46 C3 XYL 3 4.524 -16.021 -8.286 0.00 0.00 C3
26 ATOM 47 C4 XYL 3 5.231 -15.028 -7.349 0.00 0.00 C4
27 ATOM 48 C5 XYL 3 4.854 -15.404 -5.899 0.00 0.00 C5
28 ---------------------------------------------------------------------
29 ATOM 74 H1 GLC 4 6.312 -20.297 -3.897 0.00 0.00 H1
30 ATOM 75 H2 GLC 4 4.081 -21.295 -1.991 0.00 0.00 H2
31 ATOM 76 H3 GLC 4 4.709 -22.175 -4.882 0.00 0.00 H3
32 ATOM 77 H4 GLC 4 2.240 -20.654 -3.830 0.00 0.00 H4
33 ATOM 78 H5 GLC 4 4.504 -19.584 -5.636 0.00 0.00 H5
34 ATOM 79 H6 GLC 4 1.833 -18.619 -5.118 0.00 0.00 H6
35 ATOM 80 H24 GLC 4 2.931 -17.520 -4.272 0.00 0.00 H24
36 ---------------------------------------------------------------------
37 ATOM 81 C1 GLC 5 1.057 -21.319 -5.860 0.00 0.00 C1
38 ATOM 82 C2 GLC 5 0.609 -21.564 -7.318 0.00 0.00 C2
39 ---------------------------------------------------------------------
40 ATOM 199 C1 GAL 11 5.825 -12.737 3.053 0.00 0.00 C1
41 ATOM 200 C2 GAL 11 4.966 -12.753 1.793 0.00 0.00 C2
42 ATOM 201 C3 GAL 11 3.486 -12.876 2.114 0.00 0.00 C3
43 ATOM 202 C4 GAL 11 3.243 -14.031 3.058 0.00 0.00 C4
44 ATOM 203 C5 GAL 11 4.137 -13.890 4.291 0.00 0.00 C5
45 ATOM 204 C6 GAL 11 4.003 -15.003 5.307 0.00 0.00 C6
46 ---------------------------------------------------------------------
47 ATOM 255 H5 XYL 13 19.537 -11.651 -0.139 0.00 0.00 H5
48 ATOM 256 H1 XYL 13 16.585 -11.560 -2.329 0.00 0.00 H1
49 ATOM 257 H2 XYL 13 18.338 -12.051 -3.974 0.00 0.00 H2
50 ATOM 258 H3 XYL 13 19.481 -13.841 -1.798 0.00 0.00 H3
51 ATOM 259 H4 XYL 13 20.596 -11.287 -3.032 0.00 0.00 H4
52 TER

Input File generated by POLYS (Starch Double Helical Structure)

pdbpolys1
1 ATOM 1 C1 GLC A 1 2.145 -3.715 3.129 1.00 0.00
2 ATOM 2 C2 GLC A 1 0.918 -4.595 2.908 1.00 0.00
3 ATOM 3 C3 GLC A 1 -0.334 -3.978 3.523 1.00 0.00
4 ATOM 4 C4 GLC A 1 -0.058 -3.703 4.999 1.00 0.00
5 ATOM 5 C5 GLC A 1 1.189 -2.828 5.142 1.00 0.00
6 ATOM 6 C6 GLC A 1 1.589 -2.597 6.600 1.00 0.00
7 ATOM 7 O1 GLC A 1 1.983 -2.496 2.397 1.00 0.00
8 ATOM 8 O2 GLC A 1 0.715 -4.752 1.496 1.00 0.00
9 ---------------------------------------------------------------------
10 ATOM 214 C1 GLC B 11 -3.715 2.145 1.564 1.00 0.00
11 ATOM 215 C2 GLC B 11 -3.093 3.520 1.344 1.00 0.00
12 ATOM 216 C3 GLC B 11 -1.699 3.613 1.959 1.00 0.00
13 ATOM 217 C4 GLC B 11 -1.801 3.236 3.434 1.00 0.00
14 ATOM 218 C5 GLC B 11 -2.444 1.855 3.577 1.00 0.00
15 ATOM 219 C6 GLC B 11 -2.675 1.455 5.035 1.00 0.00
16 ATOM 220 O1 GLC B 11 -2.965 1.171 0.832 1.00 0.00
17 ATOM 221 O2 GLC B 11 -2.995 3.758 -0.068 1.00 0.00
18 ATOM 222 O3 GLC B 11 -1.264 4.978 1.894 1.00 0.00

Sugar ring color code for monosaccharides

colcodmonos1
colcodmonos2

Color code for monosaccharides table

3 letter code Colour 3 letter code Colour
6DAL Pink LDM Green
6DTA Light Blue LYX Yellow
ABE Orange M5A Purple
ALL Purple M5C Light Blue
ALT Pink MAN Green
API Blue MUR Bown
ARA Green N5G Light Blue
BAC Blue NEU Brown
COL Light Blue OLI Blue
DDM Pink PAR Pink
DHA Orage PSI Pink
DIG Purple QUI Blue
FRU Green RHA Green
FUC Red RIB Pink
GAL Yellow SIA Purple
GLC Blue SOR Orange
GUL Orange TAL Light Blue
IDO Brown TYV Green
KDN Green XYL Orange
KDO Yellow - -
- - - -
3 letter code Colour 3 letter code Colour
BLU Blue PUR Purple
GRE Green LBL Light Blue
YEL Yellow BRO Brown
ORA Orange RED Red
PIN Pink GRE Grey

Examples

This section features screenshots of various representations available in UnityMol.

Particles mode

particlesex1 -halfwidth

Smooth HyperBalls mode

shballsex1 -halfwidth

Default Smooth HyperBalls mode

cpkex1 -halfwidth

CPK mode

licoriceex1 -halfwidth

Licorice

vdwex1 -halfwidth

VDW

Texture sets

cpktextureex1

CPK

acidbtextureex1

Acid-Basic

Other examples (Renderer Menu)

otherrenderex1
otherrenderex2
otherrenderex3

Coloration Mode

goodsellcolex1 -halfwidth

GoodSell

watcolex1 -halfwidth

WaterColor

basiccolex1 -halfwidth

Basic

iupaccolex1 -halfwidth

IUPAC

chaincolex1 -halfwidth

Chain

sugarcolex1 -halfwidth

Sugar

dnarnacolex1 -halfwidth

DNA/RNA

Secondary Structure Menu

Secondary Structure

ssex1

Ca-Trace

catraceex1 -halfwidth

B-factor

bfacex1 -halfwidth

Surface Mode

surfaceex1

Surface with static/mobile Cut

surfaceex2

Ring blending (with sugar coloration)

pchainsugex1

SugarRibbons

sugribex1

Special Effect

blureff1

BLUR

noiseeff1 -halfwidth

NOISE

blureff2 -halfwidth

BLUR2

edgeeff1 -halfwidth

EDGE

vortexeff1 -halfwidth

VORTEX

grayeff1 -halfwidth

GRAY

gloweff1 -halfwidth

GLOW

Miscellaneous

misc1 -wide

"Coarse grain" representation of six low energy conformations of LewisX trisaccharide and its interaction with a lectin.

misc2 -wide

Three modes of graphical representation of a complex plant polysaccharide, making use of some of the options offered by SweetUnityMol.