Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding jigsaw examples #4734

Merged
merged 8 commits into from
Jan 24, 2022
Merged

Adding jigsaw examples #4734

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
04f873b
jigsaw ex KAGTC AP15; initil commit
ladoramkershner Jan 3, 2022
0b1b387
splitting long example into three
ladoramkershner Jan 5, 2022
f776bca
Updating Changelog
ladoramkershner Jan 5, 2022
1e5a826
removing CHANGELOG entry
ladoramkershner Jan 7, 2022
28190b2
addressing comments round1
ladoramkershner Jan 8, 2022
3b8a2cd
adding bundlout.txt examples to documents
ladoramkershner Jan 13, 2022
98dfb5e
adding table summaries before and after update
ladoramkershner Jan 13, 2022
9029647
Small language tweaks for overhermite/existing
jessemapel Jan 21, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ Keywords when running CAMSTATS. [#3605](https://github.com/USGS-Astrogeology/IS
- Added additional translation files for TGO CaSSiS in order to support PSA compliant labels. [#4567](https://github.com/USGS-Astrogeology/ISIS3/issues/4567)
- Added support for KaguyaTC SP Support data ingest. [#4668](https://github.com/USGS-Astrogeology/ISIS3/issues/4668)
- Added examples to the jigsaw documentation. [#4718](https://github.com/USGS-Astrogeology/ISIS3/issues/4718)
- Added three examples to the jigsaw documentation covering relative and ground control bundles. [#4718](https://github.com/USGS-Astrogeology/ISIS3/issues/4718)
ladoramkershner marked this conversation as resolved.
Show resolved Hide resolved

### Deprecated
- Deprecated edrget as discussed in [#3313](https://github.com/USGS-Astrogeology/ISIS3/issues/3313).
Expand Down
101 changes: 101 additions & 0 deletions isis/src/control/apps/jigsaw/jigsaw.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1513,5 +1513,106 @@
</dataFiles>
</example>

<example>
<brief>Run of jigsaw parameterized for Kaguya Terrain Camera (TC) images and <b>a relative control</b> network covering the Apollo 15 landing site. </brief>
<description>
<p>
A relative network is a network that has no points connected to a ground source, but connects overlapping images together. Since there is no connection to
ground in the network, only camera specific parameters can be solved in the bundle. The required information to turn on spacecraft, radius, or other such
bundle solve parameters is not recommended.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if this paragraph is entirely correct. You can certainly still solve for all of these things, as long as you have enough observations for the number of unknowns, but they will all be determined relative to the spacecraft. So, the ground solution relative to the spacecraft will be correct, but the correctness of the ground solution relative to the rest of the body is unknown. You can come back and use tools like PC align to correct for this type of error.

There is likely a more technical set of terms for this, I'll reach out to Brent.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess I am under the impression that within ISIS, if you do not have ground in a network then solving for spacecraft position is not really worth the effort. But I would really appreciate more certain terminology, let me know if you hear from Brent

</p>
<p>
This relative bundle turns on and parameterizes the camera twist and camera acceleration solve parameters. Turning on camera twist allows for the bundle to solve
for the cameras rotation around the bore sight axis and does not require parameterization. Setting the camera solve parameter to acceleration is useful for
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and does not require parameterization what does this mean? Is this saying that solving for twist is optional?

Copy link
Contributor Author

@ladoramkershner ladoramkershner Jan 7, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mean twist is a flag and does not have a corresponding uncertainty estimation requirement. I will update to be more clear.

line scan imagers and requires 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 derivative parameters have on the bundle solution.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Change higher derivative parameters to higher order parameters. We're still just computing first partials with respect to all of these parameters, the acceleration is a higher order term in the pointing polynomials.

</p>
<p>
The ‘overexisting’ flag allows the bundle solution to approximate the camera solution with a polynomial function as opposed to storing every individual measurement.
This saves time and memory required for the bundle solution at the expense of accuracy. If one required the accuracy, overexisting could be used until the bundle
is converging in a satisfactory way and then turned off for the final solution.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This paragraph is incorrect. The bundle solves for a polynomial regardless of overexisting or not. When you do not have overexisting on, the bundle starts by fitting a polynomial to the a-priori ephemerides and then just uses that polynomial to compute all ephemerides. If you enable overexisting, it instead saves the a-priori ephemerides and begins with a zero polynomial. The a-priori ephemerides are then added to ephemerides computed from the polynomial that the bundle solves for. Here's a simple example:

overexisting off

Initial data : {(1,1), (2, 4), (3, 9), (4, 16)}

fitting a linear polynomial we get f(x) = 5x - 5

then, we throw the initial data away and we now compute all ephemerides using our function, f. So, {(1, f(1)), (2, f(2), ...}

The bundle will compute corrections to the coefficient of f.

overexisting on

Initial data : {(1,1), (2, 4), (3, 9), (4, 16)}

We start with a zero polynomial, f(x) = 0x + 0

Now, we keep the original data and add the result of f to it. So, {(1, 1+f(1)), (2, 4+f(2)), (3, 9+f(3)), ...}.

The bundle still computes corrections to our function f and because the initial data is just a constant offset, it doesn't impact our partial computations in the bundle.

</p>
<p>
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.
</p>
</description>
<terminalInterface>
<commandLine>
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 \
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a not above that you have update=no because you are still evaluating the solution and do not want to apply it to your images just yet.

twist=yes camsolve=accelerations overexisting=yes camera_angles_sigma=.25 camera_angular_velocity_sigma=.1 camera_angular_acceleration_sigma=.01
</commandLine>
<description>
</description>
</terminalInterface>
</example>

<example>
<brief>Run of jigsaw parameterized for Kaguya Terrain Camera (TC) images and <b>an intermediate ground control</b> network covering the Apollo 15 landing site. </brief>
ladoramkershner marked this conversation as resolved.
Show resolved Hide resolved
<description>
<p>
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 can expand the bundle solve parameters to attempt solving for point radius values and the position of the spacecraft.
</p>
<p>
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 smith a network with only relative points and add ground point in AFTER the relative network (and its bundle solution) is of sufficient quality.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would avoid the word smith as it could be confused with smithed kernels that are produced from bundle adjusted images. I would instead use something like refined or improve.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would bold after instead of using all caps. In the brief description bold is used for emphasis but here all caps are.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I switched because I was having trouble with bold not showing up, I will switch it to be consistent (which is a good suggestion) and hopefully I can figure out why the bold is not showing when I build the docs locally.

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.
</p>
<p>
In addition to the previous solve parameters, this bundle turns on the point radius and spacecraft position solve parameters. Radius and spacecraft position
are two parameters which can only be solved for when ground points are present in the bundle solution since they are concerned with absolute positioning.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See my comment on the previous example about relative solutions vs grounded solutions. You can 100% still solve for these things and they will be relatively correct without ground.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will just delete the sentence "Radius and spacecraft position are two parameters which can only be solved for when ground points are present in the bundle solution since they are concerned with absolute positioning"

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 pointing corresponding to the correct elevation on the shape model. 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 the radius total correction of points exceeds the provided sigma,
the uncertainty may need to be increased.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Be careful correlating these too closely. We've had users confused about the sigmas not being hard constraints. They are a-priori uncertainties, or standard deviations, not hard constraints. So, it's expected that some amount of points have corrections higher than their sigmas, in fact in a perfect world, we'd expect about a third of the points to have corrections higher than 1 sigmas.

</p>
<p>
Applying the space craft position solve parameter requires an uncertainty estimation through spacecraft_position_sigma, while [file_prefix]_bundleout_images.csv
holds the resulting image adjustments in the X Correction, Y Correction, and Z Correction columns. The overhermite flag allows a polynomial to estimate the
spacecraft position, like the overexisting flag estimates the camera pointing with a polynomial. As such, this option saves memory and time at the expense of
some loss in accuracy and this loss can be mitigated by switching it off for the final run.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See my comments in the previous example. using overexisting or overhermite actually takes more memory than just solving for a polynomial as we have to store the a-priori ephemerides and the polynomial.

</p>
</description>
<terminalInterface>
<commandLine>
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
</commandLine>
<description>
</description>
</terminalInterface>
</example>

<example>
<brief>Run of jigsaw parameterized for Kaguya Terrain Camera (TC) images and <b>a final ground control</b> network covering Apollo 15 landing site. </brief>
ladoramkershner marked this conversation as resolved.
Show resolved Hide resolved
<description>
<p>
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. In the final run you can turn off overexisting and overhermite,
if you want to regain the accuracy, but note that the bundle solution will differ from your previous run. Therefore, it is advisable to conduct one intermediate
run to check the bundle is acceptable without these flags before updating the cubes. Finally, during the final run we turn on the error propagation flag. This
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would recommend not changing any parameters besides update in the final solution. You should check that you like the whole solution before you save it. It's kind of a hassle, but there's an issue open already to allow us to apply a previous solution independently. #4474

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).
</p>
<p>
If you want to double check the update was completed, see cathist or catlab (search for ‘Jigged’).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be great to provide an example of a table that has been updated and one that hasn't. Like a before and after.

</p>
</description>
<terminalInterface>
<commandLine>
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 camera_angles_sigma=.25 camera_angular_velocity_sigma=.1 camera_angular_acceleration_sigma=.01 \
radius=yes point_radius_sigma=500 spsolve=positions spacecraft_position_sigma=1000 errorpropagation=yes
</commandLine>
<description>
</description>
</terminalInterface>
</example>


jessemapel marked this conversation as resolved.
Show resolved Hide resolved
</examples>
</application>