cogli2

cogli2 is a simple tool for the visualisation of configurations of coarse-grained systems. It has its own format for input files (*.mgl), but it also natively supports oxDNA configurations. It can be extended to support additional custom input types. Figures can be generated either by directly writing the current view to a png file or by exporting a povray file that can be then raytraced.

Table of Contents

• Building the executable
  • Requirements
  • Compilation
  • CMake options
• Usage
• File formats
  • The mgl format
  • The visibility file
  • Setting custom colors
• Actions

Building the executable

Requirements

• xorg-dev
• libgl1-mesa-dev
• cmake >= 3.1
• make
• A c++11-compliant compiler (tested with g++ >= 5.4)
• Optionally, some information is drawn on the screen if the FreeType library is installed (libfreetype6-dev)

Compilation

Extract the cogli2 archive (or download the nightly build via svn) and compile it with the following commands:

cd cogli2       # enter the cogli2 folder
mkdir build     # create a new build folder. It is good practice to compile out-of-source
cd build
cmake ..        # here you can specify additional options, see next section
make -j4        # compile the code. The -jX make option makes it compile the code in parallel by using X threads.

At the end of the compilation the final executable (cogli2) will be placed in the build/bin folder.

CMake options

Here is a list of options that can be passed to cmake during the pre-compilation stage:

• -DDebug=ON Compiles with debug symbols and without optimisation flags
• -DG=ON Compiles with debug symbols + optimisation flags
• -DLR_TETRA=ON Enable a particular color scheme for DNA configurations.
• -DNOPNG=ON Forces cmake to not compile against libpng even if it is found. It is sometimes necessary on Mac OS X systems.

Usage

USAGE: cogli2 [options] input_1 input_2 ...

Options:
  --help, -h
          Print usage and exit
  --dim widthxheight
          Set the initial window dimensions (defaults to 1024x768)
  --bring-in-box, -b
          Bring particles back into the box
  --debug, -d
          Debug mode. All primitives are rendered as wireframes
  --topology, -t <topology_file>
          Topology file required to open oxDNA configurations
  --visibility, -i <visibility_file>
          Visibility file containing a list of particles that should not appear
in the box
  --load, -l file
          Load a cogli1 state file
  --shift-every, -s value
          Group particles so that periodic boundary conditions are applied only
to the centres of mass of the group
  --ribbons
          Export DNA strands as ribbons in povray format
  --kern-frenkel, -k
          Export patches on patchy particles as truncated cones in povray format
  --only-pov, -o
          Generate povray output and exit
  --com-centre, -v
          Centre the first configuration's centre of mass
  --always-centre [<index>]
          Configurations are centred each time they are visualised with respect
to their centre of mass (if no arguments are given) or to a specific
particle/strand (if the <index> argument is given)
  --inertia, -I
          When centred, configurations are rotated so that their principal axes
of inertia are aligned along x, y and z
  --mm-grooving, -m
          Set major/minor grooving for DNA configurations
  --rna
          Assume RNA strands
  --starr[=2]
          Assume Starr configurations. The optional parameter changes the size
of the dimer cores when visualizing vitrimer configurations
  --manfredo
          Used for displaying coarse-grained tetramer configurations. Requires a
topology file
  --ico
               Used for displaying icosahedra. Requires a topology file
  --nathan, -n <size_ratio>
          Used for displaying Nathan-related configurations. Requires a topology
file. Expects a numerical value indicating the colloid-to-polymer size ratio
  --patchy, -p <delta,cosmax,N_A[,N_B]>
          Assumes a patchy configuration, as generated by oxDNA. Requires a
topology file. Expects a comma-separated list of parameters (radial and angular
widths, number of patches on species A and, optionally, of species B)
  --patchy-swap <delta,cosmax>
          Assumes a patchy swap configuration, as generated by oxDNA. Requires a
topology file. Expects a comma-separated list of parameters (radial and angular
widths)
  --outlines, -u
          Draw outlines around objects. It does not work for every object
  --resolution, -r <initial_resolution>
          Set the initial resolution of the objects. The default is 15
  --confs-to-skip, -c <skip_n_confs>
          Number of configurations that should be skipped every time the user
chooses to change the current configuration by using '+' or '-'
  --colors-from=<file>
          Files to load the colors from
  --groups-from=<file>
          Files to load the groups from
  --rbc
          Assume an RBC file
  --box=<Lx,Ly,Lz>
          Set the lengths of the box sides, overriding the values found in the
input files
  --levy
          Assume Levy configurations (requires a topology file)
  --tep
          Assume TEP configurations (requires a topology file)
  --tep_t
          Threshold for the colouring of TEP beads (defaults to 0.98)
  --opacity
          If given, the particles indicated in the visibility file will not be
hidden but assigned the value of opacity provided
  --bcab
          Give DNA bases the same color as their respective backbones (bcab ==
Base Color As Backbone)
  --drums
          Color-code DNA bases depending on chemical identity, according to the
DRuMS color scheme: adenine is blue, guanine is green, cytosine is red, thymine
is yellow, uracil is orange.
  --drums-full
          Color-code DNA nucleotides (both backbone and base) depending on
chemical identity, according to the DRuMS color scheme: adenine is blue, guanine
is green, cytosine is red, thymine is yellow, uracil is orange.
  --actions-from, -a <action_file>
          A file containing the list of actions that will be performed on the
single configurations. Each action will effectively become a new configuration.
'+' and '-' can be used to navigate back and forth through actions
  --ashell, -A
          Assume ashell configurations (requires a topology file)
  --povray-shadows
          Let povray-generated objects cast shadows
  --no-box
          Hide the box
  --end-handling, -e <keyword>
          Set how the appearance of the strand direction (5' -> 3') of DNA and
RNA strands is handled. The supported keywords are 'normal' (default, no change
in appearance), 'size' (the 5' end backbone is bigger, the 3' end backbone is
smaller) and 'opacity' (the opacity of the strand decreases 5' -> 3')
  --version
          Print the version and exit

Keyboard and Mouse Bindings:
  +                    show the next configuration
  -                    show the previous configuration
  F1, ..., F8          toggle light number 1, ..., 8
  P                    print povray output. Redirect to the file given by the --output option or to an automatically generated name
  ctrl+p               export the current view in PNG format
  a(A)                 increase (decrease) ambient light
  b                    hide/show the box
  c                    load the initial (or stored) camera state
  C                    save the current camera state
  d(D)                 increase (decrease) diffusive light
  e                    cycle through the ways DNA and RNA strand ends are handled (see the '--end-handling, -e' option)
  f(F)                 increase (decrease) the field of view
  h                    hide selected particles
  i                    show/hide printing of the fps counter and other useful debug information
  k                    show/hide the axes (3 arrows: red -> x axis, green -> y axis, blue -> z axis)
  l                    show/hide labels
  number               select particles in the number-th control group
  p                    change the projection from perspective to orthographic (and viceversa)
  page down            decrease the level of detail of the objects
  page up              increase the level of detail of the objects
  s                    show all the particles  x(X), y(Y), z(Z)     move all the particles in the x, y, or z positive (negative) direction
  ctrl+x(X), ctrl+y(Y) rotate the scene counterclockwise (clockwise) with respect to the vertical or horizontal axis
  u                    dump the cogli1 state to a .cpy file that can be loaded back in cogli1 by using the --load command option
  q(Q)                 zoom in (out) (pressing Ctrl at the same time increases zoom speed by a factor 5)
  v                    centre the configuration's centre of mass
  ctrl+w               select all particles
  ctrl+shift+w         invert selection
  ctrl+number          save selected particles in the number-th control group
  ctrl+click           select the particle below the cursor
  shift+click          print the id of the particle below the cursor
  x(X)                 move particles towards positive (negative) x
  y(Y)                 move particles towards positive (negative) y
  z(Z)                 move particles towards positive (negative) z

File formats

The mgl format

For historical reasons cogli2 files have a '.mgl' extension. The format of mgl files is very simple. The first line can be optionally used to specify the box dimensions:

.Box:Lx,Ly,Lz

where Lx, Ly, and Lz are the lengths of the sides of the simulation box. If the box is cubic cogli2 also supports the syntax

.Vol:TOT_VOLUME

where TOT_VOLUME is the volume of the cubic simulation box, and hence interpreted as Lx*Ly*Lz. If no header line is found, the dimensions of the bounding box of the configuration are used. Note that if the bounding box is too small (more specifically, is the length of its diagonal is smaller than unity), a default box of (5, 5, 5) is used instead.

After the header, each line is interpreted as an object. Currently, cogli2's mgl parser supports

• spheres
• cylinders
• dipolar spheres (i.e. spheres with an embedded dipole moment represented as an arrow)
• patchy particles
• icosahedra
• ellipsoids
• groups of shapes

The base syntax (used for spheres), is the following:

x y z @ r C[color]

where x, y and z give the position of the particle's centre of mass, r is the radius and color can be specified as a default color (red, blue, green, yellow, black, white, grey, cyan, magenta, orange, violet, brown or pink) or with exadecimal (e.g. #aaaaaa) or rgba (e.g. 0,1,0,1, the last digit controls the opacity) notations.

The syntax for cylinders is the following:

x y z @ r C[color] C ax ay az

where ax, ay and az specify the axis. The length of the axis is given by sqrt(ax^2 + ay^2 + az^2).

Dipolar spheres have the following syntax:

x y z @ r C[color] D dx dy dz C[arrow_color]

where dx, dy and dz is the dipole moment. arrow_color can be specified in exactly the same way as the particle color. Note that the particle color should be at least partially transparent. If not explicitly specified, the opacity of the particle will be automatically set at 0.5.

Patchy particles are rendered as spheres with Kern-Frenkel like patches. The syntax is

x y z @ r C[color] M p1x p1y p1z p1w C[p1color] p2x p2y p2z p2w C[p2color] ...

where p1x, p1y and p1z specify the orientation and length of the first patch, p1w is the half width of the patch expressed in radians and p1color is its color. Note that you can add as many patches as you want.

Icosahedra can be drawn with:

x y z @ r C[color] I x1 x2 x3 z1 z2 z3

where x1 x2 x3 and z1 z2 z3 identifies the x and z axes of the icosahedron.

Finally, ellipsoids can be drawn with:

x y z @ r C[color] E sa1 sa2 sa3 a11 a12 a13 a21 a22 a23

where sa1 sa2 sa3 are the length of the ellipsoid semiaxes and aij is the j-th component of the i-th axis.

An example with particles of different types is:

.Box:8,8,8
1 3 5 @ 0.8 C[red]
7 3 5 @ 0.5 C[green] C 2 2 2
5 7 5 @ 0.3 C[0,0,1,0.5] D 1 0 0 C[black]
3 5 5 @ 0.5 C[magenta] M 0 0 0.6 0.8 C[0,0,0.5] 0.3 0.5 0 0.55 C[1,0.5,0.3]

Different shapes can be grouped together and assigned the same id by joining lines specifying the different shapes using G as a separator. For instance, the following line defines a group of three spheres:

1 1 1 @ 0.8 C[red] G 1 2 1 @ 0.8 C[blue] G 1 3 1 @ 0.8 C[green]

Group of shapes behave as single shapes when they are selected/deselected (ctrl + mouse click), picked (shift + mouse click) or moved.

The visibility file

The visibility file, specified with the --visibility command line option, controls the appearance of the shapes rendered by cogli2. By default all shapes are visible. This behaviour can be altered by setting default:hide in the first line of the visibility line. All other lines will specify the visibility status of the shapes. Each line should contain a comma-separated list. Each element of the list should either be an integer or two integers separated by a dash, which specifies an interval of integers (with both endpoints included). Optionally, each line can be prepended with either hide: or show:. Lines are processed one after the other, meaning that settings from previous lines can be overwritten by subsequence lines. Here is an example of a visibility file that hides all shapes but those with indexes from 1 to 100, with shapes 5 and 8 excluded:

default:hide
show:1-100
hide:5,8

Setting custom colors

Nota Bene: this method is compatible with DNA and RNA configurations only.

Custom colors for nucleotides can be set by passing a file to the --colors-from switch. Each line of the color file should contain two columns: a comma-separated list of integers and a color. The syntax for the comma-separated list is the one explained above for the visibility file. A color can be specified in three ways: either with a string (supported colors: red, green, blue, yellow, cyan, magenta, orange, violet, brown, pink, black, white, grey) or with the RGB format as a comma-separated list of values. Both 0-1 or 0-255 ranges are supported. Here is an example of a color file that will color red the first 10 nucleotides and blue nucleotides with indexes ranging from 40 to 50:

0-9 red
40-50 0,0,1

Actions

The --actions-from, -a option requires a file that specifies operations to be performed on each configuration passed as input. These operations (called actions) add frames (which behave similarly to additional configurations) to the cogli2 scenes. These actions make it easier to create movies out of configurations. They are best used in conjunction with the -o option, which makes cogli2 print out a povray file for each scene, and hence action, without firing up the graphic interface.

An action file is composed by lines, each of which specifies a change to a scene. For example, a line might tell cogli2 to use 10 frames perform a rotation the configuration for 30 degrees around the y axis.

Rotations

Rotations of the camera can be performed with the following syntax:

r x y z tot_angle n_frames

Where x y z specify the rotation axis, tot_angle is the total angle one wishes to rotate the configuration for, and n_frames is the number of frames that will be used to perform the whole rotation. The rotation is performed by keeping fixed the point the camera is looking at.

Translations

Translations of the camera can be performed with the following syntax:

t x y z tot_extent n_frames

Similarly to rotations, translations are performed along a direction, specified by x y z, and for an overall displacement given by tot_extent. n_frames sets the number of frames that will be employed.

Spins

The camera can be made spin on itself by using the same syntax of rotations. Only the initial letter, which specifies the action type, changes from r to s, viz:

s x y z tot_angle n_frames

Visibility

Single particles can be hidden or shown by using the following syntax:

visibility [command] [particle_ids]

where [command] should be either hide or show and [particle_ids] specify the particles that will be acted upon with the same syntax used for the visibility file.

An example of a valid visibility line would be

visibility hide 1-10,20-30

which would hide particles with the specified ids.

Actions example

# first we translate for 5 frames
t 0 0 -1 2 5
# and then we rotate for 10 more frames
r 0 1 0 180 10

The first line tells cogli2 to use 5 frames to translate the camera towards the screen, while the second one produces a rotation along y of 180° using 10 frames. Copy the two lines in the actions.dat file and pass it to cogli2 (cogli2 -a actions.dat myconf.mgl) to see it in action.

Known issues

• In order to handle transparencies, shapes are drawn from back to front on a shape-type basis. In other words, transparent spheres will be always rendered correctly, whereas a transparent cylinder and a transparent sphere will not always be rendered in the correct order, so that one of the two may not be let light pass through when rendered from some specific direction. In general, spheres are rendered last, since these are the most common shapes.

Dependencies & Acknowledgements

cogli2 depends on a minimum number of external libraries. In particular, to compile it you will need the opengl libraries, cmake, make and a c++ compiler. On Debian-based systems, these can be installed by installing the xorg-dev, libgl1-mesa-dev, cmake, make and g++ packages. Optionally, if cmake finds libpng it will enable cogli2 to export directly in png format.

Internally, cogli2 uses the following libraries/utilities, which are included in the source tree:

• glfw
• glad
• glm
• BSpline
• CMakeRC
• glText

As far as I know, this is compatible with their licenses. If you are a developer or a mantainer of one of these projects and you think that cogli2 does not comply with your license, please contact us.

The development of this software has been partially supported by the European Commission through the Marie Skłodowska−Curie Fellowship No. 702298-DELTAS.