jigsaw

The jigsaw application performs a bundle adjustment on a group of overlapping Isis, level 1, cubes from framing and/or line-scan cameras. The adjustment simultaneously defines the selected image geometry information (camera pointing, spacecraft position) and control point coordinates (x,y,z or lat,lon,radius) to reduce boundary mismatches in mosaics of the images.

This functionality is demonstrated below in a zoomed-in area of a mosaic of a pair of overlapping Messenger images. In the before jigsaw mosaic on the left (uncontrolled), the features on the edges of the images do not match. In the after jigsaw mosaic on the right (controlled), the crater edges meet correctly and the seam between the two images is no longer visible.

The jigsaw application assumes spiceinit has been run on the input cubes so that SPICE is included in the Isis cube labels in the Kernels group. In order to run the program, the user must provide a list of input cubes, an input control net, the name of an output control net, and the adjustment parameters. jigsaw outputs a new control net that includes the initial state of the points in the network and their final state after the adjustment. The initial states of the points are tagged as a priori in the control net, and their final states are tagged as adjusted. The measured sample/line positions associated with the control points in the net are not changed. SPICE in the cube labels is updated at the end of the adjustment only if the bundle converges and the UPDATE parameter is selected.

Optional output files can be selected to provide more information for analyzing the results. BUNDLEOUT_TXT provides an overall summary of the bundle adjustment. It lists the user input parameters selected and tables of statistics for both the images and the points. The image statistics can also be written to a separate CSV file and likewise for the point statistics with the OUTPUT_CSV option selected. RESIDUALS_CSV provides a table of the measured image coordinates and the final sample, line, and overall residuals in both millimeters and pixels.

The functional model for the bundle adjustment is the collinearity condition. It stipulates that the camera perspective center, a ground point, and its associated image point measurement be collinear. The diagram below demonstrates the collinear condition in a bundle adjustment. The vectors formed by connecting each object space point (target surface x,y,z) and its corresponding image space points (sample,line) form a bundle of light rays.

Kraus, Karl., 1993. Photogrammetry Vol. I., Fundamentals and Standard Processes, Der. Dümmler Verlag, Bonn, Germany, ISBN 3-427-78684-6, 397 pages.

Relevant Documentation

For information on what the original jigsaw code was based on checkout Rand Notebook

Known Issues

Running jigsaw with a control net containing JigsawRejected flags may result in bundle failure

When running jigsaw with Outlier Rejection turned on, control points and/or control measures may be flagged as JigsawRejected in the output control net file. If this output net file is then used in a subsequent jigsaw run, these points and measures will be erroneously ignored, potentially causing the bundle adjustment to fail.

--Workarounds

1. Run jigsaw with Outlier Rejection off.
2. Do not use the output control net file in subsequent jigsaw runs.
3. Convert the output control net file from binary to PVL and back using cnetbin2pvl and cnetpvl2bin. This will clear the JigsawRejected flags.

Solving for the target body radii (triaxial or mean) is NOT possible and likely increases error in the solve.

With the current jigsaw implementation, it is NOT possible to individually solve for either the mean or triaxial radii as seperate calculations in the bundle adjustment. More specifically, the target body radii has no effect when solving for individual points and thus cannot be solved for in the bundle. A local radii solve is already part of the sequence of equations that jigsaw uses to compute various partial derivatives to populate the solve matrix. A seperate mean or triaxial radii solve can be applied to the target body and the partials from this separate application are added to the solve matrix. This option adds additional computation time to jigsaw and creates additional uncertainty/error in the bundle adjust. We advise the mean and triaxial radii solve be avoided.

If you are trying to generate a spheroid from a control network there are other programs that can do this for you. An easier but more naive method is ingesting the OUTPUT_CSV from your network, gather local radii information from those points, then generate a sphereiod from those local radii.

This example runs jigsaw in a very simple way using four MRO CTX images. Only the required parameters are entered, with all other parameters left at their default settings. This bundle solution only solves for the camera orientation (see the CAMSOLVE and TWIST parameters). This command does not update the SPICE information attached to the four cubes.

A possible use for this simple run would be to test a network to identify control points that are not well placed.

jigsaw fromlist=ctx.lis cnet=hand_dense.net onet=hand_dense-jig.net

jigsaw Linescan image example

Example GUI The top of the GUI shows the parameters filled in for input cube list, the input control network and the output control network. All other parameters were left at their default values.

Cube list file	Input file defining the file names of the four cubes used in the control network. The file names can include a path if needed. Each file name is on a separate line and the last file name can have new line at the end, but it is not required.

A relative network is a network that connects overlapping images with tie points but has no tie points connected to a ground source. Since there is no connection to ground in the network, this bundle will only solve for camera specific parameters. The bundle could still solve for other parameters and be correct relative to the camera position, but it would increase the complexity of the bundle. The proceeding two examples will include grounded networks, so we will wait to increase the complexity of the bundle until ground points are included. Additionally, in this example we are evaluating the solution and do not want to apply it to the images yet, therefore, update is set to ‘no’.

This relative bundle turns on and parameterizes the camera twist and camera acceleration solve parameters. Camera twist is a flag that allows the bundle to solve for the camera's rotation around the bore sight axis and uses the same uncertainty estimation as the other two rotations. Setting the camera solve parameter to acceleration, however, does require uncertainties to be set for the angles (deg), angular velocity (deg/s), and angular accelerations (deg/s**2). These values were set with increasing constraint because of the increasing affect alterations of higher order parameters have on the bundle solution.

The ‘overexisting’ flag tells the bundle solution to approximate the camera rotation with a zero polynomial function added to the existing rotation data (adding the polynomial over the existing data). Without the ‘overexisting’ flag, the bundle fits a polynomial to the existing rotations, throws out the existing data points, and uses the polynomial to calculate the approximate ephemerides when needed.

This bundle also lowers the max iterations to 10 (from default 50). Lowering the max iterations does not affect the bundle solution. However, setting a lower iteration limit can serve as a flag if you expect your network to bundle quickly. Finally, the sigma0 convergence criteria was not changed from its default value, it was only explicitly stated in this call.

jigsaw fromlist=cubes.lis cnet=relative_reg_jig4_edit.net onet=relative_reg_jig5.net update=no file_prefix=jig5 sigma0=1.0e-10 maxits=10 twist=yes camsolve=accelerations overexisting=yes camera_angles_sigma=.25 camera_angular_velocity_sigma=.1 camera_angular_acceleration_sigma=.01

This example jigsaw bundle is run directly after adding ground control points to the previous relative network. With ground control points inserted into the bundle solution, we will expand the bundle solve parameters to attempt solving for point radius values and the position of the spacecraft.

Ground points are weighted more heavily in the bundle than relative control points and adding parameters adds more complexity to the bundle solution. Therefore, it is common to create and refine a network with only relative points and add ground point in after the relative network (and its bundle solution) is of sufficient quality. The purpose of this bundle is to ensure the network bundle converges with the added ground points and solve parameters, before committing to updating the camera pointing on the images, so update is set to 'no'.

In addition to the previous solve parameters, this bundle turns on the point radius and spacecraft position solve parameters. Applying the point radius solve parameter requires the point_radius_sigma to be set. This value is a representation the uncertainty (in meters) of the cameras apriori pointing corresponding to the correct elevation on the shape model; this value is not a hard constraint. Often this value can be set, and the appropriateness of the set value can be checked using the 'POINTS DETAIL' section of the bundleout.txt file output by jigsaw. If more than half of the radius total corrections exceed the provided sigma, the uncertainty may need to be increased.

Applying the space craft position solve parameter requires an uncertainty estimation through spacecraft_position_sigma (again this value is not a hard constraint). The appropriateness of the provided sigma can be evaluated through the bundleout_images.csv X Correction, Y Correction, and Z Correction columns.

The 'overhermite' flag allows an estimation the spacecraft position like the 'overexisting' flag estimates the camera pointing, with a zero-polynomial added over the existing data (for spacecraft position this is a cubic Hermite spline). These options require more memory but provide a solution more representative of small variations in the original ephemeris data.

jigsaw fromlist=cubes_for_ground_update.lis cnet=grounded_relative_reg.net onet=grounded_rr_jig1.net update=no file_prefix=jig1rr sigma0=1.0e-10 maxits=10 twist=yes camsolve=accelerations overexisting=yes camera_angles_sigma=.25 camera_angular_velocity_sigma=.1 camera_angular_acceleration_sigma=.01 radius=yes point_radius_sigma=500 spsolve=positions overhermite=yes spacecraft_position_sigma=1000

jig1rr_bundleout.txt	A shorten example of a typical bundleout.txt file produced by a jigsaw run with error propegation. This file was trimmed to hold 10 images, 50 relative points, and all ground points along with their associated detail sections. Bundleout files typically contain all image and point from a network put through jigsaw.

This last example is of a final jigsaw run of a grounded network. In this example all network adjustments are done, the bundle is converging, the resulting residuals are acceptable, and therefore we are ready to update the camera pointing on the cubes. During the final run we turn on the error propagation flag, this provides the variance-covariance matrix of the parameters, from which uncertainties can be computed. This is valuable if you plan to compute certainties for your update cubes camera pointing (or any kernels resulting from these updated camera pointings).

If you want to double check the update was completed, see cathist or catlab (search for ‘Jigged’).

jigsaw fromlist=cubes_for_ground_update.lis cnet=grounded_relative_reg.net onet=grounded_rr_jig1_ErrProp.net update=yes file_prefix=jig1rrEP sigma0=1.0e-10 maxits=10 twist=yes camsolve=accelerations overexisting=yes camera_angles_sigma=.25 camera_angular_velocity_sigma=.1 camera_angular_acceleration_sigma=.01 radius=yes point_radius_sigma=500 spsolve=positions overhermite=yes spacecraft_position_sigma=1000 errorpropagation=yes

jig1rrEP_bundleout.txt	A shorten example of a typical bundleout.txt file produced by a jigsaw run with error propegation. This file was trimmed to hold 10 images, 50 relative points, and all ground points along with their associated detail sections. Bundleout files typically contain all image and point from a network put through jigsaw.
Instrument pointing and position tables before jigsaw update	Table summaries for the InstrumentPointing and InstrumentPosition tables extracted from a cube label.
Instrument point and position tables after jigsaw update	Table summaries for the InstrumentPointing and InstrumentPosition tables extracted from a jigsaw updated cube label. The InstrumentPointing table was updated due to the camera updates solved for in the bundle (camsolve=accelerations). The InstrumentPosition table was updated due to the spacecraft updates solved for in the bundle (spsolve=positions).