V10/vol2/graphics/cmd.ms-1

.so ../ADM/mac
.XX 30 491 "The 10th Edition Raster Graphics System"
.fp 5 T CW	\" T for Typewriter
.de TP	\" An indented paragraph describing some command, tagged with the command name
.IP "\\fT\\$1\\fR" 8
.if \\w'\\fT\\$1\\fR'-7n .br
..
.de CI
.nr Sf \\n(.f
\%\&\\$3\f(CW\\$1\fI\&\\$2\f\\n(Sf
..
.TL
The 10th Edition Raster Graphics System
.AU
Tom Duff
.AI
.MH
.AB
The current (late 1989) state of generating and displaying raster graphics
in Research
.UX
is described.
.AE
.2C
.NH
Introduction
.PP
The Research
.UX
system contains a number of commands to capture, manipulate,
display and record monochrome and full-color raster images.  Three groups of
commands may be identified:
interactive programs that operate on a frame-buffer,
commands that operate on images stored in picture
files (see
.I picfile (5)
or |reference(picfile v10)),
and programs that interface to various graphical I/O devices:
video cameras, scanners, paper plotters, film cameras and video-tape
recorders.
.NH
Video Facilities
.PP
No discussion of our raster graphics software can ignore the
hardware on which it runs.  The hardware available at different
sites will, of course, vary.  For definiteness, and to provide
help for the local audience, this section will discuss the
hardware available in Center 1127's graphics and image processing
laboratory (MH 2C-524) and its neighborhood.  Most other environments
will have hardware that is similar in spirit if different in detail.
.PP
There are seven work stations in 2C-528.  On the day this was written,
five of them had TTY 5620 terminals, one had a Gnot terminal and
one had a SUN-3 workstation computer.  Eventually, most of the 5620's
will be replaced with Gnots.  Each work station also has
a Sony GDM-1901-12 video monitor that displays high-resolution
video signals.
.PP
The room contains other video displays and recorders, including
a Barco video projector in the ceiling, a 35-inch Mitsubishi monitor
at the front of the room, a 19-inch Barco monitor at work station 6,
two small Sony monitors in the video rack next to the audio console,
two Panasonic Super-VHS recorders, a Sony 3/4-inch (U-MATIC) video
player, a multi-standard (SECAM, NTSC, PAL) VHS player, a
Sony BVH-2500 1-inch (SMPTE-C) video tape recorder and a Sony video
camera.
.PP
The video equipment supports at least three incompatible video formats.
High-resolution
rgb video has 1024 scan lines, a 60 hz non-interlaced vertical scan rate,
and transmits red, green and blue information on separate cables with
synchronization pulses superimposed on the green channel.
Low-resolution rgb video has between 480 and 488 scan lines, 30hz
interlaced vertical scan, and separate rgb with sync on green.
NTSC (National Television Standards Committee) video has the same timing
characteristics as low-resolution rgb video, but encodes red, green, blue
and sync into a single signal.
NTSC is the encoding used by American, Canadian and Japanese television
broadcasters, and by almost all video recording and playback equipment
in those countries.
.PP
Various computer terminals generate video in other formats that our
equipment handles with only limited success.  Gnots, 630s,
5620s, Sun terminals, IBM-compatible PCs and Macintoshes all generate
mutually incompatible video.  Their vertical and horizontal scan-rates
differ.  The voltages and impedences of the signals they produce differ.
Their color encodings differ.  Monitors that can display video from all
of these sources are rare, let alone hardware to convert from one format
to another.  For example, the only reliable way to record a signal from
any of these sources is to place a camera in front of a monitor.  The
quality of the resulting recordings is often bad.  It is a black art
to adjust our Barco video projector to handle non-standard signals,
but with a few days notice it can often be done.  Again, the results
are not often as good as one might like \(mi the projector does not
focus as tightly as a monitor and its brightness is limited.  As better
video displays become available our situation will improve.
Table 1 summarizes the equipment available and the
video formats that each supports.
.1C
.KF
.TS
center box;
l| c| c| c| c| c| c.
Equipment	High-res	Low-res	NTSC	Gnot	IBM	PAL/SECAM
	RGB	RGB
=
workstation monitors	\(bu
_
Barco projector	\(bu	\(bu	\(bu	\(bu	maybe	maybe
_
35-inch Mitsubishi 		\(bu	\(bu		\(bu
_
Barco  at work station 6		\(bu	\(bu
_
Sony rack monitors			\(bu
_
Super-VHS recorders			\(bu
_
U-MATIC player			\(bu
_
1-inch recorder			\(bu
_
multi-standard player						\(bu
_
camera		\(bu	\(bu
_
Metheus frame buffers	\(bu
_
ITI frame buffer		\(bu
_
Pixel Machine	\(bu	\(bu
.TE
.sp .3
.ce
\fBTable 1. \fRVideo devices
.SP .5
.KE
.2C
.PP
We have several Metheus 3610 frame buffers (four on
.CW pipe ,
one on
.CW arend ,
one on
.CW encke )
and an Imaging Technology, Inc. (ITI) RGB-512.  All of our
frame buffers store 32 bits at each pixel, one byte each for red, green
blue and alpha.  The 3610's generate high-resolution (1280\(mu1024)
video.  The ITI generates low-resolution (512\(mu480) video that may
be recorded on video tape after conversion to NTSC.  Connected to
.CW sol ,
the Sun-3/160 at work station 1, is an AT&T Pixel Machine with
58 processors.  It can generate either high- or low-resolution video
under software control; the Pixel Machine documentation can tell you how.
.PP
Each piece of video equipment is connected to one of two
video switches.  One switch handles high or low-resolution rgb video.
The other handles NTSC video exclusively.  Under computer control, any
output port may be connected to any input port of the same switch.
The
.CW "vsw [-dcrvpi] [\fIiopair\fP ...]
command controls the video switches.
The switches' inputs and outputs are labelled by single characters
0-9 and a-z.
An
.I iopair
is a pair of characters indicating an input and output to be connected
together.
The flags mean:
.TP -r
operate the rgb switch.
.TP -c
operate the composite (NTSC) switch.
.TP -d
print a description of the switch's inputs and outputs
.TP -p
print a list of iopairs indicating the state of the switch.
.TP -i
initialize the switch to an unknown state.
.TP -v
with
.CW -p
or
.CW -d ,
make the descriptions more verbose.
.LP
The video switch is
.I not
straightforward to use.
It is easy to be confused about what the inputs and outputs are;
always remember that these are from the switch's point of view.
Thus, the input marked
.CW "pixel machine"
is the Pixel Machine's output.
The connections to the video switch have a history of ad hoc undocumented
changes.
.PP
The Sony BVH-2500 video recorder produces very high
quality recordings on 1" video tape.  Since it can overwrite
arbitrary single frames of the tape, it is an ideal machine
on which to record animation.
.PP
Before using a new tape,
you must record (``grind'') time-code on it, numbering
each frame of the tape.
Time-code values are usually denoted by values
of the form
.I hh.mm.ss.ff
(like
.CW 02.43.17.15 ).
The 2500's monitor output, called
.CW 2500.mon
by
.I vsw ,
displays time-code superimposed on the 2500's
output signal.
.PP
To grind time-code, use
.I vsw
to connect the color bar generator
(\fIvsw\fP calls this
.CW cbars )
to the 2500's input, thread up a tape, and manually set the
2500 to record by pushing its
.I record
and
.I play
buttons simultaneously.  Let it go until the tape runs out.
.PP
The
.I 2500
command operates the recorder, reading instructions
from its standard input.  Its instruction set is
moderately complicated; for most uses the following
subset is adequate:
.TP "cue \fIhh.mm.ss.ff
Cue the tape to the given time code.  The
time-code displayed on the 2500's monitor
output may be a few frames off,
but the recorder will be cued to the correct point.
.TP "still mode on
Put the recorder in single-frame record mode.
.TP "still mode off\fP
Put the recorder out of single-frame record mode.
.TP "snap [\fIn\fT]
Record
.I n
frames (default 1) at the current cue point, and
advance the cue point by
.I n
frames.  The recorder must be in single frame mode.
.TP "play
Start playing back from the current cue point.
.TP "stop
Stop the recorder.
.TP "!\fIunix-command
Run the given
.I unix-command
using
.CW /bin/sh .
.PP
We currently have only two sources of digital video that
may be recorded on video tape.  These are the Pixel Machine
and the ITI frame buffer attached to kwee.  To use either
one, you must use
.CW "vsw -r
to patch its output to the NTSC color encoder,
and
.CW "vsw -c
to patch the endcoder's output to the video recorder.
The ITI frame buffer is also useful as a frame-grabber,
capturing its video input in its memory whence it may
be saved in a picture file or otherwise manipulated.
.PP
The ITI is served by an ancient software regime whose
commands all begin with the letters
.CW iti .
.TP "itifbinit -x
Re-initialize the ITI to the state expected by the
rest of the software.  The ITI is often unused for
days at at time, during which its health often
decays.
.CW itifbinit
is its restorative.  The
.CW -x
flag causes its input and output to be synchronized.
This is always a good idea.
.TP itigamma
Load the ITI's color map to correct intensities
for display on CRT monitors.
.TP "itigrab -[gs]
Run the frame-grabber.  The
.CW -g
flag starts the frame-grabber running.
The displayed image will track the ITI's input
video.
.CW -s
stops the frame-grabber, freezing the image.
Unadorned by flags,
.CW grab
starts the frame-grabber and stops it one frame
later.
.TP "itigit \fIpicture-file
Copy the image stored in
.I picture-file
into the ITI.
.TP "itisiv \fIpicture-file
Save the image in the ITI in
.I picture-file .
.PP
Paragraphs needed describing imagitek scanner, henry's document
scanners, matrix qcr, postscript.
.NH
Frame-buffer commands
.PP
A frame buffer is a large memory organized as a two-dimensional array of
pixels.  Our Metheus 3610 frame buffers have 1024 scan lines of 1280 pixels
each.  The ITI frame buffer has 480 lines of 512 pixels.  The coordinate
system has (0,0) in the upper left-hand corner, with x increasing to
the right, and y increasing down.  This apparent weirdness is fairly standard,
since it makes video output happen in row-major order.
.PP
Here we will mostly discuss commands for the Metheus displays.  The corresponding
ITI commands have the same names, but prefixed with the string
.CW iti .
.PP
There are several Metheus frame buffers attached to pipe, named
.CW /dev/om[0-7] .
All of the commands discussed below determine which one to use
by examining the environment variable
.CW FB .
It is often hard to tell what frame buffer is displayed on which monitor
because of the video switch.  The
.CW fbi
(frame buffer identification) command displays each frame buffer's name in it.
.PP
Our frame buffers all have 32 bits per pixel, divided into
four 8-bit channels.  The channel values are normally thought of
as fractions ranging from 0 to 1, although frame buffer commands perversely
refer to them as integers between 0 and 255.
Three of the channels specify the red, green and
blue color components of the image.  The fourth channel, called
.I alpha ,
is used to indicate whether or not the image covers the pixel, and is not
normally displayed.
.I Alpha
is used to control image compositing operations|reference(porter duff compositing digital images).
Fractional values of
.I alpha
describe pixels that the image partly or translucently covers, and
facilitate anti-aliased compositing.
.PP
Each frame buffer contains three 256 entry look-up tables that specify
mappings from the values stored in the red, green and blue channels
to the voltages supplied at the frame buffers' video outputs.
The
.CW "gamma [\fIpower\fP]
command loads these tables are loaded with a function that
inverts the power-law relation between voltage and luminous flux
normally encountered in CRT displays.  Thus, pixel values normally
correspond directly to displayed intensities.
.I Power
is the exponent of the power-law.  The default of 2.3 is adequate
for all our displays.
.PP
Other patterns may be loaded into the color map by
.CW "getmap \fIfile\fP [...]
command, whose arguments are a list of files containing color maps.
On the ITI, the argument `\fT%\fP' refers
to the current content of the frame buffer's color map.  (The Metheuses'
color maps are write-only.)  The functional composition of the specified
color maps is loaded into the frame buffer's color map.
.CW Getmap
searches for files in the current directory and in
.CW /fb/cmap
and
.CW /usr/td/cmap/lib .
A color map file contains 256 records of 3 bytes each, specifying the output
values for the corresponding red, green and blue input values.
The
.CW ranmap
command loads random values into the color map.
.PP
Our frame buffers have the ability to magnify a part of the image, via the
.CW "zoom [\fIamount\fP [\fIx y\fP]]
command.
With three arguments,
.CW zoom
magnifies by
.I amount ,
mapping the point
.I "(x, y)
(default (0,0)) to the upper left-hand corner of the screen.
With no arguments,
.I Amount
defaults to 1.
The Metheuses can magnify by any integral factor from 1 to 16.
The ITI can magnify only by 1 or 2.
.PP
An array of images can be viewed in sequence by zooming and panning
using the
.CW "movie \fIxsize ysize nx ny\fP [\fIdelay\fP]
command.  The arguments are the size of the individual
frames, the number of frames in the array in each
direction, and optionally the number of 60ths of a second
to delay between frames.  The frames must be arranged
boustrophedonically, with alternate rows proceding from
left to right and right to left.  (This is because neither
Metheus nor ITI frame buffers can pan in x and y simultaneously
without glitching.)
.PP
There are a number of commands to load simple patterns into the frame buffer:
.TP "clr [-w \fIx0 y0 x1 y1\fT] [\fIr\fT [\fIg b\fT [\fIalpha\fT]]]
sets all pixels to the given value.  If only
.I r
is given,
.I g
and
.I b
are set to
.I r .
If
.I alpha
is not given, it is set to 255 (completely opaque.)
The
.CW -w
flag restricts attention to pixels inside the window whose upper-left corner is
.I (x0,y0)
and with
.I (x1,y1)
just diagonally outside the lower-right corner.
.TP cbars
displays a color-bars test pattern.  The 8 bars at the top exercise all combinations
of the 3 primary colors.  The 9 patches at the bottom are a logarithmic
(perceptually uniform) grey scale.
.TP "ramp [-w \fIx0 y0 x1 y1\fT] [-v] [[\fIcol0\fT] \fIcol1\fT]
displays a horizontal ramp whose color is
.I col0
at the left
and
.I col1
at the right.
Colors are specified as for
.CW clr
(green and blue default equal to red, alpha defaults to 255).
If
.I col0
defaults to
.CW "0 0 0 255" .
.CW -w
restricts
.CW clr
to the given window.
.CW -v
gives a vertical ramp with
.I col0
at the top
and
.I col1
at the bottom.
.TP "colors [-gfr]
displays a 16 by 16 array of grey-colored (equal red, green and blue) squares in
the middle of the screen with red, green and blue ramps at the top.  This is
mostly useful for examining color maps.  The flags modify the display in small ways.
.CW -r
suppresses the ramps.
.CW -g
suppresses the gaps between the squares.
.CW -f
expands the display to fill the full screen, making the patches non-square and
suppressing the ramps.
.PP
The
.CW xhair
command can be used to examine the contents of the frame buffer.
It is named after the cross-hair that it draws on the screen.  Single
character commands manipulate the cross-hair, magnify the video and
print pixel values.  The commands are
.nf
.ta 8n
\fTh\fP	print the help message
\fTlrud\fP	move left, right, up or down 1 pixel
\fTLRUD\fP	move left, right, up or down 16 pixels
\fT0\fP	move to center of screen (x=256, y=240)
\fT1-8\fP	magnify \(mu1\-8
\fT9\fP	magnify \(mu16
\fTp\fP	print current coordinates and pixel value
\fTP\fP	print pixel after each command (toggle)
\fTm\fP	type coordinates to move to
\fTx\fP	type x coordinate to move to
\fTy\fP	type y coordinate to move to
\fTc\fP	change the crosshair display to a rectangle
\fTs\fP	manipulate other corner of rectangle
\fT^D,q\fP	exit xhair and run command
\fTQ\fP	exit xhair, don't demagnify or run command
\fTX\fP	exit and don't run command
.PP
If
.CW xhair
is given arguments, they represent a command to be executed before exiting,
after making substitutions for any argument whose first character is
.CW % .
The substitutions made are:
.ta 8n
.nf
\fT%r\fP	the current rectangle
\fT%w\fP	the current rectangle
\fT%p\fP	the upper-left corner of the rectangle
\fT%o\fP	the upper-left corner of the rectangle
\fT%c\fP	the lower-right corner of the rectangle
\fT%x\fP	the x coordinate of the upper-left corner
\fT%y\fP	the y coordinate of the upper-left corner
\fT%X\fP	the x coordinate of the lower-right corner
\fT%Y\fP	the y coordinate of the lower-right corner
.NH
Picture file commands
.PP
Most of our raster graphics commands require no special hardware.  They synthesize
images in picture files from textual or other discriptions, they modify images
in picture files, producting results in picture files, or they combine the contents
of several picture files to produce composite images, again storing the result in
a picture file.
.PP
The simplest picture file command is
.CW pcp ,
which takes two picture file names and copies the first onto the second.
Names whose first character is
.CW %
are interpreted specially:
.ta 8n
.nf
\fT%in\fP	read from standard input
\fT%out\fP	write standard output
\fT%0\fP	Metheus frame buffer #0.
\&...
\fT%7\fP	Metheus frame buffer #7.
\fT%iti\fP	ITI frame buffer.
.fi
.PP
.CW Pcp
has a number of options that alter the copied picture:
.TP "-o\ \fIx y
Add
.I "(x,y)
to the picture's window coordinates.
.TP "-w \fIx0\ y0\ x1\ y1
Clip the input picture's window to the given coordinates.
If
.CW -o
and
.CW -w
are both given, the window is clipped before being offset.
.TP "-t\ \fItype
The output picture will have
.CW "TYPE= \fItype" .
.TP "-c\ \fIchannels
The output picture will have
.CW "CHAN=\fIchannels" .
.I Channels
must be one of
.CW m ,
.CW ma ,
.CW rgb ,
.CW rgba ,
.CW mz... ,
.CW maz... ,
.CW rgbz... ,
or
.CW rgbaz... .
Likewise, the input picture must
have
.CW CHAN=
set to one of these possibilities.
If the input has no
.CW a
channel, 255 is used.
If it has no
.CW z...
channels, floating point 0. is used.
Color images are converted to monochrome using the standard
NTSC luminance (\fTa=.30r+.59g+.11b\fP).
Monochrome images are converted to color by \fTr\fP=\fTg\fP=\fTb\fP=\fTm\fP.
.PP
The
.CW lam
command combines any number of images, writing a picture file whose window
is large enough to contain all the windows of its inputs.  The input files
are combined with pixels of later images overwriting earlier ones.  As
this is only really useful if the windows of the input images differ,
each input name may be preceded by
.CI -w "x0 y0 x1 y1
and
.CI -o " x y
options to clip and offset it.
Options
.CI -W " x0 y0 x1 y1
and
.CI -O " x y
clip and offset the output image.
Option
.CI -o " file
specifies the output file name (standard output by default),
and
.CI -c " channels
specifies the output
.CW CHAN= .
.PP
The
.CW posit
and
.CW 3matte
commands combine images using the two- and three-dimensional compositing
operations described in |reference(porter duff compositing digital images)
and |reference(duff composite3d).
Each takes a list of picture file names as arguments, producing a composite
on standard output.  The
.CW -a
option will cause either program to output only the
.CW rgb
channels, suppressing
.CW a
(and
.CW z...
in the case of
.CW 3matte ).
.PP
There is an army of commands to read an image and, under the control of a few
parameters, write a modified image.  These include:
.TP "bwquantize \fIin out
File
.I in
contains a color image or a monochrome image with a colormap.
A gray-level image is written in
.I out ,
using the NTSC luminance formula.
.TP "clip \fIleft right in out
Clip an image horizontally to the limits
.I left
and
.I right .
A picture that does not fill out the limits is filled with black pixels.
.TP "xpand [-s] \fIin out [lo hi [inlo inhi]]
The input picture has its dynamic range adjusted so that pixels in the
range
.I inlo
to
inhi
are mapped to the range
.I lo
to
.I hi
(default 0 to 255).
The default values for
.I inlo
and
.I inhi
are determined per channel by examining the input picture.
The
.CW -s
option causes all channels to be examined together.
.I Lo ,
.I hi ,
.I inlo
and
.I inhi
may have any values whatsoever.  If
.I hi
is smaller than
.I lo ,
pixel values will be inverted, producing a negative image.
Any output pixel that would be mapped outside the range
0\-255 is set to 0 or 255.
.TP "dither \fIin out
Convert a full-color (3 channel) picture to one channel with a color-map
by dithering.
.TP "floyd \fIin out
Convert an 8-bit gray-scale picture to one bit per pixel using a version of the Floyd-Steinberg
error-diffusion method.
.TP "halftone \fIscreen in out
Convert an 8-bit gray-scale picture to one bit using a given half-tone
.I screen .
The available screens are
.KS
.in 2n
.TS
lFCW	l.
ALLEBACH	Allebach's ordered-dither
BAYER	Standard ordered-dither
BLUENOISE	A pebble-screen pattern
CLASSIC	A 3-pixel-wide dot screen
CLASSIC2	Another 3-pixel-wide dot screen
CLASSIC3	A 4-pixel-wide dot screen
CLASSIC4	An 8-pixel-wide dot screen
DIAMOND	Rao and Arce's ordered-dither
LINE	Ulichney's line screen
RING	A concentric ring screen
TILT18	A tilted dot screen
.TE
.KE
.TP "he \fIin out
Histogram equalization: the intensity histogram
of the input image is measured.  The output image
has its contrast altered for maximum use of the
output range, equalizing the histogram
as much as possible.
.TP "hysteresis \fIlow high in out
Pixel values of the input picture below
.I low
are mapped to zero.
Those above
.I high
are mapped to 255.
If
.I low
and
.I high
are not equal, any region
below
.I high
that has any 8-connected neighbors below
.I low
is mapped to zero.
.TP "picaverage \fIweight in1 in2 out
The output picture is a weighted average of the two
input pictures.
.I Weight
determines the fraction of the average contributed by
.I in1 .
.TP "piccat \fTin1 ... out
The input pictures are concatenated one atop another.  The
output has the width of the widest input.
.TP "picjoin \fTin1 ... out
The input pictures are concatenated side by side.  The
output has the height of the highest input.
.TP "adapt \fIin out
Adaptive histogram equalization: each pixel of the output image
is the histogram-equalized value of the center of a 7\(mu7 pixel
window surrouding it in the input image.
.TP "ahe \fIin out
17\(mu17 adaptive histogram equalization.  There should be an option to
.CW adapt
setting the window size.
.TP "clean \fIin out
Bayer-Powell noise removal filter.  If the center pixel of each 3\(mu3
window in the input differs from the average of the other 8 pixels by
more than 64, it is replaced by the periphery-average.  This has the
effect of flattening isolated noise pixels.
.TP "crispen \fIin out
3\(mu3 linear crispening filter.  Convolves the input image with
the kernel
.P1
-1 -1 -1
-1  9 -1
-1 -1 -1
.P2
This is a mild high-pass filter.
.TP "edge \fIin out
3\(mu3 linear edge-detection filter.
Convolves the input image with
the kernel
.P1
-1 -1 -1
-1  8 -1
-1 -1 -1
.P2
This is just the difference between the original image and the output of
.CW crispen .
.TP "edge2 \fIin out
3\(mu3 non-linear edge-detection (Sobel operator) filter.
.TP "extremum \fIin out
3\(mu3 extremum filter.  Replaces the center pixel of each
by the value in the 3\(mu3 window surrounding it that most
differs from it.
.TP "laplace \fIin out
3\(mu3 "Laplacian filter.
Convolves the input image with
the kernel
.P1
 0 -1  0
-1  5 -1
 0 -1  0
.P2
This is a fairly extreme high-pass filter.
.TP "median \fIin out
3\(mu3 median filter.  Each pixel is replaced by the
median of the 3\(mu3 window surrounding it.
.TP "smooth \fIin out
3\(mu3 Bartlett filter.
Convolves the input image with
the kernel
.P1
1/16 2/16 1/16
2/16 4/16 2/16
1/16 2/16 1/16
.P2
This is a moderately strong low-pass filter.
.TP "picreflect \fIin out
Reflect the input picture about its vertical center line.
.TP "quantize \fIin out
Convert a full-color picture to an 8-bit picture with colormap.
This does a much better job than
.CW dither .
It tries to pick an colormap that optimally clusters the input's
colors.
.TP "resample \fInpix in out
Resample the input image to be
.I npix
pixels wide.  The filter used in resampling minimizes both
pre- and post-aliasing.
.TP "transpose \fIinput output
Transpose the input picture.  This is useful in conjunction with
commands that operate on scan-lines, like
.CW resample
or
.CW clip ,
to perform operations on columns instead of rows.
.TP "shear \fIin out angle
Rotate the input image by the given
.I angle
(in degrees).  It's called
.I shear
because it operates by shearing the image 3 times
(horizontally, then vertically, then horizontally).
It fails for angles of 180\(de.
.TP "lx [-o\fIfile\fT] [-A\fIaspect\fT] [-a] [-s\fIscale\fT] [-r\fIrot\fT] [-x\fIxscale\fT] [-y\fIyscale\fT] \fIin\fT
Perform a linear transformation on the input image.
The
.CW -o
option specifies the output file name.  The default is standard output.
The
.CW -A
option specifies the aspect ratio of the pixels.  The default is 1.
The ITI frame-grabber produces images whose pixel aspect-ratio is 1.25.
The
.CW -a
option suppresses the writing of an alpha channel.  Normally
an alpha channel is computed even for input images that don't have one,
since the output picture is often rotated and thus doesn't completely
cover its window.
.IP
The transformation is specified by a sequence of options.  The specified
transformations are combined in the order given to yield a composite transformation.
The relevant options are:
.nf
.ta 8n
\fT-s\fIscale\fR	scale by \fIscale\fR.
\fT-r\fIrot\fR	rotate by \fIrot\fR degrees clockwise.
\fT-x\fIxscale\fR	scale in x by \fIxscale\fR.
\fT-y\fIyscale\fR	scale in y by \fIyscale\fR.
.PP
There are several commands to generate images from
three-dimensional geometric descriptions of various sorts.
Most of these produce
.CW CHAN=rgbaz...
images that may be combined using
.CW 3matte .
In their output files, points at the near clipping plane will be mapped to
points having
.I z=0 ,
and points at the far clipping plane will have
.I z=1 .
.TP "ncpr [-a \fIaspect\fT] [-w \fIx0 y0 x1 y1\fT] [-c \fIrgbaz\fT] \fIinput\fT [\fIoutput\fT]
New Cheezy Polygon Renderer.
.I Output
(default standard output) is the name of the picture file that will contain the rendered
version of the scene described in
.I input ,
a text file specifying a polygonal scene.
The
.CW -a
option sets the pixel aspect-ratio (default 1.)
The
.CW -w
option sets the window of the output picture.
The
.CW -c
option specifies which channels should be written to the output picture.
.IP
The input file contains a sequence of single-letter commands, each with several
numeric parameters.  The commands are:
.IP
\fTv \fIfov near far ex ey ez lx ly lz ux uy uz\fR
.br
Set viewing parameters.
.I Fov
is the angle subtended vertically by the screen at the eye point.
Points whose distance from the eye is not between
.I near
and
.I far
will be clipped away before drawing.  However tempted, do not set
.I near
to zero, lest underflow or divide-check occur.
.I "(ex, ey, ez)
is the coordinate of the eye, the point from which the scene is viewed
and the center of perspective.
.I "(lx, ly, lz)
is a vector pointing from the eye toward the center of the scene.
The point
.I "(lx+ex, ly+ey, lz+ez)
is mapped into the center of the screen.
.I "(ux, uy, uz)
is the up vector, the direction of the zenith.  The point
.I "(lx+ux, ly+uy, lz+uz)
is mapped into a point somewhere above the center of the screen.
.IP
\fTl \fIx y z\fR
.br
Set the direction of the light source to
.I "(x, y, z) .
The light source is ``at infinity'' in the given direction.
.IP
\fTb \fIred green blue alpha\fR
Clear the screen to the given color.
.I Red ,
.I green ,
.I blue
and
.I alpha
should all be between 0 and 255.
.IP
\fTc \fIindex red green blue alpha\fR
Set a color table entry.  Indices into the color table are used
to specify the colors of polygons (see below.)
The table has 500 entries.  Unless reloaded by the
.CW c
command, the first 256 entries contain the 256 shades of gray,
the following 12 entries (256-267) are set to 12 logarithmically
spaced (perceptually equal) gray shades, and the next 20 entries
(268-287) to 20 logarithmically spaced gray shades.
.IP
\fTt \fIx0 y0 z0 x1 y1 z1 x2 y2 z2 c0 c1\fR
.br
Render a triangle with vertices
.I "(x0, y0, z0)" ,
.I "(x1, y1, z1)
and
.I "(x2, y2, z2)" .
On one side its color is
.I c0 ,
on the other it is
.I c1 .
If
.I c0
or
.I c1
is positive, the polygon's color is found in the corresponding color
table entry.  If negative, the color is found by modifying the color
table entry as though the surface were illuminated by a light source
whose direction was specified by the
.CW l
command.
.IP
\fTp \fIc0 c1 x0 y0 z0 x1 y1 z1 ... xn yn zn \fT;\fR
.br
Render a polygon whose color is
.I c0
on one side and
.I c1
on the other.
The polygon's vertices are
.I "(x0, y0, z0)" ,
.I "(x1, y1, z1)" ,...,
.I "(xn, yn, zn)" .
.in -8n
.TP "quad [-a] [-z] [-w \fIx0 y0 x1 y1\fP] \fIin out
.br
Compute an image of a quadric surface.  The
.CW -a
option suppresses writing out the alpha channel.
The
.CW -z
option suppresses writing out the z channel.
The
.CW -w
option specifies the output window.
The input file should contain 34 floating point numbers.
The first ten numbers are the upper triangle of the symmetric
matrix describing the quadratic form (in screen coordinates.)
The next 16 numbers are a matrix that converts screen-space
coordinates into world-space normals for illumination computations.
The next three numbers are the direction of the light source.
The next four numbers are the red, green, blue and alpha of the
surface's color.  The last number is the amount of ambient light
in the environment.
.TP "terrain \fIin out ex ey ez lx ly fov near far
Render a terrain image.
The input file
is a 2-channel picture file containing 16-bit elevation data on a regular grid.
.I "(ex, ey, ez)
is the eye position.
.I "(lx, ly, 0)
is a vector pointing from the eye to the center of the scene.
The up direction is
.I "(0,0,1)" .
.I Fov
is the vertical field-of-view angle.
.I Near
and
.I far
are the distances from the eye to the near and far clipping planes.
.TP "bg \fIr0 g0 b0 r1 g1 b1 out
Generate a background card whose color varies smoothly
from
.I "(r0, g0, b0)
at the top to
.I "(r1, g1, b1)
at the top.
Its z coordinate is set to 2, which is beyond the far clipping plane.
.NH
Animation
.PP
To use a command-based raster graphics system as described here to
for animation requires writing command files to create and record
long sequences of images.  Typical command files contain long sequences
of repeated commands with slowly changing numeric parameters.  Several
sequences starting and ending at different times may be interleaved
to describe overlapping motion.  They are at best tedious and at worst
tricky to generate by hand or using the usual tools.
.PP
.I Moto
is a command generator tailored for an animator's needs.  Its input is
a concise description of the animation to be performed; its output is
a command file suitable for input to
.I sh ,
.I rc
or some other command interpreter.
Its arguments are an optional file name containing a
.I moto
program (default standard input) and list of numeric parameters
that are made available to the program.
.PP
A
.I moto
program consists of a list of groups of commands.  Each block is
guarded by a range of frames.  Here is an example:
.P1
1,5:	pcp this %0
	pcp %0 that
.P2
This generates
.P1
pcp this %0
pcp %0 that
pcp this %0
pcp %0 that
pcp this %0
pcp %0 that
pcp this %0
pcp %0 that
pcp this %0
pcp %0 that
.P2
The command group is repeated for each of frames 1 to 5.
.PP
Groups may contain parameter ranges enclosed in brackets
.CW [] :
.P1
1,5:	pcp frame.[1,5] %0
	echo snap|2500
.P2
This generates:
.P1
pcp frame.1 %0
echo snap|2500
pcp frame.2 %0
echo snap|2500
pcp frame.3 %0
echo snap|2500
pcp frame.4 %0
echo snap|2500
pcp frame.5 %0
echo snap|2500
.P2
.PP
Programs may have multiple groups, each guarded by
a separate range of frames.  For each frame,
.I moto
checks each group and processes those
whose guards include the current frame number.
.PP
Two special guards,
.CW BEGIN
and
.CW END ,
specify actions to be taken before an after processing frames:
.P1
BEGIN:	clr
1,5:	pcp section[1,5] %0
END:	pcp %0 composite
.P2
This generates
.P1
clr
pcp section1 %0
pcp section2 %0
pcp section3 %0
pcp section4 %0
pcp section5 %0
pcp %0 composite
.P2
.LP
.I Moto
allows complex computations inside parameter brackets:
.P1 0
1,10:	clr [127.5*(1-cos([0,360]))]
.P2
This generates
.P1
clr 0
clr 29.82933350233
clr 105.35985734747
clr 191.25
clr 247.3108091502
clr 247.3108091502
clr 191.25
clr 105.35985734747
clr 29.82933350233
clr 0
.P2
.PP
Expressions may include constants and variables.
All values are double-precision floating point numbers.
The operators
.CW = ,
.CW / ,
.CW + ,
.CW -
(both unary and binary),
.CW < ,
.CW > ,
.CW <= ,
.CW >= ,
.CW == ,
.CW != ,
.CW "? :"
and
.CW ! ,
all with their meanings as in C, except that all results
are coerced to
.CW double .
The result of
.CW a%b
is
.CW a-b*(int)(a/b) .
The result of
.CW "a && b
is
.CW "a?b:a .
The result of
.CW "a || b
is
.CW "a?a:b .
The exponentiation operator is
.CW ^ ,
also written
.CW ** .
The expression
.CW [a,b]
variesfrom
.CW a
to
.CW b ,
linearly as the frame number varies between the guards of the
group containing the expression.
The expression
.CW a[b,c]
has the value
.CW a*b+(1-a)*c .
Its value varies from
.CW b
to
.CW c
as
.CW a
varies from 0 to 1.
The expression
.CW $i
has the value of the
.CW i 'th
parameter following the file name on
.I moto 's
command line.
.PP
The precedence of operators is, from lowest to highest:
.P1
=
? :
||
&&
< <= == != > >=
+ -
* / %
[ ]
^ **
- \fR(unary)\fP ! $
.P2
Expressions may be parenthesized to alter precedence.
.PP
The following math functions are available:
.QS
.ft CW
fabs floor ceil sqrt hypot sin cos tan
asin acos atan exp log log10 sinh cosh tanh
gamma besj0 besj1 besjn besy0 besy1 besyn
.ft R
.QE
All math functions are as described in the C library,
except that angles are measured in degrees rather than
radians for the trig and inverse trig functions.
In addition
.CW hypot
may have two or three arguments,
.CW atan
may take two arguments instead of one,
and may also be spelled
.CW atan2 .
.PP
For parameterization, and to allow even more complex
computations,
.I moto
has variables, assignment and computation groups.
A computation group is distinguished from a command group
by having a double colon separating its guard from the
expressions to be computed:
.P1 0
BEGIN::	n=5
1,n::	x=512*sin([0,90])
1,n:	pcp -w 0 0 [x] 488 pic.[1,n] %0
.P2
This generates
.P1 0
pcp -w 0 0 0 488 pic.1 %0
pcp -w 0 0 195.93391737093 488 pic.2 %0
pcp -w 0 0 362.03867196751 488 pic.3 %0
pcp -w 0 0 473.02632064578 488 pic.4 %0
pcp -w 0 0 512 488 pic.5 %0
.P2
.PP
Upon occasion it is useful to split
.I moto 's
output into several files, under program control.
A group that is separated from its guards by an at-sign
.CW @
instead of a colon names a file into which
subsequent output is to be written.  For example,
.P1
1,5@	file.[1,5]
1,5:	This is file.[1,5].
.P2
creates 5 files, with names
\fTfile.1\fR,...,\fTfile.5\fR.
Each file's contents will announce its name.
.PP
As is true for all sufficiently large programs,
.I moto
has a shell escape.  A group separated from its
guards by an exclamation point
.CW !
instead of a colon has its result text interpreted
by a subshell.
.PP
Finally, Figure 1 shows an example taken from a real application.
This
.I moto
program composites the frames of a short movie showing
two flying saucers, flying in formation, chased by a third,
racing over New Jersey.  The flying
saucer images (files
.CW run.*
and
.CW chase.* )
and the background (file
.CW bg )
have been computed in advance.  In the composite, the
.CW run.*
images are re-used, staggered in time, to do the
first two saucers.
.1C
.KF
.P1
BEGIN::	 nchase=108
	 nrun=195
	 d1=12
	 d2=32
	 end=nrun+d2
	 chase=end-nchase+1
1,end:	inputs=				# empty the input list
1,nrun:	inputs="$inputs run.[1,nrun]"	# add the first saucer to the input list
1+d1,nrun+d1:
	inp="$inputs run.[1,nrun]"	# add the second saucer
chase,end:
	inp="$inputs chase.[1,nchase]"	# add the chasing saucer
1,end:
	3matte -a $inp bg frame.[1,end]	# create the composite
.P2
.ce
\fBFigure 1.\fP  Flying saucer script
.KE
.2C
.NH
References
.PP
|reference_placement