jigsaw Documentation

jigsaw - Correct camera angles on the labels of a group of images
"jigsaw" uses the MATCH_POINTs from the LEVEL1 image labels to correct
the CAMERA_ANGLES of adjoining images.

***************************LIMITATIONS**********************************
On Sun machines running Solaris, during the matrix solution sometimes a
floating point underflow occurs (floating point exception error or
[TAE-PRCSTRM] Abnormal process termination; process status code = 6).
ISIS system routines cause the program to end with an error in this
case.  To get around the problem set the environment variable
ISIS_FPU_CONTROL to SAME and try running jigsaw again
(setenv ISIS_FPU_CONTROL SAME).

Because the photogrammetric equations used in jigsaw are not linear, an
approximation to a linear least squares solution is used.  In order to
get the solution to converge when running "jigsaw" on fewer than 6
images, you will MOST LIKELY need to hold an image. "jigsaw" only
processes match points and writes the results to the labels if the error
tolerance is not exceeded.
************************************************************************

MATCH_POINTs are sets of line1, sample1, image_number, line2,
sample2 where line1, sample1 on the image matches the line2, sample2
on the image with the given image_number.  These points are stored on
image labels with TVTIE operating in the MATCH mode.

The algorithm uses a linear least squares approximation to solve for the
camera angles of the unheld images.  The current camera angles and the
average of the latitudes and longitudes of the MATCH_POINTs are used as
an estimate in the first iteration.  A new set of camera angles for each
unheld image and latitude/longitude is computed for each MATCH_POINT in
each iteration until a minimum is found for the errors on all images.

This program will update the CAMERA_ANGLES on the image labels if the
error tolerance is not exceeded.

The program assigns a unique point index to match points because the
image label point indeces are not unique (each image can have a
MATCH_POINT1).  "jigsaw's" point indeces for the MATCH_POINTS are
always greater than 1000.  In addition to the point index, the program
lists the image_number and the measured line and sample for each point
on each image to the session log file, so they can be cross referenced
with the image labels.  The line and sample errors reported are in LEVEL
1 pixels at the resolution of the first input image.

Several preliminary steps must be performed before this program is used:

  1.  MATCH_POINTs must be identified and saved with TVTIE operating in
      the MATCH mode.  At least 3 MATCH_POINTs should be picked for
      every join, which means that each image could have as many as 12
      MATCH_POINTs.  These points should be as far apart as possible.

  2.  All of the images or subimages must be on disk.

The diagram below shows the ideal spacing on 4 images for MATCH_POINTs
where:

  H=MATCH_POINTs tied to held images
  M=MATCH_POINTs

------------------------------------------------------------------------
|                               | M |                                  |
|                               |   |                                  |
|   H                           |   |                                  |
|                               |   |            H                     |
|                               |   |                                  |
|             H                 | M |                                  |
|                               |   |                                  |
|                               |   |                                  |
|                               |   |            H                     |
|                               |   |                                  |
|                               | M |                                  |
------------------------------------------------------------------------
|                               |   |                                  |
|   M          M             M  |   | M             M              M   |
|                               |   |                                  |
------------------------------------------------------------------------
|                               | M |                                  |
|                               |   |                                  |
|                               |   |                                  |
|                               |   |                                  |
|                               |   |                         H        |
|                               | M |                                  |
|    H                H         |   |                                  |
|                               |   |                                  |
|                               |   |  H                               |
|                               |   |                                  |
|                               | M |                                  |
------------------------------------------------------------------------

PROGRAMMER: Debbie A. Cook. U.S.G.S., Flagstaff, AZ

List of input image file names
           or

--

File containing list of input
image files

--

List of hold image file names
           or

--

File containing list of images
to hold constant

--

Error tolerance

16.

Use 1 or 2 point fit

1

Number of iterations for fit

5

Hold points on hold images

YES

Check for NODES

NO

Directory of geometry spice file

ISISDATA

Extension of geometry spice file

rmb

Optional error file

--

ADDITIONAL NOTES:

Parm	Description
FROM	This is the list of LEVEL1 images or subimages that are to be adjusted. The images can be the original LEVEL1 images, but the labels must contain RAW_TIE_POINTs and MATCH_POINTs. Up to 50 images can be listed.
FROMLIST	Due to the limitations of TAE, if more than 50 images are to be adjusted, they must be put into a file. A maximum of 128 characters is allowed for each file name. List one file per line. A maximum of 600 images may be listed. This file can also contain lines that will be ignored if the first column of those lines contains a !.
HOLD	This is the list of images (which is a subset of the list in FROM or FROMLIST) to hold constant. The MATCH_POINTs that are in common with these images and the rest of the input file list will be used to control the images that are not listed in HOLD or HOLDLIST if HOLDPTS=YES. A maximum of 50 HOLD images may be listed.
HOLDLIST	Due to the limitations of TAE, if more than 50 images are to be held, they must be put into a file. A maximum of 128 characters is allowed for each file name. List one file per line. This file can also contain lines that will be ignored if the first column of those lines contains a !.
TOL	If the error in lines or samples in LEVEL1 space on any one of the images is greater than the tolerance set, none of the CAMERA_ANGLES in the image labels will be updated.
OPTION	OPTION=1 allows translation of the image but no rotation. OPTION=2 allows both translation and rotation.
ITERAT	This is the number of iterations that the program will perform to make a "best fit".
NODE	If NODE=YES, the node field in the SPICE files will be checked to decide if an image should be held constant. This is in addition to any files listed in HOLD or HOLDLIST. The DIR parameter will be used to find the desired SPICE files. If NODE=NO, only the files listed in HOLD or HOLDLIST will be held constant.
HOLDPTS	If HOLDPTS=YES "jigsaw" will hold the points on the held image(s) to the latitude and longitude values determined by the pointing information on the held image(s). These latitude and longitude values will be considered truth. If HOLDPTS=NO "jigsaw" will adjust the latitude and longitude values of the points on the held image(s) as it does all the other points and camera angles for nonheld images, until the solution converges.
DIR	ISISDATA is the location of the standard geometry SPICE files. These are the files that are usually used by a large group in Flagstaff to create a new "best" fit for a set of images such as the MDIM project for Mars. The user may create his own solution for a set of images in his own directory. 64 characters are allowed for the directory name. The files must be named using the following convention so that this program can find them: PLANET_MISSION_CAMERA.ext Eg: MOON_CLEMENTINE_1_UVVIS.rmb
EXT	"rmb" is the extension of the RMB geometry SPICE files. These are the files that are usually used by a large group in Flagstaff to create a new "best" fit for a set of images such as the MDIM project for Mars. The user may create his own solution for a set of images with his own extension. 3 characters are allowed for the extension. Do not use the following extensions for your personal SPICE files: rmb, evt gem, or med. These extensions are reserved for files in the $ISISDATA area.
ERRFILE	If "jigsaw" does not update the camera angles because the error is too large, the maximum error and a list of all the input files is written to the file specified by ERRFILE. If the camera angles are updated or ERRFILE is left as the null value, then no error file is created.