% Ct ramp
% Ct save Ramp.ais
% Cm gray 2.2
% Ct pie
% Ct overlay /PCedar/ColorTrix/CtMovie.ais Ramp.ais
% Ct mirror -l

% Ct view /PCedar/ColorTrix/CtMovie.ais
% Ct movie 80 80 0 0 6 3

% Ct pie
% Ct bugeye 40 40
% Ct lerp /PCedar/ColorTrix/CtMovie.ais 0.5 -w 0 0 320 240

% Cm snake

CtBasic  low level sample map operations

CtDispatch registration of and access to command procedures

CtEncode  run-length encoding operations

CtFile  file transfer to/from sample maps

CtFill  raster fill operations

CtFilter  raster filter operations

CtMap  color map modification and creation procedures

CtMisc  miscellaneous operations (printing, buttons)

CtMod  modification of images

CtPix  creation of images

CtTransform transformation of images

CtViewer access to sample maps belonging to a viewer

The command to manipulate an image is registered as "ColorTrix" and "Ct."

The command to manipulate the color map is registered as "ColorTrixMap" and "Cm."

Both commands take as argument the name of a function to be applied to the image or colormap.
 Ct ? will list all image functions.
 Cm ? will list all colormap functions.

Commands may be concatenated, separated by a comma; for example: Ct right 100, down 100.

A target viewer may be specified with the -name <name> option. The default name is ``ColorTrix.'' <name> can be a full path or ``local.'' If the named viewer does not exist, it will be created as a ``ColorTrix class'' viewer. Any named viewer becomes the default until a different viewer is named. To select an existing viewer, the name must be the complete named as shown in the viewer caption (but without the "[Edited]" if the viewer is a text viewer and has been edited). For example, to save this viewer: Ct save Foo.ais -name ColorTrixDoc.tioga." Or, to save the contents of a PreView viewer: Ct save Foo.ais -name "PreView: /<directory>/<subdirectory>/<file> (<version>)."

Target viewers need not belong to the ColorTrix class; for such viewers no ColorTrix mouse operations are applied. Perhaps the only reason to operate on a non-ColorTrix class viewer is to save its raster as an AIS file. Operations on a Tioga viewer will not affect its source file.

The target viewer's column may be specified with the -left or -right option. If a viewer is created, it will be created in the specified column; otherwise an extant viewer will be moved to the specified column if necessary.

ColorTrix operations are performed on the image displayed within the specified or default viewer. These operations take place within a window of the viewer, defaulted to the full viewer size. The user may specify a sub-window in one of three ways:

The upper left of a viewer is its origin: (0, 0).

A number of applications will prompt the user to specify a rectangular region of a viewer. This is initiated by a left mouse down, causing a rectangle to be drawn, initially with zero area. The initial point of mouse down is fixed; the opposite corner of the rectangle will follow the user while the button is held down. The rectangle may be adjusted by releasing the mouse button, selecting a corner, edge, or center and repositioning.

A target viewer is normally the default raster that is processed; however, most ColorTrix commands may be applied to an input AIS file or AIS triplet of files, with the processed result written to an output AIS file or AIS triplet. This option is available with the -file <input name> <output name> option. Sub-windows may still be specified, but not interactively. The -file option overrules the -name and -wi options.

Undo    Undo the previous command.

View <ais | interpress file> Display the named (possibly windowed) image file.
   The complete file name should be given unless the image
   is 24 bits, in which case only the base name should be give.
   Images are un-scaled, those larger than the viewer are clipped.
   Gray ramp used if bw-ais or one component of ais triplet.
   Dither colormap used if interpress or ais triplet.
   Options:
    -center   center the image on the color display
    -cmap <file>  load the specified color map.
   

Save <name> [option] Save the image to disk. If 24 bits, '-red.ais', '-grn.ais', '-blu.ais'
   are appended to name for the appropriate file. Options:
    -w <x y w h> save this window only
    -wi  interactively specify a window
    -wp  use the previously given window
   

DumpToAIS <dump file> <ais-file-root>
[-w width] [-h height] [-header] [-separate] [-ascii] [-gbr]
 Decode the named dump file into three new RGB files.
 The dump file is assumed 24 bits per pixel, RGB, with no header
 If -separate, pixels are expected as all rrr.... then ggg.... then bbb....
 else, pixels are expected as rgbrgbrgb....
 If -header, then a header is expected, containing the number of channels
  (typically 1 or 3), the width, and the height.
 If -head is not given, then width and height must be specified.
 If -ascii, the data is interpreted as ascii integers, rather than binary
 If -gbr file contains green, then blue, then red order
 

PseudoTo24 <AIS root name>
 Convert the current 8 bpp display to 24 bpp AIS file triplet.
 

Gallery {pattern and/or list of filenames}
   Cycle through the specified AIS files.

Clear [r[g[b]]]  Clear the color display; default pixelValue is 255.

Line x0 y0 x1 y1 r[g[b]] Draw a line from (x0, y0) to (x1, y1).

Ramp [-h|-v]  Draw a horizontal or vertical ramp (vertical is the default).
   (Lance Williams has said, "from a ramp, any image is possible.")

Pie   Create a radially symmetric pattern, tapering outwards in intensity.

Dither <pixel-value> Dither the picture. If no value specified, dither the existing image;
   otherwise, create a dithered flat field of intensity <value>.

Grid [-pVal <INT>] [-spacing <INT>] [-lineWidth <INT>]
   Display a grid on the color display.

Check [-pVal <INT>] [-spacing <INT>] [-w <xywh >]
   Display a checkerboard on the color display.

Lum   Convert pseudo-color to luminance.

PseudoToRGB <base name> Converts an 8 bit image into three ais files.

PVal <new><old1>[old2] ... Set those pixels equal to old1 or old2 (etc.) to new.

Dif <x0,y0,x1,y1,x2,y2,w,h> Display the difference between two w by h color display regions.
   The first window starts at (x0, y0), the second at (x1, y1), and
   the difference window starts at (x2, y2).

Blur [blur-radius, def = 1] Blur the image in the color display.

Medial    Increase pixel values towards center of regions.

Copy <xywh> <xy[wh] > Copy first (source) window to second (destination) window.
   If second w or h omitted, default to first w or h.

Left <nPixels: INT>  Circularly shift the image to the left; if nPixels < 0, shifts right.

Up <nPixels: INT>  Circularly shift the image up; if nPixels < 0, shifts down.

Negate   Negate the image.

Reflect [-h | -v]  Reflect the image around the horizontal (h) mid-line or
   the vertical (v) mid-line. h is the default.

Mirror [-l | -r | -t | -b] Mirror the image from left to right (l), right to left (r),
   top to bottom (t), or bottom to top (b). b is the default.

Matte <image ais> <matte ais>
   Fill the color display with <image ais> as matted by <matte ais>.

Overlay <image ais> <matte ais>
   Interpolate the current color display with <image ais> according to
   <matte ais>. For a given pixel, if <matte> = 0, the color display is
   unchanged; if <matte> = 1, <image> is written to the color display.

Lerp <image ais> <value> Interpolate the current color display with <image ais> according to
   <value>; color display ← (1-value)*color display + value*image.

ExtractMatte <24 bpp image ais> <background: r g b> [options], options include:

    -image <name> (name of output 24 bpp image files)
    -matte <name> (name of the output 8 bpp matte file)
   
   Helps create mattes for image composition. The input should be an
   image file with a flat background specified as <r g b>. The output
   is two images: the first is a processed form of the original image, but
   with the background color removed for those pixels with a matte
   value < 1.0. As with any post-processer with incomplete
   information, ExtractMatte uses a number of heuristics to recover
   determine the matte. The results appear acceptable (Glassner).

Expand [-s<xywh>] [-d<xywh>]
   Expand src window to dst window using a triangle filter.
   Does not work in 24 bpp and cannot be aborted.
   The src and dst boxes can overlap.

Resample [options]  Resample src window to dst window using the specified filter.
   Like Expand, but for 24 bpp, and is somewhat slower in 8 bpp.
   This can be used for both image resizing and filtering.
   The src and dst boxes can overlap.
   Options:
   
   -s <x y w h: NAT> source window
   -d <x y w h: NAT> destination window
   
   -map <xscale xtran yscale ytran: REAL>
     optional src to dst mapping:
     dstx = xscale*srcx+xtran, similar for y.
     Mapping is indep. of src and dst windows.
     Default mapping stretches src to dst.
     
   -filt <filtname> set filter name (default=triangle)
     'ct resample -filt ?' prints filter catalog
     point, box, triangle, quadratic, and cubic
     filters are positive filters and will run much
     faster than the other, negatively lobed filters
     (because unsigned multiplies are performed in
     hardware on a Dorado)
     
   -supp <width: REAL> filter support (width), defaults in catalog
   
   -blur <factor: REAL> blur factor: > 1 is blurry, < 1 is aliased.
   
   -window <windowname>
     window a IIR (infinite) filter.
     Common windows are triangle, hanning,
     hamming, blackman, and kaiser. IIR filters
     are windowed with blackman by default;
     windowing may be disabled with
     '-window box'.

   -param <a b: REAL> set miscellaneous filter parameters
   

Notes on Resampling

This program scales and/or translates a raster image from one picture file or viewer to another. The "resize" operation consists of a scale and translation. The program supports arbitrary floating point scale and translation with independent control of x and y scales, upsampling (interpolation) or downsampling (decimation), 1-channel black and white or 3-channel color pictures, overlapping source and destination windows within the same frame buffer, and separable filtering with a large choice of filters. It can also be used for in-place separable filtering of images. The algorithm is not limited to integer or rational scale factors; it can scale by any floating point number. The program is optimized to be nearly as fast as special-purpose code for important special cases such as point sampling. The memory used by the algorithm is modest: it is proportional to the picture width times the filter width, not proportional to picture area.

To run Ct Resample, the user specifies the source and destination file or frame buffer windows, specifies the mapping (resample transformation) and filter. Most of these options have reasonable defaults. The program will read and write the full-screen area of the source and destination pictures by default; the user can specify subrectangles to read and write if desired. Rectangles are defined as xmin, ymin, xsize, ysize, By default, the source window is resampled into the destination window. Alternatively, a mapping can be specified directly with the -map option.

Filters are selected with the -filt option. If given one filter name, -filt will use that filter in both x and y; if given two names, different filters can be used in the two dimensions. The Ct Resample -filt '?' prints the list of filters currently known to Ct Resample. That list is:

 NAME SUPPORT
 point  0
 box  0.5
 triangle  1
 quadratic 1.5
 cubic  2
 catrom  2
 mitchell  2
 gaussian  1.25
 sinc  4
 bessel  3.24

The option -filt point gives fast pixel replication, -filt triangle (the default) gives bilinear interpolation, which is suitable for most purposes, and -filt mitchell gives slower, very high quality results. The other filters are provided for experimentation. The time required by a filter is proportional to its support.

Most of the filters known to Ct Resample are FIR (finite impulse response), with an intrinsic support (width), but some of them (gaussian, sinc, bessel) are IIR (infinite impulse response), and must be truncated at some arbitrary support. This can be done with the -supp option. Again, the defaults are reasonable. The IIR filters can be windowed (brought down to zero) with various window functions listed below:

 hanning
 hamming
 blackman
 kaiser

The sinc and bessel filters are blackman-windowed by default. Filters can be scaled artificially to blur or sharpen them with the \fB-blur\fP option.

EXAMPLES

Ct Resample -src
 Resample the image into the default destination device (whatever that is),
 mapping the file's rectangle into the device's rectangle, with a triangle filter.

Ct Resample -src -filt point -square -intscale
 Resample the image to the default device's full screen, but maintain the
 picture's aspect ratio, and resample it up by an integer factor with point
 sampling (pixel replication)

Ct Resample -src -dst iris -d 50 75 100 100
 Resample the image into an iris window at position (50,70) with xsize=ysize=100.

Ct Resample -src -dst -s 100 100 640 512 -d 0 0 1280 1024 -filt mitchell
 Resample from image to itself with overlapping source and destination windows,
 using a mitchell filter.

Ct Resample -src -dst -s 0 0 500 500 -d 0 0 500 500 -filt cubic -blur 2
 Blur (low pass filter) an image in-place.

SEE ALSO
 Discrete Time Signal Processing, Alan Oppenheim, Ronald Schafer, 1989.

Info [x y: INT]  Print pixel information for the specified pixel; if no pixel
   specified, provide interactive viewer.

Text <x y text> [-color <r> [<g b>]] [-font <fontname>] [-size <pointsize>]
   If arguments given, print text starting at pixel location (x, y)
   with specified color [1,1,1], font [helvetica-mrr]
   and size (approx height in pixels) [14].
   Fonts come from ///7.0/fonts/xerox/pressfonts/.
   If no arguments, create a viewer to print any selected text.
   

Movie <x y w h nFrames> Sequentially display sections of the color display; each frame is
   w by h, the first frame starting at x, y and subsequent frames
   increasing in x, until edge of the frame, at which point y is
   incremented. A test image is given; try:

Paint    Primitive color display paint program.
   

Pal [nRows: INT] [-smooth] Display the color map as a palette, excepting entry 0;
   unless -smooth, small blocks for each entry.

Safe   Outline the SMPTE safe action and safe title areas.

Escher exponent  Bulge (if exponent > 1) or contract (if exponent < 1) the image
   with respect to the center.

Bugeye xSize ySize Create a bug's-eye view of the image. The view is made up of
   overlapping sub-views of the image, like a fly's compound eye.

Shuffle xSize ySize The rows and columns of the image are randomly shifted,
   "ruffling" the image. The change in the size of the shift between
   successive rows and columns is limited by the parameters.

STLaplace threshold dif Evaluates a signed, thresholded laplacian filter of the image.

Popularity diameter Each pixel is replaced with the most popular value in its
   neighborhood. The neighborhood is a square centered around the
   pixel under consideration. The side lengths of the square are given
   by the value of diameter.

Edges xSize ySize   A cheap high-pass filter to detect edges. To find edges, each pixel
   is compared with a neighbor. The offsets to reach this neighbor are
   supplied in xSize and ySize (2 2 is suggested).

Woodcut height blend threshold clamp
   Simulated a woodcut from the image. Each horizontal stroke is
   height pixels tall. The size of the stroke at each point is averaged
   within a neighborhood controlled by blend; this is the number of
   pixels on each side averaged together (a blend of 0 indicates
   no averaging). Threshold is used to pre-scale the image before the
   woodcuts are made; using a value less than 1.0 results in thinner
   strokes. Usually threshold is useful only when clamp is non-zero,
   indicating that the result should be black-and-white only. If clamp
   is zero, then the color at each pixel within a stroke is the average
   color of all pixels within that stroke's column.

Spin cycles   Spins the image about the center by the specified number of cycles.

Block xSize ySize   Replaces the image with a low-resolution version. The "pixels" in
   the low-res version created are xSize by ySize in the original image.

Tool

This interactive tool examines an image and the color map. One may center a particular pixel on the screen or zoom in (make the pixels appear bigger). Zooming and translation are performed by modifying the original image. The original image may be recovered with Redraw button. The Reset button redraws the original image and resets the original color map.
   
The program creates a control panel, which, for 8 bit display, looks like:

The buttons at the left describe the meaning of the mouse buttons; L, M, R correspond to Left, Middle, Right, and P, S, C correspond to Plain, Shift, Control.
   
The simplest use of the tool is to left-click the mouse over a viewer of interest; this redraws the image with the click-point centered in the viewer. The click-point coordinates are displayed in the Pixel: button; the Zoom: button will display "2" and each pixel will appear as a 2-by-2 block.

The Gray: button will display the contents of the image at the click-point, and the buttons mR:, mG:, and mB: will show the color map entries for the gray value.
   
Additional left-clicks double the zoom factor; updating the buttons accordingly. Shift-left will add 1 to the current zoom factor, and Control-left will multiply the current zoom by 8. A right click zooms out by a factor of two.
   
Middle-clicking does not change the image but updates the button display of pixel information. The pixel location, gray value, and colormap entries are also printed in the typescript. Shift-middle will do the same and center the chosen pixel.
   
A new pixel of interest may be chosen by clicking on Pixel: and entering a new <x y> position. A new zoom factor may be set in the same way. The four arrow buttons in a vertical column allow incremental movement of the pixel of interest.
   
Image contents may be changed by clicking in the Gray: button and entering a value; the colormap buttons will then show the colormap entries associated with that value. The colormap entries may be changed by clicking in the colormap buttons.
   
For the above buttons, new values take effect upon either a carriage return, an arrow selection, a click in the "mouse" buttons on the far left, or by clicking in the image.

Operation is similar for a 24-bit image, the Gray: button is replaced by bR:, bG:, and bB: buttons.
   
The far-left bottom button togles the state of the tool; when "asleep," it ignores mouse .
   
The cursor may be changed to white with the InvertCursor button.