Visualization — ASE documentation

### Navigation

- index
- modules |
- Documentation for modules in ASE »

# Visualization

`ase.visualize.` `view`(atoms, data=None, viewer=None, repeat=None)

This provides an interface to various visualization tools, such as `ase.gui`, `ase.visualize.vtk`, RasMol, VMD, VTK, gOpenMol, or Avogadro. The default viewer is the ase.gui, described in the `ase.gui` module. The simplest invocation is:

    >>> from ase.visualize import view
    >>> view(atoms)

where `atoms` is any `Atoms` object. Alternative viewers can be used by specifying the optional keyword `viewer=...` - use one of ‘ase.gui’, ‘gopenmol’, ‘vmd’, or ‘rasmol’. The VMD and Avogadro viewers can take an optional `data` argument to show 3D data, such as charge density:

    >>> view(atoms, viewer='VMD', data=array)

If you do not wish to open an interactive gui, but rather visualize your structure by dumping directly to a graphics file; you can use the `write` command of the `ase.io` module, which can write ‘eps’, ‘png’, and ‘pov’ files directly, like this:

    >>> write('image.png', atoms)

## Mayavi

The `ase.visualize.mlab.plot()` function can be used from the command-line:

    python -m ase.visualize.mlab abc.cube

to plot data from a cube-file or alternatively a wave function or an electron density from a calculator restart file:

    python -m ase.visualize.mlab -C gpaw abc.gpw

Options:

> `-h, --help` | show this help message and exit
> `-n INDEX, --band-index=INDEX`
> | Band index counting from zero.
> `-s SPIN, --spin-index=SPIN`
> | Spin index: zero or one.
> `-c CONTOURS, --contours=CONTOURS`
> | Use “-c 3” for 3 contours or “-c -0.5,0.5” for specific values. Default is four contours.
> `-r REPEAT, --repeat=REPEAT`
> | Example: “-r 2,2,2”.
> `-C NAME, --calculator-name=NAME`
> | Name of calculator.

`ase.visualize.mlab.` `plot`(atoms, data, contours)

  Plot atoms, unit-cell and iso-surfaces using Mayavi.

  Parameters:

  atoms: Atoms object
    Positions, atomiz numbers and unit-cell.
  data: 3-d ndarray of float
    Data for iso-surfaces.
  countours: list of float
    Contour values.

## VTK

The Visualization Toolkit (VTK) is a powerful platform-independent graphics engine, which comes as an open source graphics toolkit licensed under the BSD license. It is available for a wide range of programming languages, including easily scriptable interfaces in Python and Tcl.

In the scientific community, VTK is used by thousands of researchers and developers for 3D computer graphics, image processing, and visualization. VTK includes a suite of 3D interaction widgets within the development framework for information visualization, integrating GUI toolkits such as Qt and Tk into a highly flexible design platform.

For visualization purposes within ASE, two different VTK-approaches are supported, namely:

Scripted on-the-fly rendering:
| ASE includes VTK-scripting for easy data visualization using the `ase.visualize.vtk` module. Development is in progress, so you might want to check out the latest development release from SVN (see Latest development release).
Interactive rendering:
| MayaVi is an easy-to-use GUI for VTK. With Enthought’s traits-based VTK-wrapper (TVTK), constructing VTK pipelines has been simplified greatly by introducing three basic concepts: data sources, filters and visualization modules. MayaVi also supports the VTK file formats, including the flexible VTK XML, which in ASE can be used to export atomic positions, forces and volume data using the `write` command in the `ase.io` module.

A key feature of VTK is the inherent ability to use MPI for parallel rending, which is provided with built-in parallel composite rendering objects to handle domain decomposition and subsequent recombination of the raster information. This is particularly useful for non-interactive ray tracing, batch isosurface generation and in-situ visualization of simulation data in cluster computing.

See also

ParaView is a VTK-based open-source, multi-platform data analysis and visualization application for extremely large data-sets using distributed memory computing resources and parallel rendering through MPI.

## PrimiPlotter

The PrimiPlotter is intended to do on-the-fly plotting of the positions of the atoms during long molecular dynamics simulations. The module `ase.visualize.primiplotter` contains the PrimiPlotter and the various output modules, see below.

class `ase.visualize.primiplotter.` `PrimiPlotter`(atoms, verbose=0, timing=0, interval=1, initframe=0)

  Primitive PostScript-based plots during a simulation.

  The PrimiPlotter plots atoms during simulations, extracting the relevant information from the list of atoms. It is created using the list of atoms as an argument to the constructor. Then one or more output devices must be attached using set_output(device). The list of supported output devices is at the end.

  The atoms are plotted as circles. The system is first rotated using the angles specified by set_rotation([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 set_scale(scale), this implies autoscale(“off”). The scale factor (from the last autoscale event or from set_scale) can be obtained with get_scale(). Finally, an explicit autoscaling can be triggered with autoscale(“now”), this is mainly useful before calling get_scale 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 set_scale). This is probably only useful in connection with autoscaling.

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

  1. If the radii are specified using PrimiPlotter.set_radii(r), they are used. Must be an array, or a single number.
  2. If the atoms has a get_atomic_radii() method, it is used. This is unlikely.
  3. If the atoms has a get_atomic_numbers() 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.

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

  1. If colors are explicitly set using PrimiPlotter.set_colors(), they are used.
  2. If these colors are specified as a dictionary, the tags (from atoms.get_tags()) are used as an index into the dictionary to get the actual colors of the atoms.
  3. If a color function has been set using PrimiPlotter.set_color_function(), it is called with the atoms as an argument, and is expected to return an array of colors.
  4. If the atoms have a get_colors() method, it is used to get the colors.
  5. If these colors are specified as a dictionary, the tags (from atoms.get_tags()) are used as an index into the dictionary to get the actual colors of the atoms.
  6. 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.

  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.set_invisible() 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.set_invisibility_function(), 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 set_cut, any atom outside the cut is made invisible.

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

  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.

  Parameters to the constructor:

  atoms: The atoms to be plottet.

  verbose = 0: Write progress information to stderr.

  timing = 0: Collect timing information.

  interval = 1: If specified, a plot is only made every interval’th time update() is called. Deprecated, normally you should use the interval argument when attaching the plotter to e.g. the dynamics.

  initframe = 0: Initial frame number, i.e. the number of the first plot.

  `log`(message)

    logs a message to the file set by set_log.

  `plot`()

    Create a plot now. Does not respect the interval timer.

    This method makes a plot unconditionally. It does not look at the interval variable, nor is this plot taken into account in the counting done by the update() method if an interval variable was specified.

  `set_color_function`(colors)

    Set a color function, to be used to color the atoms.

  `set_colors`(colors)

    Explicitly set the colors of the atoms.

    The colors can either be a dictionary mapping tags to colors or an array of colors, one per atom.

    Each color is specified as a greyscale value from 0.0 to 1.0 or as three RGB values from 0.0 to 1.0.

  `set_dimensions`(dims)

    Set the size of the canvas (a 2-tuple).

  `set_invisibility_function`(invfunc)

    Set an invisibility function.

  `set_invisible`(inv)

    Choose invisible atoms.

  `set_log`(log)

    Sets a file for logging.

    log may be an open file or a filename.

  `set_output`(device)

    Attach an output device to the plotter.

  `set_radii`(radii)

    Set the atomic radii. Give an array or a single number.

  `set_rotation`(rotation)

    Set the rotation angles (in degrees).

  `update`(newatoms=None)

    Cause a plot (respecting the interval setting).

    update causes a plot to be made. If the interval variable was specified when the plotter was create, it will only produce a plot with that interval. update takes an optional argument, newatoms, which can be used to replace the list of atoms with a new one.

## FieldPlotter

The FieldPlotter is intended to plot fields defined on the atoms in large-scale simulations. The fields could be e.g. pressure, stress or temperature (kinetic energy), i.e. any quantity that in a given simulation is best defined on a per-atom basis, but is best interpreted as a continuum field.

The current version of FieldPlotter only works if the number of atoms is at least 5-10 times larger than the number of pixels in the plot.

class `ase.visualize.fieldplotter.` `FieldPlotter`(atoms, datasource=None, verbose=0, timing=0, interval=1, initframe=0)
  `log`(message)

    logs a message to the file set by set_log.

  `plot`(data=None)

    Create a plot now. Does not respect the interval timer.

    This method makes a plot unconditionally. It does not look at the interval variable, nor is this plot taken into account in the counting done by the update() method if an interval variable was specified.

    If data is specified, it must be an array of numbers with the same length as the atoms. That data will then be plotted. If no data is given, the data source specified when creating the plotter is used.

  `set_background`(value)

    Set the data value of the background. See also set_background_color

    Set the value of the background (parts of the plot without atoms) to a specific value, or to ‘min’ or ‘max’ representing the minimal or maximal data values on the atoms.

    Calling set_background cancels previous calls to set_background_color.

  `set_background_color`(color)

    Set the background color. See also set_background.

    Set the background color. Use a single value in the range [0, 1[ for gray values, or a tuple of three such values as an RGB color.

    Calling set_background_color cancels previous calls to set_background.

  `set_black_white_colors`(reverse=False)

    Set the color to Black-White (greyscale)

  `set_color_function`(colors)

    Set a color function, to be used to color the atoms.

  `set_data_range`(range1, range2=None)

    Set the range of the data used when coloring.

    This function sets the range of data values mapped unto colors in the final plot.

    Three possibilities:

    ‘data’: Autoscale using the data on visible atoms.
      The range goes from the lowest to the highest value present on the atoms. If only a few atoms have extreme values, the entire color range may not be used on the plot, as many values may be averaged on each point in the plot.
    ‘plot’: Autoscale using the data on the plot. Unlike ‘data’
      this guarantees that the entire color range is used.

    min, max: Use the range [min, max]

  `set_dimensions`(dims)

    Set the size of the canvas (a 2-tuple).

  `set_invisibility_function`(invfunc)

    Set an invisibility function.

  `set_invisible`(inv)

    Choose invisible atoms.

  `set_log`(log)

    Sets a file for logging.

    log may be an open file or a filename.

  `set_output`(device)

    Attach an output device to the plotter.

  `set_plot_plane`(plane)

    Set the plotting plane to xy, xz or yz (default: xy)

  `set_radii`(radii)

    Set the atomic radii. Give an array or a single number.

  `set_red_yellow_colors`(reverse=False)

    Set colors to Black-Red-Yellow-White (a.k.a. STM colors)

  `set_rotation`(rotation)

    Set the rotation angles (in degrees).

  `update`(newatoms=None)

    Cause a plot (respecting the interval setting).

    update causes a plot to be made. If the interval variable was specified when the plotter was create, it will only produce a plot with that interval. update takes an optional argument, newatoms, which can be used to replace the list of atoms with a new one.

### Navigation

- index
- modules |
- Documentation for modules in ASE »