NASAView

##### Software Documentation

- About NASAView
- Installation
- Operation

##### Download

- Linux 32-bit Package
- Linux 64-bit Package
- Mac OS X Intel Package
- Mac Power PC Package
- Solaris Package
- Windows Package

##### Project Documentation

- Project Information
- Project Reports

## Operation

NASAView provides a Graphical User Interface (GUI) enabling users to view PDS label products. This section describes how to use NASAView. The following topics can be found in this section:

- Tool Setup
- Tool Execution
- Tool Interface
- Common Errors
- Mac OS X Quirks

## Tool Setup

In order to execute NASAView on Solaris and Linux machines, the user's environment must be configured appropriately. Windows and Mac OS X users, however, do not need to setup their environment. This section describes how to setup the user environment on Solaris and Linux machines. The commands for setting environment variables must not contain spaces or line continuation characters in the value for the variable.

### Linux and Solaris Setup

This section details the environment setup for Linux and Solaris machines. The following steps need to be performed:

- Set the UIDPATH Environment Variable
- Set the LD_LIBRARY_PATH Environment Variable

Set the UIDPATH Environment Variable

The UIDPATH environment variable is used by Motif to locate the NASAView resource file named nasaview.uid.

The following command demonstrates setting the UIDPATH environment variable by appending to its current setting. In this example, the nasaview.uid file is located in the nasaview directory:

    [node:~] setenv UIDPATH ${UIDPATH}:$HOME/nasaview/%U

    [node:~] echo $UIDPATH

Note: The %U symbol must be used when setting the UIDPATH environment variable. This represents a value that is substituted at runtime by NASAView.

Set the LD_LIBRARY_PATH Environment Variable

The LD_LIBRARY_PATH environment variable is used to locate the NASAView-dependent libraries such as XVT and Motif. The following command demonstrates how to set this variable, by appending to its current setting.

This example appends the locations of the NASAView-dependent libraries found in the nasaview directory as well as the Motif libraries:

    [node:~] setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/usr/local/openmotif-2.3.4/lib:$HOME/nasaview

    [node:~] echo $LD_LIBRARY_PATH

Once the UIDPATH and LD_LIBRARY_PATH environment variables have been set, the tool can be executed as demonstrated in the following example:

    [node: /home/user/nasaview] ./nasaview <optional PDS label file specification>

### Mac OS X Setup

There are no environment variables that need to be set in order to execute NASAView on a Mac OS X machine. To launch the application, double-click the NASAView executable file.

### Windows Setup

There are no environment variables that need to be set in order to execute NASAView on a Windows machine. All the dependency files for NASAView should be sitting in the same location as the NASAView executable file.

The preferred method to run NASAView is to double-click the NASAView executable file. The alternative method is to specify the NASAView executable file through the command-line as demonstrated in the following example:

    C:\nasaview> nasaview <optional PDS label file specification>

## Tool Execution

This section is intended to provide users with helpful tips on how to use NASAView when it opens more 'elaborate' PDS labels: labels that do not simply have just a single IMAGE or TABLE object.

### Examples

This section provides documentation on how to use NASAView against more elaborate PDS labels, such as:

- Displaying Multiple Objects
- Displaying a Multi-banded Image

Displaying Multiple Objects

When there are multiple objects in a PDS label, NASAView automatically determines which object to display, using the following rules:

- The first IMAGE object in the label will be displayed regardless of any other objects that exist.
- If no IMAGE object exists, then the first TABLE object in the label will be displayed.

In order to display the rest of the objects, use the Previous Table/Next Table buttons (only applies to TABLE objects) and/or use the Object Hierarchy menu option. See the Using the Object Hierarchy Menu Option for more details.

Displaying a Multi-banded Image

Before a multi-banded image is displayed, the multi-banded image GUI window appears. See the Multi-banded Image Interface for more information on how to use this interface.

The band strengths must be set to at least 1, otherwise unexpected behavior will result.

### Using the Object Hierarchy Menu Option

The Object Hierarchy menu option is used to display other objects found in a PDS label. This menu option is most commonly used when a PDS label contains both an IMAGE and a TABLE object. This section describes how to use this menu option.

Open the Object Hierarchy Window

Go to the Label menu in the menu bar and select the Object Hierarchy option. When you do this, a new window should appear:

Double-click the Object To Be Displayed

Place the mouse pointer over the object to be displayed and double-click the mouse. At this point, another window will appear:

Push the Open This Table button.

In this example, the Table Display window should appear after the button is pushed. If an IMAGE object was selected, then the image will automatically be displayed.

### Automated Browse Feature

NASAView provides an automated method of opening multiple PDS labels in a directory. This section describes how to use the automated browsing feature of NASAView.

Select the Automated CD Browse option from the File menu of NASAView. A new window should appear:

Select a directory then click OK. Another window will open to select the browse options:

This window contains the following options:

- Exclusive Browse Extension

  Specify the extension that the file must have in order to be opened. The entry is case sensitive. If this field is left blank, then NASAView will attempt to display all files in the directory.

  For example, if the desire is to open files that end in .LBL, enter LBL in the text box.

- Maximize Image Size

  Image windows are normally opened at a pre-selected size. If this option is selected, the application window will be expanded to full size and the image windows will fill as much of the application window as necessary to show the full image.

- Perform Timed Browse

  Selecting this option allows NASAView to display all files that have an attached or detached label. Files not meeting this criteria will be skipped and the user will be notified. If this option is not selected, then the user will be prompted to display or skip a file.

- Do not browse subdirectories

  This option limits the displaying of files to only the selected directory. The default is to display files in the selected directory and all of its sub-directories.

- AutoStretch

  This option will stretch each image without user intervention.

- Enter Auto Browse Interval In Seconds, Not More Than 30 Seconds

  This option controls how long each object will be displayed. The default time is 6 seconds. An interval up to 30 seconds is allowed.

- Browse Now

  This button starts the auto browse feature.

- Exit Browse

  This button will exit the auto browse function.

If the Perform Timed Browse option is selected, a window should appear:

This window will be present during an auto browse session. The following options are available:

- Exit Auto Browse

  This button will stop the auto browse feature.

- Pause

  This button will temporarily stop the auto browse feature so that a new interval can be entered.

- Continue

  This button will resume the auto browse if it was paused.

- Enter Auto Browse Interval in Seconds

  This button changes how long each image will be displayed. Pause the auto browse first before entering a new interval.

- Apply New Interval

  This button will apply the new auto browse interval value entered.

If the Perform Timed Browse option is not selected, one of two manual browser control windows will appear:

This window will be displayed if the file to be displayed contains a PDS label or has a detached label associated with it.

This window contains the following buttons:

- Display It

  This button displays the selected file.

- Skip It

  This button does not display the selected file.

- Skip All Files With This Extension

  This button skips all files with the same extension as the selected file. This is case sensitive.

- Skip The Rest Of This Directory

  This button will not display anymore files in this directory. NASAView will move onto the next sub-directory if allowed or will move on to the next directory.

- Stop Browsing

  This button will stop the auto browse feature.

The other manual browser control window that could be displayed is the following:

This window will be displayed if the selected file does not have a displayable image or table associated with its label.

This window contains the following buttons:

- Skip It

  This button does not display the selected file.

- Skip All Files With This Extension

  This button skips all files with the same extension as the selected file. This is case sensitive.

- Skip The Rest Of This Directory

  This button will not display anymore files in this directory. NASAView will move onto the next sub-directory if allowed or will move on to the next directory.

- Make A Label For This Raw Image File

  This button will present the user with a template and directions for creating a PDS label for a raw image file.

- Make A Label For This FITS File

  This button will present the user with a template and directions for creating a PDS label for a FITS file.

- Stop Browsing

  This button will stop the auto browse feature.

## Tool Interface

The Graphical User Interface (GUI) of NASAView allows the user to display and examine Planetary Data System (PDS) archive products. After launching the tool, the NASAView main window should appear on the user's desktop:

This window is what a user would see if running on a Windows machine. For users running on Solaris, Linux, and a Mac OS X, the main window will look different. The window will appear more native to the target platform to give the user an expected look-and-feel for that machine.

The main window consists of the following menus:

- File
  - Open Object

    This menu option displays an object found in a PDS label. The selected file must contain a PDS label or it must be a PDS label file (*.lbl) or there must be a PDS label file (.lbl) with the same name as the selected file. If a text file is selected it will be opened as a text file.

  - Open text

    This menu option displays text files.

  - Make a PDS Label
    - For a FITS Image

      This menu option will make a PDS label for a FITS image. Select a FITS file and NASAView will make a label for the file.

    - For a Raw Image

      This menu option will present a template for a minimal PDS label along with directions for completing the template.

  - Automated CD Browse

    This menu option allows automated browsing of files in a CD or directory. See the Tool Execution section for a detailed description on using this feature.

  - Close

    This menu option closes the current open file.

  - Save GIF

    This menu option saves the current image in a GIF file format. The file will have the same name as the original, but will have a .GIF extension. The image that will be saved is the image in memory. This image is not the same as the displayed image if the image has been stretched or otherwise altered.

  - Save GIF as

    This menu option saves the current image in a GIF file format under a user-specified file name. The default will be the name of the original file. The image that will be saved is the image in memory. This image is not the same as the displayed image if the image has been stretched or otherwise altered.

  - Save JPEG

    This menu option saves the current image in a JPEG file format. The file will have the same name as the original, but will have a .JPG extension. The image that will be saved is the image in memory. This image is not the same as the displayed image if the image has been stretched or otherwise altered.

  - Save JPEG as

    Save the current image in a JPEG file format under a user-specified file name. The default will be the name of the original file. The image that will be saved is the image in memory. This image is not the same as the displayed image if the image has been stretched or otherwise altered.

  - Exit

    This menu option exits the application.

  The Print Setup and Print menu options are disabled and not functional at this time.

- Edit

  This menu consists of the standard options (Undo, Cut, Copy, Paste, Delete) which functions as they do in any other application.

  The Undo option is not functional at this time.

- Image

  This menu consists of options that allow a user to stretch an image.

  Except for multi-banded images, all images are displayed in 255 shades of gray. An image with pixel values ranging from 0 to 254 has one shade for each value. An image with a range from 0 to 1016 has one shade for every 4 values. An image with a range of 0 to 101,600 has one shade for every 400 values. If in the case of this last image the actual range was 101,092 to 101,600, a lot of the detail would be lost because all the data is in the last 508 values, which would be represented by only 2 shades of gray. If this image is normalized, the new range is now 0 to 508. This new range would yield 1 shade of gray for every 2 pixel values. This would bring out more detail.

  - Stretch Display

    This menu option causes the display to be normalized. The pixel values get re-distributed to completely utilize all 255 gray scale values. The user can also use the histogram feature to manually control the stretch. See the description of the View Histogram option under the Options menu for more information.

    Stretching an image tends to improve image detail. Some images appear completely obscure until they are stretched and may show a lot of detail after stretching.

  - Invert Display

    This menu option reverses the colors in a 256 gray scale display.

  - Undo Display

    This menu option restores the display using the memory image as a source.

  - Stretch Image

    This menu option stretches the displayed image, but also causes the image in memory to be stretched. This allows a user to save the stretched image as a JPEG or GIF image file.

- Large Image Selection

  This menu is enabled only when a portion of an image can be displayed at a time. This occurs when an image is found to be greater than 10,000 lines and/or line samples. The options under this menu provide the capability to display the rest of an image. By default, the first 5000 lines and/or line samples is displayed.

  - Next Line Samples

    This menu option displays the next 5000 line samples of the current image.

  - Previous Line Samples

    This menu option displays the previous 5000 line samples of the current image.

  - Next Lines

    This menu option displays the next 5000 lines of the current image.

  - Previous Lines

    This menu option displays the previous 5000 lines of the current image.

  - Select Lines and Line Samples

    This menu option allows an image to be displayed using user-specified line and line sample ranges. When this option is selected, the following window should appear on the user's desktop:

    This window tells the user the total number of lines and line samples in the image and what ranges are currently being displayed. Given this information, input the desired ranges for the lines and line samples in the 4 white boxes located to the right of the screen. Click OK when finished. NASAView will display the image with the user specified ranges in a new image window.

- Label
  - Object Parameters

    This menu option displays the keywords and keyword values for the PDS object currently being displayed.

  - Object Hierarchy

    This menu option displays a list of PDS objects in the file being displayed. If the object has sub-objects, such as COLUMN objects in a TABLE object, then those will be listed also.

    This menu option also allows a user to display other objects in a PDS label.

  - Full Label

    This menu option displays the PDS label for the current file.

  - Band Min/Max

    This menu option is associated with multi-banded images. It allows each band to be stretched. To achieve the best results, it is recommended to stretch all three bands to the same degree.

- Options

  A different set of options is available depending upon the type of file opened.

  When an IMAGE/QUBE object is displayed, the following options are available:

  - View Histogram

    This menu option provides a graphic display of the pixel value distribution. When this option is selected, the following window should appear on the user's desktop:

    As shown in the above window, there are 3 controls that allow adjustment of the distribution. The top control, labeled Median, allows the median of the data to be moved through the 256 available values of a pixel. The middle control, labeled Minimum, allows the minimum value to be redefined, causing the low end of the data to be clipped. The bottom control, labeled Maximum, allows the maximum value to be redefined, causing the high end of the data to be clipped.

    The buttons found on the right allows the user to apply the following palettes: Greyscale, Red-Orange, Blue-Grey, Prism, Topo, Ramp, and Contour.

  - Show Side Data

    This menu option is only associated with QUBE objects. This option displays the keywords associated with the QUBE side data.

  - Hide/Show Qube Controls

    This menu option is only associated with QUBE objects. This option controls whether or not the QUBE Control Window is visible.

  The Parse Times as Seconds and Show Integers as Unsigned Hex menu options are not functional at this time.

  When TEXT files are displayed, the following options are available:

  - Show <LF><CR>

    This menu option controls whether or not to display carriage return/line feed characters in a file. The default is to show them. These characters will be shown as <LF> and <CR> if they are present in the file and this feature is turned ON. When the file is saved, <LF> and <CR> will be written to the file.

  Although the Font menu option appears, it is not functional at this time.

- Help

  This menu option displays the current NASAView version and copyright notice.

### Table Display Interface

This section describes the Table Display GUI interface when a TABLE object is opened in NASAView. When a TABLE object is opened, a window should appear similar to the following:

NASAView displays one column of data at a time. The indicator at the top tells which column is currently being displayed. In addition, 15 rows of data is displayed at a time.

The right of the screen shows two sets of information. The top-half represents information about the TABLE object and the bottom-half represents information about the current COLUMN/BIT COLUMN object being displayed.

The Table Display window features the following check boxes:

- Show Items

  This check box allows the display of items in a COLUMN or BIT COLUMN object. The total number of items is indicated by the Items attribute.

  When this box is checked, the Previous Column and Next Column buttons are used to display the previous and next item, respectively. The Item Number: x of y display found to the right of this check box indicates which item is being displayed, where x represents the current item on display and y represents the total number of items.

  Un-checking this box will stop the Previous Column or Next Column buttons from displaying the previous and next item, respectively.

- Show Bit Columns

  This check box allows the display of BIT COLUMN objects. The Has Bit Columns attribute indicates the total number of BIT COLUMN objects found in the COLUMN object.

  When this box is checked, the data of the first BIT COLUMN object found in the current COLUMN object will be displayed. The Previous Column and Next Column buttons are used to display the previous and next bit column, respectively. At the top of the screen, it will show the current bit column being displayed.

  Un-checking this box returns the display back to the data of the current COLUMN object.

  Note: If this box is checked and there are no BIT COLUMN objects inside the current data on display, then the Previous Column and Next Column buttons will not work. The Show Bit Columns box will need to be un-checked in order for these buttons to work again.

The Table Display window features the following buttons:

- Previous Table

  This button displays the previous TABLE object if there are multiple TABLE objects in a PDS label.

- Next Table

  This button displays the next TABLE object if there are multiple TABLE objects in a PDS label.

- Previous Column

  This button displays the previous COLUMN object, BIT COLUMN object, or item data.

- Next Column

  This button displays the next COLUMN object, BIT COLUMN object, or item data.

- Previous Row Block

  This button displays the previous 15 rows of data for a COLUMN object, BIT COLUMN object, or item.

- Next Row Block

  This button displays the next 15 rows of data for a COLUMN object, BIT COLUMN object, or item.

- No. of Cols to Skip

  This button gives the user the ability to skip over a user-specified number of columns in order to display the desired column. Specify the desired number of columns to skip in the text box located to the right of this button. Then click the button. Inputting a positive integer number will skip over columns to the right of the current column being displayed. A negative integer number will skip over columns to the left of the current column being displayed.

  As an example, if column 10 is currently being displayed and a 5 is entered, column 15 will be displayed. If a -3 is entered, column 7 will be displayed.

- Go To Row Number

  This button allows the user to specify the starting row number of the data to be displayed. Specify the starting row number in the text box located to the right of this button. Then click the button.

  As an example, if 10 is entered, then rows 10 through 25 of the data will be displayed.

- Move to Column Named

  This button displays the COLUMN object that matches the user specified column name. Enter the column name to be displayed in the text box located to the right of this button. Then click the button. If the name entered matches the NAME attribute of a COLUMN object in the PDS label, then it will be displayed.

  This button is not intended to search across both BIT COLUMN and COLUMN objects. The Show Bit Columns box must be selected first before attempting to use this button to search for BIT COLUMN objects with a specific name. In addition, this button will only search the set of BIT COLUMN objects within the current COLUMN object. It will not look to the BIT COLUMNS within the next COLUMN object and so forth to look for the specified name.

- Summary

  This button summarizes the data in a COLUMN object, BIT COLUMN object, or item and displays it. The type of summary performed depends on the data type of the column, bit column, or column item. Numeric data types such as integer and real will result in a summary that includes the minimum, maximum, and average values. Character data types will result in a summary that includes only value counts: a table of data values and the number of times each occurred in the column, bit column, or column item. Datetime types will result in a summary that includes minimum and maximum values plus an occurrence count table for values that did not appear to be dates or times. Boolean data types will result in occurrence counts.

### Multi-banded Image Interface

This section describes the GUI interface when a multi-banded image is being opened in NASAView. When a multi-banded image is being opened, a window like the following should appear before the image is displayed:

The window consists of buttons to increase/decrease the band strength and band intensity for red, green, and blue.

The buttons that control the band strength for each color increase/decrease by 1 with each click of the button.

Note: The band strengths should never be set to 0. Unexpected behavior will occur.

The buttons that control the band intensity for each color increase/decrease by 0.1 with each click of the button.

Alternatively, there are text boxes found to the right of the buttons where the band strengths and intensities can be entered manually.

The Apply Selections button is used to apply the current settings to the image and displays it. The current settings are found to the left of the buttons.

## Common Errors

At this point, there seems to be a common error when using NASAView on some Linux platforms. When the "Open Object" menu option is selected, a File Chooser GUI window appears to prompt the user to select a file. At this point, multiple error messages like the following appear on the user terminal window:

    Warning:
        Name: FilterText
        Class: XmTextField
        Character '\165' not supported in font.  Discarded.

    Warning:
        Name: FilterText
        Class: XmTextField
        Character '\170' not supported in font.  Discarded.

    Warning:
        Name: FilterText
        Class: XmTextField
        Character '\57' not supported in font.  Discarded.

When this occurs, the GUI window does not behave properly. The user will be unable to choose a file or select another directory to browse.

The exact cause of the issue is unknown, but in the cases seen, the error was due to the LANG environment variable being set to en_US.UTF-8. This represents the installation default locale. It is believed that certain versions of Motif, the X window manager, have an issue with this environment variable setting.

The solution that has been known to work is to change the LANG environment variable to en_US or C.

The following command sets the LANG environment variable to en_US

    [node:~] setenv LANG en_US

    [node:~] echo $LANG

## Mac OS X Quirks

There are a few quirks to be aware of when running NASAView on the Mac OS X platform.

Image Display

Due to a bug in the XVT software, images on the Mac platform will only be displayed up to about 2000 lines x 2000 line samples. The rest of the image can be viewed using the Large Image Selection menu. Refer to the Tool Interface section for a detailed description on this menu option.

PDS CD Volume Support

On the Mac platform, NASAView crashes after selecting a label or image file located on a CD from one of the older PDS Volumes. The error message that appears is the following:

    FATAL ERROR: MSG 0x003482ec [CAT 3/4 STD
    33516]
    Category: XVT release 3 assert (Signaled assert 4)
    Function: XVT_app_create
    File: /Users/build_user/builds/dsc_osx/svn/src/
    ptk/mac/kfsys.c line: 411

Volume Sets that are known to cause this error are CDs of Magellan, Viking Orbiter, Voyager, and Galileo REDR images or labels. The work around is to copy the files from the CD to the local Mac machine running NASAView.