Introduction

We should have a uniform interface to RasMol, VMD, PyMOL, VTK, ...

>>> from ASE.Visualization.RasMol import RasMol
>>> plot = RasMol(water)
>>> plot.Update()

Some visualization tools can only plot atoms, eventually coloring them according to some data. Others can also visualize other kind of data such as wavefunctions.

Gnuplot 2D plots (mainly for plotting graphs)

ASE defines a interface to the Gnuplot program. You can use this as shown below:

>>> from ASE.Visualization.gnuplot import gnuplot
>>> data = [1,2,3,4,5]
>>> plot = gnuplot(data)

You can add titles, labels and legends to the plot and set the plotstyle. This is done by adding attributes to the data. One can not add attributes directly to a python list as used in the example above, so in this case a user defined class derived from the python class list must be used. Such a class is defined in the ASE.Utilities.List module.

The example below illustrates how to add titles etc to the plot. The example also shows how to combine plot together, using the parent keyword , in the construction of the plot. If a parent is given the plot will not open a window of its own, but will be added to the parent's window:

>>> from ASE.Utilities.List import List
>>> data1 = List([1,2,3,4,5,4,3,2,1])
>>> data1.xlabel = 'x-label'
>>> data1.ylabel = 'y-label'
>>> data1.title = 'Gnuplot title'
>>> data1.legend  = 'plot1'
>>> plot1 = gnuplot(data1)
>>> data2 = List([[1.5,2],[2.5,4],[3.5,6],
                  [4.5,8],[5.5,10],[6.5,8],
                  [7.5,6],[8.5,4],[9.5,2]])
>>> data2.legend = 'plot2'
>>> data2.with = 'points 3 3'
>>> plot2 = gnuplot(data2,parent=plot1)

The Utilities.List modules also has a class SubjectList. This is a class derived from a python list and from the ASE class Subject.

Using this class the Gnuplot window acts as a observer on the list data, so the gnuplot window will change if the list are updated as in:

>>> from ASE.Utilities.List import SubjectList
>>> from ASE.Visualization.gnuplot import gnuplot
>>> data = [1,2,3,4,5]
>>> plot = gnuplot(data)
>>> data[2] += 1

The gnuplot module use the gnuplot-py packages.

RasMol visualization of atoms

RasMol is an interactive but somewhat primitive tool to visualize the atomic structure of a list of atoms. The atoms can be colored according to their, type or their tag. The atomic system can be rotated, zoomed etc with the mouse. RasMol support in ASE requires an external program, rasmol, to be installed.

Warning

The rasmol program only works if it runs on the local machine. Attempts to run it over an SSH connection fails. Rasmol is unfortunately no longer maintained, and as X11 develops, incompatibilities arise.

Rasmol is very simple to use:

>>> from ASE.Visualization.RasMol import RasMol
>>> plot = RasMol(water)
>>> plot.Update()

Since the plotter is updated when its Update() method is called, you can attach it to a dynamics and the plot will be updated after each time step.

You can also send commands directly to rasmol by calling the rasmol instance with the command as the argument:

>>> plot('spacefill')

A list of commands can be found in the rasmol manual

VTK 3D visualization

The Visualization ToolKit (VTK) is an open source, freely available software system for 3D visualization. For more information on VTK, go to the vtk homepage.

The module ASE.Visualization.VTK implements the following methods for 3D plotting using VTK:

VTKPlotWaveFunction:
This method use the GetWaweFunctionArray method of a DFT calculator, to make a 3D plot of a wavefunction.
VTKPlotAtoms:

3D plot of a ListOfAtoms object. Use VTKPLotAtoms like this:

plot = VTKPlotAtoms(atoms,forces=True)
plot.SetForceScaleFactor(0.5)

If forces=True is used vectors displaying the forces are added to the plot.

All methods takes a ListOfAtoms object as argument, together with optional arguments. A VTKplot object are returned.

>>> plot = VTKmethod(atoms,parent=None,**keywords)

The parent argument can be used to add the VTKplot object plot, together with an existing VTKplot object using parent=anotherplot, see the example below. The keywords argument, controls the 3D rendering. The list of possible keywords are listed below:

Keyword Description Default
contourvalues Number of contour values for a isosurface plot 4

Some of the methods available (for a complete list see the documentation for the module ASE.Visualization.VTK) for the VTKplot object are listed below:

AddAvatar(avatar):
Adds an avatar to the current avatar. When subsequently rendering the window the added avatar will be combined with the current avatar.
AddIsoSurface1:
Adds an vtkGrid3DProbeIsoSurface1 avatar This method can used to add isosurfaces to the avatar list. It will generate a number of evenly spaced isosurfaces within a specified interval. The default number is 10 and the default interval is the valuerange of the grid. For more information refer to the documentation for 'vtkGrid3DProbeIsoSurface1' .
AddIsoSurface2(contourvalues):
Adds an vtkGrid3DProbeIsoSurface2 avatar This method can be used to add isosurfaces to the avatar list. It will generate isosurfaces according to the specified contour list. For more information refer to the documentation for 'vtkGrid3DProbeIsoSurface2' .
AddOutline:
Add an vtkOutline avatar This method can be used to add the outline of the grid to the avatar list. For more information refer to the documentation for 'vtkOutline' .
GetAvatarDict:
Returns a dictionary with the added avatars The values in the dictionary are instances of the added avatars. The key corresponding to the each added avatar is the name of the avatar. These names are intended to be self-explaining.
GetAvatars:
Returns a tuple of the added avatars. This method can be used to see, which methods have been added to the current avatar. The tuple contains the instances of the added avatars.
GetColorRange:
Returns the color range
GetParents:
Returns a list of the added parents
GetPeriods:
Returns the number of periods
GetProp:
Returns a vtkProp Convenience method that can be used to obtain the 'vtkProp' associated with the 'vtkAvatar'.
GetPropAssembly:
Returns a vtkPropAssembly The vtkPropAssembly (VTK object) will contain all the vktProp's that can be found in the avatar list and the one obtained from the avatar itself.
GetTranslation:
Return the translation
RemoveAvatar:
Removes the avatar.
SaveAsBMP(filename, resolution=1):
Saves the window as bmp-file. Resolution is an integer representing the number of squares that the window is divided into when writing to the bmp-file. Thus choosing a higher number improves the quality of the saved image.
SetColorRange(colorrange):
Sets the colorrange This method can be used to set the colorrange. This interval specifies the range of the colortable. Scalar values greater than the maximum are clamped to the maximum value and scalar values smaller than the minimum are clamped to the minimum value.
SetPeriods(periods):
Sets the number of periods This method specifies the number of times the grid is repeated. Default is (1,1,1), i.e. meaning that only the grid within the unit cell at the origin is retained.
SetRepresentationToIsoSurface1:
Sets the representation to IsoSurface1 This method can be used to change the representation of the object to IsoSurface1. If the object is already represented by an IsoSurface2 this avatar is removed.
SetRepresentationToIsoSurface2(contourvalues):
Sets the representation to isosurface2 This method can be used to change the representation of the object to IsoSurface2. It the object is already represented by an IsoSurface1, this avatar is removed.
SetTranslation(translation):
Sets the translation This method can be used for translating the "window" in which the isosurfaces of the 3D grid are visualized. The window has the size of a single unit cell. The translation must be specified in terms of the FFT grid points. Default is (0,0,0).
Update:
Redraw the plot.
VTK example

To make a combined 3D plot of wavefunction and atoms, one can use, using Grid

>>> from ASE.Visualization.VTK import VTKPlotWaveFunction,VTKPlotAtoms
>>> (import DFT caculator here)
>>> atoms = DFTCalculator.ReadAtoms('oldfile')
>>> wfplot = VTKPlotWaveFunction(atoms)
>>> atomsplot = VTKPlotAtoms(atoms,parent=wfplot)
>>> wfplot.Update()

To remove the unit cell avatar

>>> wfplot.GetAvatars()
>>> #Check which number in the list of avatars the vtkListOfAtoms avatar is. In this case it is the last.
>>> a = wfplot.GetAvatars()[-1]
>>> a.GetAvatars()
>>> #Check which number in the list of avatars the vtkUnitCell avatar is. In this case it is the first.
>>> a.RemoveAvatar(a.GetAvatars()[0])
>>> wfplot.Render()

Visual Molecular Dynamics (VMD)

VMD is a program designed mainly for displaying molecular dynamics simulations in bio-chemistry, and has a lot of functionality related to this.

See the user guide for VMD at the VMD homepage, a very helpful mailing list vmd-l and the condition of use can also be found here.

VMD supports python in the way that it has an embedded python interpreter, so then you start VMD like

vmd -python some-python-script

the python script will be run and you get three windows:

  • the main vmd vindow containing all menus for controlling the mouse
  • the graphics window showing the molecule
  • a python text window in which you can enter python commands.

Note that the mouse in VMD always has two functions, if you hold the left mouse button down on the bag-ground (away from any atom) and move the cursor, you will either rotate, translate or scale the view, depending on the settings in the Mouse menu (default is rotation). If you use the left mouse button on any atom the function will be different, again depending on the settings in the Mouse menu (more on this later).

VMD as a atom manipulator
You can use:
Mouse/Move/Molecule

Now holding down the mouse on one atom and then move the cursor will move the entire molecule. You can rotate the molecule by holding down the shift key.

You can use:
Mouse/Move/Atom

to move a single atom around, you move in the plane of the view.

Analysing structures using VMD

You can use:

  • Mouse/Pick/Bonds

    Clicking on two atoms will setup a ruler displaying the distance between the two atoms.

  • Mouse/Pick/Angles

    Clicking on three atoms in row to monitor the angle formed by the atoms.

  • Mouse/Pick/Dihedral

    Clicking on 4 atoms you can monitor the dihedral angle formed by these four atoms.

The bonds and angles setup here will follow the atoms as you are moving or rotating them.

Interactive Molecular Dynamics using VMD

Interactive molecular dynamics allows interaction with molecular structures within a running simulation, applying forces on groups of atoms in the simulation. The mouse is used to select and move the atoms in VMD.

For more information about IMD refer to the VMD Homepage and the article 'A system for Interactive Molecular Dynamics Simulation, by J.E.Stone, J. Gullingsrud, and K. Schulten'.

A ASE filter called IMD allows for interactive molecular dynamics with any ASE calculator and dynamics.

The IMD filter can be used like any constrain filter; as input to another filter or directly as input to a dynamics.

The IMD filter should be placed in front of the atoms and before, if any, constrain filters, otherwise not all atoms will be shown in the VMD window.

A typical case will look like this:

 -------------       ------       ---------      -----------
|             |     |      |     |         |     |          |
| ListOfAtoms |<----| IMD  |<----| Subset  |<----| Dynamics |
|             |     |      |     |         |     |          |
 -------------       ------       ---------      -----------
                       /\
                       ||
                       \/
                     ------
                    | VMD  |
                     ------

An example is shown below. This example use the PairPotential, the Subset filter and the MDMin miminization algorithm:

>>> from ASE.Calculators.PairPotential import PairPotential
>>> from ASE.Dynamics.MDMin import MDMin
>>> from ASE.IO.NetCDF import ReadNetCDF
>>> from ASE.Filters.Subset import Subset
>>> ASE.Filters.IMD import IMD
>>>
>>> atoms = ReadNetCDF('N2-slab.nc')
>>> atoms.SetCalculator(PairPotential())
>>>
>>> imd = IMD(atoms)
>>>
>>> subset = Subset(imd, indices=[-1,-2])
>>>
>>> dyn = MDMin(subset, 0.05)
>>> dyn.Run(1000000)

In principle all ASE calculators can use the IMD filter, however in order to have reasonably responds time, the relevant calculators are probably Asap, MMTK and the PairPotential.

One should not used the Conjugate Gradient minimization algorithm, as this is dependent on correspondence between energy and force, and this will not be the case then applying IMD forces on the system.

Options to the IMD filter:

port
The socket port used for communication with VMD (default 3001).
frequency:
The the number of MD steps before a frame is send to VMD (default 1 corresponding to every frame).
forcefactor:
Determines the force corresponding to a certain mouse movement; the larger the force factor the smaller the mouse movement in order to get the same force (default is 10). The correct forcefactor will depend on the system (small or large spring-constants) and how large pertubations one wants.

For the low level socket communication betwen python and VMD you need to install the PyIMD python packages. You can install from a binary rpm for linux, or from the source tar file. The README file in the tar file gives more details about PyIMD.

Visualizing volumetric data

You can use VMD to make isosurface and volumeslice of volumetric data. From a ASE ListOfAtoms and a numeric array containing the volumetric data you can generate a Gaussian Cube file.

In the example below the atoms and density from the ASE logo are written as a Cube file:

import Numeric as num
from ASE.IO.NetCDF import ReadNetCDF
from ASE.IO.Cube import WriteCube

density = num.load(file('ASE/Tools/ase-density.pickle'))
atoms = ReadNetCDF('ASE/Tools/ase.nc')
WriteCube(atoms,density,'ase.cube')

Now you can use:

vmd ase.cube

In Graphics/Represention add a representation for viewing the atoms, this can be eg. CPK, and add a representation for the volumetric data, this can be either Isosurface` or VolumeSlice.

One can add more representations, eg. combining a isosurface plot and a volume slice plot.

The isosurface can be colored using the volumetric data from another Cube file (only VMD version >= 1.8.3).

Warning

This color scheme, for the current 1.8.3 version, only works for cubic unit cells.

For the Isosurface representation, you can select the Coloring method to be Volume. For a complex array argument to the method WriteCube, two Cube files will be written; one for the absolute value and one for the phase of the complex number, eg. for a complex wavefunction:

wavefunction = calc.GetWaveFunctionArray(band=0)
WriteCube(atoms, wavefunction,'wave0.cube')
vmd -f wave0.cube wave0_phase.cube

If the keyword real is set to True the complex array are cast into real form, by assuming the array has a constant phase, this is mostly relevat for localized Wannier functions.

PrimiPlotter (plotting atoms from a script)

PrimiPlotter is mainly intended for use in scripts, but can also be used interactively (although RasMol often is a better choice). PrimiPlotter produces PostScript output, with each atom as a small colored circle. The PostScript output can be saved in a file, converted to other graphics formats, or displayed in a window (multiple types are possible).

Creating a PrimiPlotter

It is created using the list of atoms as an argument to the constructor. Then one or more output devices must be attached using SetOutput(device):

>>> from Visualization.PrimiPlotter import *
>>> plot = PrimiPlotter(atoms)
>>> plot.SetOutput(X11Window())

The following output devices are implemented:

PostScriptFile(prefix):
Create PS files names prefix0000.ps etc.
PnmFile(prefix):
Similar, but makes PNM files.
GifFile(prefix):
Similar, but makes GIF files.
JpegFile(prefix):
Similar, but makes JPEG files.
X11Window():
Show the plot in an X11 window using ghostscript.

Output devices writing to files take an extra optional argument to the constructor, compress, specifying if the output file should be gzipped. This is not allowed for some (already compressed) file formats.

Instead of a filename prefix, a filename containing a % can be used. In that case the filename is expected to expand to a real filename when used with the Python string formatting operator (%) with the frame number as argument. Avoid generating spaces in the file names: use e.g. %03d instead of %3d.

Controlling the plotting

The atoms are plotted as circles. The system is first rotated using the angles specified by SetRotation([vx, vy, vz]). The rotation is vx degrees around the x axis (positive from the y toward the z axis), then vy degrees around the y axis (from x toward z), then vz degrees around the z axis (from x toward y). The rotation matrix is the same as the one used by RasMol.

Per default, the system is scaled so it fits within the canvas (autoscale mode). Autoscale mode is enabled and disables using AutoScale("on") or AutoScale("off"). A manual scale factor can be set with SetScale(scale), this implies AutoScale("off"). The scale factor (from the last autoscale event or from SetScale) can be obtained with GetScale(). Finally, an explicit autoscaling can be triggered with AutoScale("now"), this is mainly useful before calling GetScale or before disabling further autoscaling. Finally, a relative scaling factor can be set with SetRelativeScaling(), it is multiplied to the usual scale factor (from autoscale or from SetScale). This is probably only useful in connection with autoscaling.

Atomic radii

The radii of the atoms are obtained from the first of the following methods which work:

  1. If the radii are specified using PrimiPlotter.SetRadii(r), they are used. Must be an array, or a single number.
  2. If the atoms has a GetAtomicRadii() method, it is used. This is unlikely.
  3. If the atoms has a GetAtomicNumbers() method, the corresponding covalent radii are extracted from the ASE.ChemicalElements module.
  4. If all else fails, the radius is set to 1.0 Angstrom.
Colors

The atoms are colored using the first of the following methods which work.

  1. If colors are explicitly set using PrimiPlotter.SetColors(), they are used.

    • If these colors are specified as a dictionary, the tags (from atoms.GetTags()) are used as an index into the dictionary to get the actual colors of the atoms.
  2. If a color function has been set using PrimiPlotter.SetColorFunction(), it is called with the atoms as an argument, and is expected to return an array of colors.
  3. If the atoms have a GetColors() method, it is used to get the colors.

    • If these colors are specified as a dictionary, the tags (from atoms.GetTags()) are used as an index into the dictionary to get the actual colors of the atoms.
  4. If all else fails, the atoms will be white.

The colors are specified as an array of colors, one color per atom. Each color is either a real number from 0.0 to 1.0, specifying a grayscale (0.0 = black, 1.0 = white), or an array of three numbers from 0.0 to 1.0, specifying RGB values. The colors of all atoms are thus a Numerical Python N-vector or a 3xN matrix.

In cases 1a and 3a above, the keys of the dictionary are integers, and the values are either numbers (grayscales) or 3-vectors (RGB values), or strings with X11 color names, which are then translated to RGB values. Only in case 1a and 3a are strings recognized as colors.

Invisible atoms

Some atoms may be invisible, and thus left out of the plot. Invisible atoms are determined from the following algorithm. Unlike the radius or the coloring, all points below are tried and if an atom is invisible by any criterion, it is left out of the plot.

  1. All atoms are visible.
  2. If PrimiPlotter.SetInvisible() has be used to specify invisible atoms, any atoms for which the value is non-zero becomes invisible.
  3. If an invisiblility function has been set with PrimiPlotter.SetInvisibilityFunction(), it is called with the atoms as argument. It is expected to return an integer per atom, any non-zero value makes that atom invisible.
  4. If a cut has been specified using SetCut, any atom outside the cut is made invisible.

Note that invisible atoms are still included in the algorithm for positioning and scaling the plot.

Plotting

Two methods cause a plot to be created:

Update():
This is the main function causing the generation of a plot. If the PrimiPlotter constructor was given the optional argument interval=n (a number), then a plot is only created every n'th time Update() is called. This is useful if the plotter is attached to the dynamics.
Plot():
Causes the generation of a plot, regardless of the 'interval'.
PrimiPlotter methods
Update() and Plot():
Create plots, see Plotting above.
SetDimensions(dims):
Set the size of the canvas (a 2-tuple).
SetRotation(rotation):
Set the rotation angles (in degrees).
SetRadii(radii):
Set the atomic radii. Give an array or a single number. If not used, the atomic number will be used to determine the radius.
SetColors(colors) and SetColorFunction(function):
Set the colors of the atoms. Specify a color per atom, or a dictionary mapping from tags to colors. See Colors above.
SetInvisible(inv) and SetInvisibilityFunction(function):
Mark some atoms as invisible. See Invisible atoms above.
SetCut(xmin=None, xmax=None, ymin=None, ymax=None, zmin=None, zmax=None):
Make a cut through the system. Atoms outside the cut are invisible. One or more of the arguments xmin .. zmax must be specified to set a cut, they represent the minimal/maximal coordinates of the atoms being shown. If no arguments are given, an existing cut is removed.
ParallelPrimiPlotter

A special version of the PrimiPlotter, called ParallelPrimiPlotter, is defined for use in parallel ASAP simulations only. It is used exactly like the ordinary PrimiPlotter.

Dacapo users should use the ordinary PrimiPlotter, even for on-the-fly visualization in scripts running Dacapo in parallel.

PovrayPlotter (Raytracing)

The PovrayPlotter is an interface to the Persistence of Vision Raytracer (POV-Ray). It generates input files to the raytracer, and runs the raytracer. It is mainly intended for making pictures for publications and presentations.

Raytracing is a rather complex operation, and POV-ray has many features. The PovrayPlotter attempts to make it relatively easy to use the raytracer, without sacrificing (too much of) the advanced stuff.

The coordinate system

POV-Ray uses a left-handed coordinate system, so your figure may be mirrored compared to what you expect. In most cases that does not matter, but if you plot chiral structures you may want to multiply the coordinates with -1.

Setting up PovrayPlotter

A plotter is created with the commands

>>> from ASE.Visualization.PovrayPlotter import PovrayPlotter
>>> plot = PovrayPlotter(atoms, filename)

An additional argument interval=n creates a plotter that only produces a plot every n times it is called, useful for attaching to the dynamics.

The filename can be a filename, a prefix or a template. Filenames and prefixes cannot contain the % (percent) character or whitespace.

filename
A filename ends on .png and is intended for producing single pictures. The output file will be placed in that file. If Update() is called multiple times, the file will be overwritten.
prefix
A prefix does not end in .png and is intended for multiple pictures. Each time Update is called, a new file is generated. They are named prefix0000.png, prefix0001.png etc.
template
A template contains the % character, and is used to construct filenames from file numbers using the standard Python string formatting. The prefix 'a' is equivalent to the template 'a%04d.png'. Avoid generating spaces in the file name, i.e. use %04d not %4d.
Setting up the scene.

A scene is created containing all the atoms as spheres with appropriate radii. You need to place a camera and one or more lamps in the scene, the default placements are unlikely to be useful. These are placed in the coordinate system used by the atoms.

SetCamera(position, lookat=None, sky=None):

Set the camera position, and optionally the lookat point.

The first argument specifies the camera position.

The optional argument lookat specifies a new lookat point, the point towards which the camera is turned. If not specified, the lookat point is unchanged, initially it is (0,0,0). Both arguments should either be 3-tuples or equivalent, or a string with a PovRay vector.

The optional argument sky specifies the sky vector. It controls how the camera is panned and tilted to look at the lookat point, and determines which direction is considered up in the final picture. If not specified, the sky vector is unchanged, initially it is 'y', which is the POV-Ray default. If the final picture is rotated in a weird way, try changing this to 'z'. The value can be a 3-tuple or a string specifying a POV-Ray vector, including the standard directions 'x', 'y' and 'z'.

SetLamp(position, color="White"):

Add a lamp. The position is a 3-tuple or a RovRay vector, the color is a string with a PovRay color specification (default: White).

If SetLamp is called more than once, multiple lamps are defined.

SetSize(x, y, aspect=None):
Set the size of the image (two integers). An optional aspect ratio can be specified if pixels are not square.
Creating the plot

A picture is created using the Update() method. If interval=n was specified in the constructor, only every n'th call to Update() produces a picture. The Update() can be passed a new list of atoms as an optional argument, this can be used to plot multiple systems with the same raytracer settings.

The Plot() method also creates a picture, regardless of the value of the interval counter.

Draft rendering and final rendering

A number of methods control features, some of which are convenient for draft rendering, some which improve the quality of the final figure. All of these functions affect the result of following calls to Update()

KeepWindow():
When running interactively, you can watch the progress of the raytracing process in a window. Normally, this window disappears once the rendering is finished. If you call this function, the window will remain until you click on it, this is very useful while experimenting with camera and lamp positions. Calling KeepWindow(False) returns to the default behavior.
AntiAlias():

This function enables anti-aliasing. It will make edges of atoms look smoother, at the price of a significant increase in computer time. This is recommended for the final rendering of publication-quality figures. Calling AntiAlias(False) turns anti-aliasing off.

You can control the anti-aliasing process by calling this function with a string containing one or more command line options for the povray executable. The string will be used instead of +A to turn on anti-aliasing. A well-chosen string will allow you to control the details of the anti-aliasing process, as described in the POV-ray manual.

Scaling or rotating the atoms

The system can be scaled with SetScale(factor) or rotated with SetRotation([a,b,c]). The system is then rotated a degrees around the x axis, b degrees around the y axis, and finally c degrees around the z axis.

In a raytracing environment, it is normally more natural to move the camera than to scale or rotate the system, but in some cases, mainly when producing animations, these functions can be convenient.

Colors etc.

Per default, all atoms are rendered as silvery metallic spheres. This is unlikely to be what you want (and may be improved in the future). You can specify not only the coloring of atoms, but also their texture, but due to the flexibility of POV-ray it can be a bit complicated. POV-Ray operates with textures and colors, the color specifiation PovrayPlotter provides three different ways (color modes) to specify color and texture of the atoms.

Specifying colors:

This is the default color mode. Atoms are rendered as metallic-looking spheres of the specified colors. The reflectivity is chosen rather low, since multiple reflections look good in artwork, but are confusing in scientific figures.

The colors of atoms may be given as three numbers for each atom, specifying red, green and blue, or as strings representing predefined colors from povray's colors.inc or metals.inc files, or colors you have pre-defined yourself.

This color mode is chosen with SetColorMode("color").

Sample color specifications:

[1.0, 0.0, 0.0]: A red atom.

P_Copper4: A copper atom.

P_Silver4: This is the default color.

Specifying textures:

Atoms are rendered as as spheres, the "color" specifies the texture. The "color" should be valid pov-ray texture definitions, either a full texture definition for each atom, or textures defined in colors.inc or metals.inc, or textures defined yourself.

This color mode is chosen with SetColorMode("texture").

Predefined texture definitions:
T_Campos_Plastic:
A plastic atom.
T_Campos_Glass:
A glass atom.
T_Campos_Silver:
A silver atom (equivalent to specifying P_Silver4 in color mode).
T_Campos_Copper:
A copper atom.
T_Gold_1A:
A gold atom using a standard POV-ray texture. The reflectivity may be a bit high.
User mode:

Advanced users only! This mode gives you almost full control over the code used to define the atoms. You could even define cylindrical atoms. User mode is selected by calling SetColorMode("user", template) where the template is a string used to generate the atom specification in the POV-ray input file. Standard Python string formatting is used to generate the atom specification from the template and a tuple containing four numbers and a string (the coordinates, the radius and the color specification).

Color mode corresponds to this template:

sphere {
  <%.3f, %.3f, %.3f>, %.3f
  texture {
    pigment { %s }
    finish { F_Campos_Metal }
  }
}

Texture mode corresponds to this template:

sphere {
  <%.3f, %.3f, %.3f>, %.3f
  texture { %s }
}
Determining the colors of the atoms

The colors of the atoms may be set using the SetColors() method. The colors can be any of the following:

  • An array of strings, one string per atom, specifying the color or the texture (useful in color, texture and user mode).
  • A two-dimensional array of numbers, three numbers per atom, specifying the colors as RGB values (useful in color mode, and possibly in user mode).
  • A dictionary mapping integers to either strings or 3-arrays of RGB values. In this case the tags are read from the atoms using the GetTags() method, and the dictionary is used to map from tags to colors.
Predefined colors and textures

A limited number of textures and colors are defined. The standard PovRay include files colors.inc and metals.inc are included. You can see all available colors and metallic textures by locating the file t_metal.ini on your computer (probably in /usr/share/povray-X.X/scenes/portfolio). Copy everything from that directory into an empty directory, and run povray on the files t_metals.ini and c_colors.ini. A few minutes later, you can see the result by browsing the file index.html (if you render all .ini files, your computer will be busy for hours, but some of the results are impressive). The results can also be seen here.

In addition to these standard colors and textures, a few extra textures are defined. Two metals, T_Campos_Copper and T_Campos_Silver are low-reflectivity copper and silver-like metals. In addition, transparent atoms can be made with T_Campos_Glass and T_Campos_Plastic. These can be used in texture mode only.

Defining your own colors, textures etc.

New definitions can easily be added, by appending the definitions to the list plotter.pov.user_definitions (that is the plotter object has an attribute called pov, which again has an attribute called user_definitions, which is a list). Add strings defining the new colors or textures. The textures mentioned above correspond to these definitions:

#declare F_Campos_Metal =
finish {
    ambient 0.05
    brilliance 3
    diffuse 0.6
    metallic
    specular 0.70
    roughness 0.04
    reflection 0.15
}

#declare T_Campos_Copper =
texture {
    pigment { P_Copper4 }
    finish { F_Campos_Metal }
}

#declare T_Campos_Silver =
texture {
    pigment { P_Silver4 }
    finish { F_Campos_Metal }
}

#declare T_Campos_Glass =
texture {
    pigment { White filter 0.7 }
    finish {
        ambient 0.05
        diffuse 0.3
        reflection 0.1
        specular 1
        roughness .001
    }
}

#declare T_Campos_Plastic =
texture {
    pigment { White filter 1 }
    finish {
        ambient 0
        diffuse 0
        reflection .05
        specular 0.2
        roughness .025
    }
}