Spaceborne Imaging Radar (SIR-C) Image Registration Software
User's Guide
v1.1
John C. Curlander
Lynne Norikane
Dan Stotz
September 9, 1994
Vexcel Corporation
2477 55th Street
Boulder, Colorado 80302
(303) 444-0094
This work was performed for the Jet Propulsion Laboratory, California Institute of Technology, sponsored by the National Aeronautics and Space Administration.
Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise, does not constitute or imply its endorsement by the United States Government, Vexcel Corporation, or the Jet Propulsion Laboratory, California Institute of Technology.
Abstract
This document contains information describing the use of the Shuttle Imaging Radar (SIR-C) Image Registration Software system. It provides instructions for installation and operation of the system. It also describes the software modules which constitute the system.
This document describes version 1.2 of the system.
Document Change Log
Date Section Ver. Comment Revised By
9/10/94 Many 1.1 Document changes to handle new Eugene Chu,
SIR-C CEOS file formats and (JPL)
corrected minor typographical
errors
Table of Contents
2.4.5.3.1.1 Other Ways to Add Tie Points 16
2.4.5.3.1.2 How Many Tie Points Do You Need 17
2.4.5.3.1.3 Maximum Number of Tie Point Pairs 17
2.4.5.3.9.1 When to Use It 19
2.4.5.3.9.2 How to Use It 19
Welcome to the Shuttle Imaging Radar (SIR-C) Image Registration Software system! To make it easier, we'll call this system "SIR-C Reg" from now on.
SIR-C Reg is an interactive tool for registering SIR-C data, X-SAR data, or byte images to SIR-C data, X-SAR data, byte images, digital elevation maps (DEMs), or JPL AIRSAR data. Tools are provided for reading data in native format (e.g. CEOS for SIR-C and X-SAR data), viewing the data and collecting tie points, registering the data, and exporting the data in native or other formats. The user interface is written in Research System Incorporated's Image Display Languagereg.. Computational routines are written in both IDL and in C as appropriate.
Version 1.1 of SIR-C Reg contains some extra image tracking features that are only available if you are running IDL version 3.0. These features are not compatible with IDL version 3.5.1. Please note that IDL version 3.5.1 has been found to contain new bugs with respect to version 3.0. It is recommended that you use version 3.0 if at all possible so as to take advantage of the additional features in SIR-C Reg v1.1.
This document describes how to install and use the SIR-C Registration system. A tutorial is provided in Chapter 2. The tutorial will provide you with most of the information you need to use the system effectively.
Details of implementation are described in the Technical Specifications Document (version 1.2) which should accompany this User's Guide. References are made throughout this document to the relevant sections in the Technical Specifications Document (TSD).
Additional program details are also included in this document.
SIR-C Reg is composed of four main subsystems:
(1) Image Import Subsystem
(2) Tie / Check Point Collection Subsystem
(3) Image Registration Subsystem
(4) Image Export Subsystem
The Image Import subsystem generates displayable byte images from a variety of data sources. These include the following:
SIR-C MLC and MLD data
X-SAR MGD data
JPL AIRSAR compressed Stokes matrix data
I*2 DEMs
byte images
The representative byte images are used in the Tie / Check Point Collection Subsystem and are stored in a special format (see TSD Section 3.1). For SAR data, the user may choose to synthesize a power or amplitude image.
The Image Import Subsystem is described in TSD Section 3.
1.3.2 Tie / Check Point Collection Subsystem
The Tie / Check Point Collection Subsystem provides an interface with which the user selects tie and check points between a master image and a slave image. The master image is that to which the slave image is being registered. Tie points are differentiated from check points in that tie points are used to generate the registration equation coefficients. Check points are used as a means of measuring the registration error.
The user is provided with standard tools such as zooming in and out in order to facilitate the selection of tie and check points. In addition, the user may choose the "correlation chip" option in order to have the computer automatically deduce the location of a tie or check point.
This subsystem is described in TSD Section 1.3. The correlation chip function is described in TSD Section 5.
1.3.3 Image Registration Subsystem
Once enough tie points have been selected, the user may choose one of two image warping options:
translation, scaling, rotation
warping
Generally, the translation, scaling, and rotation step is applied first. This involves the determination and application of a set of first-order warping equations. At least 6 tie points are required to determine the coefficients of the warping equations. This warping step is described in TSD Section 7.2.
The warping step is generally applied second. The equations are second order. At least 12 tie points are required to compute the coefficients. The second order warping step is described in TSD Section 7.3.
After either step, a results file is created which contains the updated tie points and measures of the registration error. The contents of the results file is contained in TSD Section 7.5.
The Image Export Subsystem generates the final registered output data sets. The user may choose to generate a data set in the same format as the original, a byte image, or an IEEE floating point image. The user selects the image to be exported. The warping equations used are read from the associated image descriptor file and are applied to form the exported data set. This subsystem is described in TSD Section 4.
The directories in which data files, images, tie point files, etc. are kept are relative to a project directory. The project directory is set with the environment variable PROJ_DIR. You would set this variable as follows:
setenv PROJ_DIR <your project directory>
If PROJ_DIR is undefined, then the system assumes that it is the current directory (i.e. `.').
The following directories must be contained within the project directory:
The DATA directory contains the original data sets (e.g. a SIR-C MLC data set) and the exported data sets.
The IMAGES directory contains the representative byte images created by the Image Import Subsystem.
The DESCRIPTORS directory contains files which describe the representative byte images. These are generated by the Image Import Subsystem and are updated by the Image Registration Subsystem to include any warping equations applied to a given image.
The TIEPTS directory contain the tie points associated with images in the IMAGES directory and are created by the Tie / Check Point Collection Subsystem.
The RESULTS directory contains the files generated by the Image Registration Subsystem comparing old and new tie points. These files also contain a measure of the registration accuracy.
SIR-C Reg v1.1 should be usable on any BSD 4.3 type Unix system with an ANSI C compiler and IDL version 3.0 or 3.5.1. Additional features are available under IDL 3.0.
SIR-C Reg is targeted to run on a Sun SPARC II running under operating system OS 4.1.3 or later with 32 MB of internal memory. It was integrated and tested, however, on a Sun SPARCstation 4/280 with 8 MB of memory and is clearly compatible with older computers with fewer resources. It has also been tested on Sun 670MP systems running SunOS 4.1.3 and DECstations running ULTRIX 4.3.
SIR-C Reg v1.1 will run under IDL versions 3.0 or 3.5.1. However, it contains some additional image tracking features that are only available if you are running IDL version 3.0.
1.5 Supported Image Sizes and Display Requirements
SIR-C Reg supports images of variable sizes up to 32767 samples x 32767 lines.
To use the Tie / Check Point Collection Subsystem, at least an 8-bit gray scale or color display is required.
The following data can be used as master data:
SIR-C MLC or MLD data
X-SAR MGD data
JPL AIRSAR data
I*2 DEMs
byte images
The following data can be used as slave data:
SIR-C MLC or MLD data
X-SAR MGD data
byte images
For SIR-C data files created by the SIR-C CEOS tape reader, the CEOS leader, trailer, image descriptor, and image data files are required. The file naming convention expected is "<base_name>_ldr_ceos", "<base_name>_tlr_ceos", "<base_name>_img_ceos", and "<base_name>_img_ceos_image", respectively. This differs from standard CEOS files in that the data has been separated out of the imagery options file, with the 12 byte prefix removed from the beginning of each record, and the data descriptor record kept in the separate file. The programs will also recognize the SIR-C archive CEOS file format containing the CEOS leader, trailer, and imagery options files with the names "<base_name>_ldr_ceos", "<base_name>_tlr_ceos", and "<base_name>_img_ceos". The volume definition file and null volume definition file are not needed. Only the MLC and MLD data formats are supported. See TSD Sections 3.2 and 4.3 for the equations used to uncompress and compress the SAR data.
For X-SAR data, the CEOS leader and imagery options files are required. The expected file naming convention expected is the same as that for SIR-C. If your X-SAR files are not named appropriately, you must rename them to the expected forms before running the programs. The volume definition file and null volume definition file are not needed. No trailer file is generated for X-SAR data. Only the MGD data format is supported. See TSD Sections 3.3 and 4.4 for the equations used to decode the SAR data.
For JPL AIRSAR data, only the compressed Stokes matrix format is supported. See TSD Section 3.4 for the equations used to uncompress the SAR data.
For DEMs, only the I*2 (2-byte integer) data format is supported. These are generally read as short data types in C. The data may optionally have a header which is ignored by the system. The user must provide the size of the header in bytes.
Byte images may also have a header which is ignored by the system. The user must provide the size of the header in bytes.
You should have received with this manual a tape, floppy disk, or other media containing the SIR-C Reg system. Presumably this tape contains a tar file. In order to install the system, follow these instructions, substituting the appropriate directories and device names:
1) insert or mount the tape or other media into or onto the appropriate drive
2) cd to the directory where you want the system stored, for example, on a Sun:
cd /usr/local
3) extract the tar file
tar xvf /dev/rst0
4) dismount the tape or other media
Be sure you have at least 0.5 MB of free disk space for SIR-C Reg. If you need additional help, please see your system administrator.
After you have successfully restored the SIR-C Reg system to your hard disk, type make to build all the executables.
To the run the system, first cd to the directory where SIR-C Reg was installed. If you intend to store your data files, images, tie point files, etc. in the current directory, then please create the following directories:
DATA
IMAGES
DESCRIPTORS
TIEPTS
RESULTS
If you wish to store your data files elsewhere (e.g. "/data"), then create the directories listed above in "/data". Then set the PROJ_DIR environment:
setenv PROJ_DIR /data
If you run into any problems either installing the system or running it, first consult your system administrator. For further problems, please contact:
Eugene Chu
Jet Propulsion Laboratory
4800 Oak Grove Drive
Mail Stop 300-243
Pasadena, California 91109
(818) 354-6496
fax: (818) 393-5285
internet: Eugene.Chu@jpl.nasa.gov
This tutorial is designed to take you through all the steps required to register one data set to another. Please read this section carefully as it explains completely how the SIR-C Reg system is used. It also contains instructions for registering multi-frequency data sets with the same set of tie points.
The overall process is as follows:
(1) Import the master and slave data sets
(2) Collect tie and check points
(3) Perform linear warp on slave data
(4) Modify or add new tie points (using new slave data)
(5) Perform polynomial warp on new slave data
(6) Check final registration
(7) Export the newest slave data
2.4.1 Gathering Your Input Data
Copy or move the data you want to register to the $PROJ_DIR/DATA directory. Make sure that both the master and slave data reside in this directory.
If you are using SIR-C or X-SAR data, be sure to use the following file naming conventions:
"_ldr_ceos" - SAR leader file
"_tlr_ceos" - SAR trailer file (for SIR-C data only)
For SIR-C CEOS files created by the SIR-C CEOS tape reader:
"_img_ceos" - Imagery Options file descriptor record
"_img_ceos_image - Imagery Options file data records
For "standard" CEOS files (SIR-C archive CEOS files)
"_img_ceos" - Imagery Options file
For example, the following file names are valid: "pr03031_ldr_ceos", "pr03031_img_ceos", "pr03031_img_ceos_image, and "pr03031_tlr_ceos".
2.4.2 Don't Use "set noclobber"
Be sure that "set noclobber" has NOT been specified. (This command prevents files from being overwritten with the Unix > redirection.) This command may reside in your ".cshrc" file. If it does, please comment it out (or remove it entirely). Logout and log back in again.
Change directory (cd) to wherever the SIR-C Reg system was installed. Type idl or other appropriate command to start IDL. After you get the IDL prompt, type sirc. The main interface should appear:
The buttons in the top row give you access to each of the four subsystems. The buttons in the bottom row are for cleaning up files and quitting.
In order to collect tie points between the master and slave data sets, you must be able to view those data sets. The Image Import subsystem creates viewable byte images from your input data sets. Those byte images are stored in the PROJ_DIR/IMAGES directory. A descriptor file is also created describing the byte image and is stored in PROJ_DIR/DESCRIPTORS. The formats of a representative byte image and its associated descriptor file are described in TSD Section 3.1.
Select
from the main interface with the right mouse button. The following interface
should appear:
The files in the DATA directory are listed in the upper part of the window.
Select the file you wish to import by using the scroll bar and selecting the
desired file with the right mouse button. If you are importing SIR-C or X-SAR
data, you may select the Imagery Options file ("_img_ceos" and
"_img_ceos_image), the SAR Leader file ("_ldr_ceos"), or the SAR Trailer file
("_tlr_ceos"). The name of the file should appear in the "Selected:" box. If
this is the correct file, select the
button.
2.4.4.1 Automated Data Type Determination (AIRSAR, SIR-C, X-SAR)
The system attempts to determine what type of data you are importing. (See IDL program "get_datatype.pro" for details).
It first checks to see if the selected file is an AIRSAR data file by seeing if it contains a variable format header.
If it is not an AIRSAR data file, then the system looks for the SAR Leader file. If the Leader file exists then the sensor field is extracted. For SIR-C data, "SIR-C" is contained within this field. For X-SAR data, "X-SAR" is contained within this field. The data product type is also checked. For SIR-C, only MLC (multi-look complex) and MLD (multi-look detected) data products are supported. For X-SAR data, only MGD (multi-look ground range detected) data products are supported.
2.4.4.2 Manual Data Type Determination (DEM, byte image)
If the data type has still not been determined, then the system assumes it is either a byte image or a DEM. You are asked to indicate which one it is:
Use the "Input Data Type" menu to select the appropriate data type:
DEM stored South to North
DEM stored North to South
Byte Image
The selected data type will appear in the text box to the right.
Next enter the number of header bytes contained in the data file. The default value is 0. These header bytes will not be interpreted in any way. Also enter the number of lines and samples in the appropriate boxes. Be sure to press RETURN after entering any new numbers.
Note that if you are importing an I*2 DEM, then the number of samples is 1/2 the number of bytes per line.
Select the
button when finished.
2.4.4.3 Importing AIRSAR, SIR-C, or X-SAR Data
If you are importing either AIRSAR data, SIR-C data, or X-SAR data, the system will generate either a power or amplitude image. You must select which one you would like:
The equations used to compute the representative byte images for these data types are located in TSD Chapter 3.
While the representative byte image is being generated, the cursor turns into an hourglass. Note that this step can require a lot of time, depending on how big the image is, and how fast your computer runs.
2.4.4.4 Importing DEMs or Byte Images
After you have selected the data type and entered the lines, samples, and number of header bytes, the representative byte image is generated. While this is occurring, the cursor turns into an hourglass.
2.4.4.5 Import Both Master and Slave Data
Before you go on, be sure that you have imported both your master and your slave data sets.
2.4.5 Collecting Tie Points and Check Points
The next step in the registration process is to collect tie points between the
master and slave images. Select the
button in the main interface. The following window will appear:
Note that when you select this function for the first time in a run session,
this step may take many seconds before you get a response, so please refrain
from selecting the
button more than once. If you do, it will bring up a second file selection
window, which could confuse the tie pointing software.
The master and slave data you just imported should be listed in the top area. Before you select these, examine the Zoom Factor. The Zoom Factor determines the amount of zooming which occurs with each zoom step. The default value is 2, meaning that if you are zooming in or out, the magnification is multiplied or divided by 2 with each step. You may change this value if desired by entering a new value in the text box and pressing RETURN. You must do this BEFORE you select the image to which you would like it to be applied.
Select the master image from the list of images. Two windows will appear, the image window (larger) and the tie point window (smaller). If the master image is large (i.e. greater than 1024 x 1024 bytes), it will be subsampled by an automatically determined factor. This may take a little time.
Now select the slave image from the list of images. Two more windows will appear, the image window and tie point window for the slave data. Again, the slave image may be subsampled and this may take a little time.
Note: Only one click of the mouse is required to select the file. If you
accidentally double-clicked on a file when selecting your master file, it will
be shown as both the master and slave. In this case, click the
button
in the file selection window and start over.
The windows for the tie point selection process should be laid out approximately as follows:
Looking at one of the image windows more closely:
Note that the "Correlate" button is only in the master image window.
Note that as you move the cursor around in the image portion of the window, the current sample and line are shown in the text box. The current zoom factor is also shown in the same text box.
Use the horizontal and vertical scroll bars to view the entire image. (If the image you are displaying is small enough, the scroll bars may not be shown).
To zoom in, position the cursor on the center of the area you wish to zoom in on. Select the right mouse button. After the new image appears, note that the scroll bars are gone. You cannot use the scroll bars when either zoomed in or out past the original resolution. For example, if the image was initially read in at 1/2 resolution (i.e. subsampled by 2 in both directions), then if you zoom in to 1:1 resolution or zoom out to 1/4 resolution, you may not use the scroll bars.
To zoom out, select the middle mouse button.
You will notice that the associated tie point window contains a white rectangle. This rectangle outlines the area currently displayable in the image window. The following is an example:
2.4.5.2 Manipulating the Color Table
If the images are difficult to view, the situation may be improved by
manipulating the color table. Select the
button. Unless you have deleted "xloadct.pro" from your SIR-C Reg
installation, a modified version of the IDL widget XLoadCT is called. Your
best bet is to move the "Stretch Bottom", "Stretch Top", and "Gamma Correction"
sliders around until you can see your images better. Then exit XLoadCT by
selecting the
button.
If you are running IDL version 3.5.1, you may experience some problems trying to use XLoadCT more than once.
2.4.5.3 Selecting Tie Points and Check Points
Now that you know how to look at your images, we can begin collecting tie points and check points.
Check points differ from tie points in that only tie points are used to generate the coefficients for the warping equations. After the warping equations have been determined, all check points and tie points for the slave image (if a linear warp was applied) or the master image (if a polynomial warp was applied) are warped to new positions. This is done in part to assess how well the tie and check points were matched after warping was applied. The corresponding results file (stored in PROJ_DIR/RESULTS) contains this information.
Thus check points can be used to measure the quality of the warp (for example at image boundaries) without affecting the warping equations which may favor better registration in the center of the image.
To add a tie point pair, you must be in edit mode for both the master and slave image (see "lock"/"edit" below).
To add a tie point pair, select the
button in either the master image window or the slave image window. With the
left mouse button, select the tie point in the associated image window. Now
select the corresponding tie point in the opposing image window.
For example, select
in the master image window. Select a tie point in the master image window.
Then select the corresponding tie point in the slave image window.
Select several pairs of tie points in this manner. You may see something like the following:
Note that the tie points are represented by
's.
The current tie point is labeled with its tie point number in the tie point
window, flashes, and looks like an asterisk. This number is also shown in the
tie point text box:
The tie points shown are in green.
Note that the current cursor position is indicated with a diamond.
2.4.5.3.1.1 Other Ways to Add Tie Points
If you wish, you do not have to add tie points as pairs. Whenever you select
the
button while in edit mode, a new entry is added to the end of both the current
master and slave tie point lists. This entry is empty in both lists. Whenever
the current tie point entry is empty and you are in edit mode, you may fill in
the empty entry with a valid tie point simply by clicking in the image window
with the right button.
For example, select
twice in either the master or slave image window. Be sure you are in edit
mode in both image windows. You now have two empty entries in both the master
and slave tie point lists. Let's work on the master tie point list first.
Select
in either the master or slave image window to set the current tie point to 1
(which can be verified by looking in the tie point text box). Now select your
first master tie point from the master image window. (The corresponding slave
tie point entry remains empty). Select
and then select the second master tie point from the master image window.
Now let's fill in the slave tie point list. Select
to set the current tie point to 1. Select the first slave tie point from the
slave image window. Select
and then select the second slave tie point from the slave image window.
To reiterate, whenever the current tie point entry is empty and you are in
edit mode, you may fill in the empty entry by selecting a tie point in the
appropriate image window. You do not need to select
first. In fact, doing so would only add a new empty entry to the end of the
current master and slave tie point lists.
2.4.5.3.1.2 How Many Tie Points Do You Need
The number of tie points you must collect depends on the warping function you wish to apply later on. For linear warping, you must have 6 tie points. For polynomial warping, you must have 12 tie points. Remember that check points do not count as tie points.
Warp Type Number of Required Tie Points
linear 6
polynomial 12
Since we will be doing both linear and polynomial warping in this tutorial, you might as well plan on collecting at least 12 tie points.
2.4.5.3.1.3 Maximum Number of Tie Point Pairs
The maximum number of tie point pairs supported is 1000.
After you have selected a few tie points, click on the
and
buttons. Notice that the current tie point changes as evidenced by the
changing number in the tie point text box and also by observing which tie point
is flashing in the tie point or image window.
If you are running IDL version 3.0, the image window will be shifted to contain the new current tie point if it is not already in view.
2.4.5.3.3 Manually Selecting the Current Tie Point
If you want to skip to a particular tie point without using the
or
button, simply enter the tie point number in the tie point text box and press
RETURN.
2.4.5.3.4 Selecting Tie Points Interactively
You can choose a new current tie point by clicking on it in the tie point or image window.
If you are running IDL version 3.0, the image window will be shifted to contain the new current tie point if it is not already in view.
The
button toggles between
and
.
When the button is labeled with "lock", then tie points can be added, but not
deleted (unless the opposing tie point is deleted), moved, or cleared.
Note that if you select the
button in the master image window, only the master tie point list can now be
edited. The slave tie point list remains in a locked mode.
To delete a tie point, select the
button so that it becomes
.
Set the current tie point to the one you wish to delete. Then select the
button. Both tie points are removed (even if the other list is theoretically
locked).
If you are running IDL version 3.0, the image window will be shifted to contain the new current tie point if it is not already in view.
If a tie point needs to be moved, select the
button so that it becomes
.
Set the current tie point to the one you wish to move. Then select the
button. The current tie point entry is made empty. This only affects the tie
point list corresponding to the image in which the
button was selected. Now you may fill in the empty entry by clicking in the
image window at the location of the new tie point.
If you wish to remove all of the tie points collected so far, select the
button so that it becomes
.
Then select the
button. All of the tie point entries in the list corresponding to the image in
which the
button was pressed are made empty.
2.4.5.3.9 "Correlate" or "Correlation Chip"
If you find it difficult to add tie points by eye, you may wish to use the spatial correlation function to generate tie points automatically. However, this function only works if the master and slave images are both in approximately the same orientation and have approximately the same pixel dimensions. The following case would not work:
In addition, the two images must exhibit the same reflectivity properties. For example, if you wish to generate a tie point at the intersection of 4 agricultural fields, each of these fields must exhibit the same relative brightnesses in the slave and master image. The following example would not generate a valid tie point:
The orientation and pixel dimension requirements are usually met after applying linear warping. Thus the correlation function may be useful in finding additional tie points after linear warping and before polynomial warping.
Finally, the areas that you select should have some high contrast features in order for the correlation to generate useful results. Correlating two areas of near uniform intensity (such as over calm ocean) may not produce a tie point.
The correlation function only operates when both the master and slave images are at full resolution (i.e. x 1). Choose an area where you would like to try the correlation on and zoom in to full resolution.
Select the
button in the master image window. In the master image window, select the
upper left corner of the area you would like to use for the correlation. A
rubber band box should appear. Now select the lower right corner of the
area.
Now move the cursor to the slave image window. Note that a box of the same relative dimensions (but 15 pixels wider and taller than the box selected in the master image) follows the cursor around. Center the box on the corresponding area in the slave image. The press the right mouse button.
The correlation function is now called and attempts to locate the peak of the correlation. If the peak falls on the edge of the area over which the correlation was computed, then no tie point is generated. Otherwise, a new tie point pair is generated and added to the tie point lists. (See TSD Chapter 5 for the exact implementation).
2.4.5.3.10 "Save as Check Point" and "Unset as Check Point"
As mentioned previously, check points may be selected in order to measure the quality of the registration after warping without changing the warping equations.
By default, only new tie points are added. To create a new check point, first
add it as a tie point. Then select the
button. The new tie point becomes a check point. This is visually indicated
with a red triangle. If you wish to convert the check point back to a tie
point, select the
button.
You can also convert an existing tie point to a check point by making that tie
point the current one and then selecting the
button.
A mixture of tie points and check points is shown below:
After you have entered all your tie points and check points, select the
button in both image windows. If you forget to save your tie points and try to
exit the Tie / Check Point Collection subsystem, you will be reminded and given
a chance to go back and save your tie and check points.
The tie / check point files are saved in the PROJ_DIR/TIEPTS directory.
If you wish to view the master and slave images as a red/green overlay, select
the
button in the main Tie Point Collection window. A new window should appear
containing the red/green overlay of the images as they were originally read in
(either full-resolution or sub-sampled). If they are of different dimensions,
they will be matched in the upper left-hand corner.
Select
when you are finished.
If you wish to view the master and slave images as a movie (i.e. the two images
are swapped back and forth within the same image window), select the
button. A new window should appear in which the movie is "played". The images
shown are those as they were originally read in (either full-resolution or
sub-sampled). If they are of different dimensions, they will be matched in the
upper left-hand corner.
Select
when you are finished.
2.4.5.6 Exiting the Tie / Check Point Collection Subsystem
After you have finished collecting the 6 or 12 tie points you need for image
warping, save the tie points and exit the subsystem by selecting
from the Tie / Check Point Collection subsystem main window. All the image and
tie point windows should go away.
2.4.5.7 Adding or Editing Tie Points Later On
If you discover that you need to go back and add or modify some tie points later on, simply go back to the Tie / Check Point Collection Subsystem and select the same master and slave images. Your old tie point files will be read back in and you can work from there.
The next step in the registration process is to warp the slave image to the master image. Generally this is generally done in three steps:
(1) Linear Warping
(2) Addition or Modification of Tie Points
(3) Polynomial Warping
The linear warping step corresponds to applying a translation, rotation, and scaling function to the slave image. To generate the equations for this step, at least 6 tie points are required. If you have enough tie points, then we can proceed. Otherwise, go back to the Tie / Check Point Collection subsystem and add some more tie points. (Your old ones will be read back in automatically).
Select the
button in the main interface. The following window should appear:
Initially, the Master and Slave text boxes will be empty. First select the tie point list for the master image. This file name will appear in the Master text box. Then select the tie point list for the slave image. This file name will appear in the Slave text box. If you continue selecting tie point file names, these will continue to be added to the Master and Slave text boxes, replacing whatever file names already exist on those boxes.
When the master and slave tie point files have been properly selected, select
the
button. The window will go away and the registration process will begin. A
new slave image will be generated, new slave tie and check points will be
computed from the original slave tie and check points, a new image descriptor
file is created for the new slave image, and a results file is created
containing a comparison of the new slave tie and check points with the master
tie and check points. For details on linear warping, see TSD Section 7.2. The
cursor will turn into an hourglass during registration.
At the end of registration, the mean absolute difference in samples and lines between the new slave tie and check points and the master tie and check points are shown in the window in which IDL is being run. These results are also saved in the results file for the new slave image along with other statistical measures and the new slave tie and check points side-by-side with the master tie and check points.
Before we go on, let's review what new files we've created.
After any warping step (either linear fit or polynomial fit), a new slave image must be generated. The base name for the new slave image and related files is taken from the base name of the original slave image file name.
All imported images (i.e. files in the PROJ_DIR/IMAGES directory) end with ".img". In the example we've been using so far, the slave image name was "slave.img". The new slave image file name is derived from the original name by first removing the ".img". If a ".<n>" remains at the end of the file where <n> is an integer, then the new base file name will end with ".<n+1>". Otherwise, a ".1" is appended to the base name.
For example, "slave.1" would be converted to "slave.2" and "slave" would be converted to "slave.1".
The new image file name is then created by appending ".img" to the new base file name. The new tie points file name is created by appending ".tiepts", the new descriptor file is created by appending ".info", and the new results file is created by appending ".results". These are all stored in the appropriate directories of course.
2.4.6.2 Addition or Modification of Tie Points
To examine the results of the linear fit, go back to the Tie / Check Point
Collection subsystem by selecting
from the main interface. Select the same master image. For the slave image,
select the new one created during the registration process (e.g.
"slave.1.img").
You can check the registration so far by using the
button or the
button. If needed, tie points can be added or modified. Now is also an ideal
time to try adding tie points using the
function.
Before continuing, be sure you have at least 12 tie points.
The polynomial warping step corresponds to applying what is known as a rubber sheeting function to the slave image. To generate the equations for this step, at least 12 tie points are required. If you have enough tie points, then we can proceed. Otherwise, go back to the Tie / Check Point Collection subsystem and add some more tie points.
Select the
button in the main interface. The following window should appear:
Initially, the Master and Slave text boxes will be empty. First select the tie point list for the master image. This file name will appear in the Master text box. Then select the tie point list for the new slave image. Be sure to select the new slave tie points file! This file name will appear in the Slave text box. If you continue selecting tie point file names, these will continue to be added to the Master and Slave text boxes, replacing whatever file names already exist on those boxes.
When the master and slave tie point files have been properly selected, select
the
button. The window will go away and the registration process will begin. A
new slave image will be generated, a new image descriptor file is created for
the new slave image, and a results file is created containing a comparison of
the original slave tie and check points (after linear warping) with new master
tie and check points. For details on polynomial warping, see TSD Section 7.3.
The cursor will turn into an hourglass during registration.
At the end of registration, the mean absolute difference in samples and lines between the original slave tie and check points and the new master tie and check points are shown in the window in which IDL is being run. These results are also saved in the results file for the new slave image along with other statistical measures and the original slave tie and check points side-by-side with the new master tie and check points.
As before, we've created some new files: a new slave image, a new slave image descriptor file, and a new results file.
2.4.6.4 Checking the Final Registration
To examine the results of the polynomial fit, go back to the Tie / Check Point
Collection subsystem by selecting
from the main interface. Select the same master image. For the slave image,
select the new one created during the registration process (e.g.
"slave.2.img").
You can check the registration by using the
button or the
button. Hopefully, everything looks fine.
2.4.7 Exporting the Registered Data
2.4.7.1 Possible Output Products
So far, we have created a registered slave image (e.g. "slave.2.img"). However, this is not the final output product as the image is in a non-standard format. Three types of output products can be generated:
(1) byte images
(2) IEEE floating point images
(3) data in the same format as the input data
For example, if the original slave data was a SIR-C MLC data product, then we can generate a byte image, a IEEE floating point image, or a new SIR-C MLC data product as our output product. The output product would be stored in the PROJ_DIR/DATA directory. The process of generating the output product is called exporting the data.
Note that only SIR-C MLC and MLD products as well as X-SAR MGD products are supported as valid exportable data formats.
To export the registered slave image, select the
button in the main interface. The following window should appear:
Select the image file generated by the polynomial warping function to export (e.g. "slave.2.img"). This file name should appear in the "Selected:" text box.
Use the "Output Data Type" menu to select which output product to generate. Choose either a byte image, an IEEE floating point image, or data in the input format. (If your slave data was from an AIRSAR data set or a I*2 DEM, you may not select the "input format" option).
Select
.
You will now be asked if you want to export the data now or do it later. The option to do it later is given because the data export programs may run faster when fewer processes are running on the system. For example, by exiting out of IDL and then running the export program, you may see a considerable speed-up in elapsed time.
Unless you are working on a particularly slow system, select the
button. The data will be exported, during which time the cursor will become an
hourglass.
If you chose to export the data later, you will get a message similar to the following:
Write down the name of the file and select the
button. After you exit the SIR-C Reg system and IDL, you can type "source
slave.2.command" at the command line and your data will be exported. You may
then delete the command file.
The following naming conventions are used for exported data. Assume the base name of the final registered image is "small.2". Then the output product file names would be:
Output Product Type File Name(s)
byte image slave.2.byte
IEEE floating pt. slave.2.float
SIR-C slave.2_ldr_ceos
slave.2_img_ceos
slave.2_img_ceos_image
slave.2_tlr_ceos
X-SAR slave.2_ldr_ceos
slave.2_img_ceos
slave.2_img_ceos_image
The output product(s) would be stored in the PROJ_DIR/DATA directory.
If the image selected for export had no warping applied to it, then the output base name is created by appending ".EXPORT" to the input image base name. For example, "small" would be changed to "small.EXPORT". This is to prevent overwriting of the original data set.
Before you exit from SIR-C Reg, you may wish to clean up some of your files. For example, the intermediate and final image products may no longer be of interest to you.
Select the
button from the main interface. You should get the following window:
The buttons in the top row set which directory we're currently looking at. The
current directory is listed in the "Directory:" text box. Select a file to
delete by selecting a file from the list. The name of the selected file should
appear in the "Selected:" text box. To delete the selected file, select the
button.
If you will not be registering multi-frequency data sets, delete all of the slave images in the IMAGES directory. If you are not planning on using the master image anymore, delete that as well. The corresponding image descriptor files in the DESCRIPTORS directory are deleted as well.
If you will be registering multi-frequency data sets, delete all of the slave images up to the final registered image (i.e. "slave.img" and "slave.1.img"). Keep "slave.2.img" and the master image around.
In the RESULTS directory, you may delete all the files if you are no longer interested in examining the results of image registration and you will not be registering multi-frequency data sets. If you will be registering multi-frequency data sets, do not delete the results file corresponding to the registered slave image (i.e. "slave.2.results").
In the TIEPTS directory, you may also delete all the files. (All of the information required to export multi-frequency, registered data sets are included in the "slave.2.info" descriptor file).
To exit from SIR-C Reg, select the
button from the main interface. To exit from IDL, type "exit".
2.4.10 Registering Multi-frequency Data
To register multi-frequency data sets, you need the final registered slave image, its associated descriptor file, and associated results file. Be sure you don't delete these files when you are cleaning up your directories!
Select a base name for your new output product. For example, if we already registered the L-band version of a data set with output base name "slave_L.2", then perhaps you would choose "slave_P.2" as your output base name for the P-band data set. These names are used as examples below.
Change directory to "PROJ_DIR/IMAGES". Copy (cp) or rename (mv) the registered image "slave_L.2.img" to "slave_P.2.img". It does not matter that the new file does not actually contain the P-band image.
Change directory to "PROJ_DIR/RESULTS". Copy (cp) or rename (mv) the results file corresponding to the registered image from "slave_L.2.results" to "slave_P.2.results".
Change directory to "PROJ_DIR/DESCRIPTORS". Copy (cp) or rename (mv) the descriptor file "slave_L.2.info" to "slave_P.2.info". Now edit the new descriptor file. In the first line, change the name of the master input data set from "./DATA/slave_L" to "./DATA/slave_P". Be sure to keep the data paths the same. Now save the changes.
Before we continue, be sure that the original data set for "slave_P" really is stored in the PROJ_DIR/DATA directory.
To export this new data set, run the SIR-C Reg system. Select the
button. Select the file "slave_P.2.img", set the output data type to "input
format", and select the
button. Proceed as you did previously. When the data export function is
finished, you will have a new data set in PROJ_DIR/DATA.
This section describes briefly the C and IDL programs which compose the SIR-C Reg system.
This is the IDL program which handles the main interface for SIR-C Reg. It actually handles most of the Image Import Subsystem by itself.
This IDL program attempts to determine the data type of a given file (e.g. SIR-C, X-SAR, AIRSAR, or unknown).
This IDL program defines the widget used for selecting the data file to import.
This IDL program defines the widget used if the data type of a given file cannot be determined. The user chooses between a DEM or a byte image and also specifies the image dimensions and the number of header bytes to skip.
This IDL program defines the widget used if the data type is SIR-C, X-SAR, or AIRSAR and the user must specify whether to generate a power or amplitude image.
This program creates a byte image from a JPL AIRSAR data set. It can generate a power or amplitude image. The output byte image is stored in the format required by the Tie / Check Point Collection Subsystem. (See TSD Section 3.4).
This program creates a byte image from a byte image. The output byte image is stored in the format required by the Tie / Check Point Collection Subsystem. (See TSD Section 3.6).
This program creates a byte image from an I*2 DEM. It can handle DEMs stored from South to North or from North to South. The output byte image is stored in the format required by the Tie / Check Point Collection Subsystem. (See TSD Section 3.5).
This program creates a byte image from a SIR-C MLC or MLD data set. It can generate a power or amplitude image. The output byte image is stored in the format required by the Tie / Check Point Collection Subsystem. (See TSD Section 3.2).
This program creates a byte image from an X-SAR MGD data set. It can generate a power or amplitude image. The output byte image is stored in the format required by the Tie / Check Point Collection Subsystem. (See TSD Section 3.3).
3.4 Tie / Check Point Collection Subsystem
This IDL program computes the spatial correlation between selected areas of a master and slave image and returns the location of the peak. (See TSD Chapter 5).
This IDL program creates temporary files containing the contents of various directories as is required by "tie.pro".
mosaic.c, mosaic.h, mosaic_args.c, mosaic_comp.c, mosaic_proc.c
These program modules and header files are used to clip a region of interest from the original image for fast zooming.
This IDL program defines the main widget for the Tie / Check Point Collection Subsystem. (This is the widget with the "Red/Green Overlay" button).
This IDL program contains the global and common variables used by the Tie / Check Point Collection Subsystem.
This IDL program is not used, but maintained for compatibility.
This IDL program is not used, but maintained for compatibility.
This IDL program handles event processing for the main tie point collection subsystem widget.
This IDL program is not used, but maintained for compatibility.
This IDL program handles the tie point window display and functionality.
This IDL program loads images.
This IDL program creates data structures for the tie point window.
The IDL program handles the image window display and functionality.
This IDL program sets up the image and tie point windows for a given image.
This IDL program loads the tie point files and relocates them on zoom.
This IDL program performs image zooming.
xloadct.pro, filepath.pro, loadct.pro, reverse.pro, stretch.pro,
These IDL programs constitute the standard "xloadct" widget provided by IDL with some modifications to make it work with IDL 3.5.1. It also reloads the red and green colors used for displaying tie and check points.
zoom.c, zoom.h, zoom_args.c, zoom_proc.c
These program modules and header files constitute the resampling program which is used when needed for zooming.
3.5 Image Registration Subsystem
This IDL program defines the widget used to select the master and slave tie point files and the registration type, linear or polynomial.
This program actually does the image registration. It creates a new byte image from an old one by applying the warping equations passed to it. (See TSD Chapter 7).
This IDL program reads in the master and slave tie points, generates the warping equations, comes up with a new slave file name, spawns the registration job, creates a new image descriptor file, creates a new tie points file if needed, computes the registration errors, and creates a new results file.
This IDL program defines the widget which asks the user if he or she wants to export the selected image now or later.
This program creates either a floating point output image or a new data set in SIR-C MLC or MLD format from an original master data set and the warping equations required to generate the new data. It also updates the appropriate CEOS headers. (See TSD Sections 4.3 and 4.5 and Chapter 6).
This program creates either a byte image or a floating point image from the image selected for export. The warping equations are not required because the image selected for export has already been warped presumably. (See TSD Sections 4.5 and 4.6 and Chapter 6).
This IDL program takes the selected image and the selected output data type, generates the appropriate command to spawn, and spawns it. It also modifies the output data file base name if the selected image had no warping applied to it.
This IDL program defines the widget used to select the image to export and the output data type.
This program creates either a floating point output image or a new data set in X-SAR MGD format from an original master data set and the warping equations required to generate the new data. It also updates the appropriate CEOS headers. (See TSD Sections 4.4 and 4.5 and Chapter 6).
This IDL program reads a results file and returns the mean squared error of the registration. It takes as input the name of a tie points file, image file, descriptor file, or results file and deduces the name of the associated results file which is then read. The mean squared error is then stored as part of the update to a CEOS header.
This IDL program defines the widget which displays the name of the command file to source if the user chooses to export the data later.
This IDL program defines the widget which allows the user to delete files from the IMAGES/DESCRIPTORS directory, the RESULTS directory, and the TIEPTS directory.
3.8 Utilities and Miscellaneous
dem_defs.h, dem_defs_short.h, dem_defs.pro
These files contain the DEM header definitions at the beginning of all images used by the Tie / Check Point Collection Subsystem.
These header files contain the definitions required by the functions in "needtoread.c". They define the structures used in a linked list of elements. Each element contains a pointer to a block of data read from the input file, amongst other things.
This function provides a means of reading individual parameters from a CEOS leader, trailer, or imagery options file.
This header contains interfaces to the system functions used for interpreting command line arguments.
These files contain the routines to handle generic doubly-linked lists. It is used by mosaic.
This IDL program was used during the Acceptance Tests to measure the radiometric and phase errors. The file names, data types, and dimensions are hardcoded, but can be adapted for use with other data.
This C file contains a string manipulation function.
The file contains the functions used to create and maintain a linked list of elements, each of which contains a pointer to a block of data read from an input file. It is used with "register.c" and the export programs in order to speed up generation of output data sets.
This C file contains function prototypes for routines defined in misc.c and linklist.c.
This is a utility program which can be used to interactively read selected parameters from a CEOS file. It was used during the Acceptance Tests to verify that updates to various CEOS headers made by the Image Export Subsystem were really made.
This IDL program reads a descriptor file and returns the information read. It takes as input the name of a tie points file, image file, descriptor file, or results file and deduces the name of the associated descriptor file which is then read.
This C header file contains standard headers, defines, and macros used by linklist.c.