.so ../ADM/mac .XX raster 483 "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)), 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, four of them had TTY 5620 terminals, two had Gnot terminals 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 impedances 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 \(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 (seven 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 pyxis , a four CPU SGI 4D-240, 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 may be connected to any other via a video patch bay in 2C-538 (the .CW alice room.) Alternating rows of the patch bay present video outputs and inputs. If an output and the input immediately below it are not plugged into anything, an internal connection routes one to the other. The patch bay has been layed out so that the most useful configurations require no patch cords. The patch bay is carefully labelled so that its proper use ought to be obvious. .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, available on the video patch bay, displays time-code superimposed on the 2500's output signal. .PP To grind time-code, use the patch bay to connect the color bar generator to the 2500's input, thread up a tape, and manually set the 2500 to record by pushing its .CW REC and .CW 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 .CW kwee . To use either one, you must patch its output to the NTSC color encoder, and patch the encoder'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 output signal to be synchronized to the sync pulses of its input, instead of running from its internal clock. 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 . .NH Other output devices .PP Many modern laser printers and typesetters read data in the PostScript format. .TP "pic2ps [-h \fIheight\fP] [\fIpicture\fP] converts a picture file into encapsulated PostScript, suitable for inclusion in any PostScript document. The .CW -h option specifies the height, in inches, of the output image. It is not often required, as document processors usually insert PostScript illustrations in a scale-independent manner. .PP The .CW alice room contains an Imagitex scanner that can be used to convert photographs to digital form. To use it, place the image to be scanned under the hold-down leaves, slide the leaves to make a window around the section you wish to scan, and use the .I imscan command. .TP "imscan [-s\fIscale\fP] [-l\fIlens\fP] file" . The .CW -l option causes the scanner to use a lens of focal length .I lens inches. The possibilities are 5 (754 dots per inch) and 8 (480 dots per inch); 8 is the default. The .CW -s option sets the sub-sampling .I scale , which can vary from 1 to 9. One pixel in each .I scale by .I scale square will be stored. The default is 4. In conjunction with the default 8-inch lens, this causes scans to be stored at 120 dot-per-inch resolution. .PP There is a high-resolution one-bit-per-pixel Canon document scanner at the back of the graphics lab accessed through the .I cscan command. .TP "cscan [-f\fIx\fP,\fIy\fP] [-fL] [-s\fIseconds\fP] [-v] [\fIfile ...\fP] scans pages into the given files (default, one page onto standard output.) The .CW -f option sets the size of the scan in pixels (400 to the inch); .CW -fL sets double-letter size (11 by 17 inches, the largest possible.) The .CW -s option sets the number of seconds to wait before scanning each page after the first. .PP In the Alice room is a Matrix Instruments QCR digital film recorder. It will record color or black-and-white images in a variety of photographic formats, include 8x10 Polaroid, 4x5 and 35mm. The .I qsnap (1) command will output an image to film. \ \ \ \ \ \ \ .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 seven Metheus frame buffers attached to pipe, named .CW /dev/om[0-6] . 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 connections in the patch bay. 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. A couple of commands manipulate these mappings. .TP "gamma [\fIpower\fP] command loads these tables 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. .TP "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. .I Getmap searches for files in .CW . , then .CW /fb/cmap , then .CW /usr/td/2d/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. .TP ranmap command loads random values into the color map. .PP The .I zoom and .I movie commands support magnification and animation of images. .TP "zoom [\fIamount\fP [\fIx y\fP]] magnifies part of the image. With three arguments, .I 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. .TP "movie \fIxsize ysize nx ny\fP [\fIdelay\fP] views an array of images in sequence by zooming and panning. 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 proceeding 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] [[\fIc0\fT] \fIc1\fT] displays a horizontal ramp whose color is .I c0 at the left and .I c1 at the right. Colors are specified as for .CW clr (green and blue default equal to red, alpha defaults to 255). .I C0 defaults to .CW "0 0 0 255" . .CW -w restricts .CW ramp to the given window. .CW -v gives a vertical ramp with .I c0 at the top and .I c1 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 .I 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 .I 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 .PP The .I mplot command is a version of the standard UNIX .I plot (1) filter that produces output in a Metheus frame buffer. .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 descriptions, they modify images in picture files, producing 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 .I pcp command takes two names of picture files or frame buffers and copies the first onto the second. As with all picture file commands, the special names .CW IN and .CW OUT refer to standard input and standard output. Frame buffers are designated by names that begin with \fT%\fP: .ta 8n .nf \fT%0\fP Metheus frame buffer #0. \&... \fT%9\fP Metheus frame buffer #9. .fi .PP .I 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 be assembled from the given channels of the input picture. In many cases, a request for a channel not found in the input picture will be satisfied by standard conversions. For example, if .I channels includes .CW m , but the input picture has only .CW rgb , a monochrome channel is synthesized by computing NTSC luminance (\fTm=.299r+.587g+.114b\fP). Conversely, .CW rgb will be synthesized from .CW m by lookup in the input's color map, if it has one, or by .CW r=g=b otherwise. If .I channels mentions .CW a and the input has none, 255 is used. If .I channels mentions .CW z... and the input has none, 1.0 (floating point) is used. Any other channel missing in the input is set to zero. .TP "-C\ \fIchannels" Put .CW CHAN=\fIchannels in the output's header. Without this option, the output's .CW CHAN attribute is taken from the .CW -c option, or failing that from the input's .CW CHAN attribute. .CW -C is useful, for example, to create a monochrome (\fTCHAN=m\fP) image from the red channel of a color image using .CW "pcp -cr -Cm" . .PP The .I 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. This is only really useful if the windows of the input images differ. .CI -o " file specifies the output file name (standard output by default). All input images must have the same .CW NCHAN . .PP The .I posit and .I 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 .I 3matte ). .PP There is an army of commands to read an image and, under the control of a few parameters, write a modified image on standard output. Those that read a single picture file by default use standard input, so they are usable in a pipeline. They include: .TP "lum [\fIpicture\fP] File .I picture (default standard input) contains a color image or a monochrome image with a color map. A gray-level image is written on standard output, using the NTSC luminance formula. .TP "clip [-o \fIx y\fP] \fIx0 y0 x1 y1\fP [\fIpicture\fP] Clip an image to have .CW "WINDOW=\fIx0 y0 x1 y1" . A picture that does not fill out the window is filled with black pixels. .TP "xpand [-s] [\fIpicture\fP] [\fIlo hi\fP [\fIinlo inhi\fP]] 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 [\fIpicture\fP] Convert a full-color (3 channel) picture to one channel with a color map by dithering. .TP "floyd [\fIpicture\fP] 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\fP [\fIpicture\fP] Convert an 8-bit gray-scale picture to one bit using a given half-tone .I screen . A description of the screen is read from a file in .CW /usr/td/lib/screens . The available screens include (among others) .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 [\fIpicture\fP] 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\fP [\fIpicture\fP] Pixel values of .I 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 picture1 picture2 The output picture is a weighted average of .I picture1 and .I picture2 . .I Weight determines the fraction of the average contributed by .I picture1 . .TP "piccat \fIpicture ... The input .I picture s are concatenated one atop another. The output has the width of the widest input. .TP "picjoin \fIpicture ... The input .I picture s are concatenated side by side. The output has the height of the highest input. .TP "adapt [\fIpicture\fP] Adaptive contrast enhancement: a 7 by 7 neighborhood around each pixel is examined for its minimum and maximum values. The center pixel is remapped linearly in a way that would send the neighborhood's maximum to 255 and its minimum to 0. That is, .CW "cen=255*(cen-min)/(max-min)" . .TP "ahe [\fIpicture\fP] Adaptive histogram equalization: each pixel of the output image is the histogram-equalized value of the center of a 17\(mu17 pixel window surrounding it in the input image. .TP "clean [\fIpicture\fP] 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 [\fIpicture\fP] 3\(mu3 linear crispening filter. Convolves the input image with the kernel .P1 20n -1 -1 -1 -1 9 -1 -1 -1 -1 .P2 This is a mild high-pass filter. .TP "edge [\fIpicture\fP] 3\(mu3 linear edge-detection filter. Convolves the input image with the kernel .P1 20n -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 [\fIpicture\fP] 3\(mu3 non-linear edge-detection (Sobel operator) filter. .TP "extremum [\fIpicture\fP] 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 [\fIpicture\fP] 3\(mu3 Laplacian filter. Convolves the input image with the kernel .P1 20n 0 -1 0 -1 5 -1 0 -1 0 .P2 This is a fairly extreme high-pass filter. .TP "median [\fIpicture\fP] 3\(mu3 median filter. Each pixel is replaced by the median of the 3\(mu3 window surrounding it. .TP "smooth [\fIpicture\fP] 3\(mu3 Bartlett filter. Convolves the input image with the kernel .P1 20n 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 "3to1 [-e] \fIcolormap\fP [\fIpicture\fP] Converts the input picture from full-color (\fTrgb\fP) to a single channel mapping each pixel to the closest entry of .I colormap . .TP "mcut [\fIpicture\fP] Reads a picture, and writes a color map on standard output suitable for use by .I 3to1 . .I Mcut uses Heckbert's median-cut algorithm to pick a color map that matches .I picture 's colors pretty well. .TP "improve \fIcolormap\fP [\fIpicture\fP] Given a color map and a picture file, this outputs a new color map that better represents the colors of the picture. The algorithm is to output the centroid of those pixel values that are closest to each input color map entry. Running .I improve several times may produce better and better color maps. .TP "quantize [\fIpicture\fP] Convert a full-color picture to an 8-bit picture with color map. This is just a command file that calls .I mcut , .I improve and .I 3to1 . It does a much better job than .I dither . .TP "remap \fIcolormap\fP [\fIpicture\fP] The input picture should be full color (\fTCHAN=rgb\fP). The output will have its pixel values will be altered so that when mapped through the given .I colormap they will be as close as possible to the input's pixel values. .TP "resample \fIwidth\fP [\fIpicture\fP] [\fIB C\fP] Resample the input image to be .I width pixels wide. The default filter used in resampling minimizes both pre- and post-aliasing. Numeric parameters .I B and .I C (both default to 1/3) pick the resampling kernel from a Mitchell and Netravali's two-parameter family of piecewise cubic kernels. .TP "transpose [-vhadrlui] [-o \fIx y\fP] [\fIpicture\fP] Transpose the input picture. This is useful in conjunction with commands that operate on scan-lines, like .I resample , to perform operations on columns instead of rows. Under control of its options, .I transpose can perform any symmetry operation of the integer lattice. The .CW -v option reflects through a vertical line. The .CW -h option reflects through a horizontal line. The .CW -a option reflects through an ascending diagonal line. The .CW -d option reflects through a descending diagonal line (the default). The .CW -r option rotates right (clockwise 90 degrees). The .CW -l option rotates left (counterclockwise 90 degrees). The .CW -u option flips the image upside down (180 degree rotation.) For completeness, the .CW -i option does the identity transformation. The .CW -o option translates the picture, adding .I x,y ) ( to all coordinates. Without this option, the upper-left corner of the image's window does not change. .TP "shear \fIangle\fP [\fIpicture\fP] 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). .TP "lx [-o\fIfile\fP] [-A\fIaspect\fP] [-a] [-s\fIscale\fP] [-r\fIrot\fP] [-x\fIxscale\fP] [-y\fIyscale\fP] [\fIpicture\fP] 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 .I 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 ). ( The side the normal (calculated using the right hand rule) out of has color .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. .TP "aplot [-t \fItype\fP] [-r \fIrange\fP] [-w \fIx0 y0 x1 y1\fP] \fIinput Produces an anti-aliased isometric plot of a square array of binary data, read from its input file. The .CW -r option specifies the maximum absolute value of the data. This may be adjusted to affect the height of the highest peaks in the plot. By default, the input is examined to find its range. The .CW -w option specifies the window in which the plot will be drawn. The data file is just a binary dump of a square array. It has no header, and in particular is not a picture file. The .CW -t option (default .CW -tf) specifies the type of data in the array. .KS .TS center; c c aFCW a. _ option type = -tf float -ts short int -ti int -tl long int -td double -tc char -tu unsigned char _ .TE .KE .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] varies from .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. .SP 10 ........... .PP The following math functions are available: .KS .TS center; lFCW lFCW lFCW lFCW. acos besy0 exp log10 asin besy1 fabs sin atan besyn floor sinh besj0 ceil gamma sqrt besj1 cos hypot tan besjn cosh log tanh .TE .KE 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 .I hypot may have two or three arguments, .I atan may take two arguments instead of one, and may also be spelled .I 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 .1C .KF bottom .sp 4 .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 .SP .ce \fBFigure 1.\fP Flying saucer script .KE .2C .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. .NH References .PP |reference_placement .BP photo page .BP divider with title .sp .ce Implementation and Maintenance