Molywood is there to make cool molecular movies for you.
Specifically, molywood
automatizes the most tedious steps in
generation of these movies, i.e. scripting in TCL, rendering, generating
overlays and combining frames, as well as merging frames into the final
movie.
We try to simplify the movie making syntax to supersede the existing TCL UserAni library, and add extended functionalities such as animating trajectory data with matplotlib, adding insets or making multi-panel movies.
The basic idea behind the functionalities of molywood
is best understood
through the examples hosted on ... More advanced users might want to
familiarize themselves with the general structure of the code
illustrated in script_structure.svg
.
Full functionality requires that python3
, VMD
, imagemagick
and
ffmpeg
be installed. The good news is that it can be done externally,
e.g. on a remote workstation, once you set up the visualization state
locally. Using the draft mode with render=f
(see below), you can also
preview your movie only with python3
and VMD
.
Note:
- It is recommended to use
python3
from the Anaconda distribution as it containsnumpy
andmatplotlib
as a pre-installed package. VMD
can be obtained athttps://www.ks.uiuc.edu/Research/vmd/
.imagemagick
is installed by default on most Linux distributions; run e.g.convert
to make sure it is available on your machine.ffmpeg
can be installed e.g. from the Ubuntu repository by typingsudo apt-get install ffmpeg
.
If any dependencies are missing on your machine (or on the workstation
you don't have root access to), you can also automatically
batch-download them by creating a local conda
environment.
To this end, run the following commands from your console:
conda env create -f environment.yml
source activate molywood
and then run source deactivate molywood
once you're done.
Sample movie scripts are available in the examples
directory: try
them first to see how the library works.
molywood
can be run from the console (e.g. in the examples/simple_movie
directory) as:
python ../../molywood/moly.py script.txt
In general, to run molywood
the following files are needed:
- either (a) a visualization state generated by VMD, or (b) a structure
file; (a) is the preferred way - user may define the representations
as well as set the camera angle as desired, and then go to File > Save
Visualization State); in option (b), a default representation is used,
and a compatible trajectory file can be provided. One can only provide
a four-character
pdb_code=...
, and the structure will be automatically downloaded from the PDB database. - a 'movie script', i.e. a simple text file containing directives, including a reference to the VMD visualization state (see examples and the explanations below).
- center_view (selection='...')
- add_label (label='...' atom_index=... [label_color=... text_size=... alias=...])
- add_distance (selection1='...' selection2='...' [label_color=... text_size=... alias=...])
- remove_label ([alias=... remove_all=n])
- remove_distance ([alias=... remove_all=n])
- fit_trajectory (selection='...' [axis=x/y/z/"v_x v_y v_z" t=...s])
- rotate (axis=x/y/z angle=... [sigmoid=t/f/sls t=...s])
- zoom_in/zoom_out (scale=... [sigmoid=t/f/sls t=...s])
- animate (frames=init_frame:final_frame t=...s [smooth=...])
- make_transparent/make_opaque (material=... t=...s [sigmoid=t/f/sls])
- show_figure (t=...s [figure=... datafile=... dataframes=init_frame:final_frame])
- do_nothing (t=...s)
- add_overlay (t=...s [figure=... datafile=... origin=0,0 text=... relative_size=1 dataframes=init_frame:final_frame aspect_ratio=... 2D=t/f] textsize=[24] sigmoid=[t/f])
- highlight (selection=... t=... [color=red mode=u/d/ud style=newcartoon/licorice/surf/quicksurf alias=...])
(Note that only finite-time actions can be combined using curly
brackets. Also, almost all finite-time actions (except for rotate
)
require the t=...s keyword. Above, square brackets denote optional
parameters. Values in bold font indicate defaults when parameters
are optional.)
- global ([fps=20 draft=t/f keepframes=t/f name=movie render=t/f])
- layout ([rows=1 columns=1])
- figure ([files=figure1.png,figure2.png,...])
- scene_identifier ([visualization=... structure=... trajectory=... pdb_code=... position=0,0 resolution=1000,1000])
(instead of scene_identifier, you should put the actual identifier
of the scene in question, e.g. scene_1
in the example below)
- A hash
#
marks the beginning of a scene input section, and should be followed by a single-word scene identifier, e.g.# scene_1
- Single actions have to be specified on a single line, starting with
a keyword and followed by any number of whitespace-separated
parameter=value
pairs (note: no spaces encircling the=
sign) - Multiple actions (e.g. rotation and zoom_in) can be performed
simultaneously if they are encircled in curly brackets and separated
with semicolons, e.g.
{rotate t=1s angle=50; zoom_in t=1s scale=2}
; they can also be split over several lines for convenience. Note that here, the secondt=1s
parameter specification will overwrite the first, so that time might as well only be specified once - A line starting with a
$
sign specifies global keywords, e.g.$ global fps=20
(see available global keywords above) - true/false values can be specified as
true/false
,yes/no
or in shorthand notation (t/f
,y/n
) - Comments can be introduced with an exclamation mark,
!
- External figures (e.g. ending credits) can be featured in the movies.
The external graphics file has to be specified as a parameter in the
show_figure
action (e.g.show_figure t=4s figure=picture.png
). - Note that it is the user who is responsible for setting correct resolutions for the individual scenes. By default, each scene is rendered in a resolution of 1000x1000; if e.g. a source figure isn't exactly rectangular, it will be scaled to fit in the rectangle, but its aspect ratio (shape) will not be affected.
- Multiple overlays (insets) can be added to each scene. The inset can
either be a static image (specified with the
figure
keyword inadd_overlay
), or a dynamically generated matplotlib plot (by specifying thedatafile
parameter inadd_overlay
). Currently 1D line plots (generated with plt.plot) and 2D histograms (generated with plt.hexbin) are supported; the former is default if adatafile
is supplied, and the latter can be requested with2D=t
. The relative coordinates of the origin (from0,0
to denote bottom left to1,1
to denote upper right corner), inset size relative to the background figure, and the aspect ratio (X to Y size) can all be specified independently to position the inset/overlay as desired. - When generating figures with matplotlib, axis labels can be specified
directly in the datafile by adding a
# x label; y label
(spaces and latex-compatible math notation are allowed). In addition, multiple matplotlib-compatiblekeyword=value
pairs can be enumerated after the!
character to modify plt.plot/plt.hexbin defaults, e.g.! bins='log' cmap='seismic'
, or plot properties, e.g.! xlim=-1,2 ylim=0,500
(no spaces around the=
sign).
center_view
is an instantaneous action that sets the geometric center ofselection
(VMD-compatible) as the new camera center to which zoom will converge; useful when zooming onto e.g. a reaction centeradd_label
instantaneously adds a text label anchored to an atom. specified withatom_index
, with the labeling text specified through thelabel
parameter; if desired, text size and color can be specified withlabel_color
andtext_size
.add_distance
instantaneously adds a distance label between the centers of geometry of two VMD-compatible selections, specified withselection1
andselection2
; as above, text size and color can be specified withlabel_color
andtext_size
.remove_label
instantaneously deletes a label specified throughalias=...
identical to analias
previously specified inadd_label
; alternatively,all=t
removes all existing labels. Note thatalias=...
andall=t
should be mutually exclusive: one either deletes a specific label or all of them.remove_distance
works identically toremove_label
, but affects labels added usingadd_distance
instead ofadd_label
.
rotate
rotates the scene byangle
degrees aboutaxis
in timet
.sigmoid=t
gives a smooth transition, whilesigmoid=f
gives a constant-velocity one; optionally,sigmoid=sls
performs a smooth- linear-smooth transition (preferable for e.g. multiple full rotations); whent
is not specified,rotate
will behave as an instantaneous action.fit_trajectory
uses RMSD-based fitting to instantaneously align a trajectory to the reference (first) frame, using theselection
to calculate the optimal alignment; whent
is specified, this alignment will be gradual instead of abrupt. Whenaxis=x/y/z/"x_comp y_comp z_comp"
is specified, the main principal axis ofselection
will be aligned to the chosen/defined axis.zoom_in
/zoom_out
scales the view by a factor ofscale
in timet
;sigmoid
works like forrotation
. Whent
is not specified, the zoom will be performed instantaneously.
animate
runs the trajectory frominit_frame
tofinal_frame
, adjusting the playback speed to the time specified witht
;smooth=X
sets the smoothing of all VMD representations to X.make_transparent
/make_opaque
change the opacity of a selectedmaterial
to make it fully transparent or fully opaque in timet
.sigmoid
works like forrotation
.show_figure
just shows an image instead of a VMD render during timet
; the image is specified usingfigure_index
in conjunction with the globally defined list of figure paths,$ figure files=...
.do_nothing
renders the VMD scene for timet
without doing anything else.add_overlay
allows to add an inset to the scene, with the position specified throughorigin
(0,0 corresponds to the bottom left corner, as in a regular Cartesian coordinate system), and size throughrelative_size
(1 means fit into the whole scene, 0.1 means fit into a rectangle 10% of the scene size).- The content of the overlay can be an external figure (specified
through
figure_index
), an on-the-fly generated matplotlib line plot (based on a data file speficied with thedatafile
parameter) or plain text. - If
datafile=...
is specified, a dot will dynamically follow the values on the plot. By default, the script will try to useframes
from the accompanyinganimate
action to select datapoint indices from thedatafile
. To independently select datapoint indices for the 1D plot (e.g. when thedatafile
has much more entries than the trajectory used inanimate
, one can supplydatafile=...
withdataframes=...
- it will take precendence overanimate
'sframes
. - If the data file starts with a single line formatted as
# x axis label; y axis label
,x axis label
andy axis label
will be used to label the corresponding axes of the plot. - If
text="sample text
is used, the text will be displayed at a position specified withorigin
. - Mulitple overlays can be added to a scene simultaneously; adding
many
add_overlay
commands separated by semicolons and encircled in curly brackets works just as any other multiple action (seeNotes on input formatting
above).
- The content of the overlay can be an external figure (specified
through
highlight
creates a new representation to highlight a subset of the system selected by specifying theselection
parameter. Color can be chosen withcolor
, using either simple color names (black, red, blue, orange, yellow, green and white), VMD-compatible ColorIDs (0-32) or a coloring scheme keyword (name, type, element, structure etc.). Similarly,style
can be set to newcartoon, licorice, surf, quicksurf, vdw or tube (non-case sensitive).- By default, highlight appears (fades in from transparency) and
disappears smoothly over the course of the action. If you want your
highlight to stay visible, use
mode=u
(up) to make it appear only. - To turn off a previously created highlight (possibly after several
intervening actions), use
mode=d
(down) along withalias=...
identical to a previously setalias
of the highlight to be turned off; you only need to provide an alias to a highlight if you first turn it on and want to turn off later.
- By default, highlight appears (fades in from transparency) and
disappears smoothly over the course of the action. If you want your
highlight to stay visible, use
- VMD labels are always rendered using the
Opaque
material, so that making this material transparent (make_transparent material=Opaque
) will make the labels disappear as well; the straightforward solution is to use a different material, or generate a copy. (VMD Main > Graphics > Materials > Create New
) - Also, the labels are rendered with a slightly different size and
appearance with the Snapshot (
draft=t
) and Tachyon (draft=f
) renderers. fit_trajectory
combined withaxis
can become slow if combined with largeselection
(in terms of number of atoms) andanimation
with largesmooth=...
values; it is suggested to only use backbones for alignment to principal axes, as the repeated calculation of tensors of inertia can be time-consuming in VMD.- With the default
ffmpeg
settings, choppy video playback has been reported when VLC is being run on OSX; this is solely a video player issue.