MOGUL(1)

NAME
xmogul - render pictures of molecular geometries

SYNOPSIS
xmogul [--init=script] [--noinit] [--device=name] [--movie] [--help] [geometry] [X11-options]

DESCRIPTION
xmogul reads a molecular geometry specification and renders a picture on (by default) an X terminal. xmogul is not too fancy, but can do realistic shading and perspective views, and can create not too terribly huge PostScript renditions of these views. PostScript snapshots of the current view may be made at any time. When used with GhostScript, xmogul can also make frames in GIF, PPM or JPEG format. (These frames can be compiled into MPEG movies with an appropriate encoder tool.) xmogul can read molecular geometries in any format supported by libdmd (see geometry(5)). If the input file is seekable, xmogul provides random access to any of the frames in the file by using a scrollbar. Finally, xmogul can operate without any X display, rendering frames of a movie in a batch environment (see the --device option below.)

OPTIONS

--init=script
    Read script instead of the default initialization script file ``.mogulrc''. script can be `-' to specify standard input. The format of the initialization script is described below. xmogul will attempt to load the initialization script, or ``.mogulrc'', in the current directory or in the path given by the environment variable MOGULPATH, after all of the input options have been processed. If no script can be found, and the --noinit option had not been given, xmogul will load an internal default script.

--noinit
    Start up with a null initialization script. This will prevent any rendering, which might be useful for very large geometries if you want to manually add groups of atoms to a computationally expensive rendering.

--device=name
    Use the device described by name as the default device, instead of opening a window on an X terminal. The possible values of name depend on the devices that have been compiled into xmogul, and may be obtained by giving the --help option. Additional device options may be appended to name as a colon-separated list. See the device options section below for more information about specific device options. When an alternate device is chosen, a single frame of geometry data is rendered on the device, unless the --movie option has been given, in which case all of the frames in the input geometry file are rendered.

--movie
    Render all of the frames in the input geometry. This option does nothing unless the --device option has been used to select an alternate default device.

INPUT DATA FORMAT

xmogul can read molecular geometries in any format supported by libdmd (see geometry(5)).

INITIALIZATION SCRIPT

xmogul use a very simple scripting language to describe features of a molecular geometry plot. The script is executed whenever a new molecular geometry is loaded, either because a new geometry file was opened or a new frame of the current geometry file was selected. The script is line-oriented, with one command per line. The commands are not documented here yet.

WINDOW ACTIONS

The scrollbar at the bottom of xmogul's window controls the frame within the current geometry file. Buttons are provided to rewind, play, stop, and fast forward. Clicking on the left (right) mouse button within the scrollbar region steps by a single frame forward (backward). The scrollbar at the right controls the zoom operation. Press the `zero' button to reset the zoom scale so that the reference position on the scrollbar represents the current camera scale. Within the main window, the left mouse button can be used to orbit the currently displayed geometry, and the middle mouse button performs a panning operation, moving the camera within the plane of the lens (the computer screen).

DEVICE SPECIFIC OPTIONS

Some of the alternate devices and the opions they support are listed here for convenience. --device=ps The Postscript device. All of the rendered frames are collected together into a single file. Options supported:

file=filename
    Write the Postscript file to filename.

psize=width,height
    Generate the plot in an area whose dimensions in millimeters are given by width and height.

plots_per_page=N
    Put N plots on each page (default 1).

--device=ppm|gif|jpeg For the ``ppm'', ``gif'', and ``jpeg'' devices, each frame is written to a file whose name contains the frame number. By default, the file names are ``mogul.frame.suffix'' where frame is the frame number (starting at zero) in the inpout geometry file, and suffix is chosen depending on the particular output format. You can then run the Berkeley MPEG encoder (see mpeg_encode(1)) or a similar encoder in order to compile the frames into a single MPEG video stream. Options supported:

file=filename
    Write the final file to filename, substituting the frame number for each occurance of the string ``%f'' in filename.

size=widthxheight
    Generate a plot whose size in pixels is width by height.

res=dpi
    Generate a plot whose apprent resolution in pixels per inch is dpi.

compress=yes|no
    If yes, use gzip(1) to compress each frame file.

SEE ALSO
geotools(1), mpeg_encode(1), gs(1), geometry(5)

BUGS

This application has some rough edges.  Among them are
    Error messages are not collected for display in a window; many simply get printed to stderr. Communication with the window manager is not implemented yet.

The shading modes are handled at the device level, using algorithms which may be strictly valid only for non-perspective viewer transformations. Highly ``perspectived'' views will therefore have the annoying error that the atoms look suspicisously like flat disks instead of spheres. Also, since the algorithm is device-specific, X11 previews may not be identical to a rendering of the same view. Although the PostScript output is not huge in size, the time it takes to interprept the PostScript might be unbearably long on an older printer if solid atoms are rendered. xmogul is not in any way related to Project Mogul, a top secret NYU program to detect Soviet a-bomb tests using long-range balloons, that the Air Force claims is to blame for the 1947 ``Roswell Incident.''

AUTHOR

xmogul was written by David Deaven while at the Pennsylvania State University, 1987. It was then dredged up in 1992 at the University of California, Berkeley, and hacked into a form suitable for plotting a few figures in a Ph.D. thesis. Finally, it was refined at Ames Laboratory, USDOE, by David Deaven <deaven@ishmael.ameslab.gov>. The present code is (c)1994,1995,1996 David Deaven. PostScript(tm) is a registered trademark of Adobe Systems Inc.