.TH XDISP 1 "30 May 1989" "Project Riemann"
.SH NAME
xdisp \- X11 3D graphics displayer
.SH SYNOPSIS
\fBxdisp\fR [\fB-display \fIdisplay\fR] [\fB-db\fR] [\fB-vr\fR] [\fB-nd\fR]
[\fB-cl1 \fIcolor\fR] [\fB-cl2 \fIcolor\fR] [\fB-clg \fIcolor\fR]
[\fB-bg \fIcolor\fR] [\fB-t \fIangle\fR] [\fB-e \fIangle\fR] 
[\fB-d \fIdistance\fR] [\fB-fn \fIfont\fR] [\fB-geometry \fIgeometry\fR] 
[\fB-cgeometry \fIgeometry\fR] [\fIfile\fR]
.SH DESCRIPTION
.PP
\fIXdisp\fR is a graphics display program running under X Windows Version 11 
for project Riemann data files.  \fIXdisp\fR reads input from \fIfile\fR, if
it is specified, and otherwise reads input from standard input.  \fIFile\fR is
assumed to be a project Riemann data file describing the curvature lines or 
geodesics on a three-dimensional surface.  \fIXdisp\fR features interactive 
control of the viewer's position in three space (thus allowing
the user to rotate the object), a large degree of user customizability, and
many options.
.PP
\fIXdisp\fR creates two top level X windows.  One, the picture window, contains
the picture of the surface.  The second, the control window, allows the user
interactive control over the display of the surface.  The control window
contains three kinds of controls: slider bars, check boxes, and buttons.  All
three controls are used intuitively by clicking the mouse on top of them.  
The purpose of the different controls is described under the command line
options and X defaults keywords that do the same actions as the controls.
Controls are grayed when it is invalid to manipulate them.  Two key presses are
recognized by \fIxdisp\fR: "q" (quit) and "r" (redraw).  Both of these
key presses can be entered in either the control or picture window.
.PP
Most of this document assumes that \fIxdisp\fR is being used to display a 
three-dimensional surface.  However, when \fIxdisp\fR is used with parameter
space data files, it regresses to a two-dimensional display environment.  With
parameter space files, the viewer position and parallel projection 
specifications are ignored.
.PP
In \fIxdisp\fR the user can think of himself as being a viewer at a certain
position in three space.  The 3D surface always stays in the same
position but the viewer can change his position to view the surface
from different locations.  One can think of there being a viewing coordinate
system.  The viewing coordinate system is simply the world coordinate system 
translated so that the origin of the viewing coordinate system is coincident
with the center of the surface.  The center of the surface is found by finding
the maximum and minimum x, y, and z coordinates in the data file and averaging
the three maximums with their associated minimums.  The viewer 
always looks at the center of the surface.  Both the viewing and world 
coordinate systems are right-handed.
.PP
The viewer's position is specified by angles theta and eta, both of which are
always specified in degrees, and a distance.  Theta is the angle in the 
x-y plane 
of the viewing coordinate system that the viewer is from the positive x-axis.  
Theta is measured counterclockwise when looking onto the x-y plane from the 
positive z-axis.  Thus a
theta of 90 degrees places the viewer in the half plane formed by the positive
y-axis and the z-axis.  Eta is the elevation of the viewer
above or below the x-y plane of the viewing coordinate system.  Thus an eta of
-90 degrees places the viewer on the negative z-axis.  Theta and eta alone 
are enough to
specify a unique line of sight, but to specify a unique point in three space
the distance of the viewer from the viewing coordinate system's origin is 
specified.
.PP
\fIXdisp\fR displays the surface in an X window as follows.  First \fIxdisp\fR
figures out what the surface would look like when seen from the viewer's
position (recall that the viewer always looks at the surface's center).  Then 
\fIxdisp\fR
maps the projected surface into the X window so that the entire projected 
surface is visible and as large as possible.  \fIXdisp\fR does this by 
computing the
bounding box of the surface (the smallest rectangular parallelepiped that 
completely encloses the surface) and mapping the projected surface into the X 
window so
that the projection of this imaginary bounding box is as large as possible but
always at least five pixels inside the picture window border.  Sometimes 
the surface will appear to grow and shrink
as the viewer's position changes but this is just a side-effect of \fIxdisp\fR
making the displayed surface as large as it can.
.PP
\fIXdisp\fR can do both parallel and perspective projections.  In a parallel
projection one can think of the distance of the viewer from the center of the
surface as being infinite.  Therefore, lines that are parallel in the surface
are parallel when projected.  One might think that the further the viewer is 
from the surface, the smaller the displayed surface will be, but this is not
true since \fIxdisp\fR displays the surface as large as it can display it and 
still fit it in the X window.  In perspective projections, the distance of the
viewer from the center of the surface is finite.  In perspective projections
parallel lines in the surface appear to converge in the projected surface at 
vanishing points just as parallel railroad tracks appear to come together to
a single point when one looks down them.  The degree of the perspective effect
grows larger as the distance of the viewer from the surface grows smaller.  
Perspective projections are theoretically more realistic, but parallel 
projections are computationally more efficient (though line drawing tends to 
dominate the computation time) and sometimes look better.
.SH OPTIONS
.TP .5i
\fB-display \fIdisplay\fR
Specifies the display connection to use.  If this option is not specified then
the display connection name is obtained from the DISPLAY environment variable.
See \fIX\fR(1) for more details.
.TP .5i
\fB-db\fR
Turns on debugging mode.  In this mode \fIxdisp\fR disables request and
event buffering (via \fIXSynchronize\fR(3X11)) and outputs event names as events
occur.
.TP .5i
\fB-vr\fR
Turns on verbose debugging mode.  In this mode \fIxdisp\fR outputs the 
transformation matrix and data describing the surface.
.TP .5i
\fB-nd\fR
Turns off drawing.  This option (mnemonic for "no draw") is useful for debugging
when combined with \fB-vr\fR.  It simply causes \fIxdisp\fR to exit before putting the
X windows on the screen.
.TP .5i
\fB-cl1 \fIcolor\fR
Causes curvature lines in direction one to be of color \fIcolor\fR.  Colors in
X can be specified in two ways.  One can specify an English name like "red",
"green", or "MediumSlateBlue."  Or one can specify a pound sign followed by a
string of hexadecimal digits giving the relative intensity of red, green, and 
blue.  For example, "#00FF00" is full intensity green.  See \fIX\fR(1) for more 
details on color specification.
.TP .5i
\fB-cl2 \fIcolor\fR
Causes curvature lines in direction two to be of color \fIcolor\fR.
.TP .5i
\fB-clg \fIcolor\fR
Causes geodesics to be of color \fIcolor\fR.
.TP .5i
\fB-bg \fIcolor\fR
Specifies the background color for the picture window.
.TP .5i
\fB-t \fIangle\fR
Specifies angle theta (in degrees).
.TP .5i
\fB-e \fIangle\fR
Specifies angle eta (in degrees).
.TP .5i
\fB-d \fIdistance\fR
Specifies the distance of the viewer from the center of the surface.  Note that 
this parameter is specified in world coordinate units, \fInot\fR in multiples of
the object size.  If the specified distance is smaller than the object size 
then it is set equal to the object size.  The object size is the distance 
between opposite corners of the bounding box enclosing the surface.
.TP .5i
\fB-fn \fIfont\fR
Specifies the font that is used in the control window.  Fixed and proportionally
spaced fonts work equally well.
.TP .5i
\fB-geometry \fIgeometry\fR
Specifies the position and size of the picture window.  See \fIX\fR(1) for more
information on geometry specifications.
.TP .5i
\fB-cgeometry \fIgeometry\fR
Specifies the position of the control window.  The sizing information is
ignored.  See \fIX\fR(1) for more information on geometry specifications.
.SH X DEFAULTS
\fIXdisp\fR's various parameters can be set from at most four places: the
control window, the command line, the X windows resource database, and 
hard coded program
defaults.  In general, when \fIxdisp\fR starts it sets its parameters as 
follows.  First it checks the command line.  For all parameters not specified
on the command line, \fIxdisp\fR checks the resource database.  For any 
parameters still not specified, \fIxdisp\fR uses hard coded defaults.  This
section focuses on the resource database.
.PP
Values for the resource database are typically specified in the 
file \fI.Xdefaults\fR
in the user's home directory.  This file is typically read when X starts up and
its contents are stored in the X resource database.  The user can use the 
\fIxrdb\fR command with the \fB-load\fR option to reread the \fI.Xdefaults\fR
file into the resource database while X is running.  The format of 
the \fI.Xdefaults\fR file is 
usually "program_name.keyword:string."  See \fIX\fR(1)
and \fIxrdb\fR(1) for more details.  The following keywords can be used to set
the various \fIxdisp\fR parameters.
.TP .5i
\fBColor1: \fIcolor\fR (default: black)
Specifies the color of curvature lines in direction one.
.TP .5i
\fBColor2: \fIcolor\fR (default: black)
Specifies the color of curvature lines in direction two.
.TP .5i
\fBColorGeodesics: \fIcolor\fR (default: black)
Specifies the color used to draw geodesics.
.TP .5i
\fBBackground: \fIcolor\fR (default: white)
Specifies the background color of the picture window.
.TP .5i
\fBConnect1: on \fR|\fB off\fR (default: off)
Specifies whether a line segment should be drawn between the first and
last points of curvature lines in direction one.
.TP .5i
\fBConnect2: on \fR|\fB off\fR (default: off)
Specifies whether a line segment should be drawn between the first and
last points of curvature lines in direction two.
.TP .5i
\fBConnect: on \fR|\fB off\fR (default: off)
Setting this keyword to on is the same as setting \fBConnect1\fR and 
\fBConnect2\fR to on.
.TP .5i
\fBTheta: \fIangle\fR (default: -90)
Specifies the theta angle.
.TP .5i
\fBEta: \fIangle\fR (default: 0)
Specifies the eta angle.
.TP .5i
\fBDistance: \fIdistance\fR (default: five times the object size)
Specifies the distance of the viewer from the center of the surface.  Note that
this keyword, like its command line equivalent, specifies the distance in world
coordinate units, not in multiples of the object size.  If the specified 
distance is smaller than the object size then it is set equal to the object
size.
.TP .5i
\fBPreserveAspectRatio: on \fR|\fB off\fR (default: on)
Specifies whether the aspect ratio of the projected surface is
preserved as the picture window is resized.  Typically, users will want this 
option set to on since it makes the displayed image more realistic.  When this
option is off, \fIxdisp\fR scales the x- and y-axes on the screen independently
so that the displayed image is as large as possible but still fits in the
X window.  The advantage of not preserving the aspect ratio is that it allows
the user to do things like "stretch" spheres into ellipsoids.  Note that objects
are "stretched" in two dimensions, not three.  Also note that 
\fIxdisp\fR assumes that pixels on the screen are square, not rectangular.
.TP .5i
\fBParallelProjection: on \fR|\fB off\fR (default: off)
Specifies whether the projection type is parallel or perspective.
.TP .5i
\fBAutoRedraw: on \fR|\fB off\fR (default: off)
Specifies whether the surface is automatically redrawn after any of the
viewing controls in the control window are changed.
.TP .5i
\fBEquationTitle: on \fR|\fB off\fR (default: off)
If this option is on, \fIxdisp\fR displays the equation of the surface in the 
picture window title bar and icon.  If this 
option is off, \fIxdisp\fR displays the title from the data file in the title 
bar and icon.  Note that some window managers may not display title bars 
or icon text.  A hint: if the entire equation or title is not visible in 
the title bar, then the user can iconify the picture window and see the whole
equation or title in the icon.
.TP .5i
\fBFont: \fIfont\fR (default: 8x13)
Specifies the font to use for control window text.  Fixed and proportionally
spaced fonts work equally well.
.TP .5i
\fBGeometry: \fIgeometry\fR (default: 500x500, user-placed window)
Specifies the position and size of the picture window.  See \fIX\fR(1) for more
information on geometry specifications.
.TP .5i
\fBControlGeometry: \fIgeometry\fR (default: user-placed window)
Specifies the position of the control window.  \fIXdisp\fR ignores the sizing 
information.  The only way to change the control window size is to change the 
font.  See \fIX\fR(1) for more information on geometry specifications.
.SH BUGS
.PP
Because \fIxdisp\fR always displays the entire surface as large as it can, 
the surface appears to grow and shrink some as the user changes the viewer's 
position.
.so author

