\documentstyle [11pt]{article}
\textwidth=6.0in
\textheight=9.0in
\topmargin=-0.5in
\oddsidemargin=0.5in
\renewcommand{\baselinestretch}{1.5}
\begin{document}
 
\begin{center}
{\bf C3DCON: A Stereo 3D Electron Density Cage Contouring}\\
{\bf and Atomic Structure Plotting Program}\\
\vspace*{0.1in}
{\em Rong-Sheng Zhou, Martha M. Teeter}\\
Department of Chemistry\\
Boston College\\
Chestnut Hill, MA 02167\\
\vspace*{0.1in}
{\em Robert L. Snyder}\\
New York State College of Ceramics\\
Alfred, NY 14802\\
\end{center}
 
\vspace*{0.5in}
\begin{center}
{\bf \underline{Abstract}}\\
\end{center}

A FORTRAN computer program is described which does 3d electron density
cage contouring together with atomic structure model display on a 
Tektronix-4100 command graphics terminal hosted to a Vax/VMS computer.
The program also supports stick-ball visualization of the model, on-line 
manipulation of the display, and convenient hardcopy output. Such a 
program is useful in a research environment where an expensive graphics 
workstation is not readily available and hardcopies of publication 
quality are often desired.

\begin{center}
{\bf \underline{Introduction}}\\
\end{center}
 
{\bf C3DCON} is a user-friendly interactive 3d electron density cage
contouring and atomic structure model drawing program. It is written 
in FORTRAN-77 and designed to run on a Vax/VMS computer and display 
principally on a Tektronix-4100 graphics command language serial terminal 
(Tek4100). A menu and form driven dialogue scheme is used to setup plots 
on any DEC VT100 compatible text terminal. 

The primary motivation for writing C3DCON was to be able to do real-time 
3d electron density contouring using equipment common to most diffraction 
laboratories rather than a program like FRODO (Jones, 1985) that runs only 
on a more specialized and costly graphics workstation such as an Evans \& 
Sutherland PS390. The implementation of C3DCON's model drawing capability 
was motivated partially by the frustration the author has experienced
and witnessed over years with ORTEP (Johnson, 1965) in visualizing atomic
models when the thermal ellipsoids were never the interest.
Figure 1,2,3 show examples of stereo graphs produced from C3DCON on a DEC 
LN03 PostScript laser printer. Each of these plots takes about 1 min 
run-time to draw on a Tektronix 4207 hosted to a DEC MicroVax II.

\begin{center}
{\bf \underline{Procedure and Function}}\\
\end{center}
(1) {\em Contouring}
 
C3DCON resembles FRODO in its functionality in contouring. 
The 3d density cage contours are accomplished by 2d contouring layer after 
layer along the crystallographic {\em a,b,c} axes of the unit cell, using 
a single contour line tracing algorithm (Sutcliffe, 1980). The 3d cage 
contours are then parallel-projected to the 2d viewing plane after optional 
3d clipping. To speed up contouring, C3DCON requires the input 3d electron 
density file to be pre-treated by a subsidiary routine MAPACK, which reads 
the floating point density values sampled on the 3d grid, converts them to 
the 8-bit byte integers dynamically, and then packs them layer by layer 
along the {\em a,b,c} axes consecutively for fast direct data access 
during contouring.
 
Up to four contour levels from a single file or four different density 
files are allowed to be displayed on the same viewing screen.
They can be rendered with four different colors, line types and line
thicknesses. The desired contour region is specified by a triclinic
box whose faces are parallel to the crystallographic axes with the 
center of the display located either by arbitrary physical coordinates 
or on an atom of interest in the structure model. The input map grid
can be of a {\em complete} or an {\em incomplete} unit cell. In the 
former case, C3DCON will allow for continuous contouring {\em across} 
the cell boundaries together with structure model overlay using 
crystallographic translation symmetries. This makes it particularly 
convenient to examine the structure model in the vicinity of the cell 
boundaries without specifically computing the Fourier synthesis at 
the region.
 
\begin{flushleft}
(2) {\em Structure Model Drawing}
\end{flushleft}
 
The structure model can be constructed in either a sphere or a triclinic
box of enclosure with a dimension independent of that of the contour box,
but located at the same center of the display used for contouring. A 3d
rectangular clipping box with the desired orientation can then be applied
to the enclosure of the display to visualize such models as a chain or a 
sheet through the structure. C3DCON can essentially read any ASCII atom 
file by user specifying the column format of its atom line in the atom 
file or in the dialogue menu. Provision is made to handle input 
atom files in both fractional and angstrom, orthogonal and non-orthogonal 
coordinates. Only space-group unique symmetry operators are required and
they are read from a symmetry file. C3DCON will search for all possible 
translation symmetries to fill the enclosure of the display from the 
asymmetric unit. Provision is also made to generate symmetry-related 
atoms from any atom(s) in the asymmetric unit using a subset of symmetry 
operators. This may be necessary in visualizing a sublattice or a superlattice.
 
Model connectivity is controlled hierarchically, i.e. hierarchical connection 
classes and groups with their individual bonding distance cutoffs and bond 
types are used to accomplish a variety of bonding requirements from simple 
high symmetry lattices to macromolecules, to disorder models, and to 
multi-model overlay. The current bond types include solid line and 3d 
dash line of different colors and thickness. 

Stick-ball rendering of the model is supported with simulated lighting 
and removal of hidden bonds and surfaces. A variety of balls are 
implemented for a maximum of nine types of atom species. 
Multiple unit cell outline within the enclosure of the display can 
be included with a simple yes or no.
 
An atom ID label can be offset in 3d from the location of the atom to 
improve perspective viewing. {\em In situ} 3d bond distance labeling 
is also provided for selected bonds in the display. 
The design of C3DCON also renders itself as a structure model drawing
routine independent of the presence of an electron density file.
 
\begin{flushleft}
(3) {\em Stereo Viewing}
\end{flushleft}
 
By default, C3DCON aligns the crystallographic {\em a,b}-axes of the
display with the horizontal({\em x}) and vertical({\em y}) axes of the
viewing screen. The {\em c,z}-axes thus point out of the screen using the
right-hand rule. On the mapped 10x8 inch viewing screen of a Tek4100,
stereo pairs are displayed together but separated by 5-inch with the 
left and right eye views rotated around the {\em y}-axis. The same 
arrangement is conveniently sent to the supported hardcopy devices 
when requested.  If a larger plot of a stereo pair or a stereo view 
around other axis are needed, two mono-displays of the pair can be 
constructed separately with the desired orientations and the stereo 
pair is thus obtained.
 
\begin{flushleft}
(4) {\em Dialogue Scheme and On-line Graphics Editing}
\end{flushleft}
 
Non-scroll menu and form driven dialogue is provided by C3DCON on any
VT100 compatible text terminal that supports the ANSI escape and control 
sequences. Random-access setup of all plot parameters is accomplished 
with a set of two letter mnemonics designated to a single or group of 
related parameters succinctly laid out on the screen. Complete on-line 
help on the mnemonics and parameter functions is easily accessible.
A number of DCL-like auxiliary dialogue commands and function keys are 
also implemented to provide additional utilities such as reading and 
writing associated files, spawning sub-process, computing bond distance 
and angle and torsion, etc.
 
By default, C3DCON searches initially for a run file named C3DCON.PAR
in the users directory to set up the plot, and keeps updating it every 
time the user exits from the setup menu. If the run file is not found, 
a set of program-internal default parameters are used to set up the plot
and a new run file will be created initially. An auxiliary dialogue 
command SAVE will save the current setup into or READ will read from 
a different run file. The run file is written as a keyword-oriented 
ASCII file the user may edit, and it contains all the information 
necessary to re-generate the same plot. No additional file or command 
procedure need to be prepared or executed before running C3DCON. 
During screen plotting, CTRL/C interrupt is trapped by C3DCON to allow 
the user to abort an unwanted plot session and get back to the setup menu.
 
On-line interactive graphics editing of the display is implemented on a
Tek4100 with {\em segment graphics} capability. The editing session, when 
invoked upon a completed display, uses a crosshair cursor, a set of 
function keys and optionally a mouse to manipulate the display. 
The current version of C3DCON supports such manipulations as zoom, 
rotation, hiding toggle, stereo/mono display toggle, selective atom
ID labeling and bond connect/break, as well as display of bond distance,
angle, torsion for the selected atoms. The edited display is saved and 
can be sent for hardcopy.
 
\begin{flushleft}
(5) {\em Hardcopy output}
\end{flushleft}
 
C3DCON was designed to link to a graphics library named TEKLIB which was
modeled after a set of Calcomp calls and further developed by the author 
over years to take advantage of modern computers and computer graphics 
devices. With Tek4100 commands as its primary graphics language,
TEKLIB also supports ReGIS graphics and ASCII character-set graphics.
Therefore C3DCON can also be run on a non-Tek4100 terminal to obtain
a hardcopy. The principle of ``{\em What you see on screen is what you get 
on a hardcopy}'' is applied to C3DCON. Parallel to the screen display, 
TEKLIB automatically writes a device independent meta-file in the users 
directory. The meta-file contains all the necessary information for 
reproducing the screen display on a hardcopy. When hardcopy is requested 
with a single key stroke to C3DCON, TEKLIB presents the user with a 
hardcopy page setup menu which will allow for selection of hardcopy 
parameters such as number of copies and target hardcopy device. TEKLIB 
then releases C3DCON by sending a job entry to a system batch queue to 
activate the target hardcopy device driver. The device driver reads the 
device-independent commands and data in the meta-file, converts them to 
device-specific graphics instructions, and then writes them to a scratch 
file. Upon completion of the above process, the scratch file is submitted 
for printing to a system print queue designated to the target hardcopy 
device. Such a hardcopy making scheme, although system-dependent, makes 
hardcopy simple and fast to a regular user. At the moment, hardcopy device 
drivers are provided for PostScript laser printers, Hewlett Packard HPGL 
series and HP7221 series pen plotters, and Present Technology 35mm color 
slide makers. It is a relatively easy task for a programmer to write 
additional hardcopy device drivers of local interest since the driver 
is a standalone program and all of its subroutine calls have been unified 
into a single main program.

In addition, hardcopy output can be redirected easily to a device
eavesdrop-configured to the on-line terminal or its printer port.

\begin{center}
{\bf \underline{Installation}}
\end{center}
 
Upon request with a blank tape and the instructions for writing the tape,
a copy of C3DCON together with all subsidiary programs and installation
notes is available from the first author. C3DCON consists of about 5,000
line of source codes. Its current version is dimensioned to handle 999
atoms and 128x128 map grid layer using FORTRAN PARAMETER statements and
is therefore easily redimensionable. Virtual memory allocation by the 
same version of C3DCON is around 500 pages (512 bytes/page), which is 
less than the default working set size for a regular user on a multi-user 
Vax/VMS. A VMS Command Language Description(CLD) file with provision of 
VMS-type command parameters and qualifiers for running C3DCON is also 
available to install C3DCON into the DCL command table, so that C3DCON 
can be invoked in either normal interactive mode or bypass mode for 
hardcopy shortcut. In the interactive mode, the user can define and 
execute commands such as
\begin{flushleft}
\hspace*{0.25in} \$ TKPLOT == ``C3DCON/TERMINAL=TEKTRONIX''\\
\hspace*{0.25in} \$ TKPLOT/ALLOCATE=(128,1000)/SETUP=COMMON.PAR
\end{flushleft}
while in the bypass mode, for example
\begin{flushleft}
\hspace*{0.25in} \$ HARDCOPY == ``C3DCON/HARDCOPY/DEVICE=HP7550''\\
\hspace*{0.25in} \$ HARDCOPY/SETUP=COMMON.PAR/COPIES=5/PEN\_SPEED=5.
\end{flushleft}
VMS specific system services have been utilized and built in TEKLIB. 
An effort is underway to port TEKLIB to the UNIX environment.

\vspace*{1.0in}
\begin{center}
{\bf \underline{Reference}}
\end{center}
\begin{itemize}

\item Hearn, D. \& Baker, M.P. (1986). {\em Computer Graphics}. 
      Prentice-Hall, Inc.

\item Johnson, K.C. (1965). {\em ORNL-3794}, Oak Ridge National Lab.

\item Jones, T.A. (1985). {\em Methods Enzymol}. {\bf 115}, 157-171.

\item Sutcliffe, D.C. (1980). {\em Mathematical Methods in Computer 
      Graphics and Design}. K.W. Brodlie ed., Academic Press, New York.
\end{itemize}
\end{document}
