new_pole

Description

This program solves for a user input old and new right ascension (RA), declination (DEC), prime meridian (PM), and rotation rate (OMEGA), and updates the landmark center locations and map frames, and the spacecraft position, camera unit vectors and Sun unit vectors in all relevant files.

Input Files

• DATA/ - directory containing SPICE kernels.

• INIT_LITHOS.TXT - initialization file which contains the parameter PCK, which defines the planetary constants for a variety of objects (such as Bennu or the Sun). This is required for SPICE function calls.

• LMKFILES/ - directory containing .LMK files.

• LMRKLIST.TXT - list of landmarks.

• MAPFILES/ - directory containing MAPFILES.

• NOMINALS/ - directory containing the NOMINALS.

• PICTLIST.TXT - list of pictures.

• SUMFILES/ - directory containing the SUMFILES.

The required directories and files must be in the working directory.

Unlike pole, new_pole does not require POLE.TXT. Instead, you input the pole RA, Dec, PM, OEMGA, via standard input.

NEW_POLE does not correctly account for overlaps, according to Bob (October 2022). To avoid NaNs when running geometry or iterating the LMKs in lithos after running NEW_POLE, you should remove all overlaps from all landmarks before running either program.

Using new_pole

1. Input the old right ascension (deg), declination (deg), prime meridian (deg), and rate of rotation (deg/day).

 enter old RA, DEC, PM, OMEGA
86   -65   89.00000000   2010.48945

2. Input the new right ascension (deg), declination (deg), prime meridian (deg), and rate of rotation (deg/day).

 enter new RA, DEC, PM, OMEGA
86.60062   -65.00002    90.42707  2009.99979311

3. Input a time in UTC.

• Make sure the time is within the span supported by the kernels.

 Input epoch UTC0
2018 NOV 16 13:09:54.824

new_pole:

• Updates the landmark center location (VLM), and map frame (UX, UY, and UZ) in the LMK files;
• Updates the .MAP files;
• Updates the spacecraft position (SCOBJ), camera unit vectors (CX, CY, and CZ), and Sun unit vector (SZ) in the SUMFILES;
• Updates the spacecraft position (SCOBJ), camera unit vectors (CX, CY, and CZ), and Sun unit vector (SZ) in the NOMINALS.

• Outputs the commands required to run GEOMETRY.

Here is a sample output GEOMTERY commands:

 GEOMETRY
 10
 1
 n
 n

new_pole generates a POLE.TXT file in which it records the new RA, DEC, PM, and OMEGA.

Here is a sample POLE.TXT:

    86.60062   -65.00002    90.42707  2009.99979311

(Compiled by DL)

CategoryPrograms

densify

Description

This program is used to increase the resolution of a shape model by interpolating heights between landmarks.

densify first constructs a reference surface by interpolating the surface points of a lower resolution shape model. At each point of the reference, there is a vector V0 from the model center to that point and a normal N0 to the surface. That normal is extended some distance until it pierces one or more of the ensemble of maplets, and the average A of those distances is taken to represent the piercing point on the new model's surface. The new surface vector is V = V0 + A*N0.

The picture below is a visual representation of the paragraph above.

                ___...-------...___ maplet
                   |           |
                   |           |A*N0
             ______|___________|_________ reference
                   \          /
                    \        / V0
                     \      /

The new surface vector V will differ from V0 more noticeably when tiling at lower resolution because there are mismatches in maplet locations simply due to the formal uncertainties of the estimation process. Therefore, we have found it better to average the maplet normals N at each point, keeping a small randomly selected set of the A as conditioning heights.

Required Files

• LMRKLIST.TXT - List of all landmarks to be used

• LMKFILES/ - Directory of .LMK files for each maplet

• MAPFILES/ - Directory of .MAP files

• SHAPEFILES/ - Directory of built shapes

Optional Files

• LMRKLISTR.TXT - Specific list of landmarks desired

Output Files

• SIGMA.TXT - list of sigma values associated with the shape model (found in SHAPEFILES/)

• Shape file in ICQ format

Using densify

Although densify can be run interactively, the input commands are usually prearranged in a file (e.g., "tmpRun.txt") and you invoke the program from the command line like this:

~/bin/densify < tmpRun.txt

Here is an annotated sample "tmpRun.txt" file showing the input commands:

SHAPEFILES/PreviousShapeFile       (input shape)
2 100 1.67773                      (K (power of 2), search range (km), random seed)
SHAPEFILES/CurrentShapeFile        (output shape) <--At this point the map-averaged shape at a higher resolution is made
1                                  (more iteration) <--At this point we begin the slopes to heights integration
.005                               (fraction of points used for conditioning) <--These are sample heights we select for the slope->heights integration 
.025                               (conditioning weight)
1                                  (more iterations) <--More slope to heights integration
1
1
1
1
1
1
1
1
1
1
1
1
1
0                                  (end program)

The input commands are:

• line 1 - The input SHAPE file

• line 2 - A multiplicative scaling factor K (usually 2), a limit (in km) specifying how far along the surface normal the program should search for a maplet, a random seed in the form of a large integer

  • This random seed is superseded if you enter one on the command line after you invoke densify.

• line 3 - The output SHAPE file

• line 4 - 1 = an iteration

• line 5 - The fraction of points used for conditioning (usually .005)

• line 6 - The conditioning weight

• line 7 ... - 1 = an iteration (as many as you need)

• last line - 0 = end program

In most cases, the maplets will cover most of the surface. Where it is not covered, the normals to the input model provide the "slopes" and the integration proceeds without any randomly chosen conditioning heights from these areas.

In some cases, such as fast flybys of small bodies, only a small fraction of the surface is visible and vast areas are unknown. In these cases, conditioning heights are also taken from the input model as well. Specify this option by using a negative value for K (usually -2).

• In this case, use a negative value for K (-2) because, for every location in the shape model for which we don't have map coverage, densify will print on the screen. Setting the value to -2 will block printing to the standard output.

densify then determines the average height along each surface normal from each reference point of the densified shape. It also determines the average maplet surface normal and the standard deviation of the heights, used as a measure of uncertainty. It produces the output SHAPE file and a similar file called SIGMA.TXT that has an extra column representing the uncertainty. SIGMA.TXT can be displayed as an image to show areas that might need further work.

After it completes the commands in the file, densify gives these options:

     0. end program
     1. proceed to iteration

If you enter '0', the output shape model will be the height averaged result.

• This shows the first step in increasing the resolution of the shape model by a factor of 2. At this stage, you are only averaging the map heights to construct a higher resolution shape. If you enter ‘0’, then you skip the slope to heights integration. However, you don't want to do that. That part is already described in the example script above.

The entire script, with the output model called SHAPEX.TXT and '0' entered to the perform no iterations, looks like this:

     densify
     SHAPEFILES/SHAPE1.TXT        < input shape
     2, 1.0, 5639                 < K, search range (km), random SEED
     SHAPEFILES/SHAPEX.TXT        < output shape
     0                            < end program

If you enter '1', the program prompts:

     input fraction

Enter the fraction of averaged heights (and empty heights if K<0) used to condition the integration (usually '.005').

The program prompts:

     input weight

Input the weight given to the conditioning heights (usually '.025').

The program produces an output SHAPE file and gives these options:

     0. end program
     1. more iteration
     2. change weight

The interim shape can be viewed to see whether you want to change the weight given to the conditioning heights using the procedure described below. Usually, you just continue iterating or, finally, exit the program.

By tradition, usually use:

• SHAPE0 for Q=64
• SHAPE1 for Q=128
• SHAPE2 for Q=256
• SHAPE3 for Q=512

If there have been no problems after you complete this run, at the command line enter:

     cp SHAPEFILES/SHAPEX.TXT SHAPEFILES/SHAPE2.TXT

After another densification, when SHAPEX.TXT is Q=512, at the command line enter:

     cp SHAPEFILES/SHAPEX.TXT SHAPEFILES/SHAPE3.TXT

SHAPE.TXT is also Q=512 and you need to update that as well.

• For historical reasons, some scripts change permissions on SHAPE.TXT to read only.

At the command line enter:

     chmod +w SHAPE.TXT
     cp SHAPEFILES/SHAPEX.TXT SHAPEFILES/SHAPE.TXT

Interactive

If you want to run densify interactively, the initial inputs are:

• the input SHAPE file
• the output SHAPE file
• scaling factor K (usually 2), limit (in km) , random seed (large integer)

  This random seed is superseded if you enter one on the command line after you invoke densify.

densify will then prompt you for the remaining inputs and iterations.

(Compiled by TC)

CategoryPrograms

densifyA

Description

This program is used to increase the resolution of a shape model using albedo between landmarks.

The spatial resolution of the shape model will not increase. Adding albedo information allows for a better correlation between the shape model and landmark maps, especially when creating new landmarks.

densifyA is identical to densify except that it uses albedo.

densifyA first constructs a reference surface by interpolating the surface points of a lower resolution shape model. At each point of the reference, there is a vector V0 from the model center to that point and a normal N0 to the surface. That normal is extended some distance until it pierces one or more of the ensemble of maplets, and the average A of those distances is taken to represent the piercing point on the new model's surface. The new surface vector is V = V0 + A*N0.

The picture below is a visual representation of the paragraph above.

                ___...-------...___
                   |           |
                   |           |A*N0
             ______|___________|_________ reference
                   \          /
                    \        / V0
                     \      /

The new surface vector V will differ from V0 more noticeably when tiling at lower resolution because there are mismatches in maplet locations simply due to the formal uncertainties of the estimation process. Therefore, we have found it better to average the maplet normals N at each point, keeping a small randomly selected set of the A as conditioning heights.

Required Files

• LMRKLIST.TXT - List of all landmarks to be used

• LMKFILES/ - Directory of .LMK files for each maplet

• MAPFILES/ - Directory of .MAP files

• SHAPEFILES/ - Directory of built shapes

Optional Files

• LMRKLISTR.TXT - Specific list of landmarks desired

Output Files

• SIGMA.TXT - list of sigma values associated with the shape model (found in SHAPEFILES/)

• Shape file in ICQ format

Using densifyA

Although densifyA can be run interactively, the input commands are usually prearranged in a file (e.g., "tmpRun.txt") and you invoke the program from the command line like this:

~/bin/densify < tmpRun.txt

Here is an annotated sample "tmpRun.txt" file showing the input commands:

SHAPEFILES/PreviousShapeFile       (input shape)
2 100 1.67773                      (K (power of 2), search range (km), random seed)
SHAPEFILES/CurrentShapeFile        (output shape)
1                                  (more iteration)
.005                               (fraction of points used for conditioning)
.025                               (conditioning weight)
1                                  (more iterations)
1
1
1
1
1
1
1
1
1
1
1
1
1
0                                  (end program)

The input commands are:

• line 1 - The input SHAPE file

• line 2 - A multiplicative scaling factor K (usually 2), a limit (in km) specifying how far along the surface normal the program should search for a maplet, a random seed in the form of a large integer

  • This random seed is superseded if you enter one on the command line after you invoke densify.

• line 3 - The output SHAPE file

• line 4 - 1 = an iteration

• line 5 - The fraction of points used for conditioning (usually .005)

• line 6 - The conditioning weight

• line 7 ... - 1 = an iteration (as many as you need)

• last line - 0 = end program

In most cases, the maplets will cover most of the surface. Where it is not covered, the normals to the input model provide the "slopes" and the integration proceeds without any randomly chosen conditioning heights from these areas.

In some cases, such as fast flybys of small bodies, only a small fraction of the surface is visible and vast areas are unknown. In these cases, conditioning heights are also taken from the input model as well. Specify this option by using a negative value for K (usually -2).

densifyA then determines the average height along each surface normal from each reference point of the densified shape. It also determines the average maplet surface normal and the average albedo from the maplets. It produces the output SHAPEA file in the standard ICQ format with an extra column for albedo.

After it completes the commands in the file, densifyA gives these options:

     0. end program
     1. proceed to iteration

If you enter '0', the output shape model will be the height averaged result.

The entire script, with the output model called SHAPEX.TXT, looks like this:

     densify
     SHAPEFILES/SHAPE1.TXT        < input shape
     2, 1.0, 5639                 < K, search range (km), random SEED
     SHAPEFILES/SHAPEX.TXT        < output shape
     0                            < end program

If you enter '1', the program prompts:

     input fraction

Enter the fraction of averaged heights (and empty heights if K<0) used to condition the integration (usually '.005').

The program prompts:

     input weight

Input the weight given to the conditioning heights (usually '.025').

The program produces an output SHAPE file and gives these options:

     0. end program
     1. more iteration
     2. change weight

The interim shape can be viewed to see whether you want to change the weight given to the conditioning heights using the procedure described below. Usually, you just continue iterating or, finally, exit the program.

By tradition, usually use:

• SHAPE0 for Q=64
• SHAPE1 for Q=128
• SHAPE2 for Q=256
• SHAPE3 for Q=512

If there have been no problems after you complete this run, at the command line enter:

     cp SHAPEFILES/SHAPEX.TXT SHAPEFILES/SHAPE2.TXT

After another densification, when SHAPEX.TXT is Q=512, at the command line enter:

     cp SHAPEFILES/SHAPEX.TXT SHAPEFILES/SHAPE3.TXT

SHAPE.TXT is also Q=512 and you need to update that as well.

• For historical reasons, some scripts change permissions on SHAPE.TXT to read only.

At the command line enter:

     chmod +w SHAPE.TXT
     cp SHAPEFILES/SHAPEX.TXT SHAPEFILES/SHAPE.TXT

Interactive

If you want to run densifyA interactively, the initial inputs are:

• the input SHAPE file
• the output SHAPE file
• scaling factor K (usually 2), limit (in km) , random seed (large integer)

  This random seed is superseded if you enter one on the command line after you invoke densify.

densifyA will then prompt you for the remaining inputs and iterations.

(Compiled by TC)

CategoryPrograms