RAVEN v 2.0 Beta
User's Manual
Sharon Okonek & Robert Casey
Jet Propulsion Laboratory
July, 1994
Table Of Contents
Chapter 0: What is RAVEN? 1
0.0: Introduction
0.1: What's in RAVEN
Chapter 1: Configuration 3
1.0: Key Terms
1.1: Setting up RAVEN
1.1-0 You Need IDL
1.1-1 RAVEN Startup Commands
1.1-2 Preparing Source Files
1.1-3 A Note on Cube Files
1.1-4 X-window Defaults
Chapter 2: RAVEN Initialization 7
2.0: The Initialization Menu
2.1: Building a Cube
2.1-0 Entering the Source Filename
2.1-1 Selecting Images
2.1-2 Memory Calculation
2.1-3 Specifying a Region
2.1-4 Specifying the Output Cube Filename
2.1-5 Build the Cube
2.1-6 Synthesizing an Image
2.1-7 Canceling Out of the Menu
2.2: Loading a Cube
2.3: Editing a Cube
2.3-0 The Edit Cube Menu
2.3-1 Deleting Images
2.3-2 Adding Images
Chapter 3: RAVEN High-Level Overview 15
3.0: Main Image Window
3.1: Control Menu
3.2: Main Zoom Window
3.3: Full Image Roam Window
3.4: Image Selection Menu
Chapter 4: RAVEN Statistics Toolkit 20
4.0: Preferences
4.1: Make Patches
4.1-0 The 'Make Patches' Menu
4.1-1 Making a Patch
Chapter 5: RAVEN Graph Toolkit 24
5.0: Profile
5.1: Histogram
5.2: Co, Cross, and Total Power Plots
5.3: Polarization Signatures
5.3-0 Making a Polarization Signature
5.3-1 The Polarization Signature Menu
Chapter 6: RAVEN Model Toolkit 29
6.0: Not yet implemented
Chapter 7: RAVEN Color Slicing 30
7.0: The Color Slicing Menu
7.1: The Control Buttons
7.1-0 Add Range
7.1-1 Delete Range
7.1-2 Clear All Ranges
7.1-3 Cool to Hot
7.1-4 Blu-Red Phase
7.1-5 Exit
7.2: 8-bit vs. 24-bit Color Slicing
7.3: About Slicing by dn, dB, Phase, and Corr. Coeff.
Chapter 8: RAVEN Contrast 34
8.0: Vary Histogram Equalization
8.1: Reset Contrast
Chapter 9: RAVEN Show Cube Header 35
Chapter 10: RAVEN Output Byte Image 36
Chapter 11: RAVEN Image Selection Menu 37
11.0: Grey Scale
11.1: Color
11.2: Multiple Zoom
Chapter 12: Reporting Bugs 39
900Chapter 0:
What is RAVEN?
0.0: Introduction
RAVEN stands for Radar Analysis and Visualization ENvironment and is a software tool originally developed by CSES at the University of Colorado, Boulder to display and process AIRSAR images and allow interactive tasks to be performed on that data for scientific purposes. RAVEN V 2.0 has been expanded in scope, allowing for many types of images to be examined and providing a more versatile means of extracting vital information from the image data sets. RAVEN was created using the IDL environment, which allows for a relatively easy means of developing applications for visualizing datasets in an interactive, window-based environment.
The cube is the basic image file used by RAVEN. It is essentially a building block of images arranged in band sequential (BSQ) order, topped by a header. Originally, the cube file was intended to hold only AIRSAR images and was capable of containing information from just one bandset. The capability of RAVEN has increased since its changes began from the Version 1.0 prototype and the cube file now has the potential of containing many bandsets from many different sources such as SIR-C, SPOT, and synthesized byte images.
Images can now be arranged in many different ways, to reflect research across different frequency bands, different points in time, and different polarizations and relationships relating to the same site. This versatility comes about through the new scheme of editing the cube to create the needed arrangement of images and new ways of displaying and viewing image data.
The new RAVEN now keeps all images in memory for fast transition from one image to the next, and allows for a new form of visualization across images: simultaneous zoom. This allows for multiple zoom windows, each showing a blow-up of a different image, to be shown on the screen at the same time. The windows are slaved together so that they all point to the same location with the same magnification. The benefits of having the images in memory may extend beyond what is already provided in the current version of RAVEN.
0.1: What's in RAVEN v 2.0
* Reads AIRSAR, SIR-C, or byte data
* Cube building and editing
* Memory calculator that tells how big a cube can be given the memory in your system and the size of the area you want to look at.
* Synthesizes AIRSAR and SIR-C data files
* Reads and processes byte files
* Image display
* Color slicing by dn, dB, phase, correlation coefficient
* Contrast Enhancement
* Multiple zoom windows
* RGB color: 24-bit true color or 8-bit pseudo color
* Computes statistics for a region of interest (mean, standard deviation, kurtosis as well as the average incidence angle and wavelength). Statistics can be directed to an output file as well as the screen.
* Create patch (ie. region-of-interest) files
* Profile plots
* Co- and Cross-Polarization cross section plots
* Sigma0 plot
* Polarization plots of a region of interest
* Print cube header contents
* Output synthesized byte images to a file
Chapter 1:
Configuration
Introductory Note
Section 1.0 discusses key terms used in the body of the User Guide so that you will understand what is being discussed in the sections that follow. Section 1.1 will explain how to get RAVEN set up on your account and how to execute it. This should require only a small amount of preparation on your part.
1.0: Key Terms
There are frequent references in this manual made to things such as cubes, source files, widgets, headers, and images. Since it is essential for you to understand these concepts to learn and use RAVEN, their definitions are presented here.
What's an Image??
An image, at least in the case of RAVEN, is a two-dimensional array of byte data, providing one byte for each pixel, signaling a grey value intensity from zero to 255. The two dimensions are arranged by samples and lines, which is known as the raster format. What results is a square picture, showing visually what is seen by the remote sensor. Images can come from many sources, whether it be microwave sensors, infra-red sensors, visible-band cameras, or radar sensors. Ultimately, an image is like a picture, displaying spatial relationships between points of data.
What's a Header??
A header is a string of characters in an image file that lists key parameters relating to an image or group of images. It allows the user or a program to adjust their settings to accommodate the image(s). The RAVEN cube uses a header which gives information on the cube itself and on each of the images that the cube contains.
What's a Cube??
A cube is simply a byte file, albeit a fairly large one in many instances, which contains a collection of related images. The images are related in that they are coregistered to each other and refer to the same spatial location. The user must see to it that the source files to be used for the cube are coregistered beforehand. RAVEN does not perform image warping or coregistration.
The cube starts off with a header, which is of a predefined size, containing character string data relating to cube properties and the attributes of each image in the cube. What follows is a sequential ordering of byte images, listing the data for one complete image before starting with the next. The cube is loaded into memory as one large package when RAVEN starts up the main image viewing functions. From there, the user can select individual images from the cube for viewing, with polarimetric data being back referenced to the related source file on disk when necessary.
What's a Source File??
A source file is the data file from which the byte images are generated and can take many forms. For instance, AIRSAR images come from a source file that has a 30,000 byte header and represents data for each pixel by a 10 byte compressed Stokes matrix. Source files used by RAVEN are identified by their filenames. The type that the source file is (i.e. AIRSAR, SIR-C, byte, etc.) is known by the four letter tag added to the filename. Most images in the cube have a source file that they reference. The source file that each image points to is listed in the header of the cube.
What's a Widget??
A widget is a graphical object which appears on the screen and performs a specific function for the user. There are many types of widgets that a person may have at their disposal when running a widget-driven application. Some display images and plots, some allow for text entry, and others are buttons that can be pushed to activate a process. In all, a widget provides a new, more tactile method of performing tasks in an application, removing the need of memorizing text command sets.
1.1: Setting Up RAVEN
There are a few items that need to be set up before you can begin using RAVEN. These items are described below.
1.1-0 You Need IDL
RAVEN runs in IDL (Interactive Data Language, from Research Systems, Inc.) and this environment must be properly installed on the machine before trying to run RAVEN. RAVEN requires IDL v. 3.5.
1.1-1 RAVEN Startup Commands
You must add four environment variables to your .cshrc file, namely RAVEN_DIR, RAVEN_SOURCE_DIR, RAVEN_CUBE_DIR, and RAVEN_DAT_DIR. Here's a description of what you need:
RAVEN_DIR is an environment variable that points to the location of the RAVEN executable. Whenever you run RAVEN, this is the directory it looks for. It needs to point to the directory that contains the file raven.idl.
RAVEN_SOURCE_DIR points to the directory where the source code is. This is merely placed there for the convenience of RAVEN developers and those maintaining RAVEN.
RAVEN_CUBE_DIR tells RAVEN the default directory of the cube files. In this particular case, the variable is meant for the convenience of the user and also gives RAVEN a first hint of where to look for cube files.
RAVEN_DAT_DIR points to the location of the source files that a RAVEN session must reference. IMPORTANT: The default directory shown by this variable must contain ALL of the source files for the cube that you intend to run. RAVEN looks to this directory ONLY.
Type this set of commands (with the appropriate modifications for your needs) at some point after any IDL related settings in the file:
#...for RAVEN
setenv RAVEN_DIR /usr/local/raven/Raven_idl
setenv RAVEN_SOURCE_DIR /usr/local/raven/Raven_source
setenv RAVEN_CUBE_DIR /data/raven_cube
setenv RAVEN_DAT_DIR /data/raven_data
#...raven startup from the shell
alias raven "idl $RAVEN_DIR/raven.startup"
This should be sufficient information to get RAVEN running properly.
Again, remember that the directories shown above are examples and may not actually be the correct directories for your system. Also note that you are free to change the variables RAVEN_CUBE_DIR and RAVEN_DAT_DIR to suit your needs. Have them point to directories where you will be placing source files and cube files (you can also point them to the same directory).
As a final note, be sure that you save the changes that you made to your .cshrc file. To have these changes take effect immediately, you can do one of two things: a) you can re-run of the .cshrc commands by typing source .cshrc at the shell prompt, or b) you can log out completely from the system and log in again, thus causing the new .cshrc to be executed. Either way should give you the same results.
You are now ready to run RAVEN and can simply do so by typing raven at the shell prompt (do not enter IDL and then run raven - this causes raven to drop out).
1.1-2 Preparing Source Files
Files that will be used by RAVEN must follow a specific syntax. Here is an example source filename of an AIRSAR C-band Stokes matrix file:
cm3217.airc
The portion of the filename before the dot (".") is the name and the portion after the dot is the tag. For best results, in terms of legibility when running RAVEN, the name should not be longer than eight characters, using some shorthand code to uniquely identify the file. The tag will always be four characters. The tag is important in that it identifies the type of source file that it is. RAVEN, knowing the type of file, can then process the data correctly. If RAVEN does not recognize the tag, it will label it as UNKNOWN and will not be able to process it.
It will be your responsibility to ensure that the proper tags are placed on your source files. A preliminary list of tags are placed here. Note that only the AIRSAR tags are currently used and that further tags will become available in time.
.airc -- AIRSAR C-band Stokes matrix file
.airl -- AIRSAR L-band Stokes matrix file
.airp -- AIRSAR P-band Stokes matrix file
.sirc -- SIR-C file (NOT YET IMPLEMENTED)
.byte -- simple generated byte file
1.1-3 A Note on Cube Files
Cube files have a tag too: .cub . This allows RAVEN to filter out other non-cube files from the 'Choose cube filename' widget (see Section 2.1-0) for your convenience. It also lets RAVEN know that it is looking at a cube file. Be sure that all of your cube files have the .cub tag on them.
1.1-4 X-window Defaults
Here are some example entries that may make RAVEN run better in terms of X-window displays. These additions are made to your .Xdefaults file. If you do not have one already, feel free to create it. These variables were set for using RAVEN in Motif. If running a different window system, you may want to check with your system administrator to see if the entries need to be changed. Also, you may make changes or additions to suit your tastes (such as changing the widget colors, etc.).
Idl*background: #8900e500a000
idl*foreground: #000000000000
*clientAutoPlace: off
idl.retain: 2
There is also additional information on .Xdefaults settings in the IDL Reference Guide.
Chapter 2:
RAVEN Initialization
In this user guide, many example widget menus are presented which show what the widget under discussion looks like. Don't worry if your widgets do not look exactly like the example. You may be using a different window system from the window system which was used to create the examples (which was Motif).
After typing raven at the shell prompt, you will soon see a window pop up, which is the RAVEN Initialization menu. This is the starting point in any RAVEN session. The idea here is to either: a) build a new cube, b) load an existing cube, or c) edit an exisiting cube for RAVEN to process. In any case, RAVEN will not continue into the image viewing functions until a cube has been specified from this menu.
2.0: The Initialization Menu
The Initialization Menu is divided into four sections. The first section, located at the top of the menu, simply contains an informative message. The second section, called 'Build New Cube', is the starting point for creating a brand new cube. The third section, called 'Load Existing Cube', allows you specify which cube you want to load into memory for use by RAVEN. The last section, called 'Edit Existing Cube', is the entry point for modifying a cube that you've already created. Finally, the 'Quit Raven' button at the bottom of the menu will exit of RAVEN if you select it with the mouse.
Note that once you build a cube or edit a cube, you still need to actually load it into memory. After you've built a new cube or editted an existing one, you'll notice the cube name you last worked with is automatically placed in the window in the 'Load Existing Cube' section. All you need to do now is simply select the 'Load It' button to load the cube into memory and enter the main part of RAVEN.
2.1: Building a Cube
To build a new cube, select the 'Build It' button on the Initialization menu. This causes the 'Build New Cube' menu to pop up on the screen. Cube creation requires the following items: a source file needs to be specified; the images you wish to synthesize need to be specified; the portion of the image you want to work with needs to be specified. An output cube filename is given and the cube is then created. Keep in mind that when you're building a cube, you're dealing with only one source file, for example 3908.airc. If you want to synthesize images from 3908.airp and add them to the cube, you have to load your finished cube into the 'Edit Existing Cube' section on the Initialization menu and add new images to the cube from there.
2.1-0 Entering the Source Filename
The source filename is input at the top of the 'Build New Cube' menu and it can be entered in two ways.
The first way is to select the square button located at the top left corner of the menu. This button causes the 'Choose Filename' menu to pop up. This pop up menu allows you to select the source filename with your mouse. The field next to the 'Path:' label shows the current directory you're in. The left window allows you to traverse to a new directory by selecting an item in the window. The right window shows you all the files RAVEN recognizes as potential source files. Select one of the files to be the source file, and the selection will be echoed in the narrow 'Selection:' window at the bottom the the menu. Select the 'ok' button to accept your choice and get back to the 'Build New Cube' menu. You will see that you're selection has been automatically entered in the text field at the top of the 'Build New Cube' menu. You will see the message 'Processing Image Options'.
The second way to enter the source filename is by simply typing it directly into the text widget at the top of the 'Build New Cube' menu. After typing the name
of the source file, keep the mouse pointer inside the text widget field and hit the return key. You will see the message 'Processing Image Options'.
At this point, the following four things happen. 1) The rest of the 'Build New Cube' menu becomes sensitized. 2) RAVEN detects the source type and dimensions of the image in the data file writes this information underneath the source file text widget. 3) RAVEN then writes a list of all the types of synthesized images that are available from this source type. This list is written in the widget with the label 'Available Images'. 4) RAVEN fills in the dimensions in the label that starts with 'Maximum dimensions in image' located in the middle of the menu.
2.1-1 Selecting Images
The 'Available Images' list contains all of the images that can be synthesized from the source file. The scrollbars can be used to view all of the items, as with any list widget.Clicking on an item in this list moves a copy of the image name over to the 'Selected Images' list. The 'Selected Images' list displays the available images that were selected for synthesis. Only these images will be synthesized from the list of available images. To deselect a selected image item, just click on the name in the list.
2.1-2 Memory Calculation
This window gives the user a rough idea of how many images could be put into the cube before the system cannot contain all of the cube contents in memory. It is merely a calculator and only gives a rough estimate of the number of images that can still be added, based on the size of the images, the number of the images, and a given estimate of available memory. The information provided in this window changes every time you add/delete an image in the 'Selected Images' list or when you change the image region (as described below).
2.1-3 Specifying a Region
RAVEN allows you to define a region of the image that you want to work with. You define the region by specifying the x and y offset from the (0,0) point in the image, and specifying the number of samples and lines the region is to have. The values entered into the 'Image offset' text widgets located in the lower have of the menu represents how many pixels the synthesized images should be shifted from the top corner (0,0) of the source file. This allows the user to omit certain parts of source file data and to extract a smaller subset image from the source file. The X-axis is considered the sample (horizontal) axis and the Y-axis is the line (vertical) axis. The maximum allowable dimensions of the resultant images are reduced according to the amount of offset specified. Update this label by pressing the <REURN> key after you've entered the offsets.
The values entered in the 'Number of samples/Number of lines' text widgets are the dimensions of the resultant images, constrained according to the offset values given. The image size can be anywhere from (1,1) to the maximum dimensions of the source file. Pressing <RETURN> after an entry here will activate the 'Memory Calculation' window.
2.1-4 Specifying the Output Cube Filename
The cube will be saved to the directory and filename specified in this widget.
2.1-5 Build the Cube
Pressing the 'Build Cube' button will cause the cube to be formed, with header construction followed by byte image synthesis. If a cube with the specified cube name already exists, an error message will be returned, warning the user that another filename needs to be specified. Also, a cube cannot be constructed until the number of samples and the number of lines have been given.
2.1-6 Synthesizing an Image
Building a cube will require image synthesis (unless you're only reading in byte data). The synthesization process is as follows.
For AIRSAR, RAVEN will open the source data file, de-compress the data, and compute floating point data for the image from the uncompressed AIRSAR data. Once this is done, a menu called 'Synthesize Byte Image: xx Polarization' will pop up. This menu contains an image window, a line of informative text, and buttons.
The synthesized byte image is displayed in the window and you can change how the image looks by changing the scale factor and selecting the 'Execute' button (the scale factor is the number of standard deviations used in creating the byte image). The text window to the right of the 'Execute' button tells you what the equation that creates the byte image looks like. You cannot edit this equation. When you are finished with this image, select the 'Keep' button. This will cause the currently displayed byte image to be written to the cube.
For SIR-C images, the following menu will pop up:
In order to synthesize a SIR-C image, RAVEN needs to create a 'common block header file' (unless one already exists). The common block header file is created from one of the SIR-C CEOS ascii header files, which is an output of the CEOS Tape Reader Program. The name of this header typically has a syntax that looks like pr01556_img_ceos_ascii. Also output from the SIR-C CEOS Tape Reader program is the SIR-C image file. Note that the image file will have to have been changed to xxxxx.sirx to have been recognized by RAVEN.
2.1-7 Canceling Out of the Menu.
The user can exit from the 'Build New Cube' menu at any time after entering a source file by pressing the 'Cancel' button.
2.2: Loading a Cube
Now look at the 'Load Existing Cube' section of the RAVEN Initialization menu. Loading a cube causes the cube file specified in the text widget to be loaded into memory, resulting in the exiting of the Raven Initialization menu and the activation of the main RAVEN analysis environment. Remember that even though you may have built a cube or edited a cube, you still have to load it into memory.
There are three ways for a cube filename to be entered into the text widget. First, you can click the button located next to the 'Enter cube name below:' label. This causes the 'Choose Filename' menu to pop up. Select a cube name, press the 'OK' button, and you'll see the cube filename you chose has been automatically written into the text widget.
The second way to enter a cube name in the text widget is to type it directly into the text widget.
The third way a cube filename is entered into the text widget comes from building or editing a cube. Whatever cube file is used in building or editing is automatically put into text widget.
Once you're happy with the cube filename that's written in the text widget, select the 'Load It' button. This will load the cube into memory, destroy the Initialization menu, and start up the RAVEN analysis environment.
2.3: Editing a Cube
Now look at the 'Edit Existing Cube' section of the RAVEN Initialization menu.
Editing causes the cube file shown in the text widget to be readied for editing. Editing a cube consists of adding to or deleting images from the cube.
First, you need to enter a cube filename into the text widget. You can do this by either using the 'Choose Filename' pop-up menu (click the button next to the 'Enter cube name below:' label) or type the cube filename directly into the text widget. Once you've done this, select the 'Edit It' button. This will cause the 'Edit Cube' menu to pop up.
2.3-0 The Edit Cube Menu
This menu lets the user add images to the selected cube or delete images that are already in the cube. The 'Edit Cube' menu consists of an information section, a 'Cancel' button, a 'Delete Images' section, and an 'Add Images' section.
When the 'Edit It' button is pressed on the 'Initialization' menu, the cube header is read and critical values from the header are displayed at the top of the 'Edit Cube' menu. Next to the information is the 'Cancel' button. Pressing this button will cancel the 'Edit Cube' menu and return the user to the 'Initialization' menu.
Only one of the edit operations may be performed per editing session. Either the user adds selected images by pressing the 'Add to Cube' button OR deletes selected images by pressing the 'Delete' button.
Note the 'Memory Calculation' window only relates to the 'Add Images' section and does not display values reflecting any changes made in the 'Delete Images' section. Think of 'Add Images' and 'Delete Images' as two distinct and separate functions, running independently of each other.
2.3-1 Deleting Images
Look at the 'Delete Images' section of the 'Edit Cube' menu. This section consists of a list widget called 'Current Images', a list widget called 'Images to Delete', and a 'Delete' button. The 'Current Images' list is a list of all the images that are currently in the cube. Selecting an item from this list will remove it and place it in the 'Images to Delete' list so it will be targeted for deletion. Selecting a list item from the 'Images to Delete' list will put it back in the 'Current Images' list and remove it from the 'Images to Delete' list.
Pressing the 'Delete' button will result in the deletion of all of the images in the 'Images to Delete' list. Note that there is no double-checking on this process. Once the 'Delete' button is pushed, the images are effectively gone. The user will then be returned to the 'Raven Initialization' window.
2.3-2 Adding Images
The 'Add Images' section of the 'Edit Cube' menu is essentially the same as the 'Build New Cube' menu (see Section 2.1) except that there is no need for specifying image offsets and dimensions, since the values were previously defined when the cube was created.
Chapter 3:
RAVEN High-Level Overview
Once the 'Load It' button is pressed in the 'Initialization' menu, that window is erased and what soon appears is a message window indicating that the cube you selected is being opened. As long as everything loads okay, you will begin to see the picture shown below, which essentially fills the entire screen. All the windows can be moved around on the screen and seated where useful. The first and foremost window is the main image window, which contains the official RAVEN title at the top and the full size image displayed inside. The other windows you should see are the Zoom, Image Selection, and maybe the Full Image Roam (if your image can't completely fit on your computer screen). You will also see the RAVEN Control menu.
3.0: Main Image Window
The main image window is sized to the image when the RAVEN Main Process starts up and will be smaller for smaller images.
Although not noticeable in the picture, a box resides on top of the image, indicating the region that is currently being examined by the Zoom window and possibly by other processes. This box can be moved by clicking a different location on the image with the mouse. The Zoom window will then respond by changing its magnified view to encompass the newly-placed box region.
3.1: Control Menu
This menu provides access to all of the basic RAVEN functions on a single platform. A Status Board supplies information about the current image that's being displayed. list widget is given to aid in keeping windows visible. A set of buttons activates primary RAVEN processes. Included is a window, displaying the current status of RAVEN, indicating the current image shown and other cube-related specifics.
In the middle of the Control Menu are the button widgets. Selecting a button starts up a specific operation. Buttons with italicized labels have pull-down menus associated with them. This section of menu buttons contains the functions for analyzing polarimetric data. The first is the 'Statistics' menu, which contains the means of collecting and displaying basic statistics of an image set by selecting individual pixels or selecting a polygonal region of interest. The 'Graph' menu contains functions for plotting data points derived from generated statistics. The 'Model' menu contains functions that will allow for models and simulations to be performed based on generated data.
Also on the Control menu is list widget called 'Current Windows'. Contained in this list are all of the windows that are currently up. Clicking on an item in the list will bring the corresponding window to the front of all the other windows. This is helpful when you have lost a window and it is hidden somewhere behind another one. It also acts as a roster of the windows that you currently have active. Note that not all of the windows and platforms used in RAVEN are registered in this list, merely because of their temporary nature.
3.2: Main Zoom Window
The main 'Zoom' window shows a subsection of an image at varying levels of magnification. The main zoom window has the label 'Image Window' displayed on one line, followed by coordinates on the next line, followed by pixel data. The area encompassed by the zoom window is indicated by the green box corners on the main image window. As the zoom level is changed larger or smaller, the box corners change the area that they delineate on the image window.
The user can zoom out up to 1X magnification by pressing the left mouse button while the cursor is in the zoom display. The right mouse button allows for magnification increases up to 16X magnification. The zoom value is shown in the bottom left-hand corner of the zoom display. The user can point to a pixel in the zoom display, and upon pressing the middle button, the zoom will center on this point, with the crosshairs lining up on that pixel. The data shown below the window always refers to the pixel currently in the crosshairs. The green box corners in the image window will move accordingly.
Also, clicking any location in the main image window will cause the zoom window to pan to that location. When RGB overlays are used, the zoom window will also display a three-color overlay, with the three separate pixel values displayed simultaneously below the zoom display.
3.3: Full Image Roam Window
This window allows the user to change the main image window's current view from one section of a very large image to another. This window only appears if the dimensions of the cube image exceed that of the display. In order to slide to a different area, simply hold down the left mouse button in the window and slide the "box" outline to encompass the region of interest. After a moment, the main image window will shift to the specified region.
The image shown in the 'Full Image Roam' window is effectively a sub-sample of the original image, scaled to fit in the small window space.
3.4: Image Selection Menu
This is an important part of RAVEN because it allows the user to switch views from one image in the cube to another at the touch of a button.
At the top of this platform is a list, showing all of the images present in the cube. Below that are three sections for specifying an image name for display. Each of the sections is used for calling a certain display type, whether it be a normal grey scale, or a three-color overlay, or an image-specific zoom window.
Along the bottom are the activation buttons. Only one is sensitive at any one time and reflects which selection is currently active.
Chapter 4:
RAVEN Statistics Toolkit
Selecting the Statistics button on the 'Control' menu will cause a pull down menu to be displayed. There are two items to choose from on the pull down menu, 'Preferences' and 'Make Patches'. In 'Preferences' you define settings, and in 'Make Patches' you create patches on which RAVEN will perform statistics based on the settings you defined in 'Preferences'.
4.0: Preferences
Selecting the 'Preferences' line item in the 'Statistics' button causes the 'Statistics: Preferences' menu to pop up. This menu contains three sections, an information message at the top, a band (image) selection section in the middle, and an output units selector at the bottom.
21
The band selection section of the menu contains two text windows, 'Select A Band:' and 'Bands Selected:'. In this section, band is another name for image. Clicking on a band name in the 'Select a Band:' text window will cause that band name to appear in the 'Bands Selected:' text window. All the bands in the 'Bands Selected' text window will have statistics computed on them when you create patch statistics in the 'Make Patches' menu. You can de-select a band by clicking on it.
You specify what units you want your output to be in by clicking on the available units in the 'Select Output Units' section. Note that you should only chose 'Phase' for phase images and 'Corr. Coeff.' for correlation coefficient bands.
4.1: Make Patches
4.1-0 The 'Make Patches' Menu
Selecting the 'Make Patches' line item in the 'Statistics' button causes the 'Statistics: Make Patches' menu to pop up. This menu contains five sections and a 'Cancel' button.
The first section is the Message text window. This window provides information that guides you through the steps you need to take to make a patch.
The second section, located at the top right portion of the menu, lets you specify how you want to create a patch. If you click on the image window button, you will create a patch from a window that is the same size and has the same display as the image window. If you click on the zoom window button, you will create a patch from a window that is the same size and has the same display as the zoom window. If you click on the 'read patch file' button, you will be prompted to supply the name of an already existing file that contains data which defines one or more patches (the next paragraph tells how you create a patch file).
The third section asks whether you want to save all the patches you will create in this session to an output (ie. patch) file. The default is 'NO'. If you click on 'YES', the text window in this section will become sensitized, and you need to enter supply a filename for the patch file that will be created.
Once you've supplied all the information for sections one through 3, you then tell RAVEN you want to make the patch. You do this by clicking on the 'Make New Patches' button.
4.1-1 Making a Patch
When you click on the 'Make New Patches' button in the 'Statistics: Make Patches' menu, a new menu pops up, titled 'Patch Selection'. This menu consists of an image window at the top and widget buttons at the bottom.
You can create a patch in two ways - as a single point or by outlining a polygon around the region.
To define a single point, do the following:
1) At the bottom of the menu under label 'Selection Modes', select the 'Pixel' button.
2) With your mouse, go into the image and select your pixel point. You can select more than one pixel point.
3) To delete the last pixel in last-drawn-first-deleted order, press the middle mouse button.
To outline a polygon, do the following:
1) At the bottom of the menu under label 'Selection Modes', select the 'Polygon' button (this is the default mode).
2) With your mouse, go into the image and locate the region you want to outline.
3) Using the left mouse button, click on points that outline the region. You will notice a line is drawn from one point to the next. To delete the last segment of the polygon, press the middle mouse button. To close off the polygon, press the third mouse button.
4) To delete the last polygon in last-drawn-first-deleted order, make sure your polygon is closed off and press the middle mouse button.
To get rid of all the patches you made, press the 'Clear All Pixels' buttons.
If you're happy with the patches you made and want to continue, press the 'Accept Selected Pixels' button. This will cause the 'Patch Selection' menu to disappear and re-activate the 'Statistics: Make Patches' menu. Next, RAVEN then computes statistics for each patch you created. Statistics are computed for the patch areas in each of the bands you selected in the 'Statistics: Preferences' menu. Statistics on the patch area include the mean, standard deviation, kurtosis, average incidence angle, and it also specifies the wavelength of the band.
Chapter 5:
RAVEN Graph Toolkit
The graph toolkit provides several functions for analyzing your data. When you press the 'Graph' button on the 'Control' panel, a pull-down menu is displayed. Your choices are 'Profile', 'Histogram', 'Co/Cross Pol & Sig0', and 'Polarization Sig.'.
5.0: Profile
The profile function allows you to draw a line segment on the display image and examine the values of the pixels along that line segment. Selecting the 'Profile' line item in the 'Graph' button causes a pop-up menu called 'Graph Toolkit: Profile' to be displayed.
At the top of the menu, you can specify whether you wan t the values of the profile displayed in dn, dB, or amplitude. Note that some of these choices may be greyed out depending on the type of image that is currently displayed. For example, you can't get dB from a byte image.
Next, you can specify if you want the values of the profile vertices to be saved to an output file. You must select 'YES' or 'NO'.
Finally, you must specify if you want to save the profile vertices and values to a file.
If you press 'YES', you are prompted to supply the name of the output file in the newly sensitized text widget. After supplying the filename, keep the mouse cursor in the text widget window and press the <RETURN> key.
Having specified 'YES' or 'NO', a message is written into the message box in the middle of the menu. It tells you to put the mouse in the image display window and pick the two endpoints of the line segment (use the left mouse button). You'll see the profile written into the black window on the profile menu.
Exit this function by putting your mouse in the image display window and pressing the third mouse button.
5.1: Histogram
This function reads in a patch data file and displays a plot of dn, dB, or amplitude vs. Number of Pixels. Selecting the 'Histogram' line item in the 'Graph' button causes a pop up menu to appear.
Supply the name of the patch data file, press the <RETURN> key, and the 'Graph Toolkit: Patch Histogram' menu will appear. At the top of the menu is the name of the data file being used. Below that is the plot window, and below that are the buttons you use to select the output units for the plot. Below that you'll find buttons that correspond to the number of patches that are found in the patch data file. When you press on a patch button, the histogram for that patch will be displayed.
5.2: Co/Cross Polarization and Sigma0 Plots
This function requires an AIRSAR triplet (P-, L- and C-bands) and displays three types of plots: a 3-dimensional co-polarization cross-section plot of a pixel point, a 3-dimensional cross-polarization cross-section plot of a pixel point, and a plot of the sigma0 values (in P-, L- and C-band) for the pixel point.
Select the 'Co/Cross & Sig0' line item in the 'Graph' button on the 'Control' panel. This causes a pop-up menu called 'AIRSAR Images' to be displayed. Use this menu to pick which triplet you want to look at. Select the 'Done' button when you're ready with your choice.
Once you hit the 'Done' button, the plots will be displayed. At the bottom of both the co- and cross-polarization plots are the buttons labeled '1', '2', and '3'. Look at the main title bar of the plots window to see what these labels correspond to.
Selecting the '1', '2', or '3' buttons will bring up the various cross-section plots. If you select a new point in the main image display window, all three plots will be updated.
1
5.3: Polarization Signatures
This function displays the co-polarized and cross-polarized polarization signatures for a given pixel or a patch as both 2-dimensional and 3-dimensional surfaces.
5.3-0 Making a Polarization Signature
Select the 'Polarization Sig.' line item in the 'Graph' button causes a pop-up menu called 'RADAR Images' to be displayed. If you want to select an AIRSAR image in your cube click on the 'AIRSAR' button (likewise for SIR-C).
A list appears under the 'Select and Image' label, and you are to select the data file you want to create the signature from. When you've selected the image, press the 'Done' button.
Next, a menu pops up called 'Polarization Signature: Input Mode'.
This menu allows you to specify how you want to define the region you will be making a polarization signature for. You can select from the zoom window, the image window, or you can read in a patch file. If you select zoom or image, the patch creation window appears and you can make your patch (see section 4.1 for how to make a patch). Once you've created the patch and accepted it, the patch creation menu will disappear and a new menu containing the plots will appear.
If you select that you want to use patches from a patch file, you will be prompted to supply the name of the patch file. Once you've entered the filename in the text widget at the bottom of the 'Polarization Signature: Input Mode' menu, put the mouse cursor in the text widget window and press the <RETURN> key. The will cause the pop-up menu to disappear, and the polarization signature menu appears. At the bottom of the menu you will see buttons associated with the number of patches that are in the patch data file. By pressing on a patch number, you will see the plots appear for that patch.
5.3-1 The Polarization Signature Menu
This menu consists of windows for displaying the 2-D and 3-D plots as well as buttons called 'Save', 'Color', and 'Close'.
The 'Save' button is a pull-down menu containing two choices, 'Data File' and 'Postscript File'. If you select 'Data File', the displayed polarization plots will be saved to a binary file as two 181 x 91 arrays of floating point numbers. Selecting 'Postscript File' will save the polarization signature plots a postscript file.
Pressing the 'Color' button will toggle the 2-dimensional images to a blue-to-red (cool-to-hot) density slice, and the 3-dimensional surfaces to shaded surfaces with the same density slice.
Pressing the 'Close' button removes this menu from the screen.
Chapter 6:
RAVEN Model Toolkit
Not yet implemented.
Chapter 7:
RAVEN Color Slicing
Color slicing causes a user-specified range of grey values in the image to change to a different color. This range can be specified in terms of dB, dn, phase, or correlation coefficient. Once a range of values is selected and a color picked for that range, any pixel on the image that falls in the range will change to the chosen color, marking out that range of values. Note that the 'Color Slicing' button on the 'Control' menu displays a pull-down menu with dB, dn, phase, and corr. coeff. as the line items. Some of these line items will be greyed out (ie. de-sensitized) depending on the type of image in the display window. For example, color slicing by phase only makes sense with phase images. So if the image in the main display window is not a phase image, color slicing by phase will not be an available choice. Note that color slicing is done with respect to the image that is currently displayed in the main image window. Only one 'Color Slicing' window may be brought up at any one time. The old window must be closed before attempting to bring up a new one.
If you are currently displaying an image in color, the 'Color Slicing' button is desensitized so that you can't invoke it. The results returned would be meaningless. If 'Color Slicing' has been activated followed by color RGB overlay, the color slicing will still take effect, creating meaningless garbage. This is a pattern to be avoided.
7.0: The Color Slicing Menu
The color slicing menu contains the following items.
At the top of the menu is some text that specifies the name of the image that will be color sliced and the range of values that the image contains.
Next, there are two labels called 'Min xx' and 'Max xx' (xx = the type of color slicing done), each with it's own text window. You specify the lower and upper end of the range using these windows. The range of values is confined to the range shown at the top of the menu. Also, you are not allowed to enter a minimum value that is larger than the maximum value entry and vice versa.
The 'Color' button is a pull down menu that contains 16 color choices. Each range that you pick must have a unique color associated with it, and you select a color using this pull down menu. This means that you can have up to 16 ranges active at the same time. You'll notice the box to the right of the 'Color' button will change to the color that you select from the list. If you don't like the color, simply return to the menu and select another one. Colors that get picked and assigned to a range will become desensitized in the color list. This provision ensures that you don't use the same color twice for two different slices. When selecting a color, you might notice some of the dark areas on your image all of a sudden change to the color you selected for a slice. Don't worry - this is not a permanent. It's merely a side effect of altering the color table so that your color selection is visible to you. You'll also notice that the cursor moves immediately to the square color window after you select a color. This is because changes to the color table won't become visible until the mouse cursor is passed over a display window. Call it a feature.
The big window in the middle of the menu is a text widget. This window will show which ranges are active and the color associated with the range.
Below the range list window is a bar displaying all of the color table values from the minimum value to the maximum value. This allows the user to see what the color table looks like at any given time as color slices are added or other color table modes are invoked.
The control buttons that direct the color slicing are at the bottom of the menu. You may notice that when you press any of these buttons (except 'Exit'), the cursor is moved to this color bar. This makes the color table changes immediately visible.
7.1: The Control Buttons
7.1-0 Add Range
Pressing this button will create a color slice based on the minimum and maximum values and the chosen color. Note that the color slice can only become active if the minimum and maximum values are given in the entry boxes AND a color has been selected. You'll see the color slice information written in the range list in the middle of the menu.
If the user presses the 'Add Range' button when there is not a complete color slice entry available, the image will toggle between the displaying color slices and not displaying color slices. This allows the user to flash back and forth between color slicing and the basic image for comparison.
7.1-1 Delete Range
To delete a color slice, select a color slice range from the range list with your mouse. Now press the 'Delete Range' button. Pressing this button after clicking an item in the range list will delete the slice from the image and remove it from the list. Once deleted, it cannot be brought back.
7.1-2 Clear All Ranges
Pressing this button resets the color table and removes all color slices. Consider this a "reset" button.
7.1-3 Cool to Hot
This button alters the color table so that intensity values are displayed as a color spectrum between the lowest value, blue, and the highest value, red. This button can also toggle between Cool to Hot mode and the previous display mode whether it was the color sliced display or the normal display.
7.1-4 Blu-Red Phase
This button will only be visible if you're color slicing a phase image (in which values range from negative pi to positive pi). The color table dithers from an intense red value to blue and then to red again. The red values are the +/- pi values and the blue represents values around zero radians. Like the 'Cool to Hot' button, this button can toggle between display modes as well.
7.1-5 Exit
Pressing this button exits the user from the 'Color Slicing' menu. Any color slices still in effect will remain until the user resets the color table by invoking 'Color Slicing' again or selecting the 'Reset Contrast' button in the 'Image
Contrast' menu.
7.2: 8-bit vs. 24-bit Color Slicing
In color slicing, we use a dn range of 0-255. However, for 8 bit systems there are never 255 free slots in the color table to work with. The system will allocate some slots in the color table for it's own needs. Because 256 color slots are not available (the system generally allocates around 30 color table slots for it's own use), this color slicing program will allocate all the available color table slots while in color slicing mode. This means that the original RAVEN color table set up at the beginning of the program is over-written. The user will notice the cross-hairs change color, and the magnification number in the zoom window also changes color. The user will also see a slight shift in the displayed image because the image will have to be redisplayed using the higher resolution color table (ie. the image is redisplayed using more shades than before). The original color table and image will be re-established when color slicing is finished. This program scales dn values from range 0-255 into 0-num_available_colors (unless minimum dn value is image is not = 0, in which case RAVEN shifts the values up the color table by the value of the minimum dn), so the user thinks they're actually working with the range 0-255.
For 24-bit systems, there are many slots available in the color table so scaling usually won't need to be done.
7.3: About Slicing by dn, dB, Phase, and Correlation Coefficient
Whether you're doing color slicing by dB, phase, or correlation coefficient, the values must ultimately be expressed in dn in order to put the color slice on the image (which is in dn). So keep in mind that your color slicing is not exact. For example, say a range of dB values is given, showing the minimum and maximum possible values that the user can specify. Due to statistical clipping, these numbers do not reflect the true extent of the dB range of the image, but refer simply to the dB range pointing sufficiently to all of the grey scale values.
Chapter 8:
RAVEN Contrast
The contrast functions allow you to enhance the variation of grey scale values in the image. Features in the image will then show up more clearly. Also, you can reset the image to its original intensity from this menu. When you select the 'Contrast' button from the 'Control' menu, you can select one of two choices, 'Vary Histogram Equ.' or 'Reset Contrast'.
8.0: Vary Histogram Equ. (Histogram Equalization)
Pressing this menu button brings up a window showing a plot of the histogram equalization function to be used. The user varies the level of histogram equalization from 0 to 100 percent by moving the cursor horizontally in the plot window. You will see the results in the image display. Press the third mouse button to set the contrast level. Note that only the color table is altered - the data remains the same.
8.1: Reset Contrast
This button will set the color table back to the RAVEN default, which is color table 0 (linear grey scale). Use this button any time while running RAVEN to reset the display when it has been altered by histogram equalization or color slicing functions.
Chapter 9:
RAVEN Show Cube Header
Guess what the 'Show Cube Header' button on the 'Control' menu does. Press it and find out.
Chapter 10:
RAVEN Output Byte Image
You're cube contains byte images, and you can the write byte data for any image in the cube to a file. You do this by selecting the 'Output Byte Image' button on the 'Control' menu. Once you've selected this button, a menu pops up called 'Output Byte Image' and this menu consists of three sections.
In the first section, you select which byte image you want to write to a file by selecting the name of the image in the 'Select a byte image:' list widget. This action will cause the name of the selected band to be echoed in the 'Selected Image' box, and it also causes a default output filename to be written in the output filename text widget located in the next section on the menu.
The second section requires you to fill in the name of the output file. If you don't like the default name that gets put in there, just move your mouse into the box and type in the name you want.
Once you've supplied the information in sections one and two, tell RAVEN to write the data to the file by selecting the 'Do It!' button in the third section. Next to this button is a little message window that tells you what RAVEN is doing.
Note that there is NO header written to this byte file. This means that you have to keep track of the number of lines and samples that define the size of the image.
Chapter 11:
RAVEN Image Selection Menu
The 'Image Selection' menu allows the user to switch views from one image in the cube to another or create multiple zoom windows (one for any band in the cube you wish).
This menu contains five sections. The first section contains a list of all the images that are in your cube. The second section contains a button, the label 'Grey', and a text widget. This section controls which image becomes the current grey-scale image in the image display window. The third section contains three lines, where each line contains a button, the label 'Red', 'Green', or 'Blue', and a text widget. This section controls which images are included in a three color overlay. The fourth section contains a button, the label 'Zoom', and a text widget. Use this section to specify which image you want a zoom window created for. The last section contains control buttons which execute based on the image names in the text widgets. Only one is sensitive at any one time and reflects which selection is currently active.
11.0: Grey Scale
To put a grey scale image on the display, press the 'Grey' button. Note that the 'Load Grey' button at the bottom of the menu is now sensitized. Now select an image from the image list. The name of the selected image is shown in the text field and may be changed by selecting a new item from the list above. Press the 'Load Grey' button and after a moment of processing, the selected image will be displayed.
11.1: Color
This is similar to procedure for grey scale. This time, the user has three colors to specify images for. Click the button of the color you want to select an image for and pick an image from the list above. Once all of the colors have the desired choices, click the now active 'Load Color' button to bring up the overlay. If your display monitor can make use of 24-bit color, pressing the 'Load Color' button will cause a pull down menu to appear. From this pull down menu, you can select if you want your color image to make use of 8-bit or 24-bit color.
11.2: Multiple Zoom
RAVEN v 2.0 has the capability of displaying many zoom windows on the screen, all at the same time. These additional zoom windows are image-specific, meaning that the user specifies the image that is being zoomed for each of the windows. Only one image-specific zoom window can be displayed per image.
To select an image to be zoomed, click the 'Zoom' button, select the image from the list widget, and then press the 'Load Zoom' button to bring up the zoom window. All of the zoom windows are slaved to each other so that they examine the same location and have the same zoom factor. However, since each shows data from a different image, the user will see different relationships of the same region simultaneously. Note that the image-specific zoom windows are slightly different than the default zoom window. First of all, the extra windows have a 'Quit' button. Pressing this button will cause the window to be deregistered from RAVEN. The main zoom window which has the label 'Image Window' cannot be exited and remains on the screen.
Also, you will note that the default zoom window is not image-specific, but is instead display-specific. This zoom window always displays data referring the to currently displayed image. When a new image is displayed in the main image window, the default zoom window follows suit. The other zoom windows do not change, since they point to a particular image in all cases.
The default zoom window also is the only window that will display RGB overlays, mimicking the main image window when it performs a color overlay.
Chapter 12:
RAVEN Reporting Bugs
As RAVEN v 2.0 is a beta release, there are bound to be bugs and many suggestions for improvement.
To send a bug report, do the following:
1) Address e-mail to raven@kahn.jpl.nasa.gov.
2) Start off the Subject: line with 'Bug: xxxxxxx' . The xxxxxx = your descriptor.
3) Specify what you were doing when the bug occurred, and write down any
error messages that were printed.
To send a suggestion, do the following:
1) Address e-mail to raven@kahn.jpl.nasa.gov.
2) Start off the Subject: line with 'Suggestion: xxxxxxx' . The xxxxxx = your
descriptor.
3) Specify in explicit detail what your suggestion is.