STScI Logo




cv -- Control image device and take snapshots




Output file for snap image.
Character size for added text strings.


The following commands are available. This list is also available when running the task with the commands h(elp) or ?.

--- () : optional; [] : select one; N : number; C/F/Q : see below
b(link) N F (C Q) (F (C Q)..)	blink	(N = 10 is one second)
c(ursor) [on off F]		cursor
di F (C Q) [on off]		display image
dg C (F Q) [on off]		display graphics
e(rase) [N a(ll) g(raphics) F]	erase (clear)
m(atch) (o) F (C) (to) (F) (C)	match (output) lookup table
o(ffset)  C N			offset color (N: 0 to +- 4095)
p(an) (F) 			pan images
ps(eudo) (o) (F C) (rn sn)	pseudo color mapping
				rn/sn: random n/seed n
r(ange) N (C) (N C ...)		scale image (N: 1-8)
re(set) [r i t a]		reset display
sn(ap) (C)			snap a picture
s(plit) [c o px,y nx,y]		split picture
t(ell)				tell display state
w(indow) (o) (F C)		window (output) frames
wr(ite) [F C] text		write text to frame/graphics
z(oom) N (F) 			zoom frames (N: 1-8)
x   or   q			exit/quit
--- C: letter c followed by r/g/b/a or, for snap r,g,b,m,bw,rgb,
---   or for dg r/g/b/y/p/m/w, as 'cr', 'ca', or 'cgb'
--- F: f followed by a frame number or 'a' for all
--- Q: q followed by quadrant number or t,b,l,r for top, bottom,...


The cv program is used to control the image display from within IRAF . It differs from most IRAF programs since it has its own prompt and its own internal "language". Each of the available commands is described in the following paragraphs, but first a few comments on the command structure seem in order. Commands are distinguished by their first letter, except for a few instances where the second letter is needed. The rest of the command name can be typed if you wish. Commands often require specification of frames numbers, colors, quadrants, or numeric values. In most cases, the order is unimportant, but, zoom, for instance, does require the zoom power right after the command name. The order given in the help command will always work.

A frame list is indicated in the help listing with an F . This is to be replaced in the typed command by an f followed (no spaces) with a list of the pertinent image planes. Thus, f1 means frame 1 while f42 means frames 4 and 2 . In most cases, the leading f can be omitted. The specification fa means all frames . In those cases in the help menu where the frame specification is optional, omitting the frame list is the same as typing fa ; that is, operate on all frames.

A color specification is a c followed by a set of letters. The letter a means all , just as in the frame specification. The letters r, b, and g are the other possibilities for all commands other than dg and snap . For displaying graphics planes (dg ), the other possibilities are y, p, m, w which stand for yellow, purple, mauve, and white . (Mauve is the wrong name and will get changed.) The snap command accepts, in addition to the standard three colors, m, bw, and rgb , which stand for monochrome, black and white, and full color . (See the discussion under snap for further explanation.) An omitted color specification is the same as all colors .

Quadrants are given by a q followed by numbers from the set one through four, or the letter a as in the frame and color cases. Quadrants are numbered in the standard way, with the upper right being 1 , the upper left 2 , etc. Adjacent quadrants may be referenced by t, b, l, and r , standing for top, bottom, left, and right . An omitted quadrant specification is the same as all quadrants . Quadrants are effective only if the split screen command has set the split point to something other than the "origin".

blink N F (C Q) (F C Q)
The blink rate is given by N , which is in tenths of a second. Although current timing routines in IRAF do not recognize partial seconds, for the NOAO 4.2BSD UNIX implementation, a non-portable timing routine is used so that tenth seconds are usable. Erratic timing is pretty much the rule when the system load is large. One frame must be given, followed by any color or quadrant specification, and then optionally followed by any number of similar triads. A specification of 10 f12 f3 f3 f4 would display frames one and two for one second, then frame three for two one second intervals, then frame 4, and then recycle. The first blink cycle may appear somewhat odd as the code "settles in", but the sequence should become regular after that (except for timing problems due to system load). In split screen mode, it is necessary to specify all the frames together with quadrants, which leads to a lot of typing: The reason is that blink simply cycles through a series of di commands, and hence it requires the same information as that command.
cursor [on off F]
This command is used to turn the cursor on or off, and to read coordinates and pixel values from a frame. Pixel coordinates for a feature are those of the image as loaded into the display, and do not change as the image is panned or zoomed. Fractional pixel positions are given for zoomed images, with a minimum number of decimal places printed (but the same number for both the x and y coordinates). For an unpanned, unzoomed image plane, the lower left corner of the screen is (1,1) even if the image you loaded is smaller than 512x512, occupies only a portion of the display screen, and does not extend to the lower left corner of the screen. This defect will likely be remedied when the cv package is properly integrated into IRAF . Pixel information can be read from a frame that is not being displayed.
di F (C Q) [on off]
The d isplay i mage command selects frames to be displayed on the monitor. If neither on or off is given, the specified frames are turned on and all others are turned off. Turning a frame on with the on specification displays the frames along with whatever else is present; that is the new frame is added to the display. Note that turning a frame off does not erase it. A frame need not have all colors turned on, nor appear in all quadrants of a split screen display.
dg C (F Q) [on off]
The d isplay g raphics command turns specific graphics planes on or off. For the IIS display, neither the frame nor the quadrant parameters are relevant. A side-effect of this command is that it resets the graphics hardware to the cv standard: red cursor and seven graphics planes, each colored differently. If the display is in a "weird" state that is not cured with the reset r/t commands, and a reset i would destroy images of interest, try a dg ca on command followed by dg ca off .
erase [F all graphics]
This command erases the specified frame, or all the graphics planes, or all data planes. The command clear is a synonym.
match (o) (F) (C) (to) (F) (C)
This command allows the user to copy a look-up table to a specified set of tables, and hence, to match the mapping function of frames (and/or colors) to a reference table. If the o parameter is omitted, the match is among the look-up tables associated with particular frames; otherwise, the ouput tables are used (hence, the o ). In the latter case, only colors are important; the frame information should be omitted. For the individual frame tables, colors can be omitted, in which case a match of frame one to two means to copy the three tables of frame two (red, green, and blue) to those of frame one. Only one reference frame or color should be given, but match f23 cgb f1 cr is legal and means to match the green and blue color tables of both frames two and three to the red table of frame one.
offset C N
The value N, which can range from -4095 to +4095 is added to the data pipeline for color C , thus offsetting the data. This is useful if one needs to change the data range that is mapped into the useful part of the output tables.
pan (F)
When invoked, this command connects the trackball to the specified frames and allows the user to move (pan/roam/scroll) the image about the screen. This function is automatically invoked whenever the zoom factor is changed.
pseudo (o) (F C) (rn sn)
Look-up tables are changed with the window and the pseudocolor commands. Windowing provides linear functions and is discussed under that command; pseudo provides pseudo-coloring capabilities. Pseudo-color maps are usually best done in the output tables, rather than in the look-up tables associated with particular frames; hence, ps o is the more likely invocation of the start of the command line. A color (or colors) can be specified for "output" pseudocolor, in which case, only those colors will be affected. For frame look-up tables, the frame must be specified.

Two mappings are provided. One uses a set of randomly selected colors mapped to a specified number of pixel value ranges. The other uses triangle color mappings. The former is invoked with the (rn sn) options. In this case, the number following r gives the number of ranges/levels into which the input data range is to be divided; to each such range, a randomly selected color is assigned. The number following s is a seed for the random number generator; changing this while using the same number of levels gives different color mappings. The default seed is the number of levels. If only the seed is given (r omitted), the default number of levels is 8. This mapping is used when a contour type display is desired: each color represents an intensity range whose width is inversely proportional to the number of levels.

The triangle mapping uses a different triangle in each of the three look-up tables (either the sets associated with the specified frames, or the output tables). The initial tables map low intensity to blue, middle values to green, and high values to red, as shown in the diagram. (The red and blue triangles are truncated as their centers are on a table boundary.)

Once invoked, the program then allows the user to adjust the triangle mapping. In response to the prompt line, select the color to be changed and move the trackball: the center of the triangle is given by the x cursor coordinate and the width by the y coordinate. Narrow functions (small y ) allow one to map colors to a limited range of intensity. When the mapping is satisfactory, a press of any button "fixes" the mapping and the user may then either select another color or exit. Before selecting a color, place the cursor at approximately the default position for the mapping (or where it was for the last mapping of that color under the current command); otherwise, the color map will change suddenly when the color is selected via the trackball buttons.

range N (C) (N C ...)
This command changes the range function in the specified color pipeline so that the data is scaled by (divided by) the value N . For the IIS, useful range values are 1,2,4 and 8; anything else will be changed to the next lowest legal value.
reset [r i t a]
Various registers and tables are reset with this command. If the r option is used, the registers are reset. This means that zoom is set to one, all images are centered, split screen is removed, the range values are set to one and the offset values are set to zero. Also, the cursor is turned on and its shape is set. Option i causes all the image and graphics planes to be erased and turned off. Option t resets all the look-up tables to their default linear, positive slope, form, and removes any color mappings by making all the output tables the same, and all the frame specific tables the same. Option a does all the above.
snap (C)
This command creates an IRAF image file whose contents are a 512x512 digital snapshot of the image display screen. If no color is specified, or if cm (color monochromatic) is given, the snapshot is of the blue image, which, if you have a black and white image, is the same as the red or the green image. Specifying cg for instance will take a snapshot of the image that you would get had you specified cg for each frame turned on by the di command. Color is of interest only when the window or pseudo color commands have made the three colors distinguishable. If the "snapped" image is intended to be fed to the Dicomed film recorder, a black and white image is all that is usually provided and so a color snap is probably not appropriate. In the case of the "no color/monochromatic" snap, the graphics planes are all added together, while, if a real color is given, only the graphics planes that have some of that color are included in the image. The color rgb can be given, in which case the red, green, and blue images are weighted equally to produce a single image file. This image does not represent well what you see, partly because of the equal weight given all colors: some mapping of eye sensitivity is probably what is required, but it is not implemented.

The program operates by first determining zoom, pan, offset, tables, etc, and, for each quadrant of the split screen, which images planes are active. Then, for each line of the display, those images are read out from the display's memory and the transformations done in hardware are duplicated pixel by pixel in software. The word "active" needs a bit of explanation. Any image plane whose pixels are contributing to the image is active. No image is active if it has been turned off (by the di ) command (or if all images were turned off and the one of interest not subsequently turned back on). If the image is all zeroes, or if it is not but split screen is active and the part of the image being displayed is all zeroes, it is not contributing to the output. However, the snap program cannot tell that an active image is not contributing anything useful, and so it dutifully reads out each pixel and adds zeroes to the output. The moral of this is that frames of no interest should be (turned) off before snap is called (unless you don't have anything better to do than wait for computer prompts). When split screen is active, frames are read only for the quadrants in which they are active.

The fastest snaps are for single images that are zoomed but not panned and which are displayed (and snapped) in black and white, or snapped in a single color.

split [c o px,y nx,y]
This command sets the split screen point. Option c is shorthand for center , which is the normal selection. Option o stands for origin , and is the split position that corresponds to no split screen. If you wish to specify the split point in pixels, use the px,y form, in which the coordinates are given as integers. If you prefer to specify the point in NDC (which range from 0 though 1.0), use the nx,y form in which the coordinates are decimal fractions.

A peculiarity of the IIS hardware is that if no split screen is desired, the split point must be moved to the upper left corner of the display, rather than to the lower left (the IRAF 1,1 position). This means that no split screen (the o option, or what you get after re r ) is really split screen with only quadrant four displayed: if you use the di command with quadrant specification, only quadrant 4 data will be seen.

This command displays what little it knows about the display status. At present, all it can say is whether any image plane is being displayed, and if any are, what is the number of one of them. This rather weak performance is the result of various design decisions both within cv and the IRAF display code, and may be improved.
window (o) (F C)
This command operates just as the pseudo command, except that it applies a linear mapping to the output look-up tables (if option o is used) or to the frame specific tables. The mapping is controlled by the trackball, with the y cursor coordinate supplying the slope of the map, and x the offset. If different mappings are given to each color, a form of pseudo-color is generated.
write [F C] text
This command writes the given text into either an image plane (or planes) or into the specified color graphics bit plane(s). The user is prompted to place the cursor at the (lower left) corner of the text, which is then written to the right in roman font. The user is also asked for a text size (default 1.0). If the text is written into a graphics plane, and a snap is requested with no color specification, then text in any graphics plane will be included in the image. A color snap, on the other hand, will include graphics text to the extent that the text is displayed in that color. Text written into an image plane will have the same appearance as any "full on" pixel; that is, text in an image plane is written at maximum intensity, overwrites the image data, and is affected by look-up tables, offsets, and so forth, like any other image pixels.
zoom N (F)
This command zooms the display to the power given by N . For the IIS, the power must be 1,2,4, or 8; anything else is changed to the next lower legal value. The model 70 zooms all planes together. The center of the zoom is determined by the cursor position relative to the first frame specified (if none, the lowest numbered active one). Once the zoom has taken place, the pan routine is called for the specified frames.



Search Form · STSDAS