Table of Contents

Name

ds - a window and mouse-based utility for displaying a picture

Synopsis

ds [ -debug ] [ -d ] [ -mono ] [ -m ] [ -xflip ] [ -x ] [ -yflip ] [ -y ] [ -xyflip ] [ -xy ] [ -zlow lowpixvalue ] [ -l lowpixvalue ] [ -zhigh highpixvalue ] [ -h highpixvalue ] [ -zoom zoomvalue ] [ -z zoomvalue ] [ -range colormapsize ] [ -r colormapsize ] [ -color colormapselection ] [ -c colormapselection ] filnam [ lowpixvalue ] [ highpixvalue ]

Description

Options

Most options can be specified in two forms, a short form and a long form.

The file named filnam is displayed. This name may possibly be a name meaniful only to some package, like an AIPS file name (See Section on File names). If no filnam argument is specified then a name of BLANK512x512 is assumed which is a dummy file which containing a 512 by 512 array of zeroed pixels.

If the -zlow or (alternately) -l option is not present then the next positional argument is interpreted as lowpixvalue which has the same meaning as the -zlow option (see below).

Likewise if the -zhigh or (alternately) -h option is not present then the next positional argument is interpreted as highpixvalue which has the same meaning as the -zhigh option (see below).

-debug
-d
Turn on the debugging flag. This generates volumnious information on the standard error output that is sometimes useful for debugging ds.
-mono
-m
Force the display into monochrome mode, even if ds is being run from a color display. In monochrome mode a dithered array of black or white pixels is generated to represent a picture and all color facilities are disabled other than switching between a positive or a negative (inverted) display.
-xflip
-x
Flip the picture horizontally. This changes the origin from its default position on the left of the window to instead be on the right.
-yflip
-y
Flip the picture vertically. This changes the origin from its default position on the top of the window to instead be on the bottom.
-xyflip
-xy
Interchange the vertical and horizontal axes. The location of the origin on the window is unchanged.
-zlow lowpixvalue
-l lowpixvalue
Set the low pixel value for scaling to lowpixvalue. Exponential form (3.4.e-2 for example) is allowed. lowpixvalue and highpixvalue together set the scaling between the displayed pixels and the pixels contained in the original picture. If color is positive then lowpixvalue corresponds to a black display and highpixvalue corresponds to a white display. highpixvalue can be lower than lowpixvalue in which case a negative display will be obtained.
-zhigh highpixvalue
-h highpixvalue
Set the high pixel value for scaling to highpixvalue. Exponential form (3.4.e-2 for example) is allowed. lowpixvalue and highpixvalue together set the scaling between the displayed pixels and the pixels contained in the original picture. If color is positive then lowpixvalue corresponds to a black display and highpixvalue corresponds to a white display. highpixvalue can be lower than lowpixvalue in which case a negative display will be obtained.
-zoom zoomvalue
-z zoomvalue
Set the initial value of the zoom factor of the display. If the zoom factor is equal to 1 then one pixel on the displayed picture corresponds to one pixel on the display. A zoom factor of 2 produces a times 2 magnification with one pixel in the picture interpreted as a 2 by 2 array of pixels on the display. Magnification is currently done by pixel duplication. Negative zoom factors are interpreted as being the reciprical of their abolute value. For example a zoom factor of -2 produces a times two reduction in size with a 2 by 2 array of pixels in the picture corresponding to 1 pixel on the display. Reduction is currently done by pixel averaging with the pixel on the display being the average of the corresponding pixels in the picture. Currently the initial zoom factor must be a value for which the picture will fit on the screen. Otherwise the zoom value will be decreased to such a value. The default initial zoom value is 1.
-range colormapsize
-r colormapsize
Set the number of colors used to display the picture on a color or grey/level display. This must be a power of two and be less than or equal to 256. The default value is 128. A colormapsize of 1 is equivalent to the -mono option, setting the display into monochrome mode.
-color colormapselection
-c colormapselection

ds also accepts all of the generic tool arguments discussed in suntools(1) .

Subwindows

ds consists of up to four subwindows.

control panel
picture canvas
ramp canvas
blanking window

Control Panel Items

File Name Text Item
This item shows the name of the file currently displayed and can be used to select another file to display. To select this item: point the cursor at it and press the left mouse button. A triangular blinking cursor will appear to the right of the file name. To prevent accidental changing of the file file, the triangular cursor will not appear in this item unless it has been explicitly selected. With the mouse cursor then still inside the control panel the keyboard can be used to change the file name. The old file name can be cleared out with your line kill character (usually control U or control X) or your delete character (usually Delete or backspace). The file name entered here may possibly be a name meaniful only to some package, like an AIPS file name (See Section on File names). When carriage return is pressed ds will be notified to load the new file. If the new file can not be found the old file will continue to be displayed. When the new file is being loaded the cursor will be replaced by a cursor shaped like an hourglass, to indicate that ds is busy and the message "loading file..." will appear in the message item.
Z Low Text Item
Z High Text Item
These are the two Z boundary items. The value of these two items determine the mapping between pixel values in the original picture file and the brightnesses and colors shown on the screen. Ordinarily value of the Z Low Text Item corresponds to pixels that are displayed as black and the value of the Z High Text Item corresponds to pixels thatat are displayed as white, yielding a positive display (currently the only exception to this statement is when the Colormap Cycle Item has a value of Negative. Then the sense of the statement is reversed: Z Low pixels are white and Z High Pixels are black). However a Z Low Text Item value higher that the value of the Z High Text Item is legal, yielding a negative or color inverted display. Exponential form (3.4.e-2 for example) is allowed and is useful if the picture contains floating point pixels. The keyboard can be used to change the value of the item if the mouse cursor is inside the control panel and a triangular blinking cursor is present in the item. If the triangular cursor is not there already, it can be brought to the item by selecting the item (pointing to it with the mouse cursor and pressing the left mouse button). The old value can be cleared with your line kill character (usually control U or control X) or your delete character (usually Delete or backspace). Then the new value can be entered. Pressing carriage return notifies ds of your new value and sends the triangular cursor over to the other Z boundary Text item (the triangular cursor can only be moved to the File Name Text Item by selecting it explicitly). The new value will not be applied to the display of the picture until the Repaint Button Item on the control panel is invoked.
Zoom Factor Slider Item
This item controls the value of the zoom factor. Position the cursor inside the rectangular box (the "slider rectangle") and press the left mouse button. Move the cursor to the left or the right until the zoom factor (given in square brackets to the left of the slider rectangle) has the value desired. Then release the left mouse button and the display will be readjusted to the new zoom factor. The operation can be aborted and the previous zoom factor retained by moving the cursor out of the slider rectangle before releasing the left mouse button.
Colormap Cycle Item
X flip toggle
Point cursor at this item and press left mouse button to change the value of the X flip toggle. Changing the value of the X flip toggle flips the picture horizontally. When the X flip toggle is off the origin is on the left side of the window. When the X flip toggle is on the origin is on the right side of the window.
Y flip toggle
Point cursor at this item and press left mouse button to change the value of the Y flip toggle. Changing the value of the Y flip toggle flips the picture vertically. When the Y flip toggle is off the origin is on the top side of the window. When the Y flip toggle is on the origin is on the bottom side of the window.
XY flip toggle
Point cursor at this item and press left mouse button to change the value of the XY flip toggle. Changing the value of the XY flip toggle flips the picture on a diagonal line through the picture, interchanging the horizontal and vertical axes. The location of the origin on the window is unchanged. The XY flip is applied before the X and Y flips. Thus an X flip will always interchange the left and right hand sides of the display and a Y flip will always interchange the top and bottom of the display. When the XY flip toggle is off the pixel rows in the picture run horizontally. When the XY flip toggle is on the pixel rows in the picture run vertically.
Blank Button
Point cursor at this "button" and press left mouse button to invoke the screen blanking feature intended for use with hard copy devices. A window the color of the background (usually black) appears covering the whole screen. In its center is a window on the picture being displayed at the current pan and zoom. For more information see the subsection on "Blanking Feature".
Repaint Button
Point cursor at this "button" and press left mouse button to repaint the image in the picture canvas. This is generally used after the brightness scaling factors "Z Low" or "Z High" have been changed to show the image with the new scaling.
Quit Button
Point cursor at this "button" and press left mouse button to exit ds. A confirmer window will appear. Press the left mouse button a second time to confirm the quit or press the right mouse button to cancel the quit.
Help Button
Point cursor at this "button" and press left mouse button for help on the various features in ds. At the moment all that happens is the message appears in the message item "help not yet implemented". Pressing the help button will eventually bring up popup menu of items for which help is requested.
Message Item

Commands in Picture Canvas

Blanking Feature

File Names

Ds can display files that have several different formats. Each format has associated with it two routines, an examine and a load routine. Each examine routine is called in turn to look at the file. The examine routine can return 3 different statuses. If it returns NOT_OURS it goes on to the next examine routine in the list. If it returns BAD the search is aborted. If it returns OK the load routine for that format is called. If BAD status was returned by the examine routine or if the load routine returns bad status an attempt is made to reload the previous picture. A status of NOT_OURS returned by the examine routine may mean that the file didn’t exist under that name, as for some of the formats it may be stored under a modified version of that name. For example: iraf files may have a .imh tacked onto the end of the name or AIPS files may require a search of an AIPS catalog to translate the name into the long funny name where the image is actually stored. A name that begins with the characters BLANK is not expected to be on disk at all but results in a image containing zeroed pixels.

Once a picture is loaded then it is present in memory and no further reference to it is made by the ds program. The file formats recognized by the load routine are:

1) Iraf:
These files are generated by the IRAF image processing package. If filnam is a string of characters (uppercase/lowercase significant) then filnam or filnam.imh (with a .imh extension) are recognized. The accompanying .pix file (which must exist) is located by reading the header in the .imh file. Hostname prefixes in the .pix file name are currently ignored.
2) Fits:
These files are disk images in the FITS tape transmission standard. The file name recognized is the same as the name of the disk file used to store the images.
3) Sun Raster:
These files are in the standard form for picture storage used by Sun Microsystems software. The file name recognized is the same as the name of the disk file used to store the images. Either 8 bit or 1 bit monochrome images are recognized. Monochrome images result in pixels that either contain 0 or 255.
4) Aips:
These files are generated by the AIPS image processing package. The name can either be the name of the actual image head (of the form CBBxxxxx.xxx;1 ) or the AIPS catalog name. The AIPS catalog name is constructed in the form aipsname‘class‘seqno‘aipsid . A backquote separates the name sections. A doubled backquote is interpreted as a single backquote in a name section. The "aipsid" name section is optional and if omitted it defaults to the user’s uid number from the /etc/passwd file. If the "seqno" section is omitted then the picture with an otherwise matching name that has with the highest seqno will be used. A name or class of * will match any name or class. An omitted class is equivalent to a class of *. the search for an aips catalog (file name beginning with the letters "CAA") begins in the current directory. If that fails the search continues at directories pointed to by environment variables DA01, DA01, DA02, ... DA0n. The search terminates when the file is found or when an environment variable does not exist.
5) NMR picture:
These files are used to store NMR images from the Laurie Imaging center. The file name recognized is the same as the name of the disk file used to store the images. The file consists of 256 x 256 2 byte pixels offset by a 2048 byte header. Pixels are in byte-swapped order, i.e. the less significant byte is first.
6) blank file:
Generates a picture filled with zero pixels. This picture can be used as a simple default or as a blank background for graphics. The file name consists of the letters BLANK followed optionally by a single number or by two numbers separated by the letter "x". The name BLANK generates a 512 by 512 pixel blank picture. The name BLANKn where "n" is a number generates an n by n pixel blank picture. The name BLANKnxm where n and m are numbers generates an n by m pixel blank picture.

Bugs


Table of Contents