1SAOIMAGE(1) General Commands Manual SAOIMAGE(1)
2
6 SAOimage 1.23 - X11 window based, interactive, color or halftone image
7 display program for astronomical images
8
10 saoimage [ -display nodename:0.0 ] [ -geometry | -gd geometry ]
11 [ -pros | +/-imtool | -fits | -dfits | -oif ]
12 [ -u1 | -u2 | -i2 | -i4 | -r4 | -r8 [ width height ] ]
13 [ -byteswap ] [ -skip bytes ]
14 [ -upperleft | -lowerleft ] [ -one | -zero ] [ -rotate code ]
15 [ -linear | -wrap [ wraps ] | -log [ exponent ] | -sqrt [ power ]
16 | -histeq ]
17 [ -min val ] [ -max val ] [ -rmin val ] [ -rmax val ] [ -scalebias
18 scale bias ]
19 [ -palette val ] [ -red | -green | -blue ]
20 [ -vertgraph | -horizgraph ]
21 [ +/-coord ] [ +/-magnifier ] [ -mag val ]
22 [ -panboxav | -panboxsum | -panboxsample | -panboxmax ]
23 [ -idev pipename ] [ -odev pipename ] [ -fbconfig filename ]
24 [ +/-verbose ] [ -quiet ] [ -lprbuttons ] [ -mtf ] [ -bordercolor
25 color ] [ -lfrac histogram fraction ] [ -wcscom WCS command ] [ -gal |
26 -fk4 | -fk5 ] [ -zf zoom factor]
27 [ filename | -name filename ]
28
30 SAOimage is a utility for displaying astronomical images which runs
31 under the X11 window environment. Image files can be read directly, or
32 image data may be passed through a named pipe (Unix) or a mailbox (VMS)
33 from IRAF display tasks. SAOimage provides a large selection of
34 options for zooming, panning, scaling, coloring, pixel readback, dis‐
35 play blinking, and region specification. User interactions are gener‐
36 ally performed with the mouse.
37 The SAOimage desktop includes, a main image display window, a button
39 menu panel, a display magnifier, a pan and zoom reference image, and a
40 color bar. A color table graph window can be brought up by clicking on
41 the color bar.
42
44 saoimage tracks world coordinate systems as well as pixel coordinates
45 within the image, if WCS information is present. Several single char‐
46 acter keyboard commands have been added. c prints the world coordinate
47 (RA and Dec as hh:mm:ss.sss dd:mm:ss.ss and Lat Long as dd.ddddd
48 dd.ddddd) and image pixel coordinate, along with the value of that
49 pixel to standard output. w executes the command set by -wcscom, sub‐
50 stituting that same world coordinate string for %s. b prints the world
51 coordinate RA and Dec in the FK4/B1950 system. j prints the world
52 coordinate RA and Dec in the FK5/J2000 system. g prints the world
53 coordinates as galactic longitude and latitude. e prints the world
54 coordinates as ecliptic longitude and latitude. i prints the world
55 coordinates as the image header defines them. h toggles between
56 degrees and sexigesimal units for RA and Dec.
57
59 -blue Set the color of all graphics to be blue. Some inexpensive sys‐
60 tems use a monochrome monitor connected to one of the three color
61 outputs on the computer. That color must be specified to make
62 the graphics visible.
63 -bordercolor colorname
65 Specify the color of all subwindow borders. The color name must
66 be a recognized X color (there are many). This is a style issue.
67 -bc may be used instead of -bordercolor.
68 -byteswap
70 Switch the bytes order between big-endian and little-endian
71 order. This may be needed where data has been copied from
72 another machine or if there is some confusion about the FITS file
73 format. This switch toggles the previous setting. -bswap may be
74 used instead of -byteswap.
75 +/-coord
77 Set the coordinate tracking state initially on or off. In coor‐
78 dinate tracking, the coordinates of the mouse and value of the
79 pixel under it are printed in the upper-left text area, above the
80 main display window. +/-ct can be used instead of +/-coord.
81 -display nodename:0.0
83 Specify the name of the X display server. This makes it possible
84 to run the SAOimage program on a machine other than the one con‐
85 nected to your display screen, with no difference in appearance
86 or use. By default, SAOimage gets the server name from the DIS‐
87 PLAY environment variable. See the xhost manual page for more
88 details. The display server cannot be changed once SAOimage is
89 running. -display may be abbreviated -d.
90 -dfits
92 Image file is a FITS file (see -fits), but in unexpected
93 byteswapped order. The FITS standard is not swapped, but some
94 naive VAX applications may swap it (see -bswap).
95 -fbconfig filename
97 Specify an alternate frame buffer configuration file for use with
98 IRAF. By default, the file installed with SAOimage
99 (/usr/local/lib/imtoolrc) is used.
100 -fits Image file is a FITS file. If the image filename ends in .fits,
102 this switch is not necessary. Only T=SIMPLE array types are sup‐
103 ported. The header BITPIX card must be 8 (unsigned byte), 16
104 (signed short), 32 (signed int), -32 (float), -64 (double), or
105 -16 (unsigned short). (The last two are not recognized stan‐
106 dards). IEEE floats are not converted if that is not the machine
107 format.
108 -fk4 If WCS information is available in the image header, track the
110 cursor in FK4/B1950 right ascension and declination as well as
111 pixel coordinates. These coordinates, followed by B1950 will be
112 fed to an external program if the w command is used.
113 -fk5 If WCS information is available in the image header, track the
115 cursor in FK5/J2000 right ascension and declination as well as
116 pixel coordinates. These coordinates, followed by J2000 will be
117 fed to an external program if the w command is used.
118 -gal If WCS information is available in the image header, track the
120 cursor in galactic longitude and latitude as well as pixel coor‐
121 dinates. These coordinates, followed by galactic will be fed to
122 an external program if the w command is used.
123 -gd geometry
125 Specify the size of the image display subwindow and/or the screen
126 position of SAOimage. The format is a standard X geometry state‐
127 ment. This switch works like -geometry, except that width and
128 height (if given) are applied to the display subwindow. The
129 overall SAOimage window is sized accordingly.
130 -geometry geometry
132 Specify the size and/or the screen position of SAOimage. The
133 format is a standard X geometry statement. Both size and posi‐
134 tion may be specified, or only the size or the position. Width
135 and height refer to the dimensions of SAOimage's desktop window
136 (see -gd for sizing just the image display window). +x and +y
137 refer to the upper left corner in screen coordinates. -x posi‐
138 tions the right edge from the right edge of the screen. -y would
139 positions the lower edge from the bottom of the screen. Width
140 and height below a minimum size are defaulted to the minimum.
141 Specifying the default minimum size (-geometry 0x0) also triggers
142 SAOimage to use smaller dimensions for its internal windows.
143 Once SAOimage is running, use the window manager's normal size
144 and move mechanisms to make adjustments to SAOimage's main win‐
145 dow. -geometry may be abbreviated -g.
146 -green
148 Set the color of all graphics to be green. See -blue.
149 -histeq may be abbreviated -hi.
151 Set the scaling mode for histogram equalization.
152 -horizgraph
154 Use a horizontal auxiliary color graph window, with a color bar
155 along the bottom. See -vertgraph. -hg can be used as a short‐
156 hand for -horizgraph.
157 -i2 width height
159 Image file is a signed short integer array file of the given
160 dimensions. If the file is square and has no added padding, the
161 dimensions are not necessary. -shortarray width height has the
162 same function.
163 -i4 width height
165 Image file is a signed long integer array file of the given
166 dimensions. If the file is square and has no added padding, the
167 dimensions are not necessary. -longarray width height has the
168 same function.
169 -idev pipename
171 Specify the name of the named pipe used for listening. The
172 default is /dev/imt1o, which is the default used by IRAF. See
173 -odev.
174 +/-imtool
176 Open/close the named input pipe connection and wait for input
177 from IRAF. When open, SAOimage emulates IRAF's imtool. IRAF's
178 image loading and cursor read-back functions are supported.
179 Unlike imtool, SAOimage has only one frame buffer; IRAF's frame
180 buffer numbers are ignored. Listening on the pipe is possible
181 even while reading image files directly. The connection may be
182 opened, closed, or re-opened at any time. When supported, the
183 default mode is commonly to start with the IRAF connection open.
184 See -idev, -odev, and -pros.
185 -lfrac [fraction of histogram numerical peak]
187 Set the linear scaling limits to the values where the pixel value
188 distribution is at a given fraction of its peak
189 -linear
191 Set the scaling mode to linear.
192 -log [exponent for exponential curve]
194 Set the scaling mode to log (exponential), and set the exponent
195 for the curve function e sup n if given.
196 -lowerleft
198 First pixel in file represents the lower left of the image,
199 assuming the lines of input run left to right on the screen.
200 This is the IRAF standard and the SAOimage default. See -rotate,
201 -upperleft, and -zero. -lowerleft may be abbreviated -ll.
202 -lprbuttons
204 Include the button menu in the hardcopy image (only on color
205 workstations). The default on color workstations includes the
206 area above the button panel, but excludes the buttons.
207 -mag magnification
209 Set the magnification factor of the magnifier. This factor
210 relates the magnifier to the magnification of the display window.
211 The default is 4; the magnifier magnifies the image to 4 times
212 the magnification of the main display window (but never less than
213 zoom 1 of the original data).
214 +/-magnifier
216 Set the magnifier tracking state initially on or off. With mag‐
217 nifier tracking, the magnifier window is continuously updated to
218 show a magnification of the image the image under the mouse.
219 +/-mt can be used instead of +/-magnifier.
220 -max [max val]
222 Set the maximum for the image value range used to compute scal‐
223 ing. The default is to take the maximum from the image shown in
224 the display window. -max with no value resets the default. If
225 the maximum value in the displayed image is lower than the given
226 maximum, the image's maximum vale is used for the scaling range.
227 -min [min val]
229 Set the minimum for the image value range used to compute scal‐
230 ing. The default is to take the minimum from the image shown in
231 the display window. -min with no value resets the default. If
232 the minimum value in the displayed image is higher than the given
233 minimum, the image's minimum vale is used for the scaling range.
234 -mtf Give the button panel a chiseled look popularized by HP's widget
236 set. This appearance may contrast less with other applications
237 being used at the same time.
238 -name filename
240 This switch is only needed if the filename starts with a number
241 or might otherwise be recognized as a switch.
242 -odev pipename
244 Specify the name of the named pipe used for sending feedback.
245 The default is /dev/imt1i, which is the default used by IRAF.
246 See -idev.
247 -oif Image file is an IRAF image header file in OIF format. If the
249 image filename ends in .imh, this switch is not necessary. IRAF
250 STF and QPOE formats are not supported. Complex data cannot be
251 handled. The data must have at least 2 dimensions. Only the
252 first plane of multidimensional images is read. The data file is
253 read directly by SAOimage (see -imtool and -pros).
254 -one The file coordinate of the first pixel is (1,1). The real coor‐
256 dinates of the center of the first pixel are (1.0,1.0). This is
257 the IRAF standard and the default for SAOimage. The second pixel
258 is (2,1). See -zero.
259 -palette number
261 Specify the number of read/write color cells to reserve. On
262 color workstations, SAOimage reserves color cells in the default
263 colormap for its own use. SAOimage reserves as many color cells
264 as it can get, up to the number given (the default is 200). If
265 the number given is negative, SAOimage comes up in overlay mode,
266 using 1/2 + 2 of the color cells for overlays and graphics. In
267 verbose mode (see -verbose), SAOimage tells you how many cells it
268 is able to use for display colors. This number can be re-entered
269 at run-time, unless -palette 1 is given, in which case SAOimage
270 stays in halftone mode. -p is an acceptable shorthand for -pal‐
271 ette.
272 -panboxav | -panboxsum | -panboxsamp | -panboxmax
274 These switches select the kind of image reduction used to fit a
275 picture of the entire image into the pan window. Each pixel is
276 computed from a block of image pixels by averaging, summing, sam‐
277 pling, or taking the maximum. The default is to show the maximum
278 from each block. When zooming in the main display involves
279 reduction, subsampling is always used.
280 -pros Virtually identical to the +imtool switch. The difference occurs
282 when the user writes the saved regions to a disk file. imtool
283 emulation includes writing only an IRAF list file giving center
284 coordinates only. With -pros, SAOimage's normal region descrip‐
285 tor file will be written in place of the simpler list file. One
286 may switch between this mode and +imtool, or close the IRAF con‐
287 nection with -imtool.
288 -quiet
290 Disable verbose mode;-q may also be used. See -verbose.
291 -r4 width height
293 Image file is a real*4 array file of the given dimensions. If
294 the file is square and has no added padding, the dimensions are
295 not necessary. -floatarray width height has the same function.
296 -r8 width height
298 Image file is a real*8 array file of the given dimensions. If
299 the file is square and has no added padding, the dimensions are
300 not necessary. -doublearray width height has the same function.
301 -red Set the color of all graphics to be red. See -blue.
303 -rmax [max val]
305 Set maximum value for reading from the image file. This value is
306 used as the maximum value when images are pre-scaled to fit the
307 16 bit (signed short) working buffer.
308 -rmin [min val]
310 Set minimum value for reading from the image file. This value is
311 used as the minimum value when images are pre-scaled to fit the
312 16 bit (signed short) working buffer.
313 -rotate 1,2,or 3
315 Rotate the image 90, 180, or 270 degrees (respectively) before
316 displaying it. Rotation is applied after conversion to a lower
317 left coordinate system (-ll) if such conversion is also
318 requested. This is useful for images when the CCD was not
319 mounted North-up. -rot can be used as a shorthand for -rotate.
320 -scalebias scale bias
322 The data in the image file should be scaled and biased to get the
323 true image value (TrueValue = (scale * FileValue) + bias). This
324 cannot be used with the -fits image type (scale and bias are in
325 the FITS header), nor with -imtool or -pros (they are passed by
326 IRAF). -sb is a shorthand for -scalebias.
327 -skip bytes
329 Skip over the given number of bytes at the head of the file
330 before reading data. This is used to skip header information
331 or the first image if two images are stored in one file. -header
332 and -sk are aliases for -skip.
333 -sqrt [inverse of exponent for geometric curve]
335 Set the scaling function to square root (geometric), and set the
336 inverse of the exponent for the x sup {1/n} curve, if given.
337 -u1 width height
339 Image file is an unsigned byte array file of the given dimen‐
340 sions. If the file is square and has no added padding, the
341 dimensions are not necessary. -chararray width height has the
342 same function.
343 -u2 width height
345 Image file is a unsigned short integer array file of the given
346 dimensions. If the file is square and has no added padding, the
347 dimensions are not necessary. -ushortarray width height has the
348 same function.
349 -upperleft
351 First pixel in file represents the upper left of the image,
352 assuming the lines of input run left to right on the screen (see
353 -rotate and -lowerleft). This switch does not override IRAF WCS
354 image coordinates. -upperleft may be abbreviated -ul.
355 +/-verbose
357 Set verbose mode on or off. In verbose mode, informative state‐
358 ments are printed to the terminal window when various actions are
359 taken. The default mode is to be verbose. +/-v can be used
360 instead of +/-verbose.
361 -vertgraph
363 Use a vertical auxiliary color graph window, with a color bar
364 along the left side. See -horizgraph. -vg can be used as a
365 shorthand for -vertgraph.
366 -wcscom [format for command to be executed]
368 Set the command to be executed when the w key is struck, where
369 the world coordinates are substituted for %s in the string.
370 Underscores should be used instead of spaces.
371 -wrap [number of wraps within scaling range]
373 Set the scaling mode to wrapped linear, and set the number of
374 wraps for this mode, if given.
375 -zero The file coordinate of the first pixel is (0,0). The real coor‐
377 dinates of the center of the first pixel are (0.5,0.5) which
378 makes the very edge (0,0). This is the standard coordinate sys‐
379 tem for image displays, but not the default for SAOimage. The
380 second pixel is indexed (1,0). See -one.
381 -zf zoom factor
383 Zoom the initial display of the image by zoom factor. A number
384 larger than one makes the image larger by that factor, using that
385 many display pixels per image pixel. A fractional zoom factor
386 displays that the image with that fraction of a display pixel per
387 image pixel.
388
390 Refer to the SAOimage User Manual for detailed descriptions of all
391 functions.
392 Most control actions take place within the context of a mode. Modes
394 are selected by clicking on menu buttons in the top row of the button
395 panel. Each menu mode brings up its own submenu buttons (the lower row
396 in the button panel) for mode specific selections. Actions and sub‐
397 modes are selected by clicking on buttons in the submenu row of the
398 menu panel.
399 The mouse controls specific functions in both the main display window
401 and the pan/zoom window. In the main display window, the function of
402 the mouse is determined by the mode and submode selections from the
403 button menu. The function can also be recognized by the appearance of
404 the mouse pointer icon.
405 The button interface is designed to be user friendly. The user is
407 encouraged to try any and all buttons to become familiar with their
408 functions. To exit, use the QUIT button in the etc submenu (click on
409 etc, then click on QUIT).
410 Reading images
412 To read an image directly from a file, give its name anywhere on the
413 command line. The -name switch is needed only when the image file name
414 could be mistaken for a number or switch. SAOimage recognizes the
415 .fits and .imh filename suffixes as belonging to FITS and IRAF OIF
416 files. All other file types must be specified by an appropriate file
417 type switch.
418 Raw array file types must be specified by an array data type switch
420 (-u1, -u2, -i2, -i4, -r4, -r8) followed by width and height dimensions.
421 To skip over a file header, use the -sk switch followed by the number
422 of bytes. This can also be used to skip over entire images, if more
423 than one are stored in the same file.
424 Use with IRAF
426 To emulate imtool and communicate with IRAF tasks, use either the
427 -imtool or -pros switch. The two switches indicate which file format
428 to use in recording saved cursors or regions. With -imtool, an IRAF
429 list file containing only center coordinates is used (like that of
430 imtool). With -pros, a file containing a full description of the saved
431 cursors and their dimensions is used. The latter file can be read by
432 tasks in the IRAF PROS spatial package for making image masks and per‐
433 forming image analyses. Both file types are ASCII and can be read and
434 edited by the user. In either case, the file is not actually written
435 until the user clicks on the write button in the region submenu. Both
436 file types can be read back to reproduce the saved cursors.
437 New command input
439 A new command line can be entered at any time, by selecting the new
440 button in the etc submenu or striking the N key on the keyboard. This
441 allows the user to read in new images, change in and out of -imtool or
442 pros mode, set new scaling parameters, or change the number of reserved
443 display color cells. Most command line switches (except -d, -g, -gd,
444 -red, -green, -blue, and -vertgraph) will be accepted at any time.
445 When a new command line is requested, the previous command line is pre‐
447 sented in an emacs-like popup editor for editing. Ctrl-N clears the
448 previous line. Striking the RETURN key enters the line in the popup
449 window as the new command. Ctrl-C returns with no action taken.
450 Using the mouse
452 Most mouse interactions are based on mouse dragging (holding a button
453 down while moving the mouse). The user should try clicking and/or
454 dragging the mouse in each subwindow to become familiar with its func‐
455 tions. Modes selected in the button panel determine the response to
456 the mouse buttons in the main display window.
457 In Scale mode, the mouse buttons control blinking of displays (saved by
459 clicking with the same mouse button in the blink submenu button).
460 In Color mode, mouse dragging stretches and shifts the color map as per
462 the contrast/bias, threshold/saturation, and gamma submenu selections.
463 In the color graph window, color table vertexes may be added or moved
465 by clicking or dragging with the LEFT (red), MIDDLE (green), or RIGHT
466 (blue) mouse buttons. The graph will update continuously only if
467 tracking is turned on.
468 In Cursor mode, the mouse controls the size and locations of cursors.
470 The rule is: LEFT button for position, MIDDLE button for size, and
471 RIGHT button for angle or deletion (depending on the cursor).
472 Cursors
474 For box and ellipse cursors, MIDDLE button sizing is restricted depend‐
475 ing on whether dragging started on a side or near a corner.
476 With the point cursor, the LEFT and MIDDLE buttons save the current
478 mouse pointer position with a + or - indication, while the RIGHT button
479 deletes saved points.
480 For the polygon cursor, the MIDDLE button adds or moves a single ver‐
482 tex, while the RIGHT button will delete vertexes. The LEFT button
483 moves the whole polygon.
484 When annuli is set for a box, circle, or ellipse cursor, the MIDDLE
486 button adds or resizes an annulus, while the RIGHT button deletes
487 annuli.
488 For manipulating cursors, the ovlay selection in the Color submenu,
490 enables the cursor to track smoothly as an overlay graphic. The region
491 submenu button brings up another submenu with selections to display,
492 review, and edit the saved regions, and read from or write to disk
493 files.
494 Pan and zoom
496 In Pan mode, and in the pan window (regardless of mode), the LEFT but‐
497 ton selects the center of the image, while the MIDDLE button selects
498 the edge of the display, zoomed from the given center. When either
499 function is dragged, the rectangle in the pan window shows the area
500 that would appear in the display when the button is released.
501 Keys
503 In the cursor mode, the S and E keys, save the current cursor in a
504 region list, while the D and DELETE keys can be used to forget a
505 region. At any time, with the pointer in the display or pan windows,
506 the T key prints a table of pixel values at the pointer position to
507 stdout. The 4 arrow keys can be used for fine movement of the pointer
508 in any window. The SHIFT and SHIFT LOCK keys will reverse the magni‐
509 fier window, color graph window and coordinate tracking status. The N
510 key summons the pop-up editor for new command input. The A key raises
511 and redraws all of SAOimage's windows.
512
514 SAOimage does not allocate its own colormap and thus fails with static
515 color (i.e. NeWS) window managers. X resource settings of a user's
516 default preferences are not read.
517
519 Additional information about SAOimage is available on the World-Wide
520 Web at http://tdc-www.harvard.edu/software/saoimage.html
521 7 July 1998 SAOIMAGE(1)