This program reads a basic description of the crystal structure, which includes unit-cell parameters, space group, atomic coordinates, thermal parameters and/or a Fourier map, and outputs a geometry object that contains polyhedra, planes, lone-pair cones, spheres or ellipsoids, bonds, iso-surface Fourier contours and the unit-cell boundary.
Versions 4.x and 5.x differ only in the availability of a full graphical user interface
in the 5.x series.
This version of the manual describes versions 4.5 and 5.5, released March 10, 2011.
The program creates its output in several file formats:
The POV scene file can be used as is, but it can also be edited to make use of the more sophisticated (or un-scientific) features of POV like transparency, backgrounds or light effects.
The VRML version is suitable for use with WWW browsers and standalone viewers such as view3dscene, and can be used to make displays suitable for interactive examination by users. Source URL's for this and associated programs are given in Appendix A.
As of version 4.0, DRAWxtl will also render the crystal structure directly into an OpenGL window, where the model can be resized and rotated as desired.
DRAWxtl can make ball-and-stick, polyhedral, or mixed diagrams, with atoms represented as spheres or thermal ellipsoids. For the latter type, anisotropic coefficients can be input as Uij, Bij, or beta_ij, depending upon what is available.
Since V5.3, the program can also be used to plot modulated and composite crystals up to 3D modulation. All of the standard modulation functions defined in the CIF standard can be handled, except for the rigid-body terms. Since V5.5, it is also possible to have DRAWxtl generate a sequence of images corresponding to increasing t values that can be processed into animations.
Polyhedral diagrams can be made with polyhedra of any desired shape, not just tetrahedra or octahedra. For zeolite drawings, it is also possible to make the 'polyhedron' of tetrahedral ions about the center of the cages.
The program can read structural input from CIF, CSD, GSAS, SCHAKAL, and SHELX formats, as well as its own native format. In this way, the crystallographic data for complicated structures do not have to be retyped. Fourier maps may be input in the grd format from GSAS, the stf, m80 and m81 formats of JANA, as well as the Gfourier output of Fullprof, and calculated electron density distributions or ELF from Wien2k, VASP and ELK. Alternatively, if structure factors are available in CIF format, DRAWxtl will compute the Fourier map.
The program also outputs a table of bond distances from each of the atoms in the asymmetric unit to all other atoms. The full set of symmetry operators are used in this calculation, with distances less than a specified limit (default 3.5 Å) written to the listing file. This output can be used to check that input parameters are valid. For modulated structures, the minimum, maximum and average values for the bond length are tabulated. For anisotropic atoms, the eigenvalues (RMS amplitudes) and eigenvectors for the ellipsoids are computed and listed.
This program is written in highly portable C/C++ and will run on a wide variety of machines including 386- to Pentium4-based PC's, Macintoshes, high-end workstations, and VMS systems. The only requirements are a floating-point coprocessor for PC's and Mac's, and a C compiler for other platforms, although precompiled executables are available for MS Windows, OS X and sometimes for a number of UNIX machines.
DRAWxtl is available with complete source code, and is free to anyone under the terms of version 2 (exactly) of the GNU General Public License. We do hold copyright on the code, and like any other piece of intellectual property, we ask that you respect our rights.
In the program, color is represented in symbolic form, and must be one of the color names from POV's "colors.inc" file, which may be modified to define custom colors. The color names and associated RGB values are listed in Table I, and sorted by RGB values in Table II (In the graphical user interface of version 5.x, these colors are selectable from a drop-down menu). Any of these colors may be made transparent by appending the phrase "filter xx" after it, where xx is a number from 0.0 to 1.0. (The larger the value of xx, the more transparent will be the entity). Note that transparency is currently not available in the on-screen OpenGL view.
The maximum line length is 255 characters - anything beyond that is silently ignored. Each line of the input file is preceded by a character sequence that describes the type of information, as follows:
| aimsurf | name number filename color | causes the program to read from the given file a precalculated surface mesh to display at the position of the specified atom. The file must be in the format used by the aim program (part of the WIEN2k program suite) for calculating Bader surfaces of atoms according to the AIM concept. (The calculated surface should cover the whole range of 0 to pi in theta and 0 to 2pi in phi, as no symmetry expansion is performed). The rendering style can be 'dots', 'mesh' or 'solid'. |
| arrow | xp yp zp xc yc zc length diameter color | defines the position in fractional coordinates (xp,yp,zp) of the nuclear cell, the components (xc,yc,zc) of the spin vector, and the length, diameter, and color of the arrow. The reference direction for xc is parallel to direct space a, yc is parallel to (a X b) X a, and the reference direction for zc is perpendicular to xc X yc. The only symmetry elements used in placing arrows are the translations described by the mag_trans command below. |
| atom | name number x y z | defines the atoms. The 1- to 4-character name will be used on the commands that describe the objects to be created, the number is to identify which atom of this type, and x y z are the fractional coordinates in the unit cell. For special positions, where to coordinate is given by a fraction such as 1/4, the string '1/4' may be entered rather than 0.25. |
| average | causes the program to draw the average structure of an incommensurately modulated crystal even if information about positional or occupancy modulation is available in the CIF. | |
| axislines | width color | defines the width and color of the lines that depict the principal axes of ellipsoids. The color defaults to dark gray (Gray20). If this command is not given, any ellipsoids will be drawn with principal axes of 0.00015 times the overall scale factor, which should normally be appropriate. |
| background | color | defines the background color of the VRML and POV scenes |
| bestplane | number name1 name2 ... nameN width height color | causes the program to calculate the best fitting plane through a set of atoms, where 'number' is the number of unique atom names (name and number, e.g. C8) name1 to nameN in the list. The plane is drawn as a rectangle of dimensions 'width' X 'height' in the given color. |
| betaij | name number color | defines the anisotropic thermal coefficients for an atom and color of the ellipsoid. The name and number should correspond to the atom input described above. In the POV version of the program, the principal ellipses are drawn in black. The ellipses will, of course, be invisible if the ellipsoid is also black. |
| bij or Bij | name color | defines the anisotropic thermal coefficients for an atom and the color of the ellipsoid to be drawn. The name and number should correspond to the atom input described above. |
| bond | name1 name2 radius min max color | where name1 and name2 indicate the types of atoms to be connected by a bond, radius is the radius of the resulting cylinder, and the minimum and maximum lengths are given in the same units as the unit cell. |
| bounds | xlim ylim zlim | defines X-, Y- and Z-limits of the view box in Angstrom (defaults to -10..10 Angstrom around the center). This information may also be given with the -b command-line switch. |
| box | radius color | defines the radius and color of the cylinders that form the unit cell boundary. If radius is 0.0, plotting of the unit cell is suppressed. The radius of the cylinders will be scaled with the size of the drawing. The default size is 0.02. |
| cell | a b c alpha beta gamma | unit-cell lengths and angles. If no angles are listed, they are assumed to be the fixed values for the symmetry class. |
| clip | xmin xmax ymin ymax zmin zmax |
defines a-,b-,c- cliping range in fractions of the axes. Any bonds extending
beyond these limits will be cut off at half length. This is to be used in
conjunction with the pack keyword to produce 'dangling' bonds in the display of framework structures. |
| cutout | color |
(used only for POV) sets the POV generation of thermal ellipsoids to have one octant removed, as in the program ORTEP. If this command is not given, all ellipsoids will be complete. The color is for the planes that describe the edges of the cutout. N.B. In Version 2.2, there is a bug that sometimes places the cutout octant in the rear of the ellipsoid. |
| dash | number name1 name2 radius min max color | draws a dashed bond between atoms 'name1' and 'name2' if their distance is between the given minimum and maximum values. If the 'number' of segments is omitted, it defaults to 5 as in previous versions. |
| depthcue | factor | causes thickness of edges to decrease with increasimg distance from the viewer |
| edges | radius color | defines the thickness and color of cylinders along the edges of polyhedra that may be used to emphasize the faces. The radius of these cylinders will also be scaled with the size of the drawing. By default, black edges of size 0.02 will be drawn. |
| ellipcolor | name number color | defines the color for ellipsoids when the thermal ellipsoid information has been read from a CIF, GSAS, SCHAKAL or SHELX import or inline file. The name and number must match the identification information in the input file. The parameter number may be an asterisk (*) to indicate all atoms with that name. In addition, these input lines must be after the import or inline command. |
| ellipsoids | probability | sets the size of the ellipsoid such that that fraction of the electron density is contained within the bounding surface. Use either 0.50 or 50 to get the standard (default) 50% ellipsoids. |
| finish | ambient diffuse specular roughness | defines parameters for the POV lighting functions that are applied to all surfaces. Suggested values are 0.7 0.3 0.08 0.01 to reduce harsh contrasts that can result from the default material properties in POV. |
| frame | comment | similar to 'end', marks the division between two sets of input that are to be superimposed in a single output file. Each frame must have a complete set of 'atom' lines, and lines describing the objects such as bonds, polyhedra, spheres etc. to be created in this frame. Distinct packing ranges and space groups are optional. All other parameters are global and apply to all frames. A prime example of this command would be to draw structures with adsorbed molecules with symmetry lower than the cage in which it resides. Another option is to draw ball-and-stick and polyhedral pictures in side-by-side unit cells. |
| import |
cif filename datablock
csd filename (or fdat filename) discus filename elk filename(or exciting filename) gsas filename phasenumber pcr filename phasenumber schakal filename shelx filename wien2k filename |
causes the program to read structural information from an external file.
filetype defines the format of that file, and filename is the name of the
file. Import filters have been written for the CIF, DISCUS, FDAT (Cambridge Structure
Database=CSD), GSAS, PCR (Fullprof), SCHAKAL, SHELX, WIEN2k and ELK/Exciting formats. For GSAS and PCR format, the number of the phase should also be given, while for CIF, the number of the desired datablock may be entered. From these files, the atomic coordinates, thermal parameters, unit cell, and space group (CIF, FDAT, GSAS and SCHAKAL formats only) will be read. To turn on ellipsoid output, and to set colors for the ellipsoids, use the ellipcolor command. On import, atom names of the form Si3A are rearranged to give SiA with a number of 3. |
| inline |
cif
csd (or fdat) schakal shelx wien2k |
is similar to import, except that the foreign input information is included in the DRAWxtl input file in the lines immediately following this command. This form presently works for CIF, FDAT, CIF, SCHAKAL, SHELX and WIEN2k data. To turn on ellipsoid output, and to set colors for the ellipsoids, use the ellipcolor command. For SHELX files, a suitable spgr command is also required. |
| labelscale | size | changes the relative size of the labeltext entities. The default value is 1.0. |
| labeltext | x y z | plots the given string at the specified position given in fractional coordinates. |
| list | maxdist | causes the program to list bond distances up to 'maxdist' in the preliminary scan. If this command is not given, 'maxdist' defaults to 3.5 Angstrom. |
| lonepair | name number distance radius1 radius2 color | causes the program to generate the desired number (either 1 or 2) of conical shapes representing free electron pairs extending from atom 'name', where distance is the length of the cone, radius1 is the size of the tip, and radius2 is the size of its spherical end cap. |
| lookat | u1 u2 u3 v1 v2 v3 | causes the program to select an orientation such that vector u is towards the viewer, and the projection of vector v is vertical. This command overrides any view command, or the -v switch on the command line. |
| mag_trans | Aa Ab Ac Ba Bb Bc Ca Cb Cc | describes the relationship between the magnetic and nuclear unit cells. In this notation, the upper-case letter states which of the magnetic axes is being described, and the lower-case letter corresponds to the nuclear cell axis. This matrix defaults to the identity. |
| magnification | factor | sets the factor to modify the overall scaling is case the automatic value is not correct. This command matches the -m command line switch. |
| mapcalclimits | xmin max ymin ymax zmin zmax | describes the region of direct space (in fractional coordinates) for which the fourier map has been calculated. Map formats that are self-documenting such as Fullprof and Jana do not need this line. For other types, 0 to 1 in all three directions will be assumed by default. |
| mapcontour | level style color | defines a new contour at 'level'. The style can be either 'mesh' or 'solid'. |
| mapcontour2d | lower step upper color | defines a new set of 2d contours beginning at 'lower' with 'step' between contours. No contours beyond 'upper' will be drawn. The color is set by the 'color' parameter. See the mapregion command for how to set 2d mode. Contours planes drawn by this command must be parallel to a face of the unit cell. See the mapslice command for a general solution. |
| mapread | maptype filename calctype :resolution | reads a Fourier map of type 'maptype' from the file named 'filename'. At present, GSAS-style (maptype=grd), JANA200x-style (maptype=stf), WIEN2k (maptype=w2k), VASP (mapstyle=vsp), FullProf (GFOURIER output, maptype=flp), and O format (maptype=dn6) electron density maps are read, as are electron density and ELF files from the FP-LAPW programs ELK and Exciting (maptype=exc). If a SHELX/CIF-style Fo/Fc file (maptype=fcf) or a JANA-style M80 file (maptype=m80) is given, the electron density is calculated during the initial read, which may take a few seconds. Both A/B and Fo/phi data formats (Shelx commands LIST3 and LIST6) are supported. The calctype may be 'Fo', 'Fc', 'Fo-Fc', '2Fo-Fc'. or 'Fo2' (Patterson) to indicate the type of map to calculate. If this parameter is not given, an Fo map is calculated. If the 'resolution' in steps per cell unit is not given, it defaults to 4. |
| mapregion | xmin xmax ymin ymax zmin zmax | describes the region of direct space (in fractional coordinates) for which the map is to be displayed. If not entered, these values default to those of the mapcalclimits command, or 0 to 1 in all directions. If the difference between minimum and maximum for one direction is zero, a 2D map will be plotted in the plane corresponding to the other two coordinates. |
| mapslice | px py pz nx ny nz type | describes a planar slice through a fourier map at the location given by the coordinates px,py,pz of a point in the plane and in the orientation determined by the plane normal nx,ny,nz. Possible type values are 1 (contoured slice), 2 (solid, color-coded blue to red) or 3 (solid, black to white). |
| molcomp | dist | causes any incomplete molecules in the display box to be completed. The value of dist defines the maximum intramolecular distance. Caution: If this distance is greater than any intermolecular distance, or if the material is not molecular, the display list will overflow. |
| nolabels | removes all axis labels from the output diagrams | |
| noshadow | causes objects in the POV file not to cast shadows | |
| occupancy | name average minimum | defines the occupancy of the named site in the average structure of a modulated system, and the occupancy threshold for including individual copies in a plot of the modulated structure. Use a negative value for the atomic radius on the sphere command to scale atom sizes by their individual site occupancies. |
| origin | xcenter ycenter zcenter | defines center of view box in crystal coordinates (defaults to 0.5 0.5 0.5). This command is the same as the -o command-line switch. |
| orthographic | causes the camera to be changed from the normal perspective view to an orthographic projection | |
| pack | xmin xmax ymin ymax zmin zmax | defines a-,b-,c- plotting range in fractions of the axes, similar to the PLUTO (Motherwell & Clegg 1978)) PACK RANGE command (this is especially useful for highly oblique cells, where the orthorhombic view box does not always give satisfactory results). This command is the same as the -p command-line switch. |
| phaseshift | value1 value2 value3 | defines the initial phases t_n of the n'th modulation wave in a modulated structure |
| phong | value size |
(used only for POV) defines the amount of Phong highlighting on spheres and ellipsoids. The value ranges between 0.0 and 1.0, where 0.0 gives no highlight, and 1.0 causes complete saturation at the center of the highlight. The size ranges from 1.0 (very dull) to 250 highly) polished). The default quantities are 0.1 and 1.0, which gives a large, dull highlight. If value is 0.0, the image can be rendered much more quickly. |
| plane | name length color | defines the center of a plane group, such as CO3 that is to be drawn in a structure, where name is the name of the atom at the center and length is the maximum distance to coordinating anions. No atoms that are mentioned in polysz commands will be considered as the corners of a plane. |
| polyedge | name radius color | defines the thickness and color of cylinders used to emphasize the faces along the edges of polyhedra for atom 'name'. The radius of these cylinders will also be scaled with the size of the drawing. |
| polytoler | factor | defines the maximum deviation of the vertices of a polygonal face from their common plane. This command should not be used for standard structures as it can cause severe distortions in the generated polyhedra. Its sole purpose is the regularization of nearly perfect polyhedra, such as the slightly bent pentagonal faces of imperfect pentagondodecahedra that would otherwise be -correctly - depicted as adjoining triangles and trapezoids. |
| polysz | name length color | defines a polyhedron, where name is the name of an atom at the center of a polyhedron and length is the maximum length of distances to atoms that are to be considered as the vertices of the polyhedron. No atoms that are mentioned in polysz or plane commands will be considered as the vertices of a polyhedron. The polyhedra can be of any desired complexity. |
| polyvert | name1 name2 length color | defines a polyhedron, where name1 is the name of an atom at the center of a polyhedron and length is the maximum length of distances to atoms of type name2 that are to be considered as the vertices of the polyhedron. |
| qvector | value1 value2 value3 | defines the components of the wave vector q for a modulated structure |
| rem | text | Any line preceded by this command is ignored. |
| shell | name min max color | defines a polyhedral hull, where 'name' is the name of an atom at the center and 'min' and 'max' define the minimum and maximum distances for atoms to be considered vertices of the coordination polyhedron. |
| slab | a b c alpha beta gamma xoff yoff zoff xrot yrot zrot flag | defines a (possibly oblique) cutout box of the specified axis lengths and angles that is offset by xoff,yoff zoff from the origin of the structure and rotated at angles xrot yrot zrot relative to it. If flag is set to 1, any part of the structure outside the box is deleted. If flag is 2, the outline of the box is overlaid on the unchanged image to allow accurate placement of the cutout box. |
| spgp, spgr, sgrp | symbol |
Space Group name consisting of the Bravais lattice symbol (must be upper case)
followed by a space, the elements parallel to the first axis followed by a
space, etc. Examples are I 41/a m d, P 21/n, I a 3 d, P b n m, etc. The
generators will always select the origin choice with a center of symmetry at
the origin. Furthermore, all monoclinic cells will have the unique axis
parallel to the b axis, unless the full symbol is used, i.e. P 1 1 21/n
describes a monoclinic cell with c as the unique axis. N.B.: Rhombohedral space groups must be represented in the hexagonal form. |
| sphere |
name radius color or name number radius color |
where name is a one- or two-character symbol of the atom type, radius is the radius of the sphere in Angstrom, and color is the color of the sphere to be drawn. If the first form is used, all atoms with that name will be drawn. The second form restricts the command to the given name and number only. |
|
title, titl
|
text
|
General description of the structure - this line may appear anywhere in the file, but is generally first. |
| uij, Uij | name number u color | defines the anisotropic thermal coefficients for an atom and color of the ellipsoid. The name and number should correspond to the atom input described above. |
| values | name number (or *) radius | defines additional atomic properties for the given element or individual atom. Currently the only supported property is the van der Waals radius to be used in cavity calculations. (see the voids keyword). |
| vectors | posx posy posz | turns on the orientation vector triple at a corner of the diagram. If the position of the triple is omitted, it will be calculated by the program. |
| view | xrot yrot zrot | where xrot, yrot and zrot are view rotation angles in Cartesian space. These 0values correspond to a rotation of xrot about the x axis, followed by a rotation of yrot about the (new) y axis, and, a rotation of zrot about the (new) z axis. |
| voids | method probe_radius gridx gridy gridz color | causes cavities in the structure to be determined using the given method and probe radius (e.g. 1.4 for a water molecule). gridx, gridy and gridz determine the resolution of the grid used for subdividing the unit cell. Currently supported methods are 1 for a slow but reliable, sequential test at all gridpoints, 2 for using the MSMS program of Sanner, and 3 for a pseudorandom sampling of points. Methods 2 and 3 should be considered experimental. |
| vrml1 | causes the VRML output to be written in VRML-1 syntax instead of the default VRML-2. (NOTE that versions before 4.0 wrote VRML1 by default) | |
| vrml97 (or vrml2) | is supported for backward compatibility in version 4.x, where VRML97 is the default format. In earlier versions, it causes the VRML output to be written in VRML97 (VRML-2) syntax instead of the their default of VRML-1. | |
| x3d | causes VRML output to be written in X3D format (using the 'VRML classic' encoding) with the filename ending in .x3dv | |
| xyzoff | u1 u2 u3 |
causes all atom coordinates to be shifted by -u. This command is used whenever the origin defined for a structure does not conform to the standard origin selected by the space-group generator. |
| end END | The last line of a file that is read. Any information past this point will be ignored. |
| -a | autolabel (label all atoms) | |
| -A | start end step | autogenerate a sequence of POV files for a modulated structure by varying the t value from start to end with stepsize step |
| -b | xlim ylim zlim | defines X-, Y- and Z-limits of the view box in angstroms (defaults to -10..10 Angstrom around center) |
| -c | expands the VRML output by adding comments. This option should not be used for any VRML files placed in a Web site. | |
| -C | places three orthographic and three perspective cameras (viewpoints) along the crystallographic axes in the VRML output. The default is a single perspective camera. Select this multiple-camera option with caution, as not all VRML viewers support it. At this writing, the Live3D viewer in Netscape fails with multi-camera drawings, and the current version of VRweb for Windows displays the drawing correctly, but the center of rotation is incorrectly placed. The final Unix version (1.5) of VRWeb is known to work correctly. | |
| -F | mapfile | read fourier map from file (GSAS only, for the EXPGUI interface) |
| -G | suppresses the interactive graphics window of version 4.x to allow commandline or batch mode operation as in earlier versions. | |
| -h ? | displays usage information | -H | suppresses the help message describing keyboard shortcuts in the interactive display window of version 4.x. |
| -m | factor | changes the magnification factor for POV and VRML diagrams in case the initial size is not correct (defaults to 1.0) |
| -M | executable | define path to the MSMS executable for molecular surface computations |
| -n | suppresses plotting of unit cell box | |
| -o | xcenter ycenter zcenter | defines center of view box in crystal coordinates (defaults to 0.5 0.5 0.5) |
| -O | select orthographic projection | |
| -p | ymin xmax ymin ymax zmin zmax | defines a-,b-,c- plotting range in fractions of the axes, similar to the PLUTO (Motherwell & Clegg 1978) PACK RANGE command (this is especially useful for hexagonal cells, where the orthorhombic view box does not always give satisfactory results) |
| -s | flag distance | stereo image generation (requires POVray 3.7). flag=1 for cross-eyed viewing, distance is eye separation |
| -S | flag distance | stereo image generation (requires POVray 3.5 with unofficial StereoPOV patch) |
| -v | xangle yangle zangle | defines view rotation angles around the axes of the Cartesian view coordinate system (equivalent to the view keyword) (defaults to 0 0 0) |
| -u | display a orientation vector triple at the edge of the diagram. If this switch is not used, the axes are labeled. |
title Buckyball with balls and sticks cell 14.16 14.16 14.16 pack -.3 .3 -.3 .3 -.3 .3 spgp F m 3 sphere c 0.4 Red filter 0.3 bond c c 0.1 1.2 1.5 Gray30 atom c 1 0.04908 0.00000 0.24510 atom c 2 0.10028 0.08284 0.21346 atom c 3 0.18313 0.05120 0.16226 origin 0 0 0 magnification 0.7 view -18 0 0 end
POV - Source code for the Persistence of Vision Ray Tracer (POV-Ray) software, user documentation and precompiled executables for several platforms are available through www.povray.org. Code is also available through ftp.povray.org, and a number of mirror sites listed on the web site. At the time of this writing, version 3.6 and a fully functional release candidate of POV 3.7 are available.
VRML - Documentation and viewers for the Virtual Reality Modeling Language are available through www.web3d.org. These files are particularly suitable for viewing across the Internet, therefore, many of the viewers are in the form of plug-ins for popular web browsers. In addition, stand alone viewers such as view3dscene are available. The files produced by DRAWxtl adhere to the VRML V1.0 format, unless the VRML97 or x3d keyword is used.
ASYMPTOTE - Among the interesting features of this technical illustration package is its ability to create PDF files with embedded interactive 3D content. Asymptote is available at sourceforge.net.
Source code for DRAWxtl and executables for OS X and MS Windows are available at:
http://www.lwfinger.net/drawxtl
Linux executables in the form of rpm or deb packages are also available from the online repositories of various distributions. If any users experience difficulties in using or compiling the program, please contact LWF at larry.finger@lwfinger.net.