• distortion

distortion

Description

Distortion reads .REG files and provides updates to the focal length, central pixel/line, and K matrix for the camera. It also computes values for used in an Owen distortion model. Distortion is very "safe" to run, in the sense that it doesn't update anything. It only reports information. If the user wants to use the results from distortion, they must enter the updated information into make_sumfiles.txt and INIT_LITHOS.TXT. You run distortion in the main SPC directory, just like lithos, autoregister, etc.

Input Files

• ./DISTORTION.TXT

• ./REGFILES/PICNAME.REG

• ./make_sumfiles.in

Output Files

• None

Important parameters

The first line of DISTORTION.TXT determines which terms in the Owen model the program will solve for. The original Owen model had 6 parameters, E1, E2, E3, E4, E5, and E6. Ordinarily, you only solve for E2, E5, and E6. However, DISTORTION can also solve for the E4 term. Here is a list of the options for that first line and what they mean:

• 6 excludes E4, E5, and E6
• 8 excludes only E4

For a NAC, like DRACO, we don't want an E4 term. We only want to solve for E2, E5, and E6. So, we set the first line of DISTORTION.TXT to 8.

Lines two and three are the initial guesses for the camera model based on the instrument specifications. See DISTORTION.TXT and make_sumfiles.txt for more details on these.

The fourth line contains four entries that specify the initial guess for the distortion terms E2, E4, E5, and E6.. The initial guess for DRACO was that there is no distortion, so this was set to 0 0 0 0. See DISTORTION.TXT and INIT_LITHOS.TXT for additional details.

The fifth line contains sigmas on the central pixel/line location (SIGPLO), KXY (SIGKXY), and pointing (SIGMA_PTG). They determine how much you "trust" each of these values. Here are some comments about how to set those, based on experience with DRACO.

• SIGPL0: If you trust the location of P0 and L0, make SIGPL0 very small (1.E-10). Setting SIGPL0 to 1.E-10 essentially says to trust the values that you specified in the top of DISTORTION.TXT and do not more the boresight relative to the detector. If you suspect an error in the frames kernel, you could choose to run distortion with a larger sigma on the central pixel/line location because an error in the frames kernel can be "eaten up" in P0 and L0. It's easier to update P0 and L0 than to update the frames kernel.
• SIGKXY:
• SIGMA_PTG: This keeps the solution from jumping around too fast. Bob says that 1.E-3 is too large and 1.E-4 is about right for DRACO.

Using distortion

This is what it looks like when you initially run the program.

distortion                      --> you just type distortion; you don't provide any inputs at first.
      1089     37547     0.410  --> # of images (i.e., # of REG files in DISTORTION.TXT), total # of stars in those images, and the average residual
     0.021     0.033    -0.068  --> average Cx, Cy, Cz
     0.033     0.040     0.174  --> standard deviation of Cx, Cy, Cz
  ITERATE? (y/n)

The user then instructs the program to iterate by entering "y"

y

And the program then prints new values for the camera model and distortion

     2628.11469   512.500   512.500                          --> updated mmfl, P0, LO
    76.92300     0.00000    -0.00424   -76.93017             --> updated KXX, KXY, KYX, KYY
   -0.12976E-04    0.00000E+00   -0.50096E-05    0.68262E-05 --> updated E2, E4, E5, E6

      1089     37547     0.322   --> same information as described above; note the updated residual
     0.021     0.033    -0.067   --> new solutions for XYZ
     0.033     0.040     0.174   --> new errors on XYZ

  ITERATE? (y/n)                 --> the program asks if you want to keep iterating

Continue iterating until the camera matrix and distortion parameters have settled down and the residuals stop changing. Bob says you can do 40 iterations because it is biblical. But, you may need to do fewer if the values are stabilizing sooner than that. Once the solution has converged, say "n" when the "ITERATE? (y/n)" question comes up. The program will then ask whether you want to consider temperature dependence. For DRACO, we said "n".

  ITERATE? (y/n)
n
  TEMPERATURE DEPENDENCE? (y/n)
n

Computing a distortion model, in practice

Warning! A single bad REG file can cause major issues. Before running distortion, ensure that the .REG files have at least 7 stars (file size >1 KB) and that each star is centered in its red cross hairs in TEMPFILE.ppm. You must be confident in every REG file to ensure that you don't shoot yourself in the foot.

1. Set up DISTORTION.TXT. See DISTORTION.TXT for additional description.

2. Run distortion as described in the "Using distortion" section of this page.

3. Enter the updated camera model (mmfl, P0, L0, KXX, KXY, KYX, KYY) into make_sumfiles.txt. For example,

2628.11390   512.500   512.500                     MMFLN, PX0N, LN0N
76.92300     0.00000  0   -0.00451   -76.93017 0   KMATN

In the second row, the terms of the K matrix are Kx, Kxy, Kxxy, Kyx, Ky, and Kyxy. Distortion provides updated values for KXX, KXY, KYX, KYY only, so you can't just copy/paste the output from distortion into make_sumfiles.txt into that second line or you will be missing two zero terms. It is common practice to hold Kxy fixed at zero.

4. Enter the distortion parameters into INIT_LITHOS.TXT. The distortion model will be two lines long. For example,

DISTORT= 'D###########' 'OWEN'  6
 0.00000D+00        0.00000D+00    E2    0.00000D+00    E4    E5    E6

In the first line, D########### is an image name template that tells SPC to apply this distortion model to all images that begin with D. (The # is a wildcard.). The next term specifies that this is an Owen distortion model. The third term determines how many terms the distortion model contains. The Owen model has 6 terms (even if we don't solve for all of them), so this number is 6. The next line gives the values for the terms in the distortion model. Note that the second line has 7 terms in total. The first is the fractional focal length change for a particular filter (not applicable to DRACO, since DRACO has no filters). The next six terms are E1, E2, E3, E4, E5, and E6. E1 and E3 are left at zero because distortion only solves for E2, E5, and E6 or E2, E4, E5, and E6 (depending on what number you put in the first line of DISTORTION.TXT.)