lammps/doc/dump_image.txt

"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)

:line

dump image command :h3

[Syntax:]

dump ID group-ID image N file color diameter keyword value ... :pre

ID = user-assigned name for the dump :ulb,l
group-ID = ID of the group of atoms to be imaged :l
image = style of dump command (other styles {atom} or {cfg} or {dcd} or {xtc} or {xyz} or {local} or {custom} are discussed on the "dump"_dump.html doc page) :l
N = dump every this many timesteps :l
file = name of file to write image to :l
color = atom attribute that determines color of each atom :l
diameter = atom attribute that determines size of each atom :l
zero or more keyword/value pairs may be appended :l
keyword = {adiam} or {atom} or {bond} or {size} or {view} or {center} or {up} or {zoom} or {persp} or {box} or {axes} or {shiny} or {ssao} :l
  {adiam} value = number = numeric value for atom diameter (distance units)
  {atom} = yes/no = do or do not draw atoms
  {bond} values = color width = color and width of bonds
    color = {atom} or {type} or {none}
    width = number or {atom} or {type} or {none}
      number = numeric value for bond width (distance units)
  {size} values = width height = size of images
    width = width of image in # of pixels
    height = height of image in # of pixels
  {view} values = theta phi = view of simulation box
    theta = view angle from +z axis (degrees)
    phi = azimuthal view angle (degrees)
    theta or phi can be a variable (see below)
  {center} values = flag Cx Cy Cz = center point of image
    flag = "s" for static, "d" for dynamic
    Cx,Cy,Cz = center point of image as fraction of box dimension (0.5 = center of box)
    Cx,Cy,Cz can be variables (see below)
  {up} values = Ux Uy Uz = direction that is "up" in image
    Ux,Uy,Uz = components of up vector
    Ux,Uy,Uz can be variables (see below)
  {zoom} value = zfactor = size that simulation box appears in image
    zfactor = scale image size by factor > 1 to enlarge, factor < 1 to shrink
    zfactor can be a variable (see below)
  {persp} value = pfactor = amount of "perspective" in image
    pfactor = amount of perspective (0 = none, < 1 = some, > 1 = highly skewed)
    pfactor can be a variable (see below)
  {box} values = yes/no diam = draw outline of simulation box
    yes/no = do or do not draw simulation box lines
    diam = diameter of box lines as fraction of shortest box length
  {axes} values = yes/no length diam = draw xyz axes
    yes/no = do or do not draw xyz axes lines next to simulation box
    length = length of axes lines as fraction of respective box lengths
    diam = diameter of axes lines as fraction of shortest box length
  {shiny} value = sfactor = shinyness of spheres and cylinders
    sfactor = shinyness of spheres and cylinders from 0.0 to 1.0
  {ssao} value = yes/no seed dfactor = SSAO depth shading
    yes/no = turn depth shading on/off
    seed = random # seed (positive integer)
    dfactor = strength of shading from 0.0 to 1.0 :pre
:ule

[Examples:]

dump myDump all image 100 dump.*.jpg type type :pre

[Description:]

Dump a high-quality ray-traced image of the atom configuration every N
timesteps as either a JPG or PPM file.  A series of such images can
easily be converted into an animated movie of your simulation; see
further details below.  Other dump styles store snapshots of numerical
data asociated with atoms in various formats, as discussed on the
"dump"_dump.html doc page.

Here are two sample images, rendered as 1024x1024 JPG files.  Click to
see the full-size images:

<DIV ALIGN=center>

:image(JPG/dump1_small.jpg,JPG/dump1.jpg)
:image(JPG/dump2_small.jpg,JPG/dump2.jpg)

</DIV>

Only atoms in the specified group are rendered in the image.  The
"dump_modify region and thresh"_dump_modify.html commands can also
alter what atoms are included in the image.

The filename suffix determines whether a JPG or PPM file is created.
If the suffix is ".jpg" or ".jpeg", then a JPG file is created, else a
PPM file is created, which is a text-based format.  To write out JPG
files, you must build LAMMPS with a JPEG library.  See "this
section"_Section_start.html#start_2_4 of the manual for instructions
on how to do this.

IMPORTANT NOTE: Because periodic boundary conditions are enforced only
on timesteps when neighbor lists are rebuilt, the coordinates of an
atom in the image may be slightly outside the simulation box.

:line

Dumps are performed on timesteps that are a multiple of N (including
timestep 0) and on the last timestep of a minimization if the
minimization converges.  Note that this means a dump will not be
performed on the initial timestep after the dump command is invoked,
if the current timestep is not a multiple of N.  This behavior can be
changed via the "dump_modify first"_dump_modify.html command, which
can be useful if the dump command is invoked after a minimization
ended on an arbitrary timestep.  N can be changed between runs by
using the "dump_modify every"_dump_modify.html command.

Dump image filenames must contain a wildcard character "*", so that
one image file per snapshot is written.  The "*" character is replaced
with the timestep value.  For example, tmp.dump.*.jpg becomes
tmp.dump.0.jpg, tmp.dump.10000.jpg, tmp.dump.20000.jpg, etc.  Note
that the "dump_modify pad"_dump_modify.html command can be used to
insure all timestep numbers are the same length (e.g. 00010), which
can make it easier to convert a series of images into a movie in the
correct ordering.

:line

The {color} and {diameter} settings determine the color and size of
atoms rendered in the image.  They can be any atom attribute defined
for the "dump custom"_dump.html command, including {type} and
{element}.  This includes per-atom quantities calculated by a
"compute"_compute.html, "fix"_fix.html, or "variable"_variable.html,
which are prefixed by "c_", "f_", or "v_" respectively.  Note that the
{diameter} setting can be overridden with a numeric value by the
optional {adiam} keyword, in which case you can specify the {diameter}
setting with any valid atom attribute.

If {type} is specified for the {color} setting, then the color of each
atom is determined by its atom type.  By default the mapping of types
to colors is as follows:

type 1 = red
type 2 = green
type 3 = blue
type 4 = yellow
type 5 = aqua
type 6 = cyan :ul

and repeats itself for types > 6.  This mapping can be changed by the
"dump_modify acolor"_dump_modify.html command.

If {type} is specified for the {diameter} setting then the diameter of
each atom is determined by its atom type.  By default all types have
diameter 1.0.  This mapping can be changed by the "dump_modify
adiam"_dump_modify.html command.

If {element} is specified for the {color} and/or {diameter} setting,
then the color and/or diameter of each atom is determined by which
element it is, which in turn is specified by the element-to-type
mapping specified by the "dump_modify element" command.  By default
every atom type is C (carbon).  Every element has a color and diameter
associated with it, which is the same as the colors and sizes used by
the "AtomEye"_atomeye visualization package.

:link(atomeye,http://mt.seas.upenn.edu/Archive/Graphics/A)

If other atom attributes are used for the {color} or {diameter}
settings, they are interpreted in the following way.

If "vx", for example, is used as the {color} setting, then the color
of the atom will depend on the x-component of its velocity.  The
association of a per-atom value with a specific color is determined by
a "color map", which can be specified via the
"dump_modify"_dump_modify.html command.  The basic idea is that the
atom-attribute will be within a range of values, and every value
within the range is mapped to a specific color.  Depending on how the
color map is defined, that mapping can take place via interpolation so
that a value of -3.2 is halfway between "red" and "blue", or
discretely so that the value of -3.2 is "orange".

If "vx", for example, is used as the {diameter} setting, then the atom
will be rendered using the x-component of its velocity as the
diameter.  If the per-atom value <= 0.0, them the atom will not be
drawn.  Note that finite-size spherical particles, as defined by
"atom_style sphere"_atom_style.html define a per-particle radius or
diameter, which can be used as the {diameter} setting.

:line

The various kewords listed above control how the image is rendered.
As listed below, all of the keywords have defaults, most of which you
will likely not need to change.  The "dump modify"_dump_modify.html
also has options specific to the dump image style, particularly for
assigning colors to atoms, bonds, and other image features.

:line

The {adiam} keyword allows you to override the {diameter} setting to a
per-atom attribute with a specified numeric value.  All atoms will be
drawn with that diameter, e.g. 1.5, which is in whatever distance
"units"_units.html the input script defines, e.g. Angstroms.

The {atom} keyword allow you to turn off the drawing of all atoms,
if the specified value is {no}.

The {bond} keyword allows to you to alter how bonds are drawn.  A bond
is only drawn if both atoms in the bond are being drawn due to being
in the specified group and due to other selection criteria
(e.g. region, threshhold settings of the
"dump_modify"_dump_modify.html command).  By default, bonds are drawn
if they are defined in the input data file as read by the
"read_data"_read_data.html command.  Using {none} for both the bond
{color} and {width} value will turn off the drawing of all bonds.

If {atom} is specified for the bond {color} value, then each bond is
drawn in 2 halves, with the color of each half being the color of the
atom at that end of the bond.

If {type} is specified for the {color} value, then the color of each
bond is determined by its bond type.  By default the mapping of bond
types to colors is as follows:

type 1 = red
type 2 = green
type 3 = blue
type 4 = yellow
type 5 = aqua
type 6 = cyan :ul

and repeats itself for bond types > 6.  This mapping can be changed by
the "dump_modify bcolor"_dump_modify.html command.

The bond {width} value can be a numeric value or {atom} or {type} (or
{none} as indicated above).

If a numeric value is specified, then all bonds will be drawn as
cylinders with that diameter, e.g. 1.0, which is in whatever distance
"units"_units.html the input script defines, e.g. Angstroms.

If {atom} is specified for the {width} value, then each bond
will be drawn with a width corresponding to the minimum diameter
of the 2 atoms in the bond.

If {type} is specified for the {width} value then the diameter of each
bond is determined by its bond type.  By default all types have
diameter 0.5.  This mapping can be changed by the "dump_modify
bdiam"_dump_modify.html command.

:line

The {size} keyword sets the width and height of the created images,
i.e. the number of pixels in each direction.

:line

The {view}, {center}, {up}, {zoom}, and {persp} values determine how
3d simulation space is mapped to the 2d plane of the image.  Basically
they control how the simulation box appears in the image.

All of the {view}, {center}, {up}, {zoom}, and {persp} values can be
specified as numeric quantities, whose meaning is explained below.
Any of them can also be specified as an "equal-style
variable"_variable.html, by using v_name as the value, where "name" is
the variable name.  In this case the variable will be evaluated on the
timestep each image is created to create a new value.  If the
equal-style variable is time-dependent, this is a means of changing
the way the simulation box appears from image to image, effectively
doing a pan or fly-by view of your simulation.

The {view} keyword determines the viewpoint from which the simulation
box is viewed, looking towards the {center} point.  The {theta} value
is the vertical angle from the +z axis, and must be an angle from 0 to
180 degrees.  The {phi} value is an azimuthal angle around the z axis
and can be positive or negative.  A value of 0.0 is a view along the
+x axis, towards the {center} point.  If {theta} or {phi} are
specified via variables, then the variable values should be in
degrees.

The {center} keyword determines the point in simulation space that
will be at the center of the image.  {Cx}, {Cy}, and {Cz} are
speficied as fractions of the box dimensions, so that (0.5,0.5,0.5) is
the center of the simulation box.  These values do not have to be
between 0.0 and 1.0, if you want the simulation box to be offset from
the center of the image.  Note, however, that if you choose strange
values for {Cx}, {Cy}, or {Cz} you may get a blank image.  Internally,
{Cx}, {Cy}, and {Cz} are converted into a point in simulation space.
If {flag} is set to "s" for static, then this conversion is done once,
at the time the dump command is issued.  If {flag} is set to "d" for
dynamic then the conversion is performed every time a new image is
created.  If the box size or shape is changing, this will adjust the
center point in simulation space.

The {up} keyword determines what direction in simulation space will be
"up" in the image.  Internally it is stored as a vector that is in the
plane perpendicular to the view vector implied by the {theta} and
{pni} values, and which is also in the plane defined by the view
vector and user-specified up vector.  Thus this internal vector is
computed from the user-specified {up} vector as

up_internal = view cross (up cross view) :pre

This means the only restriction on the specified {up} vector is that
it cannot be parallel to the {view} vector, implied by the {theta} and
{phi} values.

The {zoom} keyword scales the size of the simulation box as it appears
in the image.  The default {zfactor} value of 1 should display an
image mostly filled by the atoms in the simulation box.  A {zfactor} >
1 will make the simulation box larger; a {zfactor} < 1 will make it
smaller.  {Zfactor} must be a value > 0.0.

The {persp} keyword determines how much depth perspective is present
in the image.  Depth perspective makes lines that are parallel in
simulation space appear non-parallel in the image.  A {pfactor} value
of 0.0 means that parallel lines will meet at infininty (1.0/pfactor),
which is an orthographic rendering with no persepctive.  A {pfactor}
value between 0.0 and 1.0 will introduce more perspective.  A {pfactor}
value > 1 will create a highly skewed image with a large amount of
perspective.

IMPORTANT NOTE: The {persp} keyword is not yet supported as an option.

:line

The {box} keyword determines how the simulation box boundaries are
rendered as thin cylinders in the image.  If {no} is set, then the box
boundaries are not drawn and the {diam} setting is ignored.  If {yes}
is set, the 12 edges of the box are drawn, with a diameter that is a
fraction of the shortest box length in x,y,z (for 3d) or x,y (for 2d).
The color of the box boundaries can be set with the "dump_modify
boxcolor"_dump_modify.html command.

The {axes} keyword determines how the coordinate axes are rendered as
thin cylinders in the image.  If {no} is set, then the axes are not
drawn and the {length} and {diam} settings are ignored.  If {yes} is
set, 3 thin cylinders are drawn to represent the x,y,z axes in colors
red,green,blue.  The origin of these cylinders will be offset from the
lower left corner of the box by 10%.  The {length} setting determines
how long the cylinders will be as a fraction of the respective box
lengths.  The {diam} setting determines their thickness as a fraction
of the shortest box length in x,y,z (for 3d) or x,y (for 2d).

:line

The {shiny} keyword determines how shiny the objects rendered in the
image will appear.  The {sfactor} value must be a value 0.0 <=
{sfactor} <= 1.0, where {sfactor} = 1 is a highly reflective surface
and {sfactor} = 0 is a rough non-shiny surface.

The {ssao} keyword turns on/off a screen space ambient occlusion
(SSAO) model for depth shading.  If {yes} is set, then atoms further
away from the viewer are darkened via a randomized process, which is
perceived as depth.  The calculation of this effect can increase the
cost of computing the image by roughly 2x.  The strength of the effect
can be scaled by the {dfactor} parameter.  If {no} is set, no depth
shading is performed.

:line

A series of JPG or PPM images can be converted into a movie file and
then played as a movie using commonly available tools.

Convert JPG or PPM files into an animated GIF or MPEG or other movie
file:

a) Use the ImageMagick convert program. :ulb,l

% convert *.jpg foo.gif
% convert *.ppm foo.mpg :pre

b) Use QuickTime. :l

Select "Open Image Sequence" under the File menu
Load the images into QuickTime to animate them
Select "Export" under the File menu
Save the movie as a QuickTime movie (*.mov) or in another format

c) Windows-based tool. :ule,l

If someone tells us how to do this via a common Windows-based tool,
we'll post the instructions here.

Play the movie:

a) Use your browser to view an animated GIF movie. :ulb,l

Select "Open File" under the File menu
Load the animated GIF file

b) Use the freely available mplayer tool to view an MPEG movie. :l

% mplayer foo.mpg :pre

c) Use the "Pizza.py"_http://www.sandia.gov/~sjplimp/pizza.html
"animate tool"_http://www.sandia.gov/~sjplimp/pizza/doc/animate.html,
which works directly on a series of image files. :l

a = animate("foo*.jpg") :pre

d) QuickTime and other Windows-based media players can
obviously play movie files directly. :ule,l

:line

See "this section"_Section_modify.html of the manual for information
on how to add new compute and fix styles to LAMMPS to calculate
per-atom quantities which could then be output into dump files.

:line

[Restrictions:]

To write JPG images, you must use a -DLAMMPS_JPEG switch when building
LAMMPS and link with a JPEG library.  See the "Making
LAMMPS"_Section_start.html#start_2_4 section of the documentation for
details.

[Related commands:]

"dump"_dump.html, "dump_modify"_dump_modify.html, "undump"_undump.html

[Default:]

The defaults for the keywords are as follows:

adiam = not specified (use diameter setting)
atom = yes
bond = none none (if no bonds in system)
bond = atom 0.5 (if bonds in system)
size = 512 512
view = 60 30 (for 3d)
view = 0 0 (for 2d)
center = s 0.5 0.5 0.5
up = 0 0 1 (for 3d)
up = 0 1 0 (for 2d)
zoom = 1.0
persp = 0.0
box = yes 0.02
axes = no 0.0 0.0
shiny = 1.0
ssao = no :ul