.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