GRIPS 2: Government Raster Image Processing Software & Data

home *** CD-ROM | disk | FTP | other *** search

/ GRIPS 2: Government Rast…rocessing Software & Data / GRIPS_2.cdr / dos / pc_mips / imdisp.rmf < prev next >

Wrap

Text File | 1990-06-25 | 76.7 KB | 1,679 lines

PLANETARY DATA SYSTEM USER'S GUIDE FOR THE PDS IMDISP PROGRAM INTRODUCTION This document describes the IMDISP program, an interactive image display utility for the IBM Personal Computer family (PC, XT and AT) and compatibles. It has been developed for use with the Compact Disk - Read-Only Memory (CDROM) storage systems currently being evaluated by the Planetary Data System (PDS). It can also be used to display images stored on floppy or hard disks. This User's Guide presents an overview of image processing and CDROM fundamentals, a section on the installation of IMDISP and CDROM software and hardware, a description of IMDISP program operation, a description of other utility programs which can be used in conjunction with IMDISP, and a command summary. Other support software for using the PDS CDROM disks has also been developed. These packages include the USGS Planetary Image Cartography System (PICS) for Microvax computers, a set of FORTRAN routines to access CDROM disks on VAX computers (VMSCD), and "C" language source code to process disks written in the High Sierra format. Contact Mike Martin (JPLPDS::MMARTIN) for access to these tools. Chapter 2 BACKGROUND Efforts to utilize small computer systems for display and analysis of scientific data have been hampered by the lack of sufficient data storage capacity to accommodate large image arrays. Most planetary images require nearly a megabyte of storage. Over the past two years a new storage technology "CDROM" has been developed which provides the capability to store up to 600 megabytes of data on a single 4.72-inch disk. The disks can be mass produced, and hundreds of copies of large digital archives distributed rather than the few sets currently produced. Readers for CDROM disks can now be purchased for under a thousand dollars for use on personal computers and some science workstations. The PDS has worked with industry and other government agencies to support the development of CDROM as a major data distribution and storage media for space science data. Initial development efforts by the PDS, the Voyager Project, and multi- disciplinary science representatives have resulted in the production of 5 CDROM disks, two samplers, and 3 disks containing all 6,538 images from the Voyager Uranus encounter. The IMDISP program can be used to display most of these data files on a personal computer equipped with a CDROM drive. 2.1 DIGITAL IMAGE PROCESSING SUMMARY A digital image is a picture converted to numerical form so that it can be stored and used in a computer. The image is divided into a matrix of small regions called picture elements, or pixels. The rows and columns of pixels are called "lines" and "samples", respectively. Each pixel has a numerical value, or DN (data number) value, quantifying the darkness or brightness of the image at that spot. In total, each pixel has an address (line number, sample number) and a DN value, which is all that the computer needs for processing. The DN value of each pixel usually represents a shade of darkness or brightness between black and white (gray levels). How many gray levels there are in an image depends on the number of bits used to represent each pixel intensity in the computer. The number of gray levels will be equal to 2^n, where n is the number of bits per pixel's DN value. If 8 bits are used to represent a pixel's DN value (gray level), the system will be capable of using 2^8, or 256, gray levels in an image, where DN 0 is pure black, and DN 255 is pure white. If each DN used only 4 bits of storage, the image would contain only 2^4 or 16 gray levels; if there were only 1 bit per DN, the image would contain only black and white pixels (bit values of 0 or 1). 2.2 OVERVIEW OF IMDISP CAPABILITIES While the specifics of IMDISP commands are discussed in Chapter 4, this section provides a general overview of how a user can manipulate images once a file is selected. There are DISPLAY commands which allow the user to display all or part of an image at various positions on the display screen. The user may also zoom in and out from a point on the image defined by the cursor, and may pan around the image. The cursor may be turned on or off; when on, the arrow keys are used to move the cursor around the screen; when off, the cursor is not visible. A user may choose to "subsample" the image, to enable more or all of the original image to be displayed on the screen at once. For example, if the image were subsampled by a factor of 2, every other pixel from every other line would be displayed, starting from the upper left corner of the image. If a factor of 3 were chosen, every third pixel from every third line would be displayed. Any positive integer may be used for subsampling. The user may produce a histogram of an image file, which is a graph showing the number of pixels per DN value, or per range of DN values, for the entire image. Histograms are overlaid on top of the image, but may be removed using the REFRESH command. Subsampling may be specified when computing a histogram to reduce the time required for the calculations. A profile may be created which plots DN value versus pixel along a line between two points on the image. After the cursor is used to select the two endpoints, the connecting line is drawn on the image and the profile is plotted at the bottom of the screen. The user may also "stretch" the image, which is analogous to turning the contrast knob on a TV set. The user specifies low and high DN values; all pixels with values lower than the specified "low" become black, and all pixels higher than the specified "high" value become white. All pixels between the low and high values are evenly shaded between black and white. There are bookkeeping types of commands, also. These allow the user to do such things as retrieve a desired image from the CD-ROM, to save an image to a file on hard disk, and to erase only the graphics from the screen or to erase the entire screen. Users may execute batch command files to do a series of tasks automatically. Lastly, the user may, of course, EXIT the IMDISP program when done. 2.3 GRAY LEVEL AND FALSE COLOR IMAGES Most planetary images are composed of 8-bit DN values representing monochrome brightness levels in the scene. To obtain color images, separate images are taken through color filters (red, green, blue) and are then combined by ground processing systems to produce a true color image. Only a very small fraction of planetary images are available in color versions. Most display and analysis is done on monochrome images. A display with 256 (2^8) gray levels is required to present the information contained in a standard image. However, the human eye can only distinguish about 32 gray levels. Thus 5-bit DN values would satisfy most display requirements. Unfortunately, computers are oriented to the storage of and manipulation of items which are a power of two, and 5-bit pixels would be very clumsy. The display devices which the IMDISP program supports are limited to 16 gray levels (PGA), 4 gray levels (EGA) or 2 gray levels (CGA). The 16 gray levels of the PGA are adequate to support image analysis; however 4 or 2 gray levels are practically useless for viewing planetary images. Fortunately the EGA display will support 16 different colors, and a color palette can be selected which uses a graduated scale of colors to represent gray levels, producing a "false color" image (false because the displayed color does not represent the actual color of the scene). A false color image (also called a pseudo color image) is created from a black and white image by assigning a color (rather than a gray level) to each DN value in the image. For instance, a DN value of 128 could be reassigned to yellow if the user so desired. Ranges of DNs (e.g., 100-125) may also be assigned one color. Pseudo colors get assigned to DN values in a pseudo color table, which the display program then uses to determine how to color the image on the monitor. Display programs often have preset pseudo color tables with commonly used DN-color combinations, and the user can simply call for one of these when generating a pseudo color image. The option exists, of course, for users to generate their own pseudo color tables. Pseudo colors are often used to highlight features of an unusual nature in an image. Since the Enhanced Graphic Adapter for the IBM PC provides only 4 gray shades (black, dark gray, light gray and white) most image viewing is done using a pseudo color table which interprets gray levels as color values ranging from black through reds, greens and blues up to white. 2.4 RADIOMETRIC AND GEOMETRIC CORRECTIONS All camera systems have some kind of distortions in the lens, in the way the shutter works, etc. Distortions in the amount of fight transferred through the camera to the imaging plate are called radiometric distortions. Geometric distortion affects the "squareness" of an image, and is detected by taking an image of a geometric grid. For spacecraft cameras, both types of distortion can be measured before launch, and in a limited fashion, in flight. These measured distortions are saved in digital files. When a raw image is received, these "calibration files," as they are called, are subtracted from (or otherwise applied to) the image, effectively removing radiometric and geometric distortion. This process is called radiometric and geometric correction. Corrected images contain the closest possible representation of the scene being imaged. 2.5 IMAGE FILE FORMATS Digital image files are seldom stored as a simple array of pixels. Generally there is an area at the beginning of an image file containing descriptive information about the image. This is referred to as a label or header area. Figure 2-1 shows a diagram of a simple image format with a label area followed by the image lines. In practice, images from planetary missions have a more complicated format, due to the need to store additional information to allow proper interpretation of the image data. Figure 2-2 shows the format of a Voyager image, which has engineering parameters embedded at the end of each image line to form a line suffix area, an engineering trailer record after the last image line, and this is followed by an image histogram. -------------------------- | Labels or Header Area | |--------------------------| | Image Array Line 1 | |--------------------------| | Image Array Line 2 | |--------------------------| . . . -------------------------- | Image Array Line n | -------------------------- Figure 2-1: Simple Image Format Different image label formats have been developed for use by nearly all image processing facilities. Two formats are widely used within the planetary and astronomy communities: the VICAR2 (Video Image Communication and Retrieval) labels used by the Multi-Mission Image Processing Laboratory (MIPL) and FITS (Flexible Image Transport) labels used for astronomy image interchange. The PDS has developed a label scheme which is very similar to these standards, called the Object Description Language (ODL). This format attempts to add a broader range of data descriptive capabilities to the proven capabilities of the existing label systems. A description of the ODL architecture is given in Appendix D. Most of the images stored on the PDS CDROM disks have either ODL or VICAR2 labels. IMDISP will automatically interpret these labels to determine the display format of the image data. -------------------------------------- | PDS ODL Labels | |--------------------------------------| | Image Array Line 1 | Line Suffix | |--------------------------------------| | Image Array Line 2 | Line Suffix | |--------------------------------------| . . . --------------------------------------- | Image Array Line 800 | Line Suffix | |--------------------------------------| | Image Engineering Trailer | |--------------------------------------| | Image Histogram | -------------------------------------- Figure 2-2: Voyager CDROM Image Format 2.6 CDROM FUNDAMENTALS The CDROM disk uses the same basic data storage format as a CD audio disk. In fact, data blocks are identified by minute, second and sector number, following the audio format. Data blocks are recorded along a spiral from the inner to the outer radius of the disk. Each raw data block (sector) contains 2,352 bytes of information, with 304 bytes used for housekeeping and error correction and 2,048 (2K) containing user data. Each data block is called a sector, and 75 sectors are stored per second. Since the nominal playing time of a CD disk is 60 minutes, the data storage capacity is 75 sectors per second * 60 seconds per minute * 60 minutes or 270,000 sectors. Thus the nominal storage capacity of a single CDROM disk is 540,000 kilobytes, which can be extended to more than 600,000 kilobytes and beyond by recording more than 60 minutes of data on a disk. In order to maximize the storage capacity of CD disks a constant linear velocity (CLV) recording format is used. This means that the player changes speed (slows down) as it reads from the inside to the outside of the disk, to maintain a constant flow of data under the read mechanism at a speed of 1.2 meters per second. This is in contrast to most magnetic disk drives which use constant angular velocity (CAV) storage, where the information density is greater on the inner tracks that the outer tracks. While the use of CLV recording increases the storage capacity of CDROM disks, it reduces access time, since the disk must change speeds as it moves to different positions on the disk radius. The strategy for locating a recorded data block is also more complicated than with constant angular velocity recording technology. As a result the average access time of CDROM drives is between 400 ms and 1 s, and the maximum data transfer rate to the host computer is 150 kilobytes per second. These rates are approximately an order of magnitude slower than magnetic disks. Therefore, the access mechanisms to disk directories and data must be customized for CDROM in order to provide acceptable performance. The development of a standard logical format for recording data files on CDROM disks was taken on by a group of CDROM applications developers, hardware vendors and computer vendors. The proposed standard resulting from this effort is called the High Sierra format. This format was submitted to the International Standards Organization (ISO) for consideration and approved on October 5, 1987. The format used for the PDS CDROM disks is dated May 28, 1986, and differs slightly from the final ISO standard. Microsoft and other CDROM software developers have committed to supporting this preliminary version of the format in later software releases. However, software developed by other vendors to support the ISO format (DEC for example) will not support the format of these disks. Chapter 3 IMDISP INSTALLATION IMDISP requires an IBM PC, XT, AT or 100 percent compatible with 512K of base memory. It supports several graphics display devices, including the Enhanced Graphics Adapter (EGA), the Video Graphics Array (VGA), the Professional Graphics Adapter (PGA), and the Color Graphics Adapter (CGA). The hardware environment in which the program has been developed and tested includes and AT class computer, deluxe or enhanced EGA board with 256K of memory, and multisync or multiscan monitor. 3.1 PROGRAM SETUP The IMDISP program can be run from a floppy or hard disk. To use the program from a floppy disk, insert the program disk in the A: or B: drive and type the MSDOS command: "A:" or "B:" to set the floppy disk as the default drive. To use the program from hard disk first create a directory to hold the IMDISP files. Use the MSDOS command "MKDIR \IMDISP" to create a directory to hold the programs. Use the "CHDIR \IMDISP" command to make IMDISP the default directory. Insert the distribution floppy disk in floppy disk drive A:. Now type "COPY A:*.*" to copy the files from the distribution disk to your hard disk. You should now be able to run all examples from that directory on your hard disk. If you wish to use IMDISP from other directories, you need to include the IMDISP directory in your MSDOS "PATH" command. This command provides MSDOS with a list of directories to search when looking for a program file to run. If you wish to run IMDISP from different directories, the \IMDISP subdirectory should be added to the PATH command in your AUTOEXEC.BAT file. A sample path command would look like this: PATH=C:\DOS;C:\UTIL;C:\WORDSTAR;C:\IMDISP The sample batch files and special pointer label files included on the distribution disk will only run if your current default directory is \IMDISP. You may want to add a line to your AUTOEXEC.BAT file which will allow you to abort the display program while running batch files or displaying large image files. If the command "BREAK=ON" is placed in CONFIG.SYS, you will (sometimes) be able to terminate the IMDISP program by typing the control and break keys simultaneously. Different computer systems offer varying response to the control-break command, and the use of this command may effect other programs you use. 3.2 CDROM SETUP To use the IMDISP program with PDS CDROM disks you will need a CDROM reader, interface board, and software provided by the vendor which will make your CD Reader look like a disk drive to your PC. The details of setting up your hardware and software configuration are beyond the scope of this manual, however several aspects of setup will be reviewed. There are many potential pitfalls in setting up your hardware and interface board. Read the directions carefully, and don't assume that "default" switch settings are correct. Check all switches to see that they correspond to the recommended settings. To work properly with the batch command and label files provided with IMDISP, your CDROM drive should be set up to be drive letter "L:". Most vendor software allows you to select the drive letter which will be assigned to the CDROM reader. 3.2.1 Microsoft Extensions If you are using the Microsoft Extensions you will load a CDROM device driver as part of your CONFIG.SYS file (or two drivers if using the Philips or DEC readers) with a line like this: DEVICE=HITACHI.SYS /D:CDROM1 /N:1 This command assumes that the driver file "HITACHI.SYS"is located in your ROOT directory. The /D:CDROM1 switch assigns a logical name CDROM1 to the drive. A name must be supplied, and is used to identify this device, in case more than one CDROM drive is being used on your system. The name should not be the same as the name of any file stored on your system. An attempt to open a file with the same name as the device driver will result in the device driver being opened, not the file. The /N:1 switch indicates that this is drive 1. This switch is used since some CDROM interface cards support multiple drives. Other commands which should be included in CONFIG.SYS if you are using a CDROM drive with the Microsoft Extensions are: LASTDRIVE=Z FILES=30 BUFFERS=50 The LASTDRIVE command tells MSDOS to allow for enough drive letters to support the CDROM drive, plus any other drives on your system. Using LASTDRIVE=L should also work in most circumstances. The files and buffers specifications provide sufficient system work area to support CDROM operations. You must also execute a program called MSCDEX.EXE which allows access to the CDROM drive as if it were a disk drive on your system. This command can be put in your AUTOEXEC.BAT file so that it is automatically run whenever you start-up your computer. The command format is: MSCDEX /D:CDROM1 /L:L /M:20 /V /E Several MSCDEX command switches are illustrated. The /L:L command assigns the drive name L: to the CDROM drive. The /D switch gives the device name of the CDROM drive (which must be the same name used in the device name parameter of the "DEVICE=CDROM.SYS" command in the CONFIG.SYS file. The /M:20 switch assigns twenty 2K blocks of memory as a buffer for use with CDROM data. The /V switch provides verbose messages when the installation program is run, and /E tells the program to use expanded memory for the cache area. 3.2.2 Other Driver Software Some vendors (Reference Technology, TMS) offer CDROM software which is comparable to the Microsoft Extensions. Our experience with these software packages is that they modify the internals of MSDOS and may cause unpredictable results with your other PC software. They often do not support CDROM applications designed to work with the MSDOS extensions for CDROM and cannot be used with the IMDISP FILE prompt mode. 3.2.3 Problems with CDROM Software The PDS CDROM disks utilize a feature of the CDROM format standard which provides extended attribute records to define the physical characteristics of data files. These records will be used by VAX and other minicomputer systems where the operating system allows a variety of record formats (fixed, variable, stream). Many of the earlier implementations of High Sierra software failed to recognize these records, which are placed at the beginning of a file's data area. If your CDROM software was developed prior to April 1987, it may interpret these records as part of the data file, causing the first 2K bytes of each file to appear as meaningless binary data. Users with this problem should contact their hardware or software vendors for updated versions of the CDROM software. The IMDISP program has been patched to recognize and skip over these records on the PDS CDROM disks, but these patches may not support other CDROM disks with extended attribute records. 3.3 DISPLAY DEVICE CHARACTERISTICS IMDISP automatically finds out which display devices are available (PGA, EGA, or CGA) and uses the one available. The Enhanced Graphics Adapter must have at least 128K of memory to work properly. Use of the Color Graphics Adapter is discouraged because the pixels have no gray levels, only black or white. The display coordinates start at (1,1) in the upper left corner of the screen; the line direction is down and the sample direction is to the right. 3.3.1 Enhanced Graphics Adapter (EGA) The EGA is a bit-mapped display device providing a resolution of 350 lines by 640 samples of 4-bits each. It produces a digital video signal for each primary color (red, green and blue), The video signal for each color can be set to one of four levels, roughly equivalent to off, low, medium and high. Thus the number of possible colors (color palette) is 64 (4^3). The following table illustrates the colors created by some of the different combinations of red, green and blue. Red= off, Green= off, Blue= off results in Black Red= low, Green= off, Blue= off results in Dark Red Red=medium, Green= off, Blue= off results in Light Red Red= high, Green= off, Blue= off results in Bright Red Red= low, Green= low, Blue= low results in Dark Gray Red=medium, Green= low, Blue= off results in Brown Red=medium, Green=medium, Blue= off results in Yellow Red=medium, Green=medium, Blue=medium results in Light Gray Red= high, Green= low, Blue= off results in Orange Red= high, Green= high, Blue= high results in White Table 3-1: Sample EGA Color Palette Settings The EGA display is limited to only 16 colors out of the 64 possible, because only 4-bits are used to store each pixel value in memory. This 4-bit pixel value points to an entry in the color table which represents one of the 64 possible combinations of red, green and blue which can be displayed. Many of the newer EGA boards are capable of displaying additional lines and samples when using a Multisync or Multiscan monitor. The standard EGA uses a 16 Mhz crystal oscillator (something like a clock which regulates the display speed), which limits the video output rate to the equivalent of 640 pixels by 350 lines. The EGA circuitry allows for a faster crystal oscillator to be added to the board (24 Mhz and beyond) allowing about 25 percent more lines to be displayed (480 lines instead of 350). A method for adding this capability to an existing EGA board (for about $10 worth of parts) is described in the September 16, 1986 issue of PC Magazine. This mode requires that a multisync or multiscan monitor be attached to the computer, and there is no way for the program to automatically detect the presence of the special monitor. Therefore this display mode is invoked by specifying an MSDOS "ENVIRONMENT" variable. This is done by issuing an MSDOS "SET" command at the MSDOS prompt as follows: SET IMDISP=EGA480 This command can also be put in your AUTOEXEC.BAT file using a text editor, so that you need not invoke it each time you run IMDISP. It should have no effect on other MSDOS system operations. There is a chance that adding this variable will exceed the size reserved by MSDOS for environment variables. If so, you should consult your MSDOS manual to increase the environment size on your system. The environment variable can be removed with the MSDOS command: SET IMDISP= Where a carriage return is typed immediately after the equal sign. The 480 line mode requires an additional 83K of memory for the refresh buffer. If you try this mode and receive the message "Insufficient memory for line buffer", it is probably because you have a 512K memory machine, or have memory resident programs operating (like Sidekick or Superkey) which reduce the available memory to less than about 400K. You will need to use the 350 line mode or remove some memory resident programs to operate in 480 line mode. Users of the EGA with Multisync and Multiscan monitors can achieve a 16 gray level display through the use of a special device called the Grayscaler 1, from Avocado Computer, Box 632, Yorba Linda, Ca, 92686, (714) 528-1025. This cable converts the digital video signals produced by the EGA board to analog signals. By selecting appropriate EGA palette entries, a fairly good representation of 16 gray levels can be achieved (use the palette selection "PAL LOAD GRAY16.PAL" to select this palette). 3.3.2 Video Graphics Array (VGA) This version (4.0) of the IMDISP program includes support for the IBM Video Graphics Array (VGA) display device. The VGA produces an analog display with several new color modes. Of particular interest to IMDISP users are the 640 x 480 line mode with 16 displayable colors (or gray levels). The 320 x 200 line mode with 256 displayable colors (or 64 gray levels) has been tested but produces very blocky pixels. This version of IMDISP supports the 640 x 480 mode. To set the VGA display mode you must set a MSDOS environment variable prior to executing IMDISP. To set the environment variable use the MSDOS command: SET IMDISP=VGA This will put the display in 640 sample by 480 line mode, with 16 gray levels or colors displayable from a palette of 256K. The display is initialized with a gray scale palette, but a pseudocolor palette can be invoked with the IMDISP command "PAL PS 0". The "PALETTE EDIT" command will allow you to step forward or backward through the 64 available shades for each primary color. See the next section of the IMDISP manual for more information on the palette edit function. Users who wish to experiment with the 320 x 200 VGA mode may use SET IMDISP=VGA320 but be warned that all text messages expect an 80 column screen, and therefore wrap-around on the display creating a mess. This mode is only provided for experimentation and is not for casual users!!! 3.3.3 Professional Graphics Adapter (PGA) The PGA is a special graphics board developed by IBM for use with CAD/CAM applications on the IBM PC. Because its architecture is incompatible with the CGA and EGA boards, it has not been well received by software developers. The PGA provides an analog video signal with a display resolution of 480 lines by 640 samples of 8-bits each. It provides 16 intensities for each primary color, resulting in a palette of 4,096 colors (16^3). The color table allows 256 colors to be displayed simultaneously, however only 16 gray levels can be selected. Use the command: SET IMDISP=PGA at the MSDOS prompt to force IMDISP to go into PGA display mode. 3.3.4 Color Graphics Adapter (CGA) The CGA display is a bit-mapped graphics device with a resolution of 200 lines by 640 samples of 1-bit each. It supports only 2 colors in this display mode, black and white. This display can be used to get a general idea of the contents of a digital image, or for displaying one bit images (graphics for example) but is not recommended for use with the PDS CDROM images. To force a multi-function display card into CGA mode, use: SET IMDISP=CGA Chapter 4 IMDISP OPERATION IMDISP can be used to display images up to several thousand lines and samples with a variety of pixel formats. These formats include bit (1 bit), nibble (4 bits), byte (8 bits), or integer (16 bits). Integer pixels are assumed to be byte-swapped, which means that the sign and most significant 7 bits are in the rightmost byte, and the least significant 8 bits are in the leftmost byte. This is the convention used by both the IBM PC and VAX computer hardware families. IBM mainframes and 68000 series computers (Macintosh and Sun, for example) use un-byte-swapped integers. Program interaction with the user is via commands typed in response to the "COMMAND:" prompt. Most interaction is performed on the graphic display screen, and program messages are printed over any image display currently on the screen. The REFRESH command can be used to restore an image after other commands have written text over the display. The ERASE command can be used to clear away the clutter left by program status messages and previously displayed images. The screen is not automatically erased after each operation in order that multiple images can be displayed simultaneously, or so a histogram can be placed on the screen with the image. IMDISP is invoked by typing "IMDISP" or "IMDISP filename", where filename is the name of an image file to be opened for processing at program start-up. The filename may include a disk drive and path name specification. The program will blank the display screen and display a welcome logo, then the prompt "COMMAND:" will appear in the lower left portion of the screen. If a filename is included in the command invocation, the welcome message is not displayed and the screen will display the COMMAND: prompt. Typing "HELP" at the command prompt will provide a list of IMDISP commands. The most frequently used commands are "FILE" to open a file for processing, and "DISPLAY" to display an image once the file has been opened. 4.1 COMMAND SYNTAX The command line syntax is of the form: COMMAND KEYWORD1 = VALUE1 KEYWORD2=VALUE2 KEYWORD3 VALUE3 . . . The command line may be typed in either upper or lower case. The command and the keyword names may be abbreviated to 3 characters in most cases. Any number of spaces may be inserted between words, and the keyword and value may be separated by a space or an equals sign. Some keywords do not require a value. All keywords are optional and have default values. 4.2 COMMAND DESCRIPTION Table 4-1 presents a summary of IMDISP commands. They are separated into 3 groups, file manipulation commands; display commands and program control commands. Only the capitalized letters are required to specify a command. 4.3 OPERATING MODES Several of the commands invoke special program operating modes. These include the FILE command when issued without a filename argument and the CURSOR, PROFILE and PALETTE EDIT commands. The FILE mode displays a list of files in the current directory on the screen for selection. It also contains several subcommands for controlling the display of files on the menu screen. In the CURSOR, PROFILE and PALETTE EDIT commands the cursor keys (arrow keys) on the numeric keypad are used in conjunction with other keys to control program operation. These modes are exited by typing either a period '.' or carriage return. File oriented commands: CD . . . . to change the default directory DIRECTORY . . . . to perform the MSDOS directory command FILE . . . . to specify the name of the image SAVE . . . . to save the image display to a file TYPE . . . . to perform the MSDOS type command LABEL . . . . to display the image labels Display commands: BROWSE . . . . to display a group of images DISPLAY . . . . to display the image ERASE . . . . to erase the display OVERLAY . . . . to place an overlay on the image REFRESH . . . . to refresh the image plane PALETTE . . . . to adjust the palette for the display HISTOGRAM . . . . to display the histogram of the image SET . . . . to set DN value range STRETCH . . . . to do a linear gray scale stretch CURSOR . . . . to move the cursor around PROFILE . . . . to plot a profile of the image TEXT . . . . to draw text on the image Program control commands: BATCH . . . . to execute a batch command file MENU . . . . to select images from a menu file EXIT or QUIT . . . . to exit from the program HELP . . . . display help information SYSTEM . . . . execute MSDOS commands Table 4-1: IMDISP Command Summary 4.4 ERROR HANDLING If an invalid command is issued at the COMMAND: prompt the program will beep and return to the COMMAND: prompt. In handling command parameters the program takes action on those parameters that are recognized, but ignores invalid parameters. For example, issuing a "SET LO = 25 HI = 100" command will not have any effect since the proper parameter names for the SET command are "DNLO" and "DNHI". It is also possible for certain system errors to be encountered which cause the program to abort leaving your computer in graphics mode. N you are using certain utilities which reset the default text mode screen colors (like the Norton Utilities screen attributes command) you may not be able to see what is being printed on the screen. The simplest approach is to perform a warm boot, by typing the Ctrl, Alt, Del keys simultaneously. Alternately, you can often type IMDISP then EXIT to reset the computer to text mode. Errors in processing image files on CDROM, hard disk or floppy disks can cause these aborts. 4.5 COMMAND REFERENCE This section lists all IMDISP commands alphabetically and describes their function, parameters which control command operation, and provides examples of command use, In the command and parameter description the following conventions are used: filename represents the name of an MSDOS file, and may include an optional drive identifier and path specification. n represents an integer value. 4.5.1 BATCH The BATCH command reads commands from the specified batch command file. If no file name is specified the current directory is searched for a file named BATCH.CMD. The CURSOR, PROFILE and PALETTE EDIT commands should not be used within batch command files since they require interactive inputs from the keyboard. The BATCH command may take the following argument: filename filename of batch command file. A batch file is simply a text file containing a list of commands, with each command terminated by a carriage return. If the command file is created with a word processor, the program should be used in the non-document mode, to assure that carriage returns are embedded between command lines. An example of creating a batch file to display the PDS logo image follows. At the MSDOS command level type: COPY CON TEST.CMD FILE LOGO.IMG DISP ZOOM 4 DISP ZOOM 2 DISP DISP SUB 2 EXIT Now run IMDISP and type"BATCH TEST.CMD" at the "COMMAND:" prompt. Make sure the file "LOGO.IMG" is in your current directory. The PDS logo should be displayed on the screen in several different sizes. 4.5.3 BROWSE The BROWSE command will display all images in a directory one after another. An optional directory mask can be supplied to display only selected files ("BROWSE *.IMG"). The command creates a list of files to be displayed, then creates and executes a batch command file to display those images. After each image is displayed, the filename is displayed at the top of the image. A BROWSE session can be interrupted by pressing control-s, then restarted by pressing control-q TWICE. A session can be halted by typing any other key during the display. It can then be restarted (from the beginning) with the command "BROWSE C:BATCH.CMD". The default file name for the batch file created by the BROWSE command is 'C:BATCH.CMD'. This name can be changed using the "SET BROWSE fname" command where fname can consist of a drive letter and filename, which should be terminated with the extension ".CMD". The BROWSE command has one argument and several optional keywords. fname optional file selection mask (must immediately follow the command BROWSE). May include a drive letter but not a subdirectory name. Examples (*.img, L:*.BRS). SIZe n allows the display of multiple images on the screen. For example, on a 640 x 480 VGA display, six 200 x 200 images can be displayed adjacent to each other. SUBsample n used in conjunction with the SIZE command, to scale each image to fit in the SIZE specification. NOLabel inhibits writing the file name label at the top of each image as it is displayed. As an example, the command "BROWSE *.* SIZE 200 SUBSAMPLE 4" will display all the files in the current directory, subsampling each by 4 and displaying them in a 200 x 200 window. The command "BROWSE *.BRS SIZE 100 SUB 2" when used with the Voyager Uranus browse images (on Volume 3 of the Uranus CDROM collection) will display up to 24 images at a time on the screen. *** NOTE *** BROWSE does not distinguish between image and non-image files, and it is up to the user to provide the appropriate directory mask to select ONLY images. If a message "Image does not have proper label" comes up on the screen during BROWSE, it is probably because a non-image file is in the directory you are browsing. You can type carriage returns several times to get back to the "COMMAND:" prompt, and the browse will continue. If you are using BROWSE on a computer without a hard disk, you will have to use the SET BROWSE command to change the default browse file name to a writable disk drive, for example: "SET BROWSE A:BROWSE.CMD". If you are using BROWSE to view files on a CDROM disk, be sure to include the drive letter of a writable disk drive if you specify a BROWSE file name. The BROWSE command file produced by the BROWSE command can be edited with a text editor to produce your own custom command files. 4.5.3 CD or CHDIR The CD or CHDIR command is used just as it is at the MSDOS command level to change the current default directory. The argument of the CD command is the path name specification of the new default directory. For example, "CD \IMDISP\IMAGES" would make \IMDISP\IMAGES the current directory if it exists. To change the current default drive use the "SYSTEM" command ("SYSTEM L:" for example) or the "FILE" command. If there is not enough memory available for the system command to be executed an error message is displayed. 4.5.4 CURSOR The CURSOR command is used to select a point in a displayed image for subsequent display commands. When first invoked, it places a small cursor symbol at the center of the screen. Depending on the current contents of the screen, the cursor may be hard to see. Moving it with the arrow keys on the numeric keypad will help you locate it. Whenever the cursor is moved, the current line and sample location of the cursor and the DN value of the pixel at that point is printed in the lower right portion of the screen. The cursor will move 16 pixels in the selected direction unless the movement value is adjusted using the + or keys. Numeric Keypad Keys ------------------------------- | 7 | 8 | 9 | PrtSc | | Home | Up | PgUp | | ------------------------------- | 4 | 5 | 6 | - | | Left | | Right | | ------------------------------- | 1 | 2 | 3 | + | | End | Down | PgDn | | ------------------------------- Action of Keypad Keys: 7 = Move up and left. 8 = Move up. 9 = Move up and right. 4 = Move left. 5 = Not active. 6 = Move right. 1 = Move down and left. 2 = Move down. 3 = Move down and right. - = Decrement cursor movement value. + = Increment cursor movement value. Table 4-2: IMDISP Cursor Keys Cursor mode is exited by typing a "." (period) or carriage return. The cursor position is retained for future use in DISPLAY commands which use the CENTER option. It is very useful with large images where the entire image may be displayed using the subsample option, then a point selected for subsequent display at full resolution. Example: Type "FILE MONTAGE.IMG" followed by "DISP" to display the MONTAGE.IMG file. Type "CUR" to enter the cursor mode, then move the cursor to the center of the Uranus image in the upper left corner of the image using the up and left arrow keys. Now type "." to exit cursor mode, then type "DISP ZOOM 4 CENTER" which will display Uranus as a large grainy ball on the screen. 4.5.5 DIR The DIR command is used just as the MSDOS dir command. Its argument is passed to MSDOS for execution. At the end of the directory listing the screen will display "Type carriage return to continue:" which will return to the IMDISP command mode. If there is not enough memory available for the system command to be executed an error message is displayed. 4.5.6 DISPLAY The DISPLAY command reads an image file and displays it on the the screen. If the image is larger than the display screen, the default mode is to display as much of the upper left portion of the image as will fit on the screen. The SUBSAMPLE keyword can be used to select every 'n' lines and samples so that representations of very large images may be displayed. The ZOOM keyword can be used to enlarge a portion of an image on the display screen. Keywords can be specified to begin displaying at any line and sample in the image with the SL (starting line) and SS (starting sample). If only a limited number of lines and samples are to be displayed the NL (number of lines) and NS (number of samples) keywords can be used. The UP, DOWN, LEFT and RIGHT keywords can be used to display different portions of the image, relative to the currently displayed portion. The display can also placed at any point on the screen using the DSL (display starting line) and DSS (display starting sample) keywords. DISPLAY takes the following keywords : SUBsample n a positive integral subsampling factor for displaying images larger than the size of the screen. SUB=2 would display an image at half the resolution. If the image lines and samples look like this: sample values line 1 1 2 3 4 5 line 2 6 7 8 9 10 line 3 11 12 13 14 15 Then the command DISP SUB 2 would produce: sample values line 1 1 3 5 line 2 11 13 15 ZOOM n a positive integral zoom factor for looking at part of an image close up. The zoom command replicates pixels by the integer value specified. If the image lines and samples look like this: sample values line 1 1 2 3 line 2 4 5 6 line 3 7 8 9 Then the command ``zoom 2" would produce the following: sample values line 1 1 1 2 2 3 3 line 2 1 1 2 2 3 3 line 3 4 4 5 5 6 6 line 4 4 4 5 5 6 6 line 5 7 7 8 8 9 9 line 6 7 7 8 8 9 9 CENTER center the display around current cursor position. This command is very useful when displaying large images or when zooming in on selected areas. NL n NS n number of lines or samples from the image file to display SL n SS n starting line or sample within the image file to display UP n DOWN n adjusts the starting line up or down from the previous value, thereby moving the display window up or down in the image. The default amount to move up or down is the size of the display. LEFT n RIGHT n adjusts the starting sample left or right from the previous value, thereby moving the display window left or right in the image DSL n DSS n start the image display at the specified line and sample on the display screen. Examples: The user wants to display an entire Voyager image (800 x 800) on the display screen then display a portion of the image at full resolution. Type "FILE MIRANDA1.LBL", then "DISP SUB 2" to display the entire image at half resolution, Use the CURSOR command to move the cursor to the center of an area of interest. Exit the cursor mode by typing ".", then type "DISP CENT" to display the selected portion of the image at full resolution. The user wishes to place 2 images which are each 800 lines by 800 samples on the screen next to each other. The first file is opened with "FILE IMAGE1.IMG". The "DISPLAY SUB 4" command is given to display every 4th line and sample of the image to create a 200 x 200 display. Next the "FILE IMAGE2.IMG" command is given. Now a "DISPLAY SUB 4 DSS 201" is given to place the second image on the screen starting at display sample position 201, next to the first image. 4.5.7 ERASE The command ERASE causes the screen to be erased by setting all of the pixels to 0, which may not necessarily be black depending on the palette setting. 4.5.8 EXIT The EXIT command exits IMDISP and returns the user to the MSDOS operating system. The contents of the image display and refresh buffer are discarded. 4.5.9 FILE FILE does not take a keyword, just a value which is the file name. The specified file will be opened, or an error message issued if the file cannot be opened. The capability to directly address any sector on the CDROM disk by providing its physical address (minute, second and sector number) is also available to users of the Microsoft Extensions software. If the FILE command is specified without a filename, the program will display a list of file names in the current directory. Each file name is preceded by a number. Typing the number associated with a file name will select that file for processing. File names that actually represent lower level directories are indicated with a <d> symbol after the name, Directories can be traversed downward by selecting the number associated with a directory name. Upward traversal is by selecting the item identified as PARENT DIR. This will move upward in the directory hierarchy. The prompt mode clears the screen and displays a menu of files and commands. These commands allows specification of the default drive, a file "mask" to use in selecting file names for display and options for moving through the list of files when the current directory contain more than 30 files. The top line of the display also indicates how many files are in the current directory. After exiting the FILE prompt mode, the previous contents of the display screen can be recovered by typing "REFRESH". The FILE prompt mode subcommands: D select default disk drive M specify a file selection mask to use in displaying files on the screen. N display the next set of file names on the screen if there are more files in the current directory than can be displayed on one screen. P display the previous set of file names. Q quit the file selection mode and return to IMDISP command mode. The N, P and Q commands are executed immediately. If the D or M commands are selected, the user is prompted to enter a drive letter or file mask. If the file selected by the "FILE filename" or FILE prompt mode has a valid label, either PDS or VICAR2, then the number of lines and samples and the pixel size will be displayed. If the file is unlabeled then the program will prompt for the values to use for the number of lines and samples, the number of bits per pixel, and the number of header bytes. PDS detached labeled images can also be displayed. The specified file remains the current file until a new FILE command is given. The FILE command resets the SET DNLO and SET DNHI values to the minimum and maximum for the pixel size (normally 0 and 255). If a specified filename is not found in the current directory then an error message is displayed. If the unlabeled image has a regular format, that is a uniform structure of repeating lines and samples, the user can specify this information when prompted by the program. For example, an image named ASTERIA.DAT with one 1422 byte header block followed by an image composed of 370 lines by 450 samples of 8 bit pixels would be processed as follows: At the COMMAND: prompt type "FILE ASTERIA.DAT" The program will display the message: Input file does not have a proper label. Input number of lines: 370 enter the value 370 Input number of samples: 450 enter the value 450 Input size of each sample: 8 enter the value 8 Input size of header label: 1422 enter 1422 for the size of the foreign label block). The COPIM utility can be used to add a PDS label to the beginning of such a file, so that it can be used subsequently without having to specify all the parameters separately. The physical address of a data block on the CDROM can also be specified using the syntax 'FILE "CD:mm:ss:bb"', where mm is the minute, ss the second, and bb the sector block number of the beginning of the desired data area. The CD:mm:ss:nn must be in double quotes and the CD must be capitalized! This mechanism can be used to access files on non-High Sierra format disks. This will only work on systems using the Microsoft Extensions software. 4.5.10 HELP HELP displays the online help message. If followed by the name of a valid command the message for that command is displayed. HELP is not provided for MSDOS commands (DIR, CHDIR, CD and TYPE). 4.5.11 HISTOGRAM The HISTOGRAM command produces a plot showing the number of pixel values in the image at each DN level. The range of DN values is displayed on the x-axis and the number of occurrences of a specific DN value on the y-axis (See Figure 4-1). The HISTOGRAM command reads through the image, calculates the histogram, and then displays the plot on the screen. The histogram is scaled so that the third highest histogram value is used as the maximum. It is recommended that the SUBSAMPLE or other subsetting keywords be used to speed up histogram calculation, which can be quite slow for large images and for images stored on CDROM. Histogram plots are displayed on top of any image currently displayed on the screen, so the user may wish to use the ERASE command to clear the screen prior to using HISTO. After the histogram is displayed, the image can be restored using the REFRESH command. 27582 | . | .. | .... COUNT | ..... | ....... | ......... | ............ | ............... --+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 0 64 128 192 256 DN value Figure 4-1: Sample Image Histogram By evaluating the histogram, the user can determine the optimum settings for the SET (DNLO and DNHI) command to produce a useful display. In the example above, the image data are clustered between DN values 32 and 144. Using the default settings of the EGA display mode the colors assigned to the 2 lowest color values and the 7 highest values (representing DN values from 0 to 31 and from 144 to 255) would not be used since the image contains no pixels with these values. By using the "SET DNLO 32 DNHI 144" command the 16 display levels available on the EGA display would be assigned to values between 32 and 144 rather than distributed evenly from 0 to 255, and all 16 colors would be used in the display. HISTOGRAM takes the following keywords and arguments: SUBSAMPLE n a integral subsample factor for speeding up histogram use of "HISTOGRAM SUBSAMPLE 4" is always recommended NL n NS n number of lines and samples from image SL n SS n starting line and sample in image CENT perform the histogram on only the displayed portion of the image. Two special keywords can be used with Voyager or Viking images on the PDS CDROM disks. These will extract histogram values stored with the image on the CDROM disk and reduce the time required for the histogram to be generated from more than 1 minute to about 3 seconds. Note that these commands will not work with Voyager image files in the \PLANET\JUPITER\ATMOS directory, or with versions of system software written before April 1987. VOY use histogram from Voyager CDROM engineering data VIK use histogram from Viking CDROM engineering data 4.5.12 LABEL The label command prints the labels for the currently selected image file on the screen. 4.5.13 MENU The menu command reads a file containing a list of file names and places the user in the MENU mode, where files from this list can be selected for display. The MENU mode is similar to the FILE mode, except that the list of files presented is that provided in the menu file, rather than from a selected directory. The MENU mode can be invoked by typing "MENU filename.MNU" at the COMMAND: prompt. It can also be invoked on program startup by typing "IMDISP filename.MNU" to initiate the program. The menu file must use the ".MNU" extension to startup IMDISP in MENU mode. Subcommands of the MENU mode are as follows: # - Enter the number corresponding to a desired file name to select the file. P)revious - display the previous screen of file names N)ext - display the next screen of file names Q)uit - quit or exit from MENU mode After selecting and displaying an image, the user can return to the current menu by typing "MENU" at the COMMAND: prompt. A menu file can take either of two formats. The preferred format is a PDS labelled table file containing file names. A sample file is shown below: NJPL1I00PDS100000000 = SFDU_LABEL FILE_TYPE = TABLE RECORD_FORMAT = STREAM OBJECT = FILE_NAME TYPE = LITERAL LENGTH = 80 ENDOBJECT NOTE = "Sample MENU file for IMDISP" END L:\OCEAN\SCBMEAN.IMG L:\OCEAN\WCMEAN.IMG L:\PLDS\TMCH01.DAT L:\PLDS\DEM.DAT L:\PLANET\SATURN\ATMOS\C3497355.IMG <END OF FILE> A second abbreviated form may also be used, where only the filenames are specified in the ".MNU" file. In this case the file would only contain the filenames shown after the END statement in the example above. 4.5.14 OVERLAY The OVERLAY command draws a lat/lon overlay grid on the displayed image. It is intended only for use with the Ocean Data System, West Coast Time Series CDROM in this program version. The OVERLAY command has the following arguments: MAXLAT Latitude of top of image. MINLAT Latitude of bottom of image. MAXLON Longitude of left side of image. MINLON Longitude of right side of image. LEGend Draw a color scale with the overlay. 4.5.15 PALETTE The PALETTE command is used for changing the colors assigned to displayable color values. This is done by modifying an internal color table which assigns intensity values for red, green and blue to a color value, The EGA provides 4 intensity values for each of 3 colors, so that 64 different colors can be created. However, the EGA pixels are only 4-bits each so only 16 color values can be used simultaneously. The palette can be modified using the EDIT command and saved and loaded from a disk file. The edit mode is invoked by typing PALETTE EDIT. With the EGA display, a bar containing 16 colors or shades will be displayed on the bottom of the screen. A small square will appear in the middle of the center color box. This indicates that this color value is currently selected for editing. To select another color value for editing, move the small square to the appropriate color using the "4" (left arrow) and "6" (right arrow) keys on the numeric keypad. The color of the current color box is changed with the "R", "G", and "B" keys (for red, green, and blue). Upper case letters increase the amount of the primary color, and lower case keys decrease the amount of the color. The "8" (up arrow) and "2" (down arrow) keys increase and decrease, respectively, the amount of red, green, and blue simultaneously. Other commands in the palette edit mode are the "s" command, which will shift all colors one value to the right, and the "x" command, which will exchange color values (the color setting for color 0 becomes the setting for color 15, while 15 replaces 0, the color setting for color 1 becomes the setting for 14, while 14 replaces 1, etc.). The up and down arrow keys can also be used to cycle through the colors available in a given display mode one at a time. Type the "." key or carriage return to exit the edit mode. PALETTE takes the following keywords and arguments: EDIT n to interactively adjust an n-color palette. See edit description (above) for details PSEUDOCOLOR n PS = 0 for default palette, PS = 1 for gray scale palette, PS = 2 for pseudo color palette SAVE filename saves the specified palette on disk LOAD filename loads the specified palette from disk The default palette file for LOAD or SAVE operations is IMDISP.PAL. The format of the default color palette when stored in a palette file is as shown below: NJPL1I00PDS000000784 = PDS_SFDU_LABEL FILE_TYPE = TABLE RECORD_TYPE = STREAM FILE_RECORDS = 28 TABLE_ROWS = 16 ROW_COLUMNS = 4 COLUMN_NAME = (COLOR_NUMBER, RED_VALUE, GREEN_VALUE, BLUE_VALUE) COLUMN_TYPE = (INTEGER,INTEGER,INTEGER,INTEGER) END 0 0 0 0 1 64 0 0 2 128 0 0 3 192 0 0 4 192 64 0 5 192 128 0 6 192 192 0 7 128 192 0 8 0 192 0 9 0 192 128 10 0 128 128 11 0 128 192 12 0 0 192 13 128 0 192 14 192 0 192 15 192 192 192 The first column of the palette table is the color value number for the display, and columns 2, 3 and 4 represent the intensity of the red, green and blue (respectively) primary colors on a scale of 0 to 255. With the EGA display these values are: 0 = off; 64 = low; 128 = medium; 192 = high. 4.5.16 PROFILE PROFILE plots the DN values of pixels located along a line between two points in the image, i.e. it creates a graph of DN value versus pixel along the line joining the two points, Cursor mode is used to select the two endpoints; typing "." or carriage return selects the current cursor position as the endpoint. After the endpoints are selected a line is drawn between the points and the graph is plotted at the bottom of the screen, showing the DN values on the x-axis and the positions along the line on the y- axis. 4.5.17 QUIT Exits the program. The contents of the image display and refresh buffer are discarded. 4.5.18 REFRESH REFRESH redisplays the image plane from the refresh buffer. When images are written to the screen they are also written to the refresh buffer. The REFRESH command writes this buffer back to the screen, thereby erasing any graphics or text overlaying the image on the screen. The refresh buffer contains as many lines from the display screen as there is room for in memory. REFRESH takes,es no parameters. It can also be used after the FILE prompt mode to redisplay the contents of the refresh buffer. Refresh is commonly used after the HELP command, or after a HISTOGRAM or PROFILE command to remove text and plots from the display screen. 4.5.19 SAVE The SAVE command copies the contents of the display screen to a file. On EGA systems the display buffer contains only 4-bits per pixel, so specifying BP = 8 will write the 4-bit pixels in full bytes, but does not save full 8-bit pixels even if the input image is an 8-bit image, Use the COPIM utility program to produce a full resolution subset of an 8-bit image. SAVE takes the following arguments and keywords, where the filename must immediately follow the SAVE command: filename filename of image to save NL n NS n number of lines and samples to save SL n SS n starting line and sample to save BP n number of bits per pixel in output image Example: Save a 200 line by 200 sample area at the center of an image in the file SMALL.IMG. First use the FILE command to select and display an input image. Now type: "SAVE SMALL.IMG SL 100 SS 210 NL 200 NS 200" to save the portion of the image beginning at line 100 and sample 210 in the new file SMALL.IMG. 4.5.20 SET SET is used to display and change the DN (pixel value) range that is used to compress the pixel values to the range appropriate for the display device. The default, which is reset for each new file, is the full range of DN values for the particular pixel format (e.g. 0 to 255 for byte). It is also used to specify a file name to be used by the browse command. The results of a SET command will not take effect until the next DISPLAY command is performed. Set takes the following keywords: DNLOW n DNHIGH n where values less than DNlow are set to color value 0, values greater than DNHIGH are set to the maximum color value available, and the color values between are assigned equally to the DN values between Dnlow and DNhi. BROwse filename sets a file name to be used for the browse file. This file name will override the default file name, which is 'c:browse.cmd'. For example, using the default color palette and an EGA display with 16 color values available, the command "SET DNLO 100 DNHI 164" will assign DN values below 100 to black and DN values above 164 to white, and spread the 16 color values between the DN limits, thus each color value will represent 4 DNs (value 0 = DN 100 to 103; value 1 - DN 104 to 107, etc.). If values other than the default are used then the images will display more slowly because scaling divisions are required. SET with no parameters will display the current values. The DNLO and DNHI values are reset to the minimum and maximum for a given pixel size when a FILE command is issued. 4.5.21 STRETCH STRETCH sets the palette to a gray scale stretched between the two specified pixel values. Stretch is most useful on the PGA display where 16 gray levels are available. On the EGA display the stretch command activates the gray level palette which provides only 4 gray levels. Use the PAL PS 0 command to return the display to the default palette after performing a stretch. STRETCH takes the following keywords : LOW n HIGh n the low and high DN values of the stretch. These pixel values refer to the DN values in the current image display, not necessarily in the original image (scaling may have been involved). For example with the EGA display the DN values in the display range from 0 to 15, even if a byte image is being displayed. The STRETCH command is not recommended for use on EGA systems. 4.5.22 SYSTEM The SYSTEM command is used to send a command to MSDOS. For example "SYS L:" will set the L: drive as the current default drive. If there is not enough memory available for the system command to be executed an error message is displayed. The SYS command will not work on floppy disk systems unless the file "COMMAND.COM" is present on the floppy disk with the IMDISP program. 4.5.23 TEXT The text command can be used to display a string of text on the screen. The text string can be entered on the command line, enclosed in apostraphies or quotes (e. g., TEXT `This is a text string'). If the text string is not entered on the command line the program will prompt for the string to be displayed. Once the command is issued and the text string entered the program is placed in CURSOR mode so that the display position can be selected. This is done by using the arrow keys to move the cursor to the desired location. After the position is selected, the user types a period (.) or carriage return and the text will be written on the display screen. The TEXT command has one argument and two optional keywords. LINe The line number to position the text at. SAMple The sample number to position the text at. 'text...' The text string to be printed, enclosed in quotes or apostraphies. The text command writes over image data in the display and refresh buffer, thus the underlying portion of the image is lost. 4.5.24 TYPE The TYPE command is used to type the contents of a text file on the display screen, using the standard MSDOS type command. Its argument is passed to MSDOS for execution. At the end of the type operation the screen will display "Type carriage return to continue:" which will return to the IMDISP command mode. If there is not enough memory available for the system command to be executed an error message is displayed. 4.6 OTHER UTILITY PROGRAMS There are several utility programs also provided on the distribution disk. These programs can read PDS labeled, VICAR2 labeled, or unlabeled images. The output images are always written with PDS ODL labels. The programs prompt for the necessary input values. 4.6.1 COPIM COPIM is a simple image copying program. It' can copy the whole image, for example to put PDS labels on a foreign image), or extract a window from the image. It can subsample the image with an integral subsampling factor. The program prompts for the input and output file names, the window to extract (just type return for the whole image), and the subsampling factor (the default is 1). If the input file is not in VICAR2 or PDS image format the program will also prompt for the number of lines and samples, pixel size and header size of the image. For example, to extract the first 100 lines and samples from the file LOGO.IMG the following commands would be used: COPIM Input Image: LOGO.IMG Lines: 350 Samples: 340 Bits per pixel: 1 Output Image: LOGOSUB.IMG Starting line: 1 Starting sample: 1 Number of lines: 100 Number of samples: 100 Line Subsampling factor (1): 1 Sample Subsampling factor(1): 1 4.6.2 CONVERT CONVERT is simple pixel format conversion program. It converts an image to an integer (16 bits), byte (8 bits), nibble (4 bits), or binary (1 bit) image. It can also perform a user specified scaring. The program prompts for the input and output file names, the output format (must be 1,4,8, or 16 bits), and the input and output numerical ranges for scaling. The default scaling values are appropriate for the data types being used. For example, to convert MONTAGE.IMG to an 8-bit per pixel image and scale the output pixels evenly between the values of 0 and 127 the following commands would be used: CONVERT Input Image: MONTAGE.IMG Lines : 350 Samples : 640 Bits per pixel : 4 Output Image: MONTBIG.IMG Output bits per pixel (1, 4, 8, 16) : 8 Input DN range (O 15) : Output DN range (O 255) : 0 127 4.6.3 CLEANUP The CLEANUP and CLEANUP2 programs are available separately with a user's guide, executables and required data files. The purpose of these programs is to clean up "noisy" Voyager images by removing the dark current. The dark current image represents the ambient noise in the camera system; therefore, removing this noise "cleans up" the original image, making it appear crisper on the monitor. Chapter 5 COMMAND SUMMARY Within this command summary listing, brackets ([]) indicate optional parameters or keywords. Filename is the name of a file in the current directory or a fully qualified filename which can include drive letter and pathname. Directory name is an MSDOS directory path specification, a valid directory mask a specification containing wild card characters (*, ?) per MSDOS rules for wildcard use in the DIRECTORY command. The symbol "n" is used to indicate an integer value. driveletter: BATCH [filenamel BROWSE [directory mask] [SIZ n] [SUB n] [NOLabel] CD [directory name] [..] CURSOR DIRECTORY [directory mask] [/w] DISPLAY [SUB n] [SL n] [SS n] [NL n] [NS n] [BP n] [CENT] [DSL n] [DSS n] ERASE EXIT FILE [filename] ["CD:mm:ss:bb"] HELP [command name] HISTOGRAM [SUB n] [SL n] [SS n] [NL n] [NS n] [BP n] [CENT] LABEL MENU [filename] OVERLAY [MAXLAT n] [MAXLON n] [MINLAT n] [MINLON n] [LEGend] PALETTE [EDIT n] [PS n] [LOAD filename] [SAVE filename] PROFILE QUIT REFRESH SAVE filename [SL n] [SS n] [NL n] [NS n] [BP n] SET [DNLO n] [DNHI n] [BROwse filename] STRETCH [LO n] [HI n] SYSTEM [MSDOS command] TEXT [LINe n] [SAMple n] "text" or 'text' TYPE filename