Scope

autoregisterP

Category B

Version 3.0

Description

This program registers existing maplets with imaging data from a single image using parallel processing (sequential image processing on a number of core processors).

Like autoregister, autoregisterP

adds landmarks to a single image, adding the image name to all relevant LMKFILEs
provides basic tools for aligning the landmarks, cross-correlating new images to existing maplets, eliminating landmarks and setting image flags
updates the S/C position and pointing in the SUMFILE

autoregisterP is similar to register, but can handle 3 degrees of freedom, orientation, and twist.

autoregisterP is almost always run in a parallel batch mode, following a script set up by make_scriptAP. It uses lockout files to prevent two processes from reading or writing to a landmark file at the same time.

autoregisterP aligns existing maplets with imaging data from a single image and uses subroutine IPL2SCOBJPTG to update the camera pointing and spacecraft-object vector in the corresponding SUMFILE.

$/!\$ autoregisterP uses the file LMRKLISTX.TXT to prescreen the maplets. If you have added or deleted maplets recently, you should run make_lmrklistX.

Required Files

IMAGEFILES/ - a directory containing the image .DAT files
SUMFILES/ - a directory containing the image .SUM files (updated solution image, S/C and camera information, lmrks and limbs)
MAPFILES/ - a directory containing the full suite of maplets
LMKFILES/ - a directory containing the full suite of landmarks
LMRKLIST.TXT - a list of the landmarks contained in the solution
LMRKLISTX.TXT - landmark information (size, scale, position vector, number of images containing the lmrk)

Optional Files

make_scriptA.seed - for batch processing using make_scriptAP

Output Files

SUMFILES/ - Landmarks are added to the image's SUMFILE. Spacecraft/camera position/attitude are updated once you accept the alignment shifts.
LMKFILES/ - LMKFILES are updated to contain the image you are working with.
LMRK_DISPLAY1.pgm - - 100x100 pixel display of images (odd rows) and maplets (even rows). Unlike lithos, each pair is a separate landmark consisting of a completely different location on the surface and image.
TEMPFILE.pgm - A pgm image of the image that you are working with.

User Warnings

$/!\$ autoregisterP uses the file LMRKLISTX.TXT to prescreen the maplets. If you have added or deleted maplets recently, you should run make_lmrklistX.
$/!\$ When landmarks are added in autoregisterP, they immediately populate the image’s SUMFILE. Further processing must be conducted if you wish to remove the image from any of the landmarks. This is different from lithos where images are not added to landmarks until the landmark file is updated.
$/!\$ Alignment changes are immediately accepted (i.e., there is no save/revert option).
$/!\$ Some Main Menu options are only available in interactive mode and are therefore not used when running autoregisterP.

Using autoregisterP

Initial Inputs

The following shows the initial inputs necessary to get to the Main Menu:

 input 12-character picture name. q to quit.

P3T11S2H0409
    1     EE0001 *
    2     EE0002 *
    3     EE0003 *
    4     EE0004 *
    5     EE0005 *
    6     EE0006 *

 gc TEMPFILE.pgm
 kb =            1      kk =            1

 Add landmarks? (y/n)
y

 enter fractional width (0=center)
.5
 Reject invisibles? (y/n)
n

    7   EE0007    0.00
    8   EE0008    0.00
    9   EE0009    0.00
   10   EE0010    0.00
   11   EE0011    0.00
   12   EE0012    0.00
   13   EE0013    0.00
   14   EE0014    0.00
   15   EE0015    0.00
   16   EE0016    0.00

Enter a 2-character USR name to distinguish between processes.
Enter the 12-character picture name. The program produces a list of existing landmarks, if any, creates the TEMPFILE.pgm and displays the kb, and kk values.
If you wish to add more landmarks, respond 'y'. An initial filter for added images is set in INIT_LITHOS.TXT:
- RESLM - the maximum ratio of the image resolution to the maplet scale
- SIZLM - the maximum ratio of the linear maplet size to the image size
- NUMLM - sets the minimum number of maplets found in the image before the other two filters come into play
Input the value for Fractional width. Normally this is '0.5'. This value allows images that overlap any part of a window that is half the size of the maplet window.
If you enter '0.0', the image must contain the landmark center.
Typically, enter 'n' for Reject invisibles? unless the object is bizarre, such as Eros.
If you respond 'y', the program uses the current shape to determine whether there is topography blocking the camera's view of the landmark center.
$/!\$ When landmarks are added in autoregisterP, they immediately populate the image’s SUMFILE. Further processing must be conducted if you wish to remove the image from any of the landmarks. This is different from lithos where images are not added to landmarks until the landmark file is updated.

After you respond to these initial inputs, the Main Menu will open.

autoregisterP Main Menu

 ...     MAIN MENU     ...

 0. Exit

 REMOVE MAPLETS
 a. Auto remove
 n. Auto remove new only
 m. Manual remove                   <- only in interactive mode
 p. Check peripheral visibility
 o. Remove low-correlation lmks

 IMAGE/MAPLET ALIGNMENT
 1. Auto align
 2. Manual align                    <- only in interactive mode

 LANDMARK ADJUSTMENTS
 3. Repredict px/ln
 4. Change flags
 l. Change repredict limit          <- only in interactive mode

autoregisterP is otherwise identical to autoregister. Refer to autoregister for detailed information and samples.

$/!\$ Some Main Menu options are only available in interactive mode and are therefore not used when running autoregisterP.

(Compiled by DL)

Based on SPOC v3.02A PDF/LITHOSPHERE/AUTOREGISTERP.f File Reference

bigmap

Category B

Version 3.0

Description

This procedure creates a large topographical/albedo map with the same file structure as a maplet.

The location of the map center is specified by one of three choices:

p - pixel/line location in a picture
l - latitude and west longitude
m - pixel line location in a bigmap or maplet

A second set of inputs contains:

the bigmap scale in km/px
the half-size (qsz)
an integer random seed
a maximum maplet scale in case lower resolution maplets are to be excluded

The program first determines the body-fixed vector to the map center and the approximate surface normal vector (Uz). It then projects the shape model onto this surface and determines a second approximation of Uz by fitting a plane to the heights. It repeats this process one more time. The new map coordinate frame is then oriented so that East is to the right.

The program checks to see if any these files exist:

BIGMAP.IN
LMRKLISTR.TXT
LMRKLIST.TXT

It takes the maplets to be used from the first of these files that it finds.

If you include the line 'LMKLX=.TRUE.' in INIT_LITHOS.TXT, bigmap will read LMRKLISTX.TXT. This will speed up the program by determining which maplets will be used without opening their .LMK files.

The bigmap reference plane has (2*qsz+1)^2 points at locations:

p(i,j) = V + j*Ux +i*Uy   (i,j = -qsz,qsz)

A line from each of these points in the normal (Uz) direction will pierce a number of maplets. For each i,j the program keeps track of:

the weighted accumulation of the heights to the piercing points
the squares of those heights
the slopes and albedos of the maplets at the piercing points

Once these arrays are filled, bigmap computes the average heights and albedos at each point of the reference plane, as well as the standard deviation of the heights. This provides a convenient measure of the height uncertainty at each point. Displaying SIGMAS.pgm provides a quick means of identifying possible problem areas, as depicted in Figure 00.

Required Files

LMKFILES/ - Directory of .LMK files for each maplet.
LMRKLIST.TXT - Required. List of landmarks.
MAPFILES/ - Directory of .MAP files.
SHAPEFILES/ - Directory of built shapes.
BIGFILES/ - Directory of .LMK files for each of the required bigmaps. This directory must be created, but changes are made within.
SUMFILES/ - Info about the maplets.
Many files must be unique. All directories can be linked to a master.

Optional Files

BIGMAP.IN - A list of landmarks that you want to use for bigmap. This file allows you to reduce the number of files and avoid low resolution maps.
LMRKLIST.TXT - This also restricts the list of LANDMARKS, but this is used by more programs than just BIGMAP.
If neither of these files exists, the program will build the list of LANDMARKS based on the coverage.

Output Files

INSIDE.TXT - The maplets that fall completely within the planned bigmap. Created by bigmap.
USED_MAPS.TXT - All the maps used to create the bigmap.
BIGLIST.TXT - List of needed mapfiles (bigmaps) used to construct the working bigmap.
USED_PICS.TXT - List of all pictures used in the creation of most recent bigmap.
bigmap - The name is based on the input (e.g., ZN0208.IN).
slope.pgm - Image that shows the slope in both horizontal and vertical. This is useful for debugging and to provide a general idea of how the landmark is developing.
SIGMAS.TXT - Each time BIGMAP is run, it adds a line to this file showing the current sigma values.
SIGMAS.pgm - Graphically shows the highest level of error (sigma) for maplets (see Figure 00).

Using bigmap

The input for bigmap consists of a long set of commands that are usually contained within a file.

$/!\$ Longitude is in west longitude. You must use a negative to match what is used in spheremapB.
$/!\$ The location of bigmap depends on your server. The default location is /usr/local/bin

Here is a sample input for bigmap:

 ~/bin/bigmap < ZN0208.IN

The following sample shows the normal format for the input file with some explanatory comments.

l   (select location, 1 is lat/lon)
    20    -40    (latitude, west longitude)
   0.06250       500   1.23400   1000  (scale, qsz (number of pixels), seed, max maplet res) 
ZN0208           (filename)
1                (end or integrate, 1 is integrate) <--- here begins the slope to heights integration 
.005             (input fraction)                   <--- fraction of points as seed heights in slope to height integration
.025             (input weight)
1                (end, continue, or change weight, 1 is continue integrating)
1                (end, continue, or change weight, 1 is continue integrating)
1                (end, continue, or change weight, 1 is continue integrating)
1                (end, continue, or change weight, 1 is continue integrating)
1                (end, continue, or change weight, 1 is continue integrating)
1                (end, continue, or change weight, 1 is continue integrating)
1                (end, continue, or change weight, 1 is continue integrating)
0                (end, continue, or change weight, 0 is end iteration)
0                (no, square, or round template, 0 is No Template)

Here is a sample of sigmas.pgm:

Figure 00: Output of SIGMAS Graphical Format

(Compiled by TC)

bigmapL

Category B

Version 3.0

Description

This program is a "light" version of bigmap. It's designed to be run in parallel to make many bigmaps at once with the script maker MAKE_TILESP.

bigmapL is primarily used in the production of ZMAPS. ZMAPS is just a convention used to sub-divide a global surface into 5° bins.

For more detailed information, see bigmap.

(Compiled by TC)

blemishes

Category B

Version 3.0

Description

This program generates BLEMISH files which mask bad pixels in individual or multiple images.

This procedure creates a blemish (.BLM) file for an image that lives in the BLEMISHES subdirectory.

Required Files

BLEMISHES/ - Directory containing BLEMISH files for individual images and BLEMISH templates for multiple affected images.
IMAGEFILES/ - Directory containing the .DAT file for the image; this program displays the image with masking for user inspection, and reads the Digital Number (DN) of pixels of interest.
SUMFILES/ - Directory containing the SUMFILE for the image to mask; this program reads NPX (number of pixels), and NLN (number of lines);
INIT_LITHOS.TXT - this program reads the parameter BLEMISH (if it exists), which references any existing template for masking bad pixels common to multiple images.
- BLEMISHES/TEMPLATENAME.BLM - template BLEMISH file for each INIT_LITHOS BLEMISH entry.

Optional Files

BLEMISH/PICNM.BLM - Existing image BLEMISH file for deletion or editing.

Output Files

TEMPFILE.pgm - Display of the image with masking applied.
BLEMISHES/PICNAME.BLM - Generated or edited BLEMISH (.BLM) file.

User Warnings

$/!\$ If the PICNM used to make the original blemish file is not consistent with the template, the program will say so and it will STOP. Otherwise, it will create the template file and, if necessary, remind you to define it in INIT_LITHOS.TXT.

Using blemishes

Initial Inputs

 Input 12-character picture name
P00045000455
 gc TEMPFILE.pgm

 b. Block
 s. Spot
 q. Quit

Choose the option for the type of blemish you want to work with:

The b. Block option masks a square block of the image specified by a minimum and maximum pixel and line. This type of blemish is typically used for missing or hashy lines due to downlink errors.

The s. Spot option masks a small region around a pixel/line center (p,l) from p-k to p+k and l-k to l+k. An additional input is a brightness threshold (Note: See below for threshold information). If you enter this as zero, everything in the spot will be masked. However, if there is a bright blemish such as a cosmic ray hit in the spot, you can set the threshold to remove only the affected pixels. In this case, you can specify a large region (large k) and all the bright blemishes in that region will be masked without affecting the rest of the data.

Here is a sample TEMPFILE.pgm image before masking is applied:

Figure 00: Image Prior to Applying Mask

Block Blemish Options

 Input pxmn, pxmx, lnmn, lnmx
512 612 250 350
 gc TEMPFILE.pgm

 b. Block
 s. Spot
 q. Quit

After you choose b. Block you must specify:

pxmn, pxmx: must be in the range [1:NPX] (where NPX is the number of pixels in image)
lnmn, lnmx: must be in the range [1:NLN] (where NLN is the number of lines in image)

This sample shows the image after block masking was applied:

Figure 00: Image after Applying Blemish Mask

Spot Blemish Options

 Input bad px/ln center, half-size. threshold.
512 250 25 100
 gc TEMPFILE.pgm

 b. Block
 s. Spot
 q. Quit

After you choose s. Spot you must specify:

px/ln center: Vector with element values in the range ([1:NPX],[1:NLN]) (where NPX is the number of pixels in image, NLN is the number of lines in image)
half-size: Half-size of masked area in pixels, e.g. a half-size of 2 will result in a masked area of 4 pixels x 4 pixels.
threshold: Digital Number (DN) representing the lowest threshold for brightness in the range, where 0 is dark, and will result in all brightnesses being masked. Note: The DN within BLEMISHES has been rescaled by 255/(Brightness DN). So if the original DN is 398 and the max is 1410, then the new DN will be 71 because the number is truncated. So if you want to mask 398, you need to enter 70 for the threshold.

This sample shows the image with spot masking and DN threshold applied:

Figure 00: Image Displaying Blemish Mask Options

Quit Blemishes Option

 Save blemish file? (y/n)
y
 Create/change template file? (y/n)
n

After you choose q. Quit you must specify whether to save the blemish file and whether to create or change a template file.

BLEMISH Templates

In the event that a camera has bad pixels common to all images, you can create a template that masks these pixels in all that camera's images. The template is specified in the INIT_LITHOS.TXT file with the key word BLEMISH.

For example, DAWN has two framing cameras with image names starting with FC1 and FC2. FC2 images all have several blemishes in the same places. A template in INIT_LITHOS specified by BLEMISH='FC2#########' will correct all of these images without having thousands of individual blemish files. If an image contains additional blemishes it can have its own file with just those additional blemishes.

In order to create a TEMPLATE, you must create a blemish file for one of the affected images with only the common bad areas masked. The procedure will ask: 'Save blemish file? (y/n)' and then 'Create/change template file? (y/n)'. If you enter 'y' and 'y', you will be asked for a 12 character template name with the common characters of the image names in their proper positions and # everywhere else.

$/!\$ If the PICNM used to make the original blemish file is not consistent with the template, the program will say so and it will STOP. Otherwise, it will create the template file and, if necessary, remind you to define it in INIT_LITHOS.TXT.

The following samples show this sequence of actions and the output file:

 Save blemish file? (y/n)
y
 Create/change template file? (y/n)
y
 Input 12 character template
P00045######
 Add: BLEMISH='P00045######' to INIT_LITHOS.TXT

Example P00045######.BLM file:

The BLEMISH file contains a list of pixel/line locations to be masked, appended with the end-of-file identifier, 'END'.

(Compiled by DL) (Updated by JRW)

Based on SPOC v3.02A PDF/LITHOSPHERE/blemishes.f File Reference.

densify

Category B

Version 3.0

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)

densifyA

Category B

Version 3.0

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
                     \      /

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

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

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)

duplicates

Category B

Version 3.0

Description

This program writes an ordered list of unique landmark names to make_script.in, the .in file required by batch processes such as lithosP processing using make_scriptP. It also checks that the landmarks are included in LMRKLIST.TXT, and that LMKFILES and MAPFILES exist for each entry.

The duplicates program serves two functions:

First, some lists of landmarks to be processed may contain duplicate names. The files check.txt and MAPCHK.TXT produced by residuals are examples. duplicates outputs only one of each to the file make_script.in.
Second, in iterating a set of landmarks, it is believed to be more reliable to proceed from lower to higher resolution maplets. Duplicates does this ordering using the Heapsort algorithm (Numerical Recipes, p. 231) as part of the process.

The input file for duplicates is LIST.TXT, which consists of a list of landmark names followed by END as the final record. The output file make_script.in has the same form.

Required Files

LMRKLIST.TXT - Full list of landmarks, appended with 'END'.
LIST.TXT - Temporary list of the subset of landmarks which the user wishes to process appended with 'END', for sorting and removal of duplicates using this program.
LMKFILES/ - Directory containing all the LMKFILES listed in LMRKLIST.TXT.
MAPFILES/ - Directory containing all the MAPFILES for landmarks listed in LMRKLIST.TXT.

Output Files

make_script.in - the .in file required by script-makers such as make_scriptP for generating the run scripts required for batch processing.

Using duplicates

Create Input File

Create LIST.TXT, a list of landmark names for the landmarks intended for batch processing, appended with the end-of-file identifier, 'END'. See sample file below.

Run duplicates

duplicates processes landmark names as follows:

For every landmark listed in LMRKLIST.TXT, duplicates
- checks that the MAPFILE exists
- obtains the maplet's Q-size and Ground Sample Distance (GSD) from the LMKFILE
- sorts the list by decreasing GSD and increasing name (lat/wlong identifier and numeric identifier)
- discards duplicate entries
For every landmark listed in LIST.TXT, duplicates
- checks that the landmark is also listed in LMRKLIST.TXT; if it is, the landmark is included in the output
duplicates writes the sub-set of ordered landmarks to make_script.in.
The LANDMARK and MAP files for the landmarks included in LMRKLIST.TXT must exist in LMKFILES/ and MAPFILES/.
duplicates only considers landmarks contained in LIST.TXT, that are also contained in LMRKLIST.TXT.

Here is a sample LMRKLIST.TXT file:

EE0001
EE0002
EE0003
EE0004
EE0005
EE0006
EE0007
EE0008
EE0009
EE0010
EF0001
EF0002
EF0003
EF0004
EF0005
EF0006
EF0007
EF0008
EF0009
EF0010
END

Here is a sample LIST.TXT file:

EF0006
EF0006
EF0006
FF0006
EE0004
FF0009
EE0007
EE0010
EE0009
EE0006
EF0010
EF0004
EE0005
EF0005
EF0008
FF0008
EE0008
FF0005
FF0010
EF0009
EF0007
FF0004
FF0007
END

$/!\$ Note that the sample LIST.TXT contains a disordered list of landmark names and many duplicate entries. Also, the FF* landmarks are not included in the sample LMRKLIST.TXT and the sample LIST.TXT does not include any landmarks ending in 1, 2, or 3. (This scenario is included for illustrative purposes only.)

Here is a sample make_script.in file generated using duplicates:

EE0004
EE0005
EE0006
EE0007
EE0008
EE0009
EE0010
EF0004
EF0005
EF0006
EF0007
EF0008
EF0009
EF0010
END

(Compiled by DL)

dynamics

Category B

Version 3.0

Description

This program augments the nominals file by appending the nominal inertial space position differences between the current image and up to four images before and after. This information is used to constrain the solution so that the spacecraft position solution does not deviate too much from a dynamically realistic state. This program also allows for different mission phases to have different "sigmas" via DYNAMICS.TXT.

In version 3.1, the number of images that is used before/after is set in INIT_LITHOS.TXT with keyword DYNO.

Dynamics will useINIT_LITHOS.TXT to set the parameters for SPICE. This is set with keyword PCK. Typically, we set the leap second kernel and the PCK.

If you want to have these the images before/after impact the location of the spacecraft, then the PICWTS option 5 (WT) must be set to 1 (or a non-zero value) in INIT_LITHOS.TXT

Required Files

Output Files

Updated NOMINALS file

Using dynamics

Input for the program in DYNAMICS.TXT includes values for 3 parameters and lists of nominals to which they apply. For additional information, see DYNAMICS.TXT.

The following sample is based on excerpts from a DYNAMICS.TXT file for DAWN at Vesta:

FRAME='BOD_FRAME' APPROACH
ETLM=  1800, 1.D-6
VSIG= 0.200, 0.200, 0.200
PSIG= 0.0001, 0.0001, 0.0001
 F11A0001225
 F11A0001241
 ...
 F21A0003895
 F21A0003910
 
FRAME='dxR_FRAME' SURVEY
ETLM=  1800, 1.D-6
VSIG= 0.100, 0.100, 0.040
PSIG= 0.0001, 0.0001, 0.0001
 F21A0003931
 F21A0003932
 ...
 F21A0032347
 F21A0032348
END

A typical ETLIM= record is:

ETLM=  1800, 1.D-6

ETLIM= gives a maximum time difference in seconds that limits the neighboring images to be used. The images that are included in dynamics are limited by both this number, as well as number of images. Dynamics will stop including images when either of these limits are reached. The second number in ETLM is an estimate of the velocity uncertainty that goes into an uncertainty estimate included in the added records. This velocity uncertainty is used to determine the sigma in position associated with dynamics. A typical value is 1 mm/s; the same as in the example. A larger value will weight the dynamics solution less, while I a smaller value will weight the dynamics solution more.

FRAME= has these three choices:

FRAME= ['dxR_FRAME', 'Dxr_FRAME', 'BOD_FRAME']

FRAME= specifies how to interpret the sigmas in spacecraft position found in the nominals file.

dxR_FRAME uses the radial direction (R) as prime for the third component with the second component being the cross track direction (X) and the first component, roughly in the downtrack direction completing the right-handed coordinate system. This is used in orbital operations around large bodies, where the radial component is well known from the Doppler data.
Dxr_FRAME is used during approach where the downtrack velocity is best known. The "radial" (impact parameter) direction is crossed with the downtrack to give the crosstrack direction.
BOD_FRAME simply uses the components in the body-fixed frame, generally with equal uncertainties in each direction.

The VSIG= record has three components:

VSIG= 0.100, 0.100, 0.040

VSIG= allows the user to change the position sigmas from those in the original nominals file. The record in the sample, sets the uncertainties in the three components to 100 m, 100 m and 40 m respectively. If, during another mission phase, these sigmas change, another VSIG= record would be added to affect subsequent nominals files.

The PSIG= record has three components:

PSIG= 0.0003, 0.0003, 0.0005

PSIG= allows the user to change the pointing sigmas in the nominal files, which are in rad. The three components refer to rotations about the three camera axes. The sample shows the approximate values expected for OSIRIS_REx with a larger twist uncertainty since there is only one star tracker.

(Compiled by TC)

Export and Import

Category B

Version 3.0

These two programs will allow you to export landmarks from multiple machines, which can then be added to another machine. Instead of merging two or more datasets, you can achieve a similar result by adding all landmarks to a "main" or "head" machine.

While this is useful for combining data from multiple users, it was originally intended to allow a user to tile an object/bigmap simultaneously on multiple machines and then combine the results onto a single machine. Hence it uses LMRKLIST1.TXT, which is a list of newly added landmarks.

User Warnings

$/!\$ You must ensure that LMRKLIST1.TXT only has the recently created landmarks (i.e., contains only the LMKs you wish to export and import into a new model). If LMRKLIST1.TXT has other LMKs you don't wish to bring into a different model, remove them from the top of the LMRKLIST1.TXT.
$/!\$ You should also ensure that there aren't any maplets or landmarks remaining in NEW_FILES. If NEW_FILES does not exist, you must create NEW_FILES, as well as NEW_FILES/LMKFILES and NEW_FILES/MAPFILES.
$/!\$ The imported landmarks will be renamed based upon region! This renaming procedure ensures that no existing landmarks will be overwritten. It also means you may end up with duplicate landmarks if you didn't make sure to exclude them when you created LMRKLIST1.TXT.

Export

Required Files

MAPFILES/ - a directory containing the full suite of maplets
LMKFILES/ - a directory containing the full suite of landmarks
LMRKLIST1.TXT - a list of the new landmarks

Output Files

EXPORT.TXT - Script that will execute the EXPORT.B script and clean up the previous version of NEW_FILES
EXPORT.B - Script that will cp new maplet and landmark files to NEW_FILE

Using Export

To run export, you must generate a script that will copy the new landmarks and put them into a tar ball.

Make EXPORT.B and the script EXPORT.TXT. Note that EXPORT.TXT will run the script EXPORT.B.
$/!\$ You must ensure that LMRKLIST1.TXT only has the recently created landmarks. If it has older ones, trim the top of the file.
$/!\$ You should also ensure that there aren't any maplets or landmarks remaining in NEW_FILES. If NEW_FILES does not exist, you must create NEW_FILES, as well as NEW_FILES/LMKFILES and NEW_FILES/MAPFILES.
Enter the following at the command line:

mkdir -p NEW_FILES
mkdir -p NEW_FILES/LMKFILES
mkdir -p NEW_FILES/MAPFILES
/usr/local/bin/EXPORT

This will populate NEW_FILES with copies of the newly created mapfiles and landmarks.

The script EXPORT.TXT looks this:

 cp LMRKLIST1.TXT NEW_FILES/LMRKLIST.TXT
 cd NEW_FILES/LMKFILES
 rm -f *.LMK
 cd ../..
 cd NEW_FILES/MAPFILES
 rm -f *.MAP
 cd ../..
 chmod +x EXPORT.b
 ./EXPORT.b
 tar -cf NEW_FILES.tar NEW_FILES
 rm -f LMRKLIST1.TXT

Run this script by entering the following at the command line:

sh EXPORT.TXT

Change the name of NEW_FILES.tar to something distinctive like
- new_<bigmapName>.tar
Transfer the tar file to the other computer.

Import

Required Files

NEW_FILES/LMRKLIST.TXT - List of new landmarks
NEW_FILES/MAPILES/ - a directory containing the new maplets
NEW_FILES/LMKFILES/ - a directory containing the new landmarks

Output Files

MAPFILES/ - a directory containing the full suite of maplets
LMKFILES/ - a directory containing the full suite of landmarks
LMRKLIST.TXT - updated landmark list
NEWLIST.TXT - list of new landmarks with the new name

Using Import

1. Untar to recover NEW_FILES directory.

If you didn't rename the tar file, from the working directory type the following at the command line:

tar -xvf NEW_FILES.TAR

This will create the directory NEW_FILE if it doesn't already exist. If you are concerned about overwriting data in the current directory, use "tar" to check the location the data will be written to.

2. Once you have confirmed that you will be writing to an empty directory, type the following at the command line of the working directory:

/usr/local/bin/IMPORT

This will import the new landmarks.
$/!\$ The imported landmarks will be renamed based upon region! This renaming procedure ensures that no existing landmarks will be overwritten. It also means you may end up with duplicate landmarks if you didn't make sure to exclude them when you created LMRKLIST1.TXT.

3. Import will update and move all the files to be integrated into the SPC working directory. However, it needs an iteration to run the renaming portion and connect the overlaps with the existing maplets.

cp NEWLIST.TXT make_script.in

For make_scriptF.seed use:

n
n
g
u
1
o
RECENT
n
1
q
END

Copy into window:

./rem_script.b
rm -f ./TESTFILES/*
rm -f ./TESTFILES1/*
make_scriptF
sh ./run_script.b &

Check progress with:

find_nofit

(Modified by JRW from text written by EEP)

find_nofit

Category B

Version 3.0

Description

This program searches batch processing output files to identify landmarks or images which may need further work.

find_nofit is a useful utility for identifying landmarks which may require further work following batch processing tasks such as those that use make_scriptF or make_scriptR.

Required Files

make_script.in - input file for batch processes such as make_scriptF, make_scriptR, make_scriptA or make_scriptAP.
Either:
- <LMRKNM>.OOT files - output by a batch process such as make_scriptF.
Or:
- <PICNM>.OOT files - output by a batch process such as make_scriptR, make_scriptA or make_scriptAP.

Output Files

Either:

redo.txt - list of landmarks that
- terminated in error
- do not correlate with at least one image, OR
- correlate weakly with at least one image

Or:

REMOVED.TXT - list of landmarks that have been eliminated from at least one image due to low or no correlation.

Using find_nofit

The batch processes initiated by make_scriptF, make_scriptR, make_scriptA and make_scriptAP produce output files <LMKNM>.OOT or <PICNM>.OOT. These are basically listings of the outputs of procedures lithos, register, autoregister and autoregisterP respectively for each input landmark or image. find_nofit looks through these output files for each landmark or picture listed in the make_script.in file to identify landmarks or images that may need further work.

For lithos

If the entries in the make_script.in file are landmarks (make_script.in for lithos runs), the find_nofit procedure identifies:

!  cat <LMKNM>.OOT - process still running or terminated in error.
*  cat <LMKNM>.OOT - maplets not correlating with at least one image.
+  cat <LMKNM>.OOT - maplets correlating weakly with at least one image.
.  cat <LMKNM>.OOT - no correlation for at least one overlap.
   cat <LMKNM>.OOT - low correlation for at least one overlap.

The cat <LMKNM>.OOT produces a listing of the output file for more complete diagnostics. The program also produces a redo.txt file listing those landmarks that failed one of the first three tests. The limit for weak correlation is set by the 'NOFIT=' keyword in INIT_LITHOS.TXT.

For register

If the entries in the make_script.in file are images (make_script.in for register, autoregister and autoregisterP runs), the find_nofit procedure identifies:

.  cat <PICNM>.OOT  image not correlating with at least one maplet.

The cat <PICNM>.OOT will produce a listing of the output file for more complete diagnostics. The program also produces a REMOVED.TXT file listing those landmarks that were eliminated from one of the images for low or no correlation.

Here is an annotated sample output from find_nofit:

*  cat EE0017.OOT              <- maplets not correlating with at least one image
   cat EE0019.OOT              <- low correlation for at least one overlap
   cat EE0022.OOT
.  cat EE0027.OOT              <- no correlation for at least one overlap
+  cat EE0034.OOT              <- maplets correlating weakly with at least one image
*  cat EE0042.OOT
*  cat EE0044.OOT
+  cat EE0045.OOT
!  cat EE0051.OOT              <- process still running or terminated in error
!  cat EE0053.OOT
+  cat EE0054.OOT
   cat EE0055.OOT
!  cat EE0063.OOT
   cat EE0067.OOT
   cat EE0069.OOT
   cat EE0081.OOT

Here is an annotated sample redo.txt file from find_nofit:

* EE0017              <- maplets not correlating with at least one image
+ EE0034              <- maplets correlating weakly with at least one image
* EE0042
* EE0044
+ EE0045
EE0051                <- process still running or terminated in error
EE0053
+ EE0054
EE0063
END

Here is an annotated sample REMOVED.TXT file from find_nofit:

AA0001                <- maplet eliminated from an image for low or no correlation
AF0023

(Compiled by DL)

find_nofitP

Category B

Version 3.0

Description

This program searches batch processing output files to identify landmarks or images which may need further work.

find_nofitP is a useful utility for identifying landmarks which may require further work following the batch iteration task set up using make_scriptP.

Required Files

make_script.in - input file for batch processing using make_scriptP
<LMKNM>.OOT files - lithosP standard output listings

Output Files

redo.txt - list of landmarks that
- terminated in error
- do not correlate with at least one image, OR
- correlate weakly with at least one image.

Using find_nofitP

The batch process initiated by make_scriptP produces output file <LMKNM>.OOT that contains listings of the lithosP standard outputs for each input landmark. find_nofitP searches the <LMKNM>.OOT files for each landmark listed in make_script.in to identify landmarks which may need further work.

$/!\$ See find_nofit to identify the flags thrown by find_nofitP.

The command 'cat <LMKNM>.OOT' provides a listing of the output file for more complete diagnostics. find_nofitP also produces a redo.txt file that lists those landmarks that failed one of the first three tests.

The limit for weak correlation is set by the 'NOFIT=' keyword in INIT_LITHOS.TXT. The limit for weak correlation is fixed by the display from the CORRELATE subroutine in LITHOSP at either

0.43 (~3/7) if NOFIT>0.35, OR
0.28 (~2/7) otherwise

Here is an annotated sample output from find_nofitP:

! cat EE0004.OOT       <- process still running or terminated in error
  cat EE0005.OOT       <- low correlation for at least one overlap
. cat EE0006.OOT       <- no correlation for at least one overlap 
  cat EE0007.OOT 
* cat EE0008.OOT       <- maplets not correlating with at least one image 
* cat EE0009.OOT 
. cat EE0010.OOT 
* cat EE0011.OOT 
  cat EE0013.OOT 
  cat EE0017.OOT 
! cat EE0022.OOT

Here is an annotated sample redo.txt file from find_nofitP:

EE0004                <- process still running or terminated in error
* EE0008              <- maplets not correlating with at least one image
* EE0009
* EE0011
EE0022
END

Compiled by KD CategoryPrograms

find_nofitT

Category B

Version 3.0

Description

This program searches batch processing output files to identify landmarks or images which may need further work.

find_nofitT is a useful utility for identifying landmarks which may require further work following the batch tiling task set up using make_scriptT.

Required Files

<NNN>.OOT files - lithos standard output listings

Output Files

NEW_LIST.TXT - List of new landmarks generated during the tiling process.

Using find_nofitT

The batch process initiated by make_scriptT produces output file <NNN>.OOT that contains listings of the outputs of procedure lithos for each created landmark during a tiling run. find_nofitT looks through these output files to find places where the landmarks or images may need further work. During tiling, each new landmark is given a 6-character name <LMKNM>. The original landmark designation is a three-digit number <NNN>.

The find_nofitT procedure identifies:

 <NNN> ! cat <NNN>.OOT:    process still running or terminated in error.
 <NNN> deleted:          insufficient data to create a maplet at that point.
 <LMKNM> * cat <NNN>.OOT:  maplet correlating weakly or not at all with at least one image.
 <LMKNM>   cat <NNN>.OOT:  low or no correlation for at least one overlap.

The command 'cat <NNN>.OOT' provides a listing of the output file for more complete diagnostics. The surviving landmark names are included at the beginning of the output to make re-processing easier.

The limit for weak correlation is set by the 'NOFIT=' keyword in INIT_LITHOS.TXT.

Here is an annotated sample output from find_nofitT:

EQ0004:   cat 004.OOT              <- low or no correlation for at least one overlap
EP0002:   cat 005.OOT 
EP0003:   cat 006.OOT 
EO0003:   cat 007.OOT 
EN0003: * cat 008.OOT              <- maplet correlating weakly or not at all with at least one image
EN0004: * cat 009.OOT 
010 deleted
   !  cat 010.OOT                  <- insufficient data to create a maplet at that point
EM0003:   cat 011.OOT 
EM0004: * cat 012.OOT

Here is a sample NEW_LIST.TXT from find_nofitT:

EP0001
EP0002
EP0003
EP0004
EQ0001
EQ0002
EQ0003
EQ0004
END

(Compiled by KD)

geometry

Category B

Version 3.0

BACK UP YOUR WORK BEFORE RUNNING GEOMETRY!

Description

This program makes a surface by solving for the spacecraft position, spacecraft pointing, and landmark locations. This procedure iterates the solutions for camera pointing and landmark vectors sequentially.

Required Files

LMKFILES/ - A directory containing the full suite of landmarks.
PICTLIST.TXT - A list of picture names generated by make_sumfiles.
LMRKLIST.TXT - A list of the landmarks contained in the solution.
LMRKLIST1.TXT - A file containing default values to be read in by SPC toolkit.
MAPFILES/ - A directory containing the full suite of maplets.
INIT_LITHOS.TXT - A text file setting limits, definitions, and logicals for SPC.
SHAPE.TXT - The shape model stored in directory SHAPEFILES/.
NOMINALS/ - A directory containing the image .NOM files.
SUMFILES/ - A directory containing the image .SUM files (updated solution image, S/C and camera information; lmrks and limbs).

Output Files

SUMFILES/ - Landmarks are added to the image's SUMFILE. Spacecraft/camera position/attitude are updated upon user acceptance of alignment shifts.
LMKFILES/ - Directory LMKFILES/ is updated to contain the image the user is working with.
MAPFILES/ - This directory is also updated because the landmark vector in the header of the MAPFILE is also updated

Optional Files

PICTLISTS.TXT - User-generated list of picture names. $/!\$ geometry will only use this file instead of PICTLIST.TXT if you specify it in INIT_LITHOS.TXT with GEOPIC='PICTLISTS.TXT'.
LMRKLISTR.TXT - User-generated restricted list of landmark names. $/!\$ geometry will only use this file instead of LMRKLIST.TXT if you specify it in INIT_LITHOS.TXT with GEOMAP='LMRKLISTR.TXT'.

User Warning

ALWAYS BACK UP YOUR WORK BEFORE USING GEOMETRY.

Using geometry

The inputs for geometry are:

input operation list - Use these values:
- 1: landmark vectors.
- 2: camera pointing, scobj
- 0: end.
enter number of iterations - Input desired number. use limbs for pointing? (y/n) - Choose whether to use limbs in determining camera pointing. continue? (y/n) - Choose whether to do it all over again.

Here are two annotated samples that show geometry inputs:

 GEOMETRY
 120<- do 1 followed by 2
 30 <- do them 30 times
 y  <- use limbs for pointing
 n  <- stop when done

 GEOMETRY
 20 <- do 2 only
 10 <- do it 10 times
 n  <- don't use limbs for pointing
 n  <- stop when done

The default is to do these operations for all landmarks in LMRKLIST.TXT and all images in PICTLIST.TXT.

If INIT_LITHOS.TXT contains a record

GEOPI='filename1'

or

GEOMAP='filename2'

then the files used are reduced. "filename1" is used instead of PICTLIST.TXT and "filename2" is used instead of LMRKLIST.TXT.

Additional Reference

Geometry Estimation Terms

Spacecraft State - Position and orientation of spacecraft affects size and location of the body in an image. Errors are reflected IN offsets of extracted image data from maplets for all maplets in the image.
Control Point Location - An error in the body-fixed control point location is reflected by offsets of extracted image data for all images containing the maplets.
Rotation - An error in the transformation from inertial to body fixed frames is reflected in time-dependent offsets in extracted image data for all maplets in all images.
Differential Stereo - Errors in the maplet heights relative to the center are reflected by differential shifts of features within the extracted image data in addition to displacements from the maplets themselves.

Figure 00: Examples of Offset and Orientation Errors

More Detailed Description of Geometry

Global solution for camera position and pointing and body-fixed maplet location.
Iterative process:
- Weighted least-squares solution of landmarks (control points) based on:
  - Position of the landmark relative to the spacecraft
  - Relative landmark-to-landmark location
  - Limb position
  - An initial starting object
- Weighted least-squares solution of camera position and pointing based on landmark location
  - Nominal camera pointing
  - Nominal camera position
  - Limb position
  - Position of the landmark relative to the spacecraft
  - The observations before and after each observation

The output covariances from one iteration become the input covariances for the next iteration so the schematic for updating sumfiles, and lmkfiles, should include the update of their uncertainties.

The typical use is a series of steps such as 120, and 3 or more iterations. Assume we created some new landmarks. The above steps mean that we first use the a priori position and pointing information to solve for the landmarks. Then, since there is some error in the a priori position and pointing inputs we use the landmarks to solve for position and pointing and so on until the corrections have converged, typically 3 iterations. However, if we are in a situation where we believe that the landmarks are correct and the camera pointing/position are incorrect then we simply run option 2 only. This is what autoregister does, when we add new images to an existing landmark database. If we are in a scenario where we believe the camera position/pointing are correct and not the landmarks then we run option 1 only.

Another consideration is the relative contribution of each constraint in the landmark/position/pointing solution via the additional weights in INIT_LITHOS.TXT, LMKWTS and PICWTS. For instance, if the shape model is too coarse for the resolution of maps we are working with, we may want to reduce the influence of the shape model as a constraint in the solution of the landmarks by reducing the value of WR in INIT_LITHOS.TXT. If we believe that the S/C state is very well known compared to the landmarks, we may want to not allow the landmarks to change the camera position much, by either using a very small position uncertainty in the nominals or in addition by reducing the value of WB in PICWTS.

Figure 00: Illustration of Iterative Process for Updating Geometry

(Compiled by TC)

lithos

Category B

Version 3.0

Description

This program aligns maplets to the current shape model and provides slight changes to the shape (stored in MAPFILES).

lithos is the key for SPC. It works on a single landmark, which defines the associated maplet. This landmark must be created (i.e., fully defined) and all the images it includes must be shifted so that everything is aligned. Once those steps are done, you can calculate the topography, which includes identifying other maps that overlap, creating a template, and then solving the whole system.

The outputs from make_scriptT and make_scriptP are used as input to lithos and lithosP for batch processing. The make_script program will create an entry for each landmark in the script.b. You will then process it as input, like this: 'lithos < LAND01.INN > LAND01.OOT'

Throughout LITHOS, you can simply hit 'Enter' for the default selection, which is usually indicted by brackets.

For instance, in the case of "Do you wish to continue? y[n]" hitting 'Enter' key will default to the 'n' selection.
When editing a seed file, a blank line will act as if the 'Enter' key was pressed at the command prompt.

Required Files

DATA/ - data specific to each mission
IMAGEFILES/ - a directory containing the image .DAT files
SUMFILES/ - a directory containing the image .SUM files (updated solution image, S/C and camera information; lmrks and limbs)
MAPFILES/ - a directory containing the full suite of maplets
LMKFILES/ - a directory containing the full suite of landmarks
BIGFILES/ - a directory containing all the bigmaps
NOMINALS/ - a directory containing the full suite of nominals
SHAPEFILES/ - a directory containing the shapemodel
LMRKLIST.TXT - a list of the landmarks contained in the solution
PICTLIST.TXT - a list of the pictures contained in the solution
- Will be used if PICTLISTX.TXT and PICTLISTRX.TXT do not exist.
BIGLIST.TXT - a list of all the bigmaps that have been created
INIT_LITHOS.TXT - file containing default values to be read in by SPC toolkit

Output Files

tmpl.pgm - Temporary pgm amp file convert by RAW2PGM
seeds.pgm - Temporary pgm amp file convert by RAW2PGM
LMRK_DISPLAY0.pgm - Temporary pgm amp file convert by RAW2PGM (See below.)
LMRK_DISPLAY1.pgm - Temporary pgm amp file convert by RAW2PGM (See below.)

Optional Files

LMRKLISTO.TXT - If present, LMRKLISTO.TXT is used to calculate overlaps instead of LMRKLIST.TXT. This action enables lithos and lithosP to run faster by searching for overlaps among a limited set of landmarks.
LMRKLISTX.TXT - Extended landmark list containing .LMK file information that speeds up processing by eliminating the need to open individual .LMK files multiple times.
PICTLISTR.TXT - User-generated restricted list of pictures for processing.
PICTLISTX.TXT - Picture information similar in concept to LMRKLISTX.TXT. This file will be used if PICTLISTRX.TXT does not exist.
PICTLISTRX.TXT - User-generated restricted extended picture list, i.e. a sub-set from PICTLISTX.TXT.

Using lithos

lithos is an interactive program that runs from a Main Menu. To access the Main Menu from anywhere within lithos, type '?' at the user prompt.

For information about each of the Main Menu options, click on its link in the Main Menu sample below:

... MAIN MENU ...
Q. Quit LITHOS
LANDMARK/MAPLET CONSTRUCTION
0. Find template
1. Align landmarks
2. Find heights
O. Attach map to maps or limbs
LANDMARK/MAPLET I/O AND CREATION
I. Input landmark
U. Update landmark files
C. Create new landmark
R. Replicate or Rename landmark
S. Change scale, qsz or orientation
G. Turn on rename
ADJUST INPUT DATA AND NOMINALS
N. Find normal
V. Find V, Z or PTG
A. Reset albedo or slopes
M. Get heights from shape model
B. Get heights from surrounding map
X. Turn on extract filter
DELETE, ELIMINATE OR IGNORE FILES
D. Delete or Disconnect landmark
E. Eliminate pictures from landmark
P. Picture status
L. Turn off picture restriction
INFORMATION AND DISPLAY
F. Find maplets containing surface point
Z. Use zoom display
H. Hide screen output

When you're using LITHOS, you can see the most recent updates in the two files that are displayed every time the Main Menu is loaded. This sample shows how those appear:

 Current landmark = EE0001
SCALE =  0.000100 QSZ =   49
 Lat/Lon/Rad =     -6.800   264.090     0.266
 Region = EE

 gc LMRK_DISPLAY0.pgm
 gc LMRK_DISPLAY1.pgm


 check display
Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH?

Below is a sample of LMRK_DISPLAY0.pgm. It displays the raw images (i.e., without brightness scaling). This image is the data used by lithos for the correlation evaluation.

width=500

Figure 00: Rarely Used Output from LMRK_DISPLAY0

Below is a sample of LMRK_DISPLAY1.pgm. It displays images with the brightness stretched to bring out features and make the images more "readable". This image is used by human operators extensively while while operating lithos.

width=500

Figure 00: Rarely Used Output from LMRK_DISPLAY1

(compiled by JRW)

Link to original one page version (renamed 1/13/16): Old_lithos_text

lithosP

Category B

Version 3.0

Description

lithosP is essentially lithos, but it is designed to be run in parallel.

$/!\$ This guide assumes that you are familiar with lithos. Some of the options found in lithos have been cut, and other options have been streamlined. Only the differences are presented here.

Required Files

IMAGEFILES/ - a directory containing the image .DAT files
SUMFILES/ - a directory containing the image .SUM files (updated solution image, S/C and camera information; lmrks and limbs)
MAPFILES/ - a directory containing the full suite of maplets
LMKFILES/ - a directory containing the full suite of landmarks
BIGFILES/ - a directory containing all the bigmaps
SHAPEFILES/ - a directory containing the shape model
TESTFILES/ - a directory containing diagnostic files output by lithosP
LMRKLIST.TXT - a list of the landmarks contained in the solution
INIT_LITHOS.TXT - file containing default values for be read in by SPC toolkit

Optional Files

LMRKLISTO.TXT - If present, LMRKLISTO.TXT is used to calculate overlaps instead of LMRKLIST.TXT. This action enables lithos and lithosP to run faster by searching for overlaps among a limited set of landmarks.
LMRKLISTX.TXT - Extended landmark list containing .LMK file information that speeds up processing by eliminating the need to open individual .LMK files multiple times.

Output Files

tmpl.pgm - Temporary pgm amp file convert by RAW2PGM
seeds.pgm - Temporary pgm amp file convert by RAW2PGM
LMRK_DISPLAY0.pgm - Temporary pgm amp file convert by RAW2PGM. See below.
LMRK_DISPLAY1.pgm - Temporary pgm amp file convert by RAW2PGM. See below.

Using lithosP

lithosP is designed to be run in parallel. The following shows the Main Menu:

... MAIN MENU ...
Q. Quit LITHOS
LANDMARK/MAPLET CONSTRUCTION
0. Find template
1. Align landmarks
2. Find heights
O. Attach map to maps or limbs
LANDMARK/MAPLET I/O AND CREATION
I. Input landmark
U. Update landmark files
ADJUST INPUT DATA AND NOMINALS
N. Find normal
V. Solve for V
Z. Predict px/ln
A. Reset albedo or slopes
M. Get heights from shape model
B. Get heights from surrounding map
X. Turn on/off extract filter
INFORMATION AND DISPLAY
H. Hide/Show screen output

$/!\$ Some of the Main Menu options found in lithos have been cut, and other options have been streamlined. Only the differences are presented here.

0. Find template - None of the sub-options exist.

From the Main Menu, enter '0-40' to iterate 40 times.

1. Align landmarks - None of the sub-options exist.

From the Main Menu, you can still use '1-0-1', but that is only because the "0" is interpreted as 0 spacing and lithosP asks you to enter the spacing again. Enter '1-1', '1-2', etc. as the "correct" commands to perform an auto-align.

2. Find heights - Only known difference is the "differential stereo" sub-option. Instead of being asked if you would like to reset entering gradients and auto heights, there is just a single 'y' or 'n'.

From Find heights, enter '6-y' instead of entering '6-y-y'.

O. Attach map to maps or limbs - There are some minor differences between lithosP and lithos within this option.

lithosP offers a subset of the lithos:o options - 1. Automatic; and 3. Limbs. The implementation of these options is the same as for lithos.
lithosP reduces the search for limbs by using only those limbs that have already been found spanning the maplet. If you want to do a full, include the line 'NEWLIM=.TRUE.' in INIT_LITHOS.TXT.

I. Input landmark - lithosP does not include an option to add more images to an existing landmark. Therefore, from the main menu, input 'i' and the landmark name. No further inputs are required. You will be returned to the main menu.

U. Update landmark files - Sub-options do not exist. The only option available is the "1" option, which is the full save.

Enter 'u' from the Main Menu instead of entering 'u-1'.

N. Find normal - Sub-options do not exist. The only option available is the "2" option which is the most used option.

Enter 'n' from the Main Menu instead of entering 'n-2'.

V. Solve for V - Sub-options do not exist. The only option available is the "1" option, which is the most used option.

Enter 'v' from the Main Menu instead of entering 'v-1'.

Z. Predict px/ln - This options exists in the code, but there is no documentation for it. This option calls the sub-routine V2INGPL which determines the pixel/line location of a landmark in an image, but the resulting data isn't output to a file.

A. Reset albedo or slopes - No known differences.

M. Get heights from shape model - No known differences.

B. Get heights from surrounding map - No known differences.

X. Turn on/off extract filter - No known differences.

H. Hide/Show screen output - No known differences.

(Compiled by JRW)

make_list

Category B

Version 3.0

Description

This program reads the image names from the LIMBLIST1.TXT file and documents any matches of those image names with the image names in LMRKLIST.TXT. The output consists of the landmark name and the number of matching images within LIMBLIST1.TXT.

Required Files

LIMBLIST1.TXT - List of images that show limbs.
LMRKLIST.TXT - List of landmarks.

Output Files

LIST.TXT -

Using make_list

To run make_list, just type 'make_list' in the command prompt.

Here is a sample LIST.TXT file for a LIMBLIST1.TXT file that had 4 pictures:

BH0001         2
BK0001         1
CF0001         3
CG0001         3
CG0002         4
CG0003         3
CH0001         4
CH0002         4
CH0003         4
CI0001         3
CI0002         4
CI0003         1
CI0004         3

Additional Reference

[From make_list.f]

Filename                      I/O  Description
----------------------------  ---  -------------------------------
LIMBLIST1.TXT                  I   List of images to be match w/
                                   images in landmark files
LMRKLIST.TXT                   I   List of current landmarks
<LMRKNM>.LMK                   I   Landmark files whose PICTURES
                                   entries will be matched w/
                                   images in LIMBLIST1.TXT
LIST.TXT                       O   List of landmarks that had
                                   images that matches the images
                                   in the LIMBLIST1.TXT and the
                                   number of images that were
                                   matched

(Compiled by JW)

make_lmrklistX

Category B

Version 3.0

Description

This program reads the landmarks in the LMRKLIST.TXT file. Then, from the corresponding landmark files, it reads the size, scale, landmark position vector from the center of the body to center of the landmark and the number of pictures containing the landmark. It writes these values out to the LMRKLISTX.TXT.

Required Files

LMRKLIST.TXT - List of the full suite of LMKFILES.

Output Files

LMRKLISTX.TXT - LMKFILE information.

Using make_lmrklistX

Just type 'make_lmrklistX' in the command prompt to use.

(Compiled by DL)

Based on SPOC v3.02A PDF/UTILITIES/MAKE_LMRKLISTX.f File Reference

Script Makers Overview

Description

The script-maker routines are designed to help you set up batch processing of pictures or landmarks using the autoregister, autoregisterP, lithos, lithosP and register program suites. The following table summarizes the script-maker routines, input files, and programs invoked by the resulting run scripts. For further details, refer to the entry for a specific script maker.

Table 00: Summary of Script Maker Routines

Script-Maker	Type of Files Processed	Program Invoked	input file	seed file	serial/parallel processing	Description
make_scriptA	image files	autoregister	make_script.in	make_scriptA.seed	serial processing	Generates the run script and .INN files required to batch autoregister new images.
make_scriptAP	image files	autoregisterP	make_script.in	make_scriptA.seed	parallel processing	Generates the run script and .INN files required to batch autoregister new images using parallel processing.
make_scriptF	landmark files	lithos	make_script.in	make_scriptF.seed	serial processing	Generates the run script and .INN files required for batch processing using lithos. The user generates a seed file containing the required lithos commands.
make_scriptP	landmark files	lithosP	make_script.in	make_scriptP.seed	parallel processing	Generates the run script and .INN files required to iterate maplets using lithosP.
make_scriptR	image files	register	make_script.in	make_scriptR.seed	serial processing	Generates the run script and .INN files required to batch register new images.
make_scriptT	new landmark files	lithos	make_scriptT.in	make_scriptT.seed	serial processing	Generates the run script and .INN files required to tile a bigmap or shape with a suite of new maplets.

(Compiled by DL)

make_scriptAP

Category B

Version 3.0

Description

This program generates the run script and .INN files required to batch autoregister new images using parallel processing.

Required Files

input file:

make_script.in - Text file containing the names of the images to batch autoregister.

seed file:

make_scriptA.seed - Text file containing the autoregisterP option commands for batch registering images.

processed files:

INIT_LITHOS - make_scriptAP reads the USRMX (maximum number of core processors) value.
TESTFILES1/ - Directory in which to store copies of LMRK_DISPLAYnn.pgm (output by autoregisterP) for each image.
$/!\$ autoregisterP requires a number of directories and files. Refer to autoregiserP for more information.

Output Files

make_scriptAP outputs:

run.sh - Controlling run script for batch image auto registration using parallel processing.
- run script for each core processor:
  - run_script01.b
  - run_script02.b
  - etc..
.INN files - autoregisterP seed file for each image.
rem_script.b - Script for removal of temporary files (working directory clean-up)

run_scriptnn.b output:

.OOT files - Standard output from autoregisterP for each image.

processed files outputs:

TESTFILES1/ - A copy of LMRK_DISPLAYnn.pgm (output by autoregisterP) is saved for each image.
SUMFILES/ - Landmarks are added to the image's SUMFILE. Spacecraft/camera position/attitude are updated upon user acceptance of alignment shifts.
LMKFILES/ - Image names are added to the LMKFILES.

User Warnings

$/!\$ You must set the correct number of core processors for USRMX, a variable contained in INIT_LITHOS. Refer to that entry for further information.

Using make_scriptAP

Create Input Files

Here is a sample make_script.in file (see that entry for further information):

 P00045000450
 P00045000451
 P00045000452
END

$/!\$ You must precede each image filename with a space.

Here is a sample make_scriptA.seed file (see that entry for further information):

a
0,65,.25,0,3
1
2
n
0
n
o
.5
4
b
0
q
END

Run make_scriptAP

make_scriptAP generates a .INN file for each image. It consists of the image filename followed by the autoregister options contained in the make_scriptA.seed file.

Here is an annotated sample .INN file for image P00045000450:

nn              <- two character USR name to distinguish between processes.
P00045000450
a
0,65,.25,0,3
1
2
n
0
n
o
.5
4
b
0
q
END

make_scriptAP also generates the run.sh script. Here is a sample run script file for image POOO45000450:

 chmod +x run_script01.b
 chmod +x run_script02.b
 ''etc..''

 ./run_script01.b &
 ./run_script02.b &
 ''etc...''

make_scriptAP also generates the run_script01.b, run_script02.b files, which look like this:

rm -f P00045000450.OOT
/usr/local/bin/AUTOREGISTERP < P00045000450.INN > P00045000450.OOT
cp LMRK_DISPLAY01.pgm ./TESTFILES1/P00045000450.pgm
rm -f P00045000452.OOT
/usr/local/bin/AUTOREGISTERP < P00045000451.INN > P00045000451.OOT
cp LMRK_DISPLAY01.pgm ./TESTFILES1/P00045000451.pgm

Batch Autoregister Images Using Parallel Processing
$/!\$ autoregister uses the file LMRKLISTX.TXT to prescreen the maplets. If you have added or deleted maplets recently, you should run make_lmrklistX.

Here is a sample command line for running run.sh:

sh run.sh

The autoregister standard output for each image is captured in the .OOT files. The LMRKDISPLAY1.pgm file output by autoregister is copied and stored in TESTFILES/ once an image has been processed. You must review the .OOT files to ascertain the success of the batch image autoregistration process.

There is currently no find-nofit program for batch image autoregistration.

Clean Working Directory

You can use rem_script.b to clean out the directory of make_scriptAP working files once autoregistration is complete and you have quality checked the image correlations.

Here is a sample rem_script.b file:

rm -f *.INN
rm -f *.OOT
rm -f run_script*

(Compiled by DL)

make_scriptF

Category B

Version 3.0

Description

This program generates the run script and .INN files required for batch processing using lithos. You must also generate a seed file containing the required lithos commands.

make_scriptF is a generic script maker for batch lithos processing tasks. You specify the set of landmarks to process in make_script.in and the sequence of commands to process in make_scriptF.seed.

make_scriptF generates the .INN files and run scripts to batch process the landmarks, and generates .OOT files and saves display files during processing for user inspection.

$/!\$ You should test the command sequence in lithos before running the script generated by make_scriptF.

Required Files

input file:

make_script.in - Text file containing the names of landmarks to be processed.

seed file:

make_scriptF.seed - Text file containing the lithos option commands intended during batch processing.

processed files:

TESTFILES/ - Directory in which to store copies of LMRK_DISPLAY1.pgm (output by lithos) for each landmark.
TESTFILES1/ - Directory in which to store copies of tmpl.pgm (output by lithos) for each landmark.
$/!\$ lithos requires a number of directories and files. Refer to lithos for more information.

Output Files

make_scriptF outputs:

run_script.b - Run script for batch processing.
.INN files - lithos command seed file for each landmark.
rem_script.b - Script for removal of temporary files (working directory clean-up).

run_script.b outputs:

.OOT files - standard output from lithos for each landmark.

processed files outputs:

TESTFILES/ - A copy of LMRK_DISPLAY1.pgm (output by lithos) is saved for each landmark.
TESTFILES1/ - A copy of tmpl.pgm (output by lithos) is saved for each landmark.
SUMFILES/ - S/C and camera information are updated by lithos if image shifts occur.
LMKFILES/ - LMKFILES for each landmark are updated by lithos.
MAPFILES/ - MAPFILES for each landmark are updated by lithos.
$/!\$ Several information text and display files in the working directory are modified by lithos. Refer to the entries for those files for more information.

User Warnings

$/!\$ The make_scriptF.seed file must start with a set of commands which deal with the lithos Check for more images? y[n] option sequence.
$/!\$ The make_scriptF.seed file must end with the lithos quit command, q, and the end-of-file identifier, END.
$/!\$ You should test the make_scriptF.seed lithos command sequence before running the script generated by make_scriptF.

Using make_scriptF

1. Create Input Files

Here is a sample make_script.in file (see that entry for further information):

EE0001
EE0002
EE0003
END

lithos expects a sequence of start and end commands which must be contained in the seed file before and after the processing commands.

Here is an annotated sample make_scriptF.seed file. The required start and end command sequences are explained below.

# Seed file to attach map to overlapping maps
#start commands
n                                                 <- don't check for more images
n                                                 <- don't include a single image
#processing commands
o
RECENT
y
1
o
RECENT
n
3
y
1, 3, 5 w
i
RECENT
n
n
v
1
u
1
o
RECENT
n
1
#end command
q                                                 <- quit
#end-of-file identifier
END                                               <- end-of-file

Start Commands

The .INN file starts with the command i: input landmark, and the landmark name. lithos then asks you whether to check for more images. The following samples show the prompts and responses for both 'y' and 'n' responses to this prompt:

 Check for more images? y[n]
n
 Include a single image? y[n]
n

 Check for more images? y[n]
y

 Enter fractional width (0=center).
.5

 Reject invisibles? y[n]
n

When you create the make_scriptF.seed file, you must start with a sequence that deals with this set of options. In the sample, the Start Commands lines are annotated to indicate these responses.

End Command

make_scriptF expects you to quit lithos on completion of each landmark. The make_scriptF.seed file must contain the quit command q on the second-to-last-line.

End-Of-File Identifier

make_scriptF expects the seed file to end with the end-of-file identifier, END. Any commands following this will not be appended to the .INN file.

Comments

Use # at the beginning of any comment line you want to include. make_scriptF does not append these to the .INN file.

2. Run make_scriptF

make_scriptF generates a .INN file for each landmark listed in make_script.in.

Here is a sample .INN file for landmark EE0001.INN:

The first two lines of the .INN file load the next landmark into lithos. The remainder of the .INN file lists the lithos commands contained in make_scriptF.seed.

make_scriptF also generates the run_script.b script, which looks like this:

rm -f EE0001.OOT
/usr/local/bin/LITHOS < EE0001.INN > EE0001.OOT
cp LMRK_DISPLAY1.pgm ./TESTFILES/EE0001.pgm
cp tmpl.pgm ./TESTFILES1/EE0001.pgm
rm -f EE0002.OOT
/usr/local/bin/LITHOS < EE0002.INN > EE0002.OOT
cp LMRK_DISPLAY1.pgm ./TESTFILES/EE0002.pgm
cp tmpl.pgm ./TESTFILES1/EE0002.pgm
rm -f EE0003.OOT
/usr/local/bin/LITHOS < EE0003.INN > EE0003.OOT
cp LMRK_DISPLAY1.pgm ./TESTFILES/EE0003.pgm
cp tmpl.pgm ./TESTFILES1/EE0003.pgm

3. Execute the Run Script

Here is a sample command line for running run_script.b:

sh run_script.b

You can also run this in the background using this command line:

nohup sh run_script.b &

The lithos standard output for each image is captured in the .OOT files. The LMRKDISPLAY1.pgm and tmpl.pgm files output by lithos are copied once a landmark has been processed. These are stored under the landmark's name in TESTFILES/ and TESTFILES1/ respectively.

4. Quality Check the New Maplets

You must review the .OOT files to determine the success of the tiling process.

5. Clean Working Directory

You can use rem_script.b to clean out the directory of make_scriptF working files once tiling is complete and you have quality checked the resulting suite of maplets.

Here is a sample rem_script.b file:

rm -f *.INN
rm -f *.OOT
rm -f run_script*

(Compiled by DL)

make_scriptR

Category B

Version 3.0

Description

This program generates the run script and .INN files required to batch register new images.

Required Files

input file:

make_script.in - Text file containing the names of the images to batch register.

seed file:

make_scriptR.seed - Text file containing the register option commands for batch registering images.

processed files:

TESTFILES/ - Directory in which to store copies of LMRK_DISPLAY.pgm (output by register) for each image.
$/!\$ register requires a number of directories and files. Refer to register for more information.

Output Files

make_scriptR outputs:

run_script.b - Run script for batch image registration.
.INN files - register seed file for each image.

run_script.b output:

.OOT files - Standard output from register for each image.

processed files outputs:

TESTFILES/ - A copy of LMRK_DISPLAY.pgm (output by register) is saved for each image.
NOMINALS/ - If the seed file includes the option to update the NOMINAL file, starting S/C and camera information will be updated. (This option is not typically selected).
SUMFILES/ - S/C and camera information are updated as image shifts are made.

Using make_scriptR

1. Create Input Files

Here is a sample make_script.in file (see that entry for further information):

 P3T11S2H0409
 P3T11S2H0410
 P3T11S2H0411
END

$/!\$ You must precede each image filename with a space.

Here is a sample make_scriptR.seed file (see that entry for further information):

s
20
3
y
XSTOP
1
10
3
y
XSTOP
0
y
n
n
q

2. Run make_scriptR

make_scriptR generates a .INN file for each image. It consists of the image filename followed by the register options contained in the make_scriptR.seed file.

Here is a sample .INN file for image P3T11S2H0409.INN:

P3T11S2H0409
s                   
20                  
3                   
y                   
XSTOP               
1                   
10                  
3                   
y                   
XSTOP               
0                   
y                   
n                   
n                   
q

make_scriptR also generates the run_script.b script, which looks like this:

rm -f P3T11S2H0409.OOT
/usr/local/bin/REGISTER < P3T11S2H0409.INN > P3T11S2H0409.OOT
cp TEMPFILE.pgm ./TESTFILES/P3T11S2H0409.pgm
rm -f P3T11S2H0410.OOT
/usr/local/bin/REGISTER < P3T11S2H0410.INN > P3T11S2H0410.OOT
cp TEMPFILE.pgm ./TESTFILES/P3T11S2H0410.pgm
rm -f P3T11S2H0411.OOT
/usr/local/bin/REGISTER < P3T11S2H0411.INN > P3T11S2H0411.OOT
cp TEMPFILE.pgm ./TESTFILES/P3T11S2H0411.pgm

3. Batch Register Images

Here is a sample command line for running run_script.b:

sh run_script.b

The register standard output for each image is captured in the .OOT files. The LMRKDISPLAY.pgm file output by register is copied and stored in TESTFILES/ once an image has been processed. You must review the .OOT files to ascertain the success of the batch image registration process.

There is currently no find-nofit program for batch image registration.

(Compiled by DL)

make_scriptT

Category B

Version 3.0

Description

This program generates the run script and .INN files required to tile a bigmap or shape with a suite of new maplets.

Required Files

input file:

make_scriptT.in - text file containing references to the bigmap and make_scriptT.seed file, and the bigmap pixel/line locations for the centers of each new maplet.

seed file:

make_scriptT.seed - text file containing the lithos option commands for generating each maplet.

processed file:

TESTFILES/ - Directory in which to store copies of LMRK_DISPLAY1.pgm (output by lithos) for each landmark.
TESTFILES1/ - Directory in which to store copies of tmpl.pgm (output by lithos) for each landmark.
$/!\$ lithos requires a number of directories and files. Refer to lithos for more information.

Output Files

make_scriptT outputs:

run_script.b - Run script for maplet creation.
.INN files - lithos seed file for each new maplet.
rem_script.b - Run script to clean out the directory of make_scriptT working files once tiling is complete and user has quality checked the resulting suite of maplets.

run_script.b output:

.OOT files - Standard output from lithos for each new maplet.

PROCESSED FILES OUTPUTS:

TESTFILES/ - A copy of LMRK_DISPLAY1.pgm (output by lithos) is saved for each landmark.
TESTFILES1/ - A copy of tmpl.pgm (output by lithos) is saved for each landmark.
SUMFILES/ - S/C and camera information are updated by lithos as image shifts are accepted because the "v 4" command in lithos is used. New landmarks and limb fits are added to the SUMFILEs.
LMKFILES/ - LMKFILES for each new maplet are created and populated by lithos.
MAPFILES/ - MAPFILES for each new maplet are created and populated by lithos.
$/!\$ Several information text and display files in the working directory are modified by lithos. Refer to the entries for those files for more information.

User Warnings

YOU MUST FOLLOW SEVERAL PROCEDURES BEFORE RUNNING make_scriptT. Refer to the 'How-To': Basic_tiling
$/!\$ You must copy the current bigmap to MAPFILES/XXXXXX.MAP, the temporary file used by the run scripts.

Using make_scriptT

YOU MUST FOLLOW SEVERAL PROCEDURES BEFORE RUNNING make_scriptT. Refer to the 'How-To': Basic_tiling

1. Create Input Files

Here is a sample make_scriptT.in file (see that entry for further information):

XXXXXX
scripts/t11-10.seed
      50   50
     100   50
     150   50
     200   50
      50  100
     100  100
     150  100
     200  100
      50  150
     100  150
     150  150
     200  150
      50  200
     100  200
     150  200
     200  200
END

Here is a sample make_scriptT.seed file (see that entry for further information):

0.00010,49
g
i
a
y
.5
n
x
.025
0
a
b
n
XXXXXX
n
2
b
n
XXXXXX
u
1
v
2
e
a
0,60,.25,.25,0,3
1
0
3
n
0
y

...

u
1
o
RECENT
y
1
o
RECENT
n
3
y
1, 3, 5 w
i
RECENT
n
n
v
1
u
1
v
4
o
RECENT
n
1
q
END

2. Run make_scriptT

make_scriptT generates a .INN file for each new maplet.

Here is a sample .INN file for maplet 001:

c
a
m
XXXXXX
   50.000000000000000        50.000000000000000     
0.00010,49                                                                      
g                                                                               
i                                                                               
etc ...

The first five lines of the .INN file create a new landmark in lithos, with a center at the correct bigmap pixel/line location or shape model lat/wlon location. The landmark, initially monikered 'a', is auto-renamed by lithos (option g) depending on its global lat/long region (e.g., 'EE0001'). The program refers to the bigmap using a temporary file named XXXXXX.

$/!\$ You must copy the current bigmap to MAPFILES/XXXXXX.MAP, the temporary file used by the run scripts.

The remainder of the .INN file includes a copy of the lithos commands contained in make_scriptT.seed.

make_scriptT also generates the run_script.b file, which looks like this:

rm -f 001.OOT
/usr/local/bin/LITHOS < 001.INN > 001.OOT
cp LMRK_DISPLAY1.pgm ./TESTFILES/001.pgm
cp tmpl.pgm ./TESTFILES1/001.pgm
rm -f 002.OOT
/usr/local/bin/LITHOS < 002.INN > 002.OOT
cp LMRK_DISPLAY1.pgm ./TESTFILES/002.pgm
cp tmpl.pgm ./TESTFILES1/002.pgm
rm -f 003.OOT
/usr/local/bin/LITHOS < 003.INN > 003.OOT
cp LMRK_DISPLAY1.pgm ./TESTFILES/003.pgm
cp tmpl.pgm ./TESTFILES1/003.pgm
etc ...

3. Tile Bigmap with New Maplets

Here is a sample command line for running run_script.b:

sh run_script.b

You can also run this in the background using this command line:

nohup sh run_script.b &

4. Quality Check New Maplets

You must review the .OOT files to ascertain the success of the tiling process. You can detect problem landmarks using find_nofitT. Refer to that entry for more information.

5. Clean Working Directory

You can use rem_script.b to clean out the directory of make_scriptT working files once tiling is complete and you have quality checked the resulting maplets.

Here is a sample rem_script.b file:

rm -f *.INN
rm -f *.OOT
rm -f run_script*

(Compiled by DL) CategoryPrograms

make_tilefile

Category B

Version 3.0

Description

This program generates the pixel/line maplet-center locations required to complete the tiling of a bigmap at a user-specified resolution.

make_tilefile analyzes a coverage_m.pgm file, which is the output of map_coverage, for areas that still need to be tiled. The output of this program is then put in the make_scriptT.in file.

Required Files

coverage_m.pgm - a Portable Graymap Format image of the bigmap-tiling in the user-specified maplet resolution range, generated using map_coverage

Output Files

std-out - list of bigmap pixel/line coordinates for new maplet center locations

Using make_tilefile

29 March 2021 - For DART, in the Blessed master version of the code (updated 3.0.5), the -d option was added to increase the density of the tilefiles. It creates a 2nd set that is offset by 25 pixels. It provides more control points (and maplets) with much increased overlaps.

1. Enter either Y or N in response to 'Upwards? (y/n)'.

Upwards? - Y - Pixel/line coordinates for tiling starting at the Southern-most line, West-to-East and South-to-North.
Upwards? - N - Pixel/line coordinates for tiling starting at the Northern-most line, West-to-East and North-to-South.

Here are two samples showing each of these responses:

 Upwards? (y/n)
y
      50  200
     100  200
     150  200
     200  200
      50  150
     100  150
#    150  150
     200  150
      50  100
     100  100
     150  100
     200  100
      50   50
#    100   50
#    150   50
     200   50
END

 Upwards? (y/n)
n
      50   50
#    100   50
#    150   50
     200   50
      50  100
     100  100
     150  100
     200  100
      50  150
     100  150
#    150  150
     200  150
      50  200
     100  200
     150  200
     200  200
END

The output columns are the pixel and line coordinates respectively for bare points in the bigmap. Locations that already contain a maplet in the required resolution-range are marked with # and will be ignored by make_scriptT. See make_scriptT for additional details.

2. Enter input and capture output using a single command line like this sample:

echo "N" | make_tilefile > out

$/!\$ Use a text editor to discard the first line of output before you append it to the make_scriptT.in. See make_scriptT.in for additional details.
make_tilefile is set to make the pixel and line coordinates in intervals of 50 because maplets have a 99 by 99 pixel dimension. This means that the center will always be at the (50,50) coordinate with respect to a maplet. Thus, when a maplet is made at the same resolution as the bigmap, the maplet center coordinates will be multiples of 50.

(Compiled by DL)

Based on SPOC v3.02A PDF/UTILITIES/make_tilefile.f File Reference

MAKE_TILES

Category B

Version 3.0

Description

This program builds <sequence>.IN files that are used to make Z-maps with bigmapL. Z-maps are essentially a combination of bigmaps that, together, fully wrap around the shape model.

MAKE_TILES creates a <sequence>.IN file for every row in the input file MAPLIST.TXT.

$/!\$ Be sure to include enough bigmap names to fully wrap around the surface (calculate with q-size and surface area of shape).

Required Files

MAPLIST.TXT - List of bigmap names you want to use.

Output Files

<sequence>.IN files - One for each row in MAPLIST.TXT

Using MAKE_TILES

The standard input includes these elements:

resolution (pix/km)
Q size
seed
maximum maplet resolution that can be included in the bigmap being created

Here is a sample input:

0.02500   500   1.23400   5.00000

Here is a sample MAPLIST.TXT file:

ZN0000
ZN0001
ZN0002
ZN0003
ZN0004
ZN0005
ZN0006
ZN0007
ZN0008
ZN0009
ZN0010
ZN0011
END

The following is a sample sequence.in file created from the above inputs:

l
    0    0
   0.02500       500   1.23400   5.00000
ZN0000
1
.005
.025
1
1
1
1
1
1
1
0
0

(Compiled by KD)

MAKE_TILESP

Category B

Version 3.0

Description

This program is the same as MAKE_TILES, but it also creates <sequence>.INN files that can be run in parallel. In other words, MAKETILESP allows bigmapL to run all the <sequence>.INN files it has made at the same time rather than one at a time.

Like MAKE_TILES, MAKE_TILESP builds <sequence>.INN files that are used to make Z-maps with bigmapL. Z-maps are essentially a combination of bigmaps that, together, fully wrap around the shape model.

MAKE_TILESP creates a <sequence>.INN file for every row in the input file MAPLIST.TXT.

$/!\$ Be sure to include enough bigmap names to fully wrap around the surface (calculate with q-size and surface area of shape).

Required Files

MAPLIST.TXT - List of bigmap names you want to use.

Output Files

<map_name>.INN files - Inputs for bigmapL
<MAKE_TILES##>.b files -

Using MAKE_TILESP

Here is a sample of the screen output from MAKE_TILESP:

chmod +x MAKE_TILES01.b
chmod +x MAKE_TILES02.b
chmod +x MAKE_TILES03.b
chmod +x MAKE_TILES04.b

./MAKE_TILES01.b &
./MAKE_TILES02.b &
./MAKE_TILES03.b &
./MAKE_TILES04.b &

Copy and paste the screen output into the terminal to create all the z-maps in parallel.

Each <MAKE_TILES##>.b file the following structure, containing one or more lines like this:

 /usr/local/bin/bigmapL < F00001.INN > F00001.OOT

(Compiled by KD)

map_coverage

Category B

Version 3.0

Description

This program generates coverage for a limited area (bigmap) of what has been tiled and processed. map_coverage produces a coverage_m.pgm file that shows areas on a bigmap that have been tiled at user specified resolutions. In the image, black means the area is not covered by a maplet while covered areas are bright. The brighter the area, the more maplets overlap that area.

Near the end of processing, there may be thousands of maplets. To speed things up, the routine will read in LMRKLISTO.TXT if it exists. This file speeds up map_coverage by telling the program exactly which maplets to show rather than having it search.

Input Files

bigmap - a name provided in stdin

Output Files

coverage_m.pgm - a regional map showing what has been tiled to the specified resolution

Using map_coverage

Input the filename of a bigmap:

 ZN0204

Input the min and max resolution of tiles (maplets) to show:

 0,.001

Here is a sample output from map_coverage:

Figure 00: Example of map_coverage Output

Compiled by KD

new_pole

Category ?

Version 3.0

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)

OMEGA

Category ?

Version 3.0

Description

This program calculates the angular velocity of a body's rotation by using the position of landmarks in subsequent images.

The images should be at least roughly registered (REGISTER) before starting.

The pointing and spacecraft position is originally determined in body-fixed space from a nominal .pck file. Then they are transformed back to inertial space.

If V is the vector of a landmark at time = 0 (PICNM0) then the inertial space vector V' at time = t (PICNM1) is given by

V' = Vcos(a) +(AxV)sin(a)/a +A(A.V)(1-cos(a))/a^2
- where A is the inertial space vector OMEGA x t and a is its magnitude with OMEGA = angular velocity.

The program solves for A, for an offset of image PICNM1 due to relative pointing errors and for the inertial space landmark positions at t=0. Many iterations (~100) are required for convergence (but it is very fast) and OMEGA is printed both as an inertial space vector and in RA, DEC,|OMEGA| in deg and deg/da.

Required Files

POLE.TXT which has an initial guess for the RA/DEC of omega and its magnitude in deg/da.
PICTLIST.TXT
LMRKLIST.TXT

Inputs

The image name of two images that have some common landmarks in them
Option to do additional iterations
Option to update the SCOBJ and C vectors in the SUMFILES

Outputs

<imagename>_ROT.TXT - Log of the translation of each common landmark from inertial to body-fixed frame.
Standard out - showing
- Omega value
- RA/DEC calculated for the angular momentum vector, as well as the rotate rate in degrees per day
- the difference in time between the two image (in ET)

Using OMEGA

Here is a sample of the standard input:

$ omega
 Input PICNM0
P601293196F2
 Input PICNM1
P601293203F2

OMEGA:                  0.10196E-04    0.17130E-03   -0.36799E-03


                       ALPHA                          DP1            DL1
       -0.00020        0.00138       -0.00247       -0.05370        0.03372

  -1.3347563804838266E-004

 Iterate? (y/n)
n
        0.02842        0.01714

OMEGA:                 -0.28363E-04    0.19784E-03   -0.35343E-03
ET1 - ET0:                  7.00000
RA DEC DEG/DA:        98.15845      -60.51164     2009.99984

 Return to iteration? (y/n)
n
 Update SUMFILE? (y/n)
n

Here is a sample output file P601293196F2_ROT.TXT:

 PICNM0 = P601293196F2  PICNM1 = P601293203F2

                              INERTIAL                                    BODY FIXED

EE0001        0.79740E-01   -0.24443E+00   -0.76561E-01   -0.24352E-01    0.26146E+00   -0.28265E-01
EE0002        0.76654E-01   -0.24740E+00   -0.76961E-01   -0.28215E-01    0.26180E+00   -0.28335E-01
EE0003        0.72600E-01   -0.24614E+00   -0.78760E-01   -0.31991E-01    0.26251E+00   -0.28429E-01
EE0004        0.69034E-01   -0.24720E+00   -0.79739E-01   -0.35877E-01    0.26275E+00   -0.28361E-01
EE0006        0.79252E-01   -0.24506E+00   -0.73033E-01   -0.24417E-01    0.26092E+00   -0.32141E-01
EE0007        0.75892E-01   -0.24655E+00   -0.73990E-01   -0.28216E-01    0.26158E+00   -0.32223E-01
...

OMEGA:                 -0.47507E-04    0.15800E-03   -0.37100E-03
RA DEC DEG/DA:         106.73459      -66.02445     2009.99984
ET1 - ET0:               7.00000
Rotation:                0.16285
IMAX:                        76
dP, dL, dS:            -0.91703E+00    0.51699E+00   -0.25762E-03

Body fixed frame:        87.19928      -64.78164     -115.42772

    0.2404600643D+00   -0.3024911368D+01    0.2313284431D+01   SCOBJ
    0.6384185077D+00   -0.4531136654D+00   -0.6280592064D+00   CX
    0.7669571811D+00    0.4425514816D+00    0.4690669420D+00   CY
    0.6479576942D-01   -0.7738450699D+00    0.6360038956D+00   CZ
   -0.5260644620D+00    0.8478532108D+00    0.6696761722D-01   SZ

(Compiled by ??)

pole

Category B

Version 3.0

Description

This program solves for the pole right ascension, declination and rotation rate for a body in principal axis rotation. The rotation rate is calculated in degrees/day while right ascension and declination are calculated in degrees.

If you "keep the result", then pole will translate the VLM (central vector) an UX, UY, UZ (normal vectors) of the landmarks, maplets, SUMFILES and NOMINALS. It will also update the information in POLE.TXT.

Input Files

POLE.TXT - simple text file containing nominal pole RA (deg), DEC (deg), PM (deg), OMEGA (deg/day)
LMRKLIST.TXT
SUMFILES

$/!\$ POLE.TXT and LMRKLIST.TXT must be in the working directory.

POLE.TXT is a single row file that contains the predicted pole RA (deg), DEC (deg), PM (deg), and OMEGA (deg/day). These values are given in the .tpc kernel file for the object. LMRKLIST.TXT contains a list of landmarks.

Using pole

When you run pole, it is expecting an initial value for POLE.TXT. If that file does not exist, the program will fail. To create the file, you can use the pole values from the current PCK (planetary constants kernel).

1. Input a time in UTC.

$/!\$ Make sure the time is within the span supported by the kernels.

2018 NOV 16 13:09:54.824

2. Create a POLE.TXT file.

Here is a sample POLE.TXT file:

       86         -65      89.00000000    2010.48945

3. Answer whether you want the rotation rate fixed (y for yes, n for no).

4. Enter

0 if you want to iterate
1 if you want to keep the result (this updates POLE.TXT)
2 if you want the previous result (this is nominal if on the first iteration)

In general you will want to do several iterations to help the inversion of the matrix converge. When the pole solution ceases to change, if you think that the solution is an improvement, you can keep it. At that point, it will change most of the files in the working directory.

Here is a sample output from the POLE.TXT input:

    86.60062   -65.00002    90.42707  2009.99979311
     0.05176     0.02171                 0.00000001

The first row gives all the new pole parameters for POLE.TXT.
The second row shows formal uncertainty (the diagonals of the covariance). These values should be multiplied a factor of 10 or 100.

Test Results

Testing using the NTE3A data set showed that picking different Epoch times over the time span of the images used (in this case 22 days) resulted in no change of RA, DEC, or rotation rate, and the PM at J2000 only change by 0.07 deg.

(Compiled by KD)

CategoryPrograms CategoryThreeAlphaThree

PROCESS_FITS

Category B

Version 3.0.1

Description

Process_fits is the main ingestion program for SPC, specifically adjusted to support OREx's metadata and file format. It does the following:

reads a FITS image file
extracts relevant information from the header
adds a record to the make_sumfiles.in file
adds a raw 16- bit unsigned integer image to the IMAGEFILES directory

SPC-OREx Naming Convention - FITS filenames are shortened to 12 characters. The 1st char and last two chars have embedded metadata in them. This explains how Bob encoded it. In general, it is camera symbol (P,M,N,T), the ET and then two char for filter number and processing status.

Required Files

FITS image file - You provide the name as part of the standard input.
INIT_LITHOS.TXT - Contains SPICE kernels. Each line entry that contains PCK= will have the spice command furnish run on it. SPC expects the leap second kernel to be defined in this list (which is also defined in make_sumfiles.txt).
IMAGEFILES/

Outputs

a row for the image is appended to make_sumfiles.in
16-bit unsigned integer image(s) are stored to IMAGEFILES directory. Stretched to a maximum 65536.

make_sumfiles.in is generated from process_fits. FITS keywords are used to provide the data to construct make_sumfiles.in. The key elements new in SPC v3.0.1 is the addition of temperature and MTR_POSITION.

Example:

Image Name	UTC or ET	Camera Num	Spacecraft Num	Binning	Temp [c]	Motor Position or Filter Position	Original filename (partial)
P596924821J3	3/0596924726.30615	3	1	1	-25.50	270	20181201T082552S75100Z_pol_L0_V002.fits

Temperature is calculated (see below) using DN2TEMP.TXT and written out in make_sumfiles.in
Motor Position is taken directly from keyword MTR_POS regardless of PolyCam or MapCam. make_sumfiles handles the differences between cameras.

User Warning

$/!\$ The program display will put the 0,0 position of the image in the top left, but OREx wants 0,0 to be in the bottom left.

Level 0

The data stored in each image file contained in the IMAGEFILES directory is a scaled unsigned integer (as 14 bits folded into 16 bits), with the exclusion of values less than 0. Acceptable values are from 0 to 16,383 (14 bit). The files will contain a bias -- i.e. an offset to ensure that the system can record no-photons detected without needing to use a negative value (in all flight conditions and temperatures)

ECR Changes from 3.0A2

Support OREx level 0 images
- Trim the second channel from the image to make it 1024x1024
- Remove dark/bias -- This comes from the shielded overscan region
- Correct the flat field
- Desmear the image

Additional Required Files

DATA/DN2TEMP.TXT
DATA/FLATFILES.TXT

Level 0 Processing Steps

The level 0 OCAMS and NavCam images need to have a basic level of calibration done to them, which occurs in process_fits. The details of the calibration comes from the following documents

software version	Document
v3.0.1 and v3.0.2	KinetX Interoffice Memorandum SNAFD.B / 023-16, Dated 25 Sept 2017

Output to the terminal

P634735130B7
 OKAY
2020 FEB 11 23:17:46.167
EXPOSURE(ms) =      3.225
 MSB SIGNED
    152.62    155.00     27.18    279.19  16383.00
   2866.0033510981912

            WRITE(6,FMT='(5F10.2)') DARKL, DARKR, SDL, SDR, FLOAT(K)

Dark for the left and right side of the chip. The standard dev for the left and right. The K, which is the max DN (I think).

OCAMS

Level 0 OCAMS images have the images stored as two FITS images. The first FITS image is the standard 1024x1024 FITS image that most of the science team will use (if they want level 0). The second FITS image array is 1111 x 1043, which is the full sensor for OCAMS and contains the overscan region used for calibration. This format is fully described in the OCAMS SIS.

These keywords are read by SPC. FITS Keywords describes what is done with each.

DN2TEMP.TXT
1. OCAMS thermoresitors DNs are converted into physical units using the OCAMS Flight Software Engineer Dictionary (OREX-DOC-05.01-00259, Rev_C, Dated 12/04/2015) for SPC v3.0.1.
2. SPC uses the 4 weighting parameters in DN2TEMP.TXT to calculate a linear weighted value for the effective temperature of the camera optics. For testing, we are weighting each thermoresistor by .25, providing each one with equal weight.
3. The OCAMS Instrument Team will provide the final weighting during operations. There is no ICD or SIS for the information, so it will have to be done via email and documented as a memo.
Reduce Size - SPC will read the second image of the file, which includes the overscan regions. It will take the main 1024x1024 pixels for the image DN, loading the other portions into Flat and Dark variables for calibration. If the label doesn't match the image, it will output "INCONSISTENCY"; otherwise, it will show "OKAY".
Dark bias - The chip has four overscan regions that are averaged to calculate a day. The chip is broken into a left and a right half, and the darks are calculated accordingly. SPC will average all of the overscan pixels in each half, then print: Dark Left, Dark Right, Std Dev Left, Std Dev Right, Max.
- ```
    DN(i,j) -= DK(i,j)
```

Frame Transfer correction - OCAMS does not have a shutter, so as the pixels are read, they are shifted one column at a time to be read, creating a smear or frame transfer artifact. As long as the image is not saturated, the bias can be removed by the same routine used for New Frontiers LORRI camera.

           Readout smear from NEW HORIZONS LORRI camera. Tf is average of frame scrub
           time T1 and frame storage time T2.  Parameter alpha = (T2-T1)/(2*Tf) so
           T1=(1-alpha)*Tf and T2=(1+alpha)*Tf.  Te is exposure time, n=number of lines,
           P is smeared image column and Q is unsmeared image column.

Flat field correction - FLATFILES.TXT contains a list of flat files for each camera and filter. process_fits will read in the relevant file for the camera/filter and apply it to the image's DN. If FLATFILES.TXT does not exist, process_fits will error and quite. If the referenced file doesn't exist, SPC will just throw a warning (NO FLATFILE) and continue without applying a flat.
- $/!\$ The code has a part that calculates and prints min and max, as well as scaling the flat: flat(i,j) /= max. However, it does not appear to be run because a boundary test ends the loop early.
  - ```
      DN (i,j) *= FLAT(i,j)
```
Scale - Normal SPC prefers to keep the data in unsigned integers; however, to do these corrections, the data had to be converted into real (float) values. Because SPC stores the image data as unsigned integers, the real values must be rounded into integers. Because this results in a 1 DN addition of noise for no value, for this project, the integer values are scaled using 2^{16 / 2}14 (65535/16384 otherwise known as 4). This reduces the impact of rounding floating point numbers into integers, and because SPC does a normalized cross correlation, it has no impact on SPC's performance.

TAGCAMS (NavCam / NFTCam)

The following FITS Keywords are read by SPC. This describes what is done with each.

Temperature Calculation - Using DN2TEMP.TXT, apply the polynomial coefficients to convert from DN to a temperature in C. Once that is done, then use the last four columns of DN2TEMP.TXT to calculate an effective temperature for the optical path. This is implemented just as for OCAMS (see above).
- ```
   temp = C1 * DN^3 + C2 * DN^2 + C3 * DN + C4
```
Reduce Size - Remove the black borders on the NavCam/NFTCam images. The TAGGACS suite (NavCam and TAGCam) contain overscan regions on all portions. SPC removes these to output a single array (stored in IMAGEFILES) that is 2592 x 1944.
- Top
  
  50
  
  Top boundary
  
  4
  
  left
  
  134
  
  left boundary
  
  6
  
  bottom
  
  2
  
  bottom boundary
  
  4
  
  right
  
  10
  
  right boundary
  
  10
Darks - NavCam and TAGCam darks are calculated from region 4 of the CCD. They are grouped into 8 bins, four on one row and four on the next. SPC calculates the dark (average) and the standard deviation for each pixel bin. It prints out each of the eight bins and the sum of all eight standard deviations. Then SPC removes the darks by simple subtraction. For TAGGAMS, this value is typically 150-180 DN. SPC checks, and if needed sets to zero, any negative values. Then it prints the minimum DN value after dark correction.
- ```
    DN(i,j) -= DK(i,j)
```
Flat field correction - SPC will multiple every DN by a flat field correction that was read in from the FLATFILES.TXT. Flat files are implemented the same way as OCAMS (see above).
- ```
    DN (i,j) *= FLAT(i,j)
```
Scale - Normal SPC prefers to keep the data in unsigned integers; however, to do the calibration, the data had to be converted into real (float) values. Because SPC stores the image data as unsigned integers, the real values must be rounded into integers. Because this results in a 1 DN addition of noise for no value, for this project, the integer values are scaled using 2^{16 / 2}12 (65535/4096 otherwise known as 16). This reduces the impact of rounding floating point numbers into integers, and because SPC does a normalized cross correlation, it has no impact of SPC's performance.

Level 1

If the source is a real (or 32-bit float) value process_fits takes the original images' data float and calculates the maximum value. Then it scales the data to spread from 0 to 65536 to maximize the accuracy of the stored data.

Using process_fits

process_fits can be run in two modes:

Single file - just give the FITS filename at the prompt
Batch mode
- If the file newpix.txt exists, then process_fits will search through ../OSIRIS_REx/NEW_IMAGES_YYYY_DDD to find the image and process.
- $/!\$ The built-in search only goes from 2015 to 2022 directories. The files don't actually have to be in the correct directories, it is just good practice for organization. SPC will search all directories from 2015/001 to 2022/365.

Here is a sample of the standard input:

 Input filename
2019-01-20T22-47-05.541_PCAM_L0b_V004.fits
 OKAY
2019 JAN 20 22:47:05.050
EXPOSURE(ms) =    100.000
 MSB SIGNED
      0.00      0.00      0.00      0.00      0.00
   5.0000000000000000
P601296494J3

Old - process_fits-3.0A2

(Compiled by EP)

CategoryThreeOhOne

register

Category B

Version 3.0.3

Description

This program is used to align new images with a known object.

register cross-correlates an image with existing data to update the knowledge of the spacecraft position/attitude. It is limited to 2 degrees of freedom.

Required Files

IMAGEFILES/ - a directory containing the image .DAT files
NOMINALS/ - a directory containing the image .NOM files (starting solution image, S/C and camera information)
SUMFILES/ - a directory containing the image .SUM files (updated solution image, S/C and camera information, lmrks and limbs)
MAPFILES/ - required for comparison with a reference map
SHAPEFILES/ - required for comparison with a shape model

Optional Files

make_scriptR.seed - for batch processing using make_scriptR

Output Files

NOMINALS/ - If you select the option to update the NOMINAL file, starting S/C and camera information will be updated (an option not typically selected)
SUMFILES/ - S/C and camera information are updated as image shifts are made. You can discard these changes upon quit.
TEMPFILE.pgm - A side by side view of the image (left) and the reference (right)
TEMPFILE.ppm - A red/cyan composite of the two items (red is image, cyan is reference)

User Warnings

$/!\$ To undo all changes since the last quit, you must select 'n' from the Main Menu.
$/!\$ Since the SUMFILE is updated in realtime, an uncontrolled exit from register will result in the SUMFILE remaining modified.

Using register

Initial Inputs

register provides an initial estimate for the spacecraft state (camera pointing and s/c-object vector) by aligning an image with a known object - either the shape model, a high resolution map or another (already registered) image.

The following shows the initial inputs necessary to get to the Main Menu:

 input 12-character picture name. q to quit.

1. Enter the image name as stored in [[IMAGEFILES]].

Some versions of process_fits will make some changes to the filename, so it may not be the "original" name.

 s = shape
 i = reference image
 m = reference map

2. Enter the object to align with.

s = shape - to use the current shape model
i = image - select an already registered image; you will be prompted for an image name
m = map - use a maplet/bigmap; you will be prompted for a map name

If you enter 0 for the map name, the program will search a set of "Zmaps" for the one most likely to overlap the image. Maps are only used after a detailed shape model and high-resolution maps have been constructed. At that time you are registering new images for navigation or improving the topography.

 enter scale (km/px)

3. Enter the scale in km. The basic display for REGISTER is 600x600 pixels.

For example, if the body is 500 m across and the scale is entered at 5 m (.005), the image will be 100 pixels across in the display.

The output will look like this:

 gc TEMPFILE.pgm
 gc TEMPFILE.ppm

TEMPFILE.pgm - A side by side view of the new image (left) and the reference (right)
TEMPFILE.ppm - A red/cyan composite of the two items (new is red, cyan is reference)

Here is a sample TEMPFILE.pgm file image:

Figure 00: Side-by-Side Example of Registration Allowing Comparison of Initial State

Here is a sample TEMPFILE.ppm file image:

Figure 00: Color Differentiated Example of Registration Allowing Comparison of Initial State

The display and the arrays of image and reference data are not the actual imaging data; instead, they are that data projected on a substrate. When you are just starting processing and looking at low-resolution images of the body, the substrate is simply a plane through the body center oriented parallel to the camera's focal plane. This flat 'f' substrate is the default value. Once a decent shape model is obtained and the images cover a small fraction of the body's surface, the substrate is taken to be that surface itself, either in the form of the shape 's' or a high-resolution map 'm'. In this case, the topography is represented as a DTM whose reference plane is the same as the flat substrate with heights in the negative camera bore sight direction.
If the reference is also an image, this data is projected on the same substrate as the image being registered.

After you have entered the initial inputs, you will then see the Main Menu.

Main Menu

The Main Menu of register looks like this:

 0. Quit
 1. Change scale
 2. Global shift
 3. Shift unknown (LEFT/RED) image
 4. Rotate unknown (LEFT/RED) image
 5. Change reference
 6. Change RANGE of (LEFT/RED) image
 7. Revert to nominal
 8. Change substrate (f)
 9. Update nominal and quit
 F. Features to body rotation
 G. Get approach range from images
 O. Find OMEGA
 W. Write log
 a. Turn off bkg
 b. Turn off image for Vlm
 l. Turn on log
 c. Change correlation limit =   0.25
 d. Fix scobj
 e. Fix pointing
 v. Fix center=0
 t. Tuck picture

Options 1, 5 and 8: Allow you to change the scale, reference object and substrate, respectively.

Option 2: Sometimes when trying to align an image to a reference, the entire display is off center. Option 2 moves both the image and reference displays by the same amount so that you can more conveniently align them, usually at smaller scale. This option only changes the user's point of view, not the image's location.

Options 3, 4 and 6: Make changes to the .SUM file in camera pointing and/or cross line-of sight scobj, camera twist and s/c range, respectively.

Option 3: This is the most often used option.

The new image is on the left or in red. Values entered (delta x, delta y) are the number of pixels by which the image will be shifted (as per the current scale).
- This isn't the same as moving the "window" as in lithos; instead, it updates the image's camera position and pointing.
After you enter option 3, you will input responses like these:

 Autocorrelate? (y/n)
y
        0.00000        0.00000        0.27302
 Enter px/ln IMAGE shift

If you respond 'y', autocorrelate estimates the offset between the image and the reference. The three values displayed in the standard output are the delta x (pixels), delta y (lines), and the correlation score.

If the correlation gives a good match (greater than a preset limit, default=0.25), autocorrelate will shift the image and go back to the menu.
Otherwise, autocorrelate will ask for a manual input.
The preset limit can be changed with Option c.

Option 7: Populates the working .SUM file. This is sometimes a bailout procedure used when the .SUM file is screwed up in some way.

option 9 lets you save the current result as the nominal without changing the .SUM file from its original value. If, for example, the spacecraft range is out to lunch (as it was on Hayabusa), the working .SUM file can be populated with the nominal, a change made to the range with option 6, and the new nominal saved with option 9.

Option F Features to body rotation. This allows you to use two images (about 20deg rotation difference) to identify a pole. It uses x/y pairs between real and model. Register-find-pole-info

Option G Allows you to try different size scalings to see if the fit is better.

Option O Computes the RA, Dec and rotation rate based on the data provided by Option F. Provide the rotation rate in degrees per day.

Option W Writes out the log of the commands that are used.

Option a: When correlating small images to a nominal shape, we want to use all the data, so the space off the body counts just as much as the body itself. Option A wakes up with a "background" turned on so that this correlation can be performed. Entering 'a' toggles this background off, so that only the common topography is correlated between the image and the reference object.

Option b: Allows a flag to be set on the image that will enable its brightness variations to be used to determine topography but keeps it from participating in the geometry solution for the landmark vector. This is used to keep Mariner 10 images of Mercury, which have questionable nominals, from messing up the vector but still, with their sometimes unique sun angles, helping with the topography determination.

Option l: Turns on the logging function for register. This is mostly for finding size or pole.

Option c: Allows you to change the autocorrelation limit (default=0.25).

Options d and e: When an image shift has been determined, either manually or through autocorrelation, the camera pointing and spacecraft-object (scobj) vector in the .SUM file are changed in a manner weighted by their respective sigmas in the nominals (.NOM) file. If you want to keep one or the other unchanged, use the 'd' or 'e' option to fix it.

Option t: Allows an image to be tucked so it will not participate in the SPC process at all. It could be tucked from lithos, but it often happens that as register is used to cycle through new images, problems are easily seen and dealt with immediately.

Option v Fix center = 0.

0. Quit: This gives you the chance to save or discard changes, and then register the next image. All toggle options will persist until you Quit register.

 Accept shift? (y/n)
 Update/Create rotation history file? (y/n)
 Update nominal file? (y/n)

Accept shift?: Note that the shift has already been applied (the SUMFILE is updated in real time).

$/!\$ To undo all changes since the last quit, you must select 'n'.

Update/Create rotation history file?: Always enter 'n'. The rotation history file was introduced to keep track of pointing errors in Clementine data during Lunar orbits in an attempt to quantify systematic shifts.

Update nominal file?: Usually enter 'n'. Rarely, you may want to set the nominal file equal to the .SUM solution.

The following sample shows standard inputs and outputs from register:

Figure 00: Sample Registration of an Image with a Shape

Figure 00: Sample Registration of an Image with a BigMap

Figure 00: Illustration of Options using Register

(Compiled by DL)

Based on SPOC v3.02A PDF/LITHOSPHERE/REGISTER.f File Reference

regres

Category B

Version 3.0.1

Description

This program generates a set of ascii interface files, one for each image, containing optical navigation observables, partials, and relevant ancillary information for use in the FDS navigation software suite(s). Both MIRAGE (KinetX) and GEODYN (GSFC) are currently ingesting these files. A file is created for each image in the restricted picture list, PICTLISTR.TXT, and only landmarks from a restricted landmark list, LMRKLISTR.TXT, are used. If the PICTLISTR.TXT file does not exist, the software defaults to PICTLIST.TXT.

Each interface file contains the following information:

SPICE IDs, image epoch, camera parameters
TITV matrix (inertial to camera frame transformation)
TPMI matrix (body-fixed to inertial transformation)
SPC solution for:
- Spacecraft-to-object vector
- Camera pointing (RA, Dec, Twist)
- Spacecraft position sigma
- Camera pointing and twist sigmas
Nominal (a priori):
- Spacecraft-to-object vector
- Camera pointing (RA, Dec, Twist)
- Solar unit vector
For each landmark identified in the image from SPC process:
- Landmark name
- Body-fixed control point vector
- Body-fixed control point sigma
- Observed landmark center in (pixel, line) image coordinates
- Predicted landmark center in (pixel, line) image coordinates based on nominal S/C position and SPC solution for camera pointing
- Partial derivatives for (pixel, line) w.r.t. spacecraft-body position vector (SCOBJ)
- Partial derivatives for (pixel, line) w.r.t. camera pointing (RA, Dec, Twist)
List of all SPICE kernels used

regres requires the directory "REGRES_FILES" in the working directory. regres exports files for each picture (<PICTURE NAME>.TXT) to the "REGRES_FILES" directory.

regres uses all pictures in PICTLIST.TXT and landmarks in LMRKLISTR.TXT to make the exported regres files. However, if you have created a PICTLISTR.TXT, regres will only use the pictures from that file.

regres uses data from NOMINAL

Input Files

Output Files

<path to working directory>/REGRES_FILES/<picture name>.TXT

Using regres

If all required inputs are available in the working directory, simply execute regres to produce the output files.

Here is a sample output file from regres:

REGRES FILE.  CREATED Tue Oct  3 14:47:34 2017
PARTIALS UNITS: PX/KM, PX/DEG

N599562509F0                                                   IMAGE ID
2018-12-31T21:07:21.000_NCAM_L0b_V005.fits                     ORIGINAL NAME
ORX_NAVCAM1                                                    CAMERA ID
       -64                                                     SPACECRAFT ID
   2101955                                                     TARGET ID
LT+S                                                           ABCORR

2018 DEC 31 21:07:21.000                                       UTC
    0.5995625102D+09                                           ET SEC PAST J2000

  2592  1944  1000 65535                                       NPX, NLN, THRSH
    0.7680000000D+01    0.1296500000D+04    0.9725000000D+03   MMFL, CTR
  454.5455    0.0000    0.0000    0.0000 -454.5455    0.0000   K-MATRIX

Camera temperature (deg C) =    N/A                            CAMERA TEMP

Distortion type =   OPENCV                                     DISTORT BEGIN
Parameters:                                                    DISTORT CONTINUE
P( 0) =   0.0000000D+00                                        DISTORT CONTINUE
P( 1) =  -0.5357300D+00                                        DISTORT CONTINUE
P( 2) =   0.3611700D+00                                        DISTORT CONTINUE
P( 3) =  -0.1534700D-06                                        DISTORT CONTINUE
P( 4) =   0.0000000D+00                                        DISTORT CONTINUE
P( 5) =   0.0000000D+00                                        DISTORT CONTINUE
P( 6) =   0.0000000D+00                                        DISTORT CONTINUE
P( 7) =   0.0000000D+00                                        DISTORT CONTINUE
P( 8) =   0.0000000D+00                                        DISTORT END

    0.5815432282D+00   -0.6754376338D+00   -0.4534219630D+00   ROW 1 TITV MATRIX
   -0.8014742143D+00   -0.5712327735D+00   -0.1770090457D+00   ROW 2 TITV MATRIX
   -0.1394509146D+00    0.4663444234D+00   -0.8735423980D+00   ROW 3 TITV MATRIX

    0.8583303375D+00   -0.5130525373D+00    0.6791585157D-02   ROW 1 TPMI MATRIX
   -0.4619122250D+00   -0.7668748603D+00    0.4455783264D+00   ROW 2 TPMI MATRIX
   -0.2233967950D+00   -0.3855905115D+00   -0.8952171968D+00   ROW 3 TPMI MATRIX

LITHOS SOLUTION:

   -0.1877903947D+00    0.1184174267D+01   -0.1797326337D+01   SC - OBJ VECTOR
    0.1066482361D+03   -0.6087293551D+02   -0.2132491821D+02   CAMERA RA, DC, TW
    0.1732050808D-01                                           S/C POSITION SIG
    0.8102846845D-08                                           PNT SIGMA (DEG)
    0.5729577951D-08                                           TWIST SIGMA (DEG)

NOMINAL STATE:

   -0.1877903947D+00    0.1184174267D+01   -0.1797326337D+01   SC - OBJ VECTOR
    0.1066482361D+03   -0.6087293551D+02   -0.2132491821D+02   CAMERA RA, DC, TW
   -0.5629404130D+00   -0.7205839705D+00   -0.4047923329D+00   SOLAR UNIT VECTOR

LANDMARKS:

END LANDMARKS

KERNEL LIST

att_nte2_m3a-m4a_truth.bc
ORX_SCLKSCET.00000.example.tsc
naif0012.tls
orx_ocams_v05.ti
orx_181215_190112_190108_od012_v1.bsp
orx_v06rwg.tf
de424.bsp
bennu_nte2_truth.tpc
pck00010.tpc

END FILE

(Compiled by KD)

regres-3.0A2

CategoryThreeOhOne

rem_done

Category B

Version 3.0

Description

This program's main purpose is to allow you to stop a parallel lithosP process and find out which landmarks in make_script.in have yet to be worked on. You should run rem_done if SPC crashes during a parallel process.

Input Files

make_script.in - Script for processing
balzyWalzy.txt - List of landmarks processed (can be called anything)
flyingMonkies.txt - List of landmarks not processed (can be called anything)

Output

None, just stops the process.

Using rem_done

1. Determine which landmarks have been processed.

In the working directory that contains .OOT and .INN files, enter this command line:

ls -1 *.OOT | cut -c -6 > balzyWalzy.txt

This puts all the .OOT filenames into the text file balzyWalzy.txt in the form of a column without the .OOT extension.
$/!\$ You must add 'END' as the last row of this text file.

2. Create a text file listing landmarks that have been processed and call it 'done.txt'.

Put the landmarks without an .OOT file (those not listed in Step 1) into the text file flyingMonkies.txt in the form of a column.
$/!\$ You must add 'END' as the last row of this text file.

 INPUT INFILE
make_script.in
 INPUT DONEFILE
done.txt
 INPUT OUTFILE
FlyingMonkies.txt

(Compiled by KD)

residuals

Category B

Version 3.0

Description

This program shows how well SPC has performed. residuals tests the landmarks to look for problems and gives reports about how well the landmarks were processed. The reports it generates are listed in the Output section.

Input Files

LMKFILES/ - a directory containing the full suite of landmarks
NOMINALS/ - a directory containing the image .NOM files (starting solution image, S/C and camera information)
SUMFILES/ - a directory containing the image .SUM files (updated solution image, S/C and camera information, lmrks and limbs)
IMAGEFILES - a directory containing the image .DAT files
PICTLIST.TXT - list of picture names generated by make_sumfiles
LMRKLIST.TXT - a list of the landmarks contained in the solution

Optional Files

PICTLISTS.TXT - user-generated list of picture names. (If this file exists, it is used instead of PICTLIST.TXT.)

Output Files

MAPINFO.TXT
PICINFO.TXT
LIMINFO.TXT
RESIDUALS.TXT
check.txt - List of landmarks and overlaps for landmarks whose linear residual is greater than the user-specified limit.
EMPTY.TXT - lithos seed file for batch deletion of landmarks which are not contained in any pictures or limbs.
FLATLIST.TXT - List of flat maps (landmarks containing no topography).
LMKVECS.TXT - Landmark vectors for every landmark contained in LMRKLIST.TXT.
MAPCHK.TXT - List of maplets whose difference between predicted and observed pixel/line locations in attached images is greater than a user-specified limit, or who have two or fewer overlaps attached to them.
MAPRES.TXT - Maplet resolution information for maplets contained in at least one picture or limb.
New_Limbs.in - lithos seed file to attach map to limbs for every landmark contained in LMRKLIST.TXT.
no_update.txt - List of landmarks whose associated pictures are not listed by increasing mission time in the .LMK file.
PRUNE.TXT - List of landmarks for which the number of pictures in which they are contained exceeds the default limit of 500, or the user-specified limit, PRNLM, set within INIT_LITHOS.TXT.
RANGES_SOLVED.TXT - Date and range information for each picture listed in PICTLISTS.TXT or PICTLIST.TXT.
veto.txt - lithos seed file to detach from landmarks and limbs a map with a linear residual greater than the user-specified limit.

Using residuals

After you invoke the program, it prompts:

enter 3 values (px,km,km)

value 1 - the value of the pixel residual limit. Images and maplets are flagged for a pixel residual limit greater than this.
- An image in a landmark will be flagged if the RSS of the pixel and line residuals in units of image pixels exceeds the input value
value 2 - the value of the linear residual beyond which images and maplets are flagged.
- An image in a landmark will be flagged if the RSS of the pixel and line residuals in metric units (km) exceeds the input value
value 3 - the max scale (km/px) that sets the scale for the histogram at the end of PICINFO.TXT.
- The two criteria, km and pixels, allow flexibility when there are images of great range in resolution in the same landmark. These criteria also apply for outliers in the limb apparitions of images in landmarks and in the case of the metric criterion, second input parameter, for the map-to-map overlaps. The limb and overlaps outliers are collected in the file veto.txt and you can delete them from the landmarks by running lithos with veto.txt as input.

Here is a sample of inputs for residuals:

     10, 0.01, 0.01

Here is a sample MAPINFO.TXT file:

Here is a sample of a single landmark in RESIDUALS.TXT:

The following shows what a bad and a fixed image look like:

Figure 00: Results from Using Residuals to Improve Processing

Additional Reference

Qualitative Checks

residuals is not the only way to check how well SPC performed. You can simply observe the maplets generated.

Here is a list of what to look for when you visually inspect a maplet to judge its quality:

Verify that the quantitative error estimates are believable.
Render a single maplet, or a DEM synthesized by a collection of maplets, at the same geometry and illumination conditions as the images themselves.
Determine if all the features in the images appear in the DEM.
Determine if the smallest discernible features in the images (e.g., boulders, craters etc.) are visible in the DEM as well.
Determine if the relative albedo solution is such that the relative brightness of adjacent image features matches that of the DEM.
Determine if the heights solution is such that the length and overall appearance of the shadows in the DEM match those of the image.

How Uncertainties are Introduced in the Data

These are the main types of uncertainties and how they manifest:

S/C trajectory, camera pointing, image timestamp
- Manifest themselves mostly in the projection of image template onto the surface. Corrected by global geometry solution.
Image noise, artifacts, smear, overall image quality
- Manifest themselves in predicted image template brightness and in its fit to the extracted image brightness.
Photometric model and reflectance function models
- Show up in slopes and heights integration
Poor choice of a-priori parameters and data weights
- Are evident at the end of each estimation step. Data won’t fit well.

Often the above contributions are correlated; you may not be able to separate individual contributors until you have taken many processing steps.

Notes

If overlap and limb weights in INIT_LITHOS.TXT (i.e. PICWTS and LMKWTS keyword) are set to 0, then RESIDUALS.TXT will not display the residuals of these values.

(Compiled by KD)

shape_info

Category B

Version 3.0

Description

This routine produces the following useful information about a shape model:

Volume (km^3)
Surface area (km^2)
Center of figure offset from center of coordinate system (km)
Moment of inertial tensor assuming body is homogenous (per unit mass)
Last bit of information is unknown

Input Files

Shape file - You provide the filename as standard input.

Output

Display in this format:

Volume =      0.62119D-01
Area =        0.77755D+00
Offset =      0.95893D-03   -0.34589D-03   -0.91561D-03

              2.33664    -0.00537    -0.00069
I/M =        -0.00537     2.38540    -0.00717   x 10 ^ -2
             -0.00069    -0.00717     2.59532

dPM =         6.30695

Using shape_info

At the prompt, enter the filename for the shape file.

$/!\$ You must use the full path.

SHAPEFILES/SHAPE.TXT

(Compiled by KD)

shift

Category B

Version 3.0

Description

This program adjusts an entire shape file by a deltaX, deltaY and deltaZ. shift is typically used to adjust the center of figure to center of mass.

shift can also deal with the fact that sometimes a shape model's center of figure can drift off the 0,0,0 coordinate center, i.e. the middle of the asteroid is no longer at the origin of the system. In such cases, you can run shape_info and use its Center of Figure offsets as the input for shift.

Required Files

For adjusting shape file

<shapefile>.TXT -

For adjusting landmarks

Output Files

standard out -
<shapefile>.TXT -
LMKFILES -
MAPFILES -

Using shift

$/!\$ When you shift a shape file, only input the root name. Do not put in the fullpath or .TXT extension.
$/!\$ shift will continue to ask you "Shape shift?" until you enter 'n'. Do not enter 'y' more than once unless you want to shift more than once.

Here is a sample set of inputs for shift:

 Enter C0(i), i=1,3
0.66624D-03   -0.24253D-03   -0.13943D-02
 Shape shift? (y/n)
y
 Input shape name (eg SHAPE2)
TESTSHAPE
 Shape shift? (y/n)
n
 Shift maplets? (y/n)
y

 GEOMETRY
20
1
n
n

The final 5 lines copy and paste to update the rest of the system (updating SCOBJ and C_vector).

$/!\$ You must do this if you update the MAPLET positions.

(Compiled by EP)

spheremapsB

Category B

Version 3.0

Description

This program transforms maplet data from DTM to common formats and map projections for export.

SpheremapB reads the Zmap files and makes the resulting map line by line, which is more robust than bigmap. It creates:

a suite of data files for a bigmap (REFMAP)
a raw (simple binary) file of a 2D matrix for the scaled albedo (sample_ALB) and the topography (DEM)
images (pgm format) of the albedo, topography, and color scaled topography

Required Files

MAPFILES/ - a directory containing the full suite of maplets
MAPLIST.TXT - a file listing the map files. You must build this yourself.
- Note: You can only have 9,000 maplets in the file.

Output Files

<BIGMAP>_DTM.pgm - Bigmap pgm image file (grayscale)
<BIGMAP>_DTM.raw - Bigmap raw image file (simple binary) - same as the pgm, but without the header
<BIGMAP>_COL.ppm - Bigmap raw image file (colorized)
<BIGMAP>_ALB.pgm - Big albedo map pgm image file (grayscale)
<BIGMAP>_ALB.raw - Big albedo map raw image file (simple binary) - same as the pgm, but without the header

Using spheremapsB

The following sample shows the prompts and standard inputs for spheremapsB:

Note: "tolerance" below refers to how far away spheremapsB will look to find maplets. A value too big here may start grabbing maplets from the other side of the body.

  input ltd (deg), elon (deg), scale (km/px),
  half-sizes (px/ln), ref radius (km), tolerance (km)

 0, 0
 0.06250
 500, 500
 265
 50

  input map name

 ZN0000

 a. orthographic
 b. stereographic
 c. equirectangular

 c

  Enter reference latitude
 0


 a. 8  bit DTM
 b. 16 bit DTM

 a

 Enter i,j,h map shift (m) (eg map-lola)
   10.098592111467099        20.849462131360269     
 0, 0, 0

 Fix hmin, hmax? (y/n)
 n

 Set max slope (deg)
 60

 Lat/Lon markings? (y/n)
 n

Examples of different scales

Fill me out!!!

Object	Size	Scale	Half-Size	Ref Radius	Tolerance
Ceres	1000 km global
Moon	20km regional
Bennu	0.5km global
Bennu	50m regional

The following samples show outputs from spheremapsB for each of the identified elements:

Figure 00: Albedo Output from spheremapsB

Figure 00: Color DTM Output from spheremapsB

Figure 00: Grayscale DTM Output from spheremapsB

Additional Reference

[From spheremapsB.f]

C     This procedure re-samples the surface vectors providid ba a set of 
C     BIGMAPs onto a sphere with a radius characteristic of the body.  Id 
C     does so one outputline at a time so that arbitrarily large maps can 
C     be produced.
C
C     The procedure produces three types of map.  A simple digital 
C     elevation map (DEM) that provides te height above (or below) the 
C     reference sphere at each point in either 8- or 16-bit format, a 
C     shaded relief map (color coded with shading), and a relative albedo 
C     map.  This latter should be taken with a grain of salt, since the 
C     albedo solution from SPC is quite crude.  The DEM and albedo map are 
C     presented as both raw and as .pgm files, while the shaded relief is 
C     a .ppm file.  The raw files are included because they are easier to 
C     ingest into other systems such as ISIS.  The .pgm DEM file has a 
C     header that includes the ancillary information for the projection.
C     It can be read by any text editor.
C
C     Three types of projection are recognized by spheremapsB.  Orthographic and 
C     stereographis are usually used for polar projections while equirectangular 
C     (cylindrical) is used for oher regions, including the global DEM.  The program 
C     first asks for:
C
C          central latitude and east longitude in degrees,
C          the scale (km/px),
C          the half-sizes in pixel and line directions, 
C          ref radius (km),
C          tolerance (km)
C
C     The last entry is a search limit in case one of the maps has some bad data in it
C     and is displaced too far from the expected height.
C
C     The user then enters a name for the map, MAPNM.  Note that his does not have to be 
C     6-characters.  Then the user chooses the projection:
C
C          a. orthographic
C          b. stereographic
C          c. equirectangular
C
C     If a or b is chosen, the user enters a cone angle.  For example, if the cone angle 
C     is 70 degrees and the central latitude is 90 degrees, then the map will cover from 
C     20 degrees north to the pole.  If c is chosen, the user is asked for a reference 
C     latitude.  At that latitude, the pixels are square at a resolution equal to the 
C     scale chosen above.  Poleward, the pixels are at higher resolution in the east-
C     west direction.  If the longitude range of the plot is to be DLON and Q is the 
C     half-size in pixels in the east-west direction, then 
C
C          2*Q*scale=R0*cos(Rlat)*DLON*pi/180
C
C     In particular, if we want a global DEM at, say 32 pixels per degree then DLON=360,
C     2*Q=360*32 and if Rlat=0 then scale=R0*pi/32*180.
C
C     After deciding on the type of projection and its parameters, the user is asked:
C
C          a. 8  bit DTM
C          b. 16 bit DTM
C
C     where if the latter is chosen the data will be "unsigned short" (MSB).  The next 
C     choice is:
C
C          Fix hmin, hmax? (y/n)
C
C     If 'n' is chosen, the minimum and maximum heights will be those found for the 
C     entire map.  On occasion,  especially if multiple maps are used to cover the body,
C     we want to use the same values for all maps and if ''y is chosen we enter those 
C     values next.
C
C          Set max slope (deg)
C
C     The shaded relief map MAPNM_COL.ppm has both color coded heights and slopes 
C     determined by pixel differencing so the maps appear to be illuminated from the 
C     left.  The maximum slope, usually set to 45 degrees, sets the scale for the 
C     apparent illumination.   A final choice is:
C
C          Lat/Lon markings? (y/n)
C
C     If 'y' is chosen, the user inputs spacings for lines of constant latitude and longitude 
C     to be marked in white on the MAPNM_COL.ppm.
C
C     The MAPNM_DEM.pgm file has a header that includes ancillary information for the 
C     projection.  For equirectangular projection the header looks like:
C     
C          P5
C          #PROJECTION = EQUIRECTANGULAR                                                   
C          #REFERENCE RADIUS =         255.00000                                           
C          #REFERENCE LATITUDE =         0.00000                                           
C          #      -90.0000000464        0.0000000000       90.0000000464   MN, CT, MX LAT  
C          #     -180.0000000928        0.0000000000      180.0000000928   MN, CT, MX LON  
C          #               17281                8641                       IMAX, JMAX      
C          #    0.9272061656D-01    0.1235028039D-02                       SCL, HTSCL      
C          #   -0.4309964495D+02    0.3783668255D+02                       HTMIN, HTMAX    
C          #    0.2550000000D+03    0.0000000000D+00    0.0000000000D+00   VLM             
C          #    0.0000000000D+00    0.0000000000D+00   -0.1000000000D+01   UX              
C          #   -0.0000000000D+00    0.1000000000D+01    0.0000000000D+00   UY              
C          #    0.1000000000D+01    0.0000000000D+00    0.0000000000D+00   UZ              
C          17281 8641
C          65535
C
C     where the lines without # specify the .pgm format.  For orthographic and stereographic 
C     projections, the heaer looks like:
C
C          P5
C          #PROJECTION = STEREOGRAPHIC                                                     
C          #REFERENCE RADIUS =         250.00000                                           
C          #               10401               10401                       IMAX, JMAX      
C          #    0.1000000000D+00    0.1235079957D-02                       SCL, HTSCL      
C          #   -0.3810336140D+02    0.4283636848D+02                       HTMIN, HTMAX    
C          #    0.0000000000D+00    0.0000000000D+00    0.2500000000D+03   VLM             
C          #    0.1000000000D+01    0.0000000000D+00    0.0000000000D+00   UX              
C          #    0.0000000000D+00    0.1000000000D+01    0.0000000000D+00   UY              
C          #    0.0000000000D+00    0.0000000000D+00    0.1000000000D+01   UZ              
C          10401 10401
C          65535

JRW Notes after further testing:

HTMIN and HTMAX is the min and max vertical distance of the DTM in km. These values are deviations from the reference radius entered (i.e. after the half sizes and before the tolerance). So if the reference radius is entered as the lowest radius of the map, then HTMIN will be zero (or near zero with rounding error).
SCL is the distance in km you entered in for scale (i.e. the third number entered (i.e the one after lat and elon).
HTSCL is determined by taking the total distance from HTMIN to HTMAX and dividing by the number of bytes (256 for 8-bit and 65536 for 16-bit)

JRW discussion with Bob Gaskell on 25 Aug 2020

The HTMIN and HTMAX are determined from the min and max of the maplets; they are NOT the min and max of the final product, which is a weighted average of the maplets.
The input option of "Fix hmin, hmax?" is usually "no", but would be "yes" if making multiple final products so that all products have the same min and max.
DN of zero means "No Data"
DN of 1 corresponds to HTMIN. If the HTMIN is less than the min of the final product (which is usually the case because of averaging), the smallest DN of the pgm is greater than 1.
DN of 65535 (for 16-bit) corresponds to HTMAX. If the HTMAX is greater than the max of the final product (which is usually the case because of averaging), the largest DN of the pgm is less than 65535.
To convert DN to height from "REFERENCE RADIUS", take (DN - 1 ) * HTSCL + HTMIN (HTSCL is already adjusted by spheremapsB for 8-bit versus 16-bit)
When making global maps, Bob normally makes a stereographic map for each pole (60 to 90 deg for North and -60 to -90 deg for South) and an equirectangular map for 60 to -60 deg. This is an example of when you may want to "Fix hmin, hmax?"
When making a global map, Bob usually adjusts the size to make 16 pixels per degree. You can go larger, but often the files become more cumbersome than it is worth.

(compiled by JRW from material by EEP)

Example

Target	Sample Files
Bennu	sphere_bennu_eq

Known Issues

Note: You can only have 9,000 maplets in the MAPLIST.TXT. The program will crash if you have more than 9,000.

Find template

(lithos Main Menu Option 0. Find template)

Description

This Main Menu option builds a template that is used to further align images.

Here is a sample of a template. This example comes from LMRK_DISPLAY1.pgm.

Figure 00: LMRK_DISPLAY1 Option Used to Align Images

This is after 2 iterations. The predicted templates do not look as sharp because 2 iterations are not sufficient to solve well for the slopes and albedo.

The odd rows are referred to as "extracted templates" because they are derived from the spacecraft pictures, but have been modified (orthorectified plus other alterations).
The even rows are referred to as "predicted templates" because they are derived from the maplet.

Many users refer to a "predicted template" as the "template", and the "extracted template" as "images." The template is the digital representation of the topography that is illuminated under the same conditions as the image immediately above the template found in each row.

SPC uses a template for aligning images using Align landmarks. It also adds image data to the template prior to building topography, which is also known as Find Heights). To do this

Select images you want to work with. Frequently, all are on (i.e., used) by default.
If you have a difficult image, you can toggle it off. For instance, if an image has a template that does not correlate well with the mean brightness template you can toggle it off so that during the current iteration run it does not contribute to the slope estimation.

Here is a sample display for Main Menu Option 0:

Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH? 0
 >0                                                                               

EE0001
Lat =    -6.819
Lon =   264.131
Rad =     0.266

    k    chi    lambda   phi     res  

    1   0.975   1.162   0.000   0.250      
    2   0.962   1.138   0.000   0.250      
   ...
   13   0.975   1.100   0.000   0.239      
   14   0.000   1.348   0.000   0.239

Here is an explanation of the elements shown in the sample above:

EE0001 - Landmark name

Lat = -6.819 - Latitude

Lon = 264.131 - Longitude

Rad = 0.266 - Radius from center of figure

k - Image number

chi - Correlation statistic for initial observed brightness versus predicted brightness

CHI0 - Correlation limit, defaults to 0.5, unless it's set in INIT_LITHOS.TXT The predicted brightness for a pixel in a maplet is given by
- B = LAMBDA*ETA*ILLUM(COS(I),COS(E),PHASE)+PHI
  - where

LAMBDA - Constant that serves to relate the topography manifested by the slopes leading to variations in I and E to the brightness measured by the imaging data.

ETA - relative albedo, normalized to 1 across the maplet I - incidence angle E - emission angle

PHI - Constant background in the brightness such as was observed due to atmospheric scattering in Viking Orbiter images of Mars. The PHI term is usually ignored by setting the parameter CHI0 = 1 in INIT_LITHOS.TXT. (If CHI < CHI0 then PHI = 0.)

res - The ratio of image resolution to maplet resolution (i.e., GSD). Larger numbers mean the image has a lower resolution than the maplet. Typically, we don't use pictures with res much greater than 4.

Suboptions

Main Menu Option 0. Find template has these suboptions:

 Picture to toggle
 a use all
 b use registered
 c use correlated
 0 end/continue
 q Quit

a use all - Includes all of the images in the calculation of the template (i.e., it removes the * from all images).

b use registered - Typically not used. This option puts a "*" on any image that has not been added to a landmark. It assumes that such images have not yet been registered.

c use correlated - Prompts you to enter a number between 0-1. It then compares the number you entered with the correlations from the last alignment performed. It excludes images below the entered value. This will be noted by putting a "*" after the "res" column for each image that has been toggled off.

0 end/continue - Begins template iterations.

You will then be prompted to:
- Enter number of iterations - Enter in the number of iterations to perform when building the template.
  - Usually enter '40', after which you will see a display like this:.

 Enter number of iterations
40
 rms brightness residual =     9.30908314089276545E-003
 rms brightness residual =     9.27805039374508290E-003
...
 rms brightness residual =     8.68283596819066118E-003
 rms brightness residual =     8.67799102637487052E-003

 slope sigma =   5.30813855279686289E-002

  -0.03482   0.11297  -0.03439   0.00162  -0.04342   0.04161

 gc tmpl.pgm

After the iterations are finished, you will return to the Main Menu.

q Quit - go back to the Main Menu

Hidden Suboptions

The following suboptions are available but are not shown in the list:

# Image number - Instead of entering 'a', 'b', or 'c', you can enter the image number.

For example: '2', then "Enter" If you enter an image number, the program will toggle the "selected" flag (*).

#, # - Similar to above, but indicates a range of images. If you enter a range of images, the program will toggle the "selected" flag (*) for all images within that range.

Using Option 0. Find Template

You will often start with some initial topography that you can align from, as shown here:

The pictures in these samples do not exactly match the text because they came from different landmarks.

Figure 00: Example of Landmarks That Can be Used for Initial Manual Alignment

Typically, you do an alignment to make sure the images are correctly aligned. If they are not, you'll want to exclude them from the "Find template" calculation.
- Most of the time it will be an auto-align. If an image does not correlate well or it shows a predicted landmark location that cannot be auto-aligned it may have the be a manual alignment

The display output from an auto-align looks like this:

 enter spacing
 1           
   1   P3T11M2H0217        0.009    -0.040     0.340 +    
   2   P3T11M2H0218       -0.004    -0.074     0.398 +    
   3   P3T11M2H0219       -0.074    -0.020     0.290 +    
   4   P3T11M2H0220       -0.002    -0.173     0.366 +    
   5   P3T11M2H0221        0.060     0.000     0.609 +++  
   6   P3T11M2H0222        0.036    -0.003     0.600 +++  
   7   P3T11M2H0223        0.029     0.005     0.489 ++   
   8   P3T11M2H0224        0.037     0.011     0.593 +++  
   9   P3T11M2H0225       -0.016     0.018     0.473 ++   
  10   P3T11M2H0226       -0.020     0.020     0.379 +    
  11   P3T11M2H0229       -0.003     0.010     0.658 +++  
  12   P3T11M2H0230       -0.013     0.008     0.678 +++  
  13   P3T11M2H0231       -0.001    -0.029     0.534 ++   
  14   P3T11M2H0232        0.000    -0.038     0.542 ++   
     0.031     0.049

From the Main Menu, enter in '0', 'c', '0.5'. This will toggle off all images that had a correlation below 0.5, then bring you back to the Main Menu. To see the result of toggling off those images, you'll have to go back into the "Find template" menu.
Enter 0 again. The display output looks like this:

    k    chi    lambda   phi     res  

    1   0.000   1.983   0.000   1.288      
    2   0.000   1.383   0.000   1.288      
    3   0.000   1.405   0.000   1.276      
    4   0.000   1.666   0.000   1.174      
    5   0.000   1.993   0.000   1.174      
    6   0.000   1.679   0.000   1.183      
    7   0.000   1.616   0.000   1.183      
    8   0.000   1.714   0.000   1.219     *
    9   0.000   1.452   0.000   1.219     *
   10   0.000   1.781   0.000   1.263     *
   11   0.000   1.394   0.000   1.263     *
   12   0.000   1.821   0.000   1.276     *
   13   0.000   1.732   0.000   1.237     *
   14   0.000   1.469   0.000   1.237     *

There were 7 images from the auto-align that had a correlation below 0.5. Now 7 images have a * by them. Also note that lithos has moved the images with a correlation below 0.5 to the bottom of the list. In other words, those image values have changed.
For typical iterations, use 0, 0, 40.
- The text output will look similar to the sample above from "0 end/continue"

At this point, LMRK_DISPLAY1.pgm looks like the following. Notice that the image is not only brighter, but a bit sharper as well.

Figure 00: LMRK_DISPLAY1 Output for Well Aligned Images

Additional Reference

From LITHOS.f

This process solves for the slope and albedo distribution for a landmark template by minimizing the brightness residuals between the predicted and observed image data. It first uses the subroutine FIND_LAMBDA to determine an overall constant brightness scale (lambda) for each image as well as a possible background (phi). The background is set to zero if the correlation chi between initial observation and prediction is less than some preset value (chi0) whose default value is 0.5. In practice, we usually dispense with phi altogether by setting CHI0=1 in INIT_LITHOS.TXT, so lambda is the only parameter that matters. Look at the abstract in FIND_LAMBDA_PIC for more details.

The process produces a table with entries:

k chi lambda phi res pflag

The column label k is the number of the image as it appears in the landmark display and res is the ratio of the image resolution ot the landmark scale. The last column, pflag, is empty if the image data is to be used in the slope/albedo determination and * if it is not.

(Compiled by JRW)

Align landmarks

(lithos Main Menu Option 1. Align landmarks)

Description

This Main Menu option is used to align all the images in a landmark. After you complete the alignment, you can then build a template (Find template) and build topography (Find heights).

Suboptions

When you choose Option 1. Align landmarks from the Main Menu, you will see this set of Suboptions:

Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH? 1
 >1                                                                               

 0. Auto align
 1. Individual shift
 2. Global shift
 3. Align with picture
 4. Align with gradient
 q. Quit

0. Auto align - Aligns images to the template.

Here is a sample of the display for 0. Auto align:

    k     picnm            lambda      phi      cvg       nlmk  

    1   P3T11M2H0217        1.158     0.000     0.871     846
    2   P3T11M2H0218        1.138     0.000     0.871     857
    3   P3T11M2H0219        1.373     0.000     0.881     853
    4   P3T11M2H0220        1.063     0.000     0.881     871
    5   P3T11M2H0222        1.067     0.000     0.942     856
    6   P3T11M2H0223        1.378     0.000     1.000     858
    7   P3T11M2H0224        1.061     0.000     1.000     875
    8   P3T11M2H0225        1.166     0.000     0.928     848
    9   P3T11M2H0226        1.135     0.000     0.929     866
   10   P3T11M2H0227        1.105     0.000     0.850     854
   11   P3T11M2H0228        1.361     0.000     0.851     868
   12   P3T11M2H0229        1.091     0.000     0.965     849
   13   P3T11M2H0231        1.100     0.000     1.000     855
   14   P3T11M2H0232        1.348     0.000     1.000     872

 gc LMRK_DISPLAY0.pgm
 gc LMRK_DISPLAY1.pgm

 check display

 enter spacing

The auto-align display includes these elements:

k - Image number
picnm - Image (picture) file name
lambda - Overall brightness scale factor (See Find template.)
phi - Background brightness factor (See Find template.)
cvg - Coverage. This is the fraction of image that is found in the landmark.
nlmk - Number of landmarks that use this image. (You can also think of this as each landmark that has been added to the image.)

Auto-align requires these additional inputs:

enter spacing - This input sets the number of pixels that lithos is allowed to shift the image.
1. Enter a number between 1 and 5.
  - The lower the number, the fewer number of pixels lithos is allowed to shift the image. '1' searches a 5x5 pixel area, '2' a 10x10 and so on. A display indicates the number of pixels moved in both x and y, and the new correlation factor for the new image location.
2. Respond to each of these suboptions:
3. new spacing? y[n] - You can choose a new number if you don't like the results. "Enter" defaults to "no."
  - 0. continue. (default) - You can continue with current positions. 'Enter' defaults to this selection.
  - 1. halve shifts. - This moves the image half the distance spacing calculated. (This can help with images that want to bounce between two locations.)
  - 2. quarter shifts. - This choice is similar to above, but it only shifts the image one quarter of the distance.
4. Update landmark pixel locations? y[n]
  - 'y' saves the new position and returns to the Main Menu
  - 'n' discards the changes and returns to the Main Menu
  - 'Enter' defaults to 'n'

1. Individual shift - Shifts an individual image.

Enter the Image number (i.e., "k" value) that you want to shift.
Enter the number of pixels to shift
- the x distance (positive moves to the right
- the y distance (positive moves down)
Enter the next Image number (i.e,. "k" value) and proceed as before.
- When you're finished with the individual shifts
Enter "0" to quit to the Main Menu.

2. Global shift - Shifts all images the specified amount.

Enter the x and y pixel shifts. You will then be asked:
Update vector? (y/n) Choose 'y' if you want to do a "v1" (from Find_V_Z_or_PTG).

3. Align with picture - You select one image, and then SPC aligns all the other images to it.

First, enter the number associated with the image you want to align to. Enter spacing as in "Option 0" above. This is used sometimes when auto-align isn't working and you don't want to align pictures by hand.
This option doesn't always work because of differing illumination conditions. Note that using this option will move the reference image to position #1 and will flag or "turn off" all the other images. You will need to perform a 0-a from the Main Menu to add them all back.

4. Align with gradient - This option is like auto-align (Option 0) except that it uses the gradients normal to the sun direction instead of the template.

This is used in the same situation as "Align with picture" and sometimes works better. Like option 3, option 4 will "turn off" all images that are not the selected image. You will have to add these back before you build a template.

q. Quit - Quit to the Main Menu.

Typical Example

The following sample shows the screen output from entering:

Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH? 1
 >1                                                                               

 0. Auto align
 1. Individual shift
 2. Global shift
 3. Align with picture
 4. Align with gradient
 q. Quit
0
 0


    k     picnm            lambda      phi      cvg       nlmk  

    1   P3T11L2H0201        1.158     0.000     0.881      96
    2   P3T11L2H0202        1.155     0.000     0.877      96
    3   P3T11L2H0203        1.354     0.000     0.879      94
    4   P3T11L2H0204        1.072     0.000     0.879      96
    5   P3T11L2H0206        1.057     0.000     0.945      97
    6   P3T11L2H0207        1.351     0.000     1.000      95
    7   P3T11L2H0208        1.070     0.000     1.000      97
    8   P3T11L2H0209        1.159     0.000     0.934      96
    9   P3T11L2H0210        1.161     0.000     0.934      97
   10   P3T11L2H0211        1.084     0.000     0.853      96
   11   P3T11L2H0212        1.355     0.000     0.853      94
   12   P3T11L2H0213        1.070     0.000     0.955      96
   13   P3T11L2H0215        1.082     0.000     1.000      96
   14   P3T11L2H0216        1.355     0.000     1.000      93

 gc LMRK_DISPLAY0.pgm
 gc LMRK_DISPLAY1.pgm

 check display

 enter spacing
1
 1           
   1   P3T11L2H0201        0.028     0.029     0.968 +++++
   2   P3T11L2H0202       -0.048     0.026     0.941 +++++
   3   P3T11L2H0203        0.038     0.026     0.909 +++++
   4   P3T11L2H0204       -0.051     0.011     0.955 +++++
   5   P3T11L2H0206       -0.053     0.003     0.961 +++++
   6   P3T11L2H0207        0.031    -0.020     0.930 +++++
   7   P3T11L2H0208       -0.054    -0.006     0.957 +++++
   8   P3T11L2H0209        0.030    -0.010     0.971 +++++
   9   P3T11L2H0210       -0.052    -0.017     0.947 +++++
  10   P3T11L2H0211        0.029     0.001     0.977 +++++
  11   P3T11L2H0212       -0.051    -0.023     0.910 +++++
  12   P3T11L2H0213        0.030     0.007     0.974 +++++
  13   P3T11L2H0215        0.028     0.015     0.974 +++++
  14   P3T11L2H0216       -0.047     0.021     0.878 +++++
     0.041     0.017

 new spacing? y[n]
n

 0.  continue. (default)
 1.  halve shifts. 
 2.  quarter shifts. 
0
 0

 Update landmark pixel locations? y[n]
y
 y

 Current landmark = EE0001
SCALE =  0.000100 QSZ =   49
 Lat/Lon/Rad =     -6.800   264.090     0.266
 Region = EE

 gc LMRK_DISPLAY0.pgm
 gc LMRK_DISPLAY1.pgm


 check display
Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH?

(Compiled by JRW)

Find heights

(lithos Main Menu Option 2. Find heights)

Description

This Main Menu option solves for the brightness and slope of each pixel. It includes a variety of options, including stereo and photoclinometry.

Suboptions

When you choose Option 2. Find heights from the Main Menu, you will see this set of Suboptions:

Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH? 2
 >2

 TOOLS
 0. Begin integration
 1. Auto include neighboring maps
 2. Include existing heights
 3. Include shape vectors
 4. Include limb vectors
 5. Include external map
 6. Include differential stereo
 7. Include shadowing
 8. Fill with shape
 9. Include control points
 Q. Exit

0. Begin integration - Provide these inputs:

Weight for the conditioning heights - Always use .025.

Whether to use weight 0.025 or not depends on a number of factors. Often in the first slope to height integration you may want to use a smaller number, 0.01. Also if you have a large number of overlapping maps and the seeds.pgm plot looks very dense, you may want to decrease the weight so as not to over constrain the solution with too many seed heights. Also, if some of the conditioning heights are derived from maps that have poorly determined heights, you should decrease the value of the weight to even less than 0.01. If this does not improve the heights integration, you may skip options 1 and 2 and use option 6 before you perform the heights integration.

Number of iterations - Typically use 30.
After the iterations are finished, enter one of these choices:
- '0' to go back to the Main Menu
- '1' to input more iterations
- '2' to change the weight

1. Auto include neighboring maps - Includes data from surrounding maplets that have been added to the "overlap" list.

If you are building a maplet for the first time, there won't be any overlaps assigned, so this option won't be needed until later.

2. Include existing heights - Use this option most times. You dn't have to use this option if you include an external map.

This option uses heights from the existing topography as conditioning heights, with the fraction input by the user (typically 1%). Therefore, this option weights data from the current maplet as well, and that way the changes will occur slowly and will remain stable.

3. Include shape vectors - This option is seldom used, perhaps only in the beginning stage of creating the first set of landmarks.

4. Include limb vectors - Constrains the solution by using limb data.

This option prompts you to enter expansion, res/scale limit, d_hgt limit. Entries can be separated by 'Enter', ' ', or ','. "Expansion" is included only for backwards compatibility, "res/scale limit" refers to the resolution of the pictures that it searches for limbs, and "d_hgt limit" refers to the distance away (in number of pixels) it will search for limbs. d_hgt limit is similar to the Enter spacing prompt from Align landmarks (i.e., you need to enter a number between 1 and 5). Typically, use the values 1, 2.5, 3 for these entries.

5. Include external map - You can use an external map, often a big map, to provide seed heights for the slope to heights integration.

You have to input a map name and a fraction of points just like when using editing heights.
If the input to the "fraction of points" is < 0.0001 then instead of seed heights use slopes directly derived from the external map. Doing so means that you can skip options 1 and 2 and go directly to option 0 integration.

6. Include differential stereo - This option calculates stereo points at random locations on the maplet. Testing has shown that this option is a good way to keep maplets from tilting at the edges.

After you enter this option, respond to these prompts:
- use gradients - enter 'y'
- autoheights - enter 'y'

7. Include shadowing - This is still an experimental procedure. It will be tried thoroughly when there's significant shadowing in the images used for the map in question.

8. Fill with shape - This option uses the shape model to fill any "holes" in the maplet, if they exist.

9. Include control points - This option is rarely used. It will use landmarks as seed heights.

Q. Exit - Exit to the Main Menu.

Typical Example

The following sample shows how to use 2. Find heights when starting at the Main Menu.

Sometimes options 6 or 7 (or both) will be removed, but the others are typically present.

2         <- Find heights option
8         <- Fill w/ shape
2         <- Include existing heights
.01       <- weighting
1         <- Include overlaps
4         <- Include limbs
1, 2.5, 3 <- inputs for limbs
7         <- Include extended shadowing
6         <- include stereo
y         <- use gradients
y         <- use auto heights
0         <- Begin integration
.025      <- weighting
30        <- number of iterations
0         <- End iterations

The following sample output begins with the '0' input for Begin integration:

0
 0
 gc seeds.pgm

 input weight
.025
 Enter number of iterations
30
    -0.33759     0.34356    -0.34050     0.41873

 gc slope.pgm

    -0.28767     0.27729    -0.25837     0.36825

 gc slope.pgm

...
    -0.22599     0.18857    -0.16774     0.26969

 gc slope.pgm

    -0.22600     0.18859    -0.16777     0.26958

 gc slope.pgm

 0. end iterations
 1. more iterations
 2. change weight
0
 -8.18594598952327801E-006

 Current landmark = EE0001
SCALE =  0.000100 QSZ =   49
 Lat/Lon/Rad =     -6.800   264.090     0.266
 Region = EE

 gc LMRK_DISPLAY0.pgm
 gc LMRK_DISPLAY1.pgm


 check display
Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH?

Additional Reference

1. Auto include neighboring maps

[From LITHOS.f] - This provides conditioning heights from overlapping maplets. Points on the overlapping maplet are chosen randomly according to a fixed formula that provides more points (up to 5%) if the overlapping maplet is higher resolution than the target maplet, 2.5% if resolutions are the same and dropping to zero at low resolution overlap. The projection is done by the subroutine GET_MAP (see abstract).

3. Include shape vectors

[From LITHOS.f] - This option provides conditioning heights from the existing shape model, with a fraction set by the user and heights from the subroutine GET_HEIGHTS. Option 3 is almost never used.

4. Include limb vectors

[From LIMB_HEIGHTS.f] - There are three user input search parameters. ZEXP is an expansion parameter that is always set to 1 but is kept for backward compatibility with old scripts. ZRES restricts the image RESOLUTION (in km/px) relative to the maplet SCALE: RESOLUTION < ZRES*SCALE. ZHGT is the maximum allowed difference between predicted limb point height on a maplet and the measured height in units of maplet SCALE.

5. Include external map

[From LITHOS.f] - This option gets conditioning heights from an externally produced map, with a fraction set by the user and heights from the subroutine GET_MAP (see abstract). If the fraction is set to zero, the option fills missing data areas with slopes from the external map, in much the same way as option 8, but with less granularity. If used in this context, option 5 should always be used before option 8. Note that this option may be used twice, once to provide conditioning heights and once to fill in missing slopes. Option 5 is the natural interface between SPC and other sources of topographic data such as SPG or scanning lidar.

6. Include differential stereo

After you enter this option, respond to these prompts:
- use gradients - enter 'y'
- autoheights - enter 'y'
[From LITHOS.f] - This option determines conditioning heights from differential stereo. Features in a maplet move on trajectories as their heights change, owing to the obliqueness of its appearance in an image. The subroutine STEREO (see abstract) uses differences in these trajectories from image to image to determine conditioning heights.

7. Include shadowing

[From LITHOS.f] - Occasionally, a template will contain no data because a portion is not illuminated in any image. This option determines the maximum height that such a point can have and still be in shadow according to existing topography and randomly uses such values as conditioning heights. This is still an experimental procedure. It produces craters, for example, with sloped ramps in permanently shadowed areas.

9. Include control points

[From LITHOS.f] - This option is some paleocode that uses landmark centers as conditioning heights. It is never used.

(Compiled by JRW)

Attach map to maps or limbs

(lithos Main Menu Option O. Attach map to maps or limbs)

Description

This Main Menu option searches for overlaps and limbs for the specified maplet.

Suboptions

When you choose Option O. Attach map to maps or limbs from the Main Menu, you will see this set of prompts and Suboptions:

Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH? O
 >O
 Input 6-character landmark name.
r

 Reset all? (y/n)
n

 1. Automatic
 2. Manual
 3. Limbs
 4. Detach from limb or landmark
 0. Quit

Input 6-character landmark name. - Enter the landmark in one of these ways:

by name - for example, 'EE0001'
by typing 'r' or 'RECENT'
- Both "r" and "RECENT" substitute for the last loaded landmark.

Reset all? (y/n) - Respond to this prompt to either:

reset all overlaps - 'y'
leave them as is - 'n'
- Typically, use 'y' in case drifting causes maplets to no longer overlap one another.

1. Automatic - Automatically searches for maplets that physically overlap with the loaded landmark. "Physically overlap" means maplets whose center, GSD, and Q size indicate that they should overlap. Diagnostics will indicate if the albedo and heights are a match between the current maplet and another maplet, and will determine the position of each maplet on the loaded maplet (and vice versa). After these searches are performed, you will return to the Main Menu.

2. Manual - This option allows you to enter overlaps manually.

3. Limbs - Searches for pictures that have this landmark at their limb, thus constraining the distance from the center of the figure to the center of the maplet. After you choose this option, respond to these prompts:

clear the existing limbs? (y/n) - 'y' is the default
Input expansion, res/scale limit, d_hgt limit
- These inputs are similar to those used when building topography (Find heights). The values entered for 3. Limb search a wider area than those used when building topography.

4. Detach from limb or landmark - Enter the name if you want to remove an overlapping landmark/limb picture from the current landmark.

Typical Example

The following sample shows how to find overlaps and limbs. At the Main Menu,

load the landmark of interest
enter the following inputs

o
RECENT
y
1
o
RECENT
n
3
y
1, 3, 5

The first 4 lines find landmark overlaps. The remainder of the lines are typical for finding limbs.

Successful overlap

This sample shows a successful overlap output for each landmark that has a physical overlap:

EE0045
  0.0292  0.0321  0.9441  0.9996
  0.0069  0.0058  0.9442  0.9996
  0.0011  0.0011  0.9444  0.9996
  0.0002  0.0003  0.9445  0.9996
    0.0374    0.0393   -0.0031

EE0001
 -0.0107 -0.0742  0.7028  0.9995
 -0.0058 -0.0063  0.7082  0.9995
 -0.0024 -0.0004  0.7082  0.9995
 -0.0004  0.0002  0.7080  0.9995
   -0.0193   -0.0807    0.0060

The outputs for each landmark originate from the subroutine ATTACH.f, which determines the relative central vectors of two overlapping maplets as follows:

The overlapping maplet (LMK1) is projected into the coordinate system of the maplet-of-interest (LMK0).
A correlation is found by shifting LMK1.
The LMK0 central vector is updated.

This process is repeated for a total of four iterations. Here are the elements of the output:

Lines 1-4 are outputs for each iteration:
- Column 1 - pixel shift
- Column 2 - line shift
- Column 3 - correlation
  - Correlation depends on the INIT_LITHOS.TXT CORRFLAG parameter:
    - 0 - Laplacian; 1 - albedo; 2 - gradient; 3 - Laplacian/albedo
- Column 4 - height correlation.]
Line 5:
- Column 1 - Total pixel shift;
- Column 2 - Total line shift;
- Column 3 - Average delta height.

Unsuccessful overlap

The overlap could also fail. In that case, it will throw a "below albedo correlation limit" or "below height correlation limit" in place of the rows of numbers.

Here are three samples of unsuccessful overlaps:

EE0126
  4.0764 -4.0374  0.2320  0.9825
  4.0366 -3.9734  0.2779  0.9730
  0.0072  0.0071  0.2842  0.9720
  0.0032  0.0021  0.2850  0.9720
  8.1234 -8.0016 -0.5042

EE0026
 No fit. Below height correlation limit
 HCOR =    7.1556346300126000E-002

EE0153
 No fit. Below albedo correlation limit
 ACOR =   0.29595196946445101

EE0043
 No fit. Below albedo correlation limit
 ACOR =   0.26043611639795511

EE0139
 No fit. Out of test area.

EE0025
 -2.2376 -2.8146  0.6090  0.9580
 -0.0506 -0.0554  0.6210  0.9581
 -0.0065  0.0016  0.6219  0.9580
 -0.0007  0.0003  0.6217  0.9580
 -2.2954 -2.8681 -3.0862

(Compiled by JRW)

Input landmark

(lithos Main Menu Option I. Input landmark)

Description

This Main Menu option loads (inputs) a maplet into memory.

Suboptions

When you choose Option I. Input landmark from the Main Menu, you will see the following set of prompts and output:

You can also enter "r" or "RECENT" to load the previously loaded landmark.

Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH? i
 >i

 Input 6-character landmark name.[Q]
EE0001
    -0.48481     0.53724    -0.55314     0.60718

 gc slope.pgm


 Check for more images? y[n]
n
 Include a single image? y[n]
n

 Current landmark = EE0001
SCALE =  0.000100 QSZ =   49
 Lat/Lon/Rad =     -6.800   264.090     0.266
 Region = EE

 gc LMRK_DISPLAY0.pgm
 gc LMRK_DISPLAY1.pgm


 check display
Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH?

Check for more images? y[n] - Usually respond 'n'. Most times when you load a landmark you will not be adding new images. If you do need to add images, see below the line break.

Include a single image? y[n] - Usually respond 'n' (the default). Most times you will want to load all images that have been added to the landmark.

If you select 'y', you will define the image explicitly. You must provide the name of the image you want to add. It will prompt you to add it automatically, in which SPC will attempt to determine the pixel/line location of the landmark within the images. If you want to enter the pixel/line location manually, you can do that. If you have entered an image in this way, you will be asked whether you want to enter another one.

If you select 'y', you must input a picture name.

If you enter 'y' for "Check for more images? y[n]" you will see these prompts and outputs:

 Check for more images? y[n]
y

 Enter fractional width (0=center).
.5

 Reject invisibles? y[n]
n

 PICTLIST.TXT
P3T11L2H0205    580.20    189.39
...
P3T11L2H0214    219.62    692.50

 Current landmark = EE0001
SCALE =  0.000100 QSZ =   49
 Lat/Lon/Rad =     -6.800   264.090     0.266
 Region = EE

 gc LMRK_DISPLAY0.pgm
 gc LMRK_DISPLAY1.pgm


 check display
Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH?

Enter fractional width (0=center). - Typically, use 0.5. This asks for the fraction of the image that can be seen in the landmark.

Reject invisibles? y[n] - Typically, enter 'n' (default). This prompt asks whether you want to include images where portions of the landmark will be blocked by some object in the front. For example, if most of the loaded landmark is of a crater, but immediately south of the crater is a large boulder, then all images taken from the south will have a boulder in the way and this boulder will be obscuring the crater. Enter 'n' to include as many images as possible; the images that would have been excluded are usually dealt with once they will no longer align properly.

The program then searches one of four files files to identify images to add:
1. PICTLIST.TXT - the list of all images
2. PICTLISTR.TXT - a restricted PICTLIST created by the user
3. PICTLISTX.TXT - an extended pictlist containing additional data to speed up processing
4. PICTLISTRX.TXT - the extended version of PICTLISTR.
The program searches in the order 4,2,3,1 and uses the first file found.

Typical Example

The following sample shows the inputs for a typical use of Option I. Input landmark in which you load a maplet without adding images.

 i
 (Landmark)
 n
 n

If you want to add images to the landmark, your inputs will look like this:

 i
 (Landmark)
 y
 0.5
 n

(Compiled by JRW)

Update landmark files

(lithos Main Menlu Option U. Update landmark files)

Description

This Main Menu option is used to save the current state of the landmark. It saves the .LMK files and .MAP files.

Suboptions

When you choose Option U. Update landmark files from the Main Menu, you will see this set of Suboptions:

Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH? u
 >u

 Current hflag =F

 0. Landmark only
 1. Save map
 q. Quit

0. Landmark only - Only saves the .LMK file. This option is not used often.

1. Save map - Saves the .LMK file and the .MAP file.

SAVE OFTEN! Use this option frequently to save work in progress.

q. Quit - Returns to Main Menu.

(Compiled by JRW)

Create new landmark

(lithos Main Menu Option C. Create new landmark)

Description

This Main Menu option is used to create a new landmark. The location of this landmark will depend upon one of three inputs:

a pixel/lin location in a picture
a latitude west longitude on a body
a pixel/line location in a maplet/bigmap

Once you create a landmark, it will not have any images included, and will have no topography.

To add topography - use Main Menu Option B. Get heights from surrounding map
To load images,
1. Save the maplet
2. Load it again
3. Choose option 'y'

Suboptions

When you choose Option C. Create new landmark from the Main Menu, you will see this set of prompts:

Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH? c
 >c
 Input 6-character landmark name. [Q]
TEST01
 pixlinpic (p) or ltdlng (l) or map p/l (m)?
l
 Input ltd, wlng (deg)
0 0
 Enter scale (km/px), qsz
.001 49


 Current landmark = NONE
Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH?

pixlinpic (p) - Enter 'p' to select the location of the center of the landmark from the location of a pixel/line value in a picture.

Enter a picture name (12 characters).
lithos will ask for a pixel/line location from the image.
- '0, 0' would be the upper left pixel/line location of the image

ltdlng (l) - Enter 'l' (lowercase "L") to select the location of the center of the landmark from latitude/longitude.

Enter the latitude/longitude, where the longitude is west longitude.

map p/l (m) - Enter 'm' to select the location of the center of the landmark from the location of a maplet/bigmap.

Enter the maplet/bigmap name (6 characters).
Enter the pixel/line location.
- '0, 0' selects the upper left of the maplet/bigmap

After you have input values for either p, l or m:

Enter scale (km/px), qsz

Enter the GSD in km - .001 is 1m
Enter the Q size - 49 (standard procedure)

(Compiled by JRW)

Replicate or Rename landmark

(lithos Main Menu Option R. Replicate or Rename landmark)

This Main Menu option either copies the landmark or renames it.

Suboptions

When you choose Option R. Replicate or Rename landmark from the Main Menu, you will see this set of prompts:

Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH? r
 >r
 Input 6-character old landmark name. [q]
TEST01
 Input 6-character new landmark name. [q]
NEW001
 Delete old landmark? y[n]
y

 Current landmark = NONE
Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH?

Delete old landmark? y[n] - Default (n) copies the landmark.

Enter 'y' to rename the landmark.
Enter 'n' to copy the landmark.

(Compiled by JRW)

Change scale, qsz or orientation

(lithos Main Menu Option S. Change scale, qsz or orientation)

Description

This option allows you to change the size of a maplet (both GSD and Q size) as well as rotate a maplet while keeping its body-fixed and image space positions unchanged. This second action can be useful if there is a difficult portion at the edge of a maplet that could be avoided.

Suboptions

When you choose Option S. Change scale, qsz or orientation from the Main menu, you will see this set of prompts:

Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH? s
 >s

SCALE =  0.000100 QSZ =   49
 Enter scale (km/px), qsz, cc window rotation (deg)
 [0 0 0 to quit]
.00001 49 0

Enter scale (km/px), qsz, cc window rotation (deg) -

Enter the new GSD
Enter the new Q size
Enter the number of degrees you want to rotate the landmark
$/!\$ Limbfits and overlaps are cleared and the slopes and albedos are re-initialized.

Here is a sample before using this option to change the scale:

Figure 00: Images Prior to Changing Scale and Orientation

Here is the sample after zooming out the scale.

Note that the template has now disappeared. It can be reloaded if needed.

Figure 00: Images After Changing Scale and Orientation (Template needs to be reloaded)

(Compiled by JRW)

Turn on rename

(lithos Main Menu Option G. Turn on rename)

Description

This option auto-renames all loaded landmarks based upon their location on the body. SPC bins portions of the body by the first two letters of the maplet name, with the first character representing latitude (A=90N-70N, B=70N-50N, ... I=70S-90S) and the second character representing longitude (A=00E-20E, B=20E-40E, ... R=340E-360E).

This Main Menu option is a toggle.

When lithos starts, Rename defaults to 'off'.
Enter 'g' to switch it (off to on or on to off).
You will usually want renaming turned on, but at times (such as when hand tiling) it's useful to leave it off.

(Compiled by JRW)

Find normal

(lithos Main Menu Option N. Find normal)

Description

This Main Menu option calculates the normal vector to the maplet in one of several ways.

Suboptions

When you choose Option N. Find normal from the Main Menu, you will see this set of Suboptions:

Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH? n
 >n

 1. Normal from radius vector
 2. Normal from heights
 3. Normal from shape
 4. Normal from stereo
 q. Quit

1. Normal from radius vector - Sets normal the same as the radius vector. (Rarely used.)

$/!\$ Note that the normal is the same as the radius vector everywhere if the object is a sphere. Rarely will conditions on an asteroid be such that this option will be correct.

2. Normal from heights - Determines normal from the average of the heights in the maplet by fitting a plane to the current topography. (Used almost exclusively.)

3. Normal from shape - Determines normal from the shape model.

4. Normal from stereo - Determines normal from three common points in two images.

$/!\$ This option is occasionally used when the shape is extremely challenging and no good model yet exists. It requires manual determination of common points.

Typical Example

The following sample shows the command input for the most common suboption choice, '2':

n
2

(Compiled by JRW)

Find V, Z or PTG

(lithos Main Menu Option V. Find V, Z or PTG)

Description

This Main Menu option is used to calculate the radius vector of maplets, the spacecraft vector, and the spacecraft pointing.

Suboptions

When you choose Option V. Find V, Z or PTG from the Main Menu, you will see the following set of Suboptions that use these terms:

V - radius vector to the maplet
Z - pixel/line image space locations of the landmark (i.e., the image alignment)
PTG/SCOBJ - spacecraft pointing and position
nominal - the "initial" space pointing and position

Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH? v
 >v

 1.  V from Z and pointing
 2.  Z from V and pointing
 3.  PTG/SCOBJ from Z and V (selected image)
 4.  PTG/SCOBJ from Z and V (current images)
 5.  PTG/SCOBJ from nominal (selected image)
 6.  PTG/SCOBJ from nominal (current images)
 7.  RA/DEC/TW (selected image)
 q.  Quit

1. V from Z and pointing - Calculates the radius vector from the image alignment and the spacecraft data.

This is the most commonly used "v" option.

2. Z from V and pointing - Moves images to the alignment predicted by the radius vector and the spacecraft position/pointing.

3. PTG/SCOBJ from Z and V (selected image) - Determines the spacecraft position and pointing based upon the image alignment and radius vector of the maplet. This option asks you to input a specific image on which to perform this calculation.

$/!\$ Make sure that you have a stable system before you do this! You can move the spacecraft in the wrong direction if you are not careful!

4. PTG/SCOBJ from Z and V (current images) - Similar to option 3 above, but this option does the calculation for all images added to the landmark.

5. PTG/SCOBJ from nominal (selected image) - Resets the spacecraft position and pointing to the nominal (i.e., the original values determined for the mission). This option resets it for a single image.

6. PTG/SCOBJ from nominal (current images) - Same as option 5 above, but this option resets it for all images associated with the loaded landmark.

7. RA/DEC/TW (selected image) - Determines the inertial space orientation of the body-fixed frame (TIPM) at an image UTC with the experimental subroutine IPL2RDT and writes the orientation as RA, DEC, TWIST.

$/!\$ Work in progress. This is the wobble program(?) R. Gaskell is developing.

Common Usage

Most of the time, you will only be using option v1. Howewver, v4 is used after the model is stable to update the s/c information, and v2 can be helpful when images are not aligning properly. v2 can also be used when you suspect there is something wrong with the model. If the model has problems, the v2 option will manifest by wildly moving the image around.

$/!\$ This process reads the current .LMK and/or .SUM files as part of the processing. If you have made any changes, update (process U) the landmark before choosing Option V. Find V, Z or PTG.

(Compiled by JRW)

Reset albedo or slopes

(lithos Main Menu Option A. Reset albedo or slopes)

Description

This Main Menu option resets the albedo or slope. You can reset either slope or albedo, or both.

It is useful to reset slopes and albedos, for instance, when there is an artifact (such as from an improperly aligned image) that is giving trouble.

$/!\$ Doing this too often (such as while iterating) will degrade the shape since you keep throwing away useful information.

Prompts

When you choose Option A. Reset albedo or slopes from the Main Menu, you will see this set of Prompts:

Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH? a
 >a
 Reset slopes? (y/n)
y
 Reset albedos? (y/n)
y

(Compiled by JRW)

Get heights from shape model

(lithos Main Menu Option M. Get heights from shape model)

Description

This Main Menu option discards all information from the maplet and reloads it with data from the shape model. There are no prompts or suboptions.

This process is used during the initial stages of maplet construction when an initial surface curvature reduces distortion in extracted image data and sets the parameter lambda in the photometric function. During the next level of maplet construction, this process provides initial topography and albedo for the construction.

Typical Example

The following sample shows the screen output from entering Option M. Get heights from shape model:

Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH? m
 >m

 Current landmark = EE0001
SCALE =  0.000100 QSZ =   49
 Lat/Lon/Rad =     -6.806   264.097     0.266
 Region = EE

 gc LMRK_DISPLAY0.pgm
 gc LMRK_DISPLAY1.pgm


 check display
Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH?

(Compiled by JRW)

Get heights from surrounding map

(lithos Main Menu Option B. Get heights from surrounding map)

Description

This Main Menu option lets you load topography from a map. This option is similar to Get heights from shape model except that you must specify a bigmap or maplet.

Prompts

When you choose Option B. Get heights from surrounding map from the Main Menu, you will see this set of Prompts:

Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH? b
 >b
 List possibilities? (y/n)
y
 AUTOPICK? (y/n)
n
EE0002    0.0001    0.6040
EE0005    0.0001    0.6499
T11T10    0.0001    0.7937
T11T05    0.0000    0.7632
T11EV1    0.0000    0.7456
T11EVB    0.0000    0.9851
 input a 6-character landmark name. 0 to cancel

List possibilities? (y/n) - Enter 'y' to list all of the bigmaps and maplets that physically overlap with the current maplet.

Note that the overlap determinations from Option O. from the Main Menu do not affect the maps listed.

AUTOPICK? (y/n) - You have the option to let lithos autopick the maplet to load.

The display includes these elements:

Column 1: The map name list.

Column 2: The GSD of the map in km.

Column 3: The percentage of the current maplet that is covered by the listed map.

Although it is not listed, you can also load topography from the current maplet. This is sometimes useful when zooming in or out using Option S. Change scale, qsz or orientation.

(Compiled by JRW)

Turn on extract filter

(lithos Main Menu Option X. Turn on extract filter)

Description

This Main Menu option turns on shadow masking.

$/!\$ Use this almost always since you do not want shadows to be interpreted as topography.

The extract filter:

enhances shadows by extending them into the lit portion. This is done because shadows are not sharp, particularly if the image is lower in resolution than the maplet, and this is interpreted as topography by the lithos software.
zeroes out data in regions that, according to the current maplet topography, should not be seen in an image. In many cases the maplet is seen obliqely in the image and some areas, especially the bottoms of craters, cannot be seen. This action is accomplished by using both a restriction on emission angle and ray tracing.
zeroes out data in regions that, according to the current maplet topography, should not be in shadow. It does this through ray tracing.

Prompt

When you choose Option X. Turn on extract filter from the Main Menu, you will see this prompt:

Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH? x
 >x
 enter tolerance
.025

 Current landmark = EE0001
SCALE =  0.000100 QSZ =   49
 Lat/Lon/Rad =     -6.806   264.097     0.266
 Region = EE

 gc LMRK_DISPLAY0.pgm
 gc LMRK_DISPLAY1.pgm


 check display
Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH?

enter tolerance - Enter '.025' (the standard input).

(Compiled by JRW)

Delete or Disconnect landmark

(lithos Main Menu Option D. Delete or Disconnect landmark)

Description

This Main Menu option is used to delete or disconnect a landmark.

Prompt and Submenu

When you choose Option D. Delete or Disconnect landmark from the Main Menu, you will see this prompt and submenu:

Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH? d
 >d                                                                               
 Input 6-character landmark name. [q]
TEST01
 1. Delete
 2. Disconnect
 q. Quit
1
 Delete ENTIRELY? y[n]
y

 Current landmark = NONE  
Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH?

Input 6-character landmark name. [q] - Enter the landmark name.

1. Delete - Use this option to get rid of an unwanted landmark. You will see this prompt:

Delete ENTIRELY? y[n]
- Enter 'y' to delete all traces (.LMK, .MAP, and references in .SUM).
- Enter 'n' or 'Enter' to delete nothing and return to the Main Menu.

2. Disconnect - This option removes all overlap and limb information, but leaves all other data intact.

(Compiled by JRW)

Eliminate pictures from landmark

(lithos Main Menu Option E. Eliminate pictures from landmark)

Description

This Main Menu option allows you to remove pictures from a landmark.

$/!\$ You must first use Option I to load the landmark.
THE EFFECT IS IMMEDIATE AND YOU CANNOT UNDO! There is no need to save afterwards.

Submenu

When you choose Option E. Eliminate pictures from landmark from the Main Menu, you will see this display and submenu:

Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH? e
 >e

   #     PICNM          EMISS      COV       ILL       RES       #LMK      PHASE      INV  +/-

   1   P3T11L2H0201     47.57      0.88      0.88      0.25        96        51         0 *
   2   P3T11L2H0202     47.57      0.88      0.88      0.25        96        52         0 *
   3   P3T11L2H0203     50.91      0.88      0.88      0.26        94        30         0 *
   4   P3T11L2H0204     50.91      0.88      0.88      0.26        96        68         0 *
   5   P3T11L2H0206     51.04      0.95      0.95      0.26        97        75         0 *
   6   P3T11L2H0207     47.92      1.00      1.00      0.25        95        30         0 *
   7   P3T11L2H0208     47.92      1.00      1.00      0.25        97        68         0 *
   8   P3T11L2H0209     43.08      0.93      0.93      0.24        96        52         0 *
   9   P3T11L2H0210     43.08      0.93      0.93      0.24        97        52         0 *
  10   P3T11L2H0211     39.22      0.85      0.85      0.23        96        68         0 *
  11   P3T11L2H0212     39.22      0.85      0.85      0.23        94        30         0 *
  12   P3T11L2H0213     39.02      0.95      0.95      0.23        96        74         0 *
  13   P3T11L2H0215     42.66      1.00      1.00      0.24        96        68         0 *
  14   P3T11L2H0216     42.66      1.00      1.00      0.24        93        30         0 *

  3.05061409811740111E-002  7.31441252330175540E-003

 c. Continue
 a. Auto remove
 m. Manual remove
 n. Auto remove (new pictures)
 o. Remove low-correlation pix
 p. Prune landmark
 v. Check peripheral visibility
 t. Auto change topo flags
 l. Change low-correlation topo flags
 q. Quit

The display includes these elements:

# - Temporary image number.

PICNM - Picture name.

EMISS - Emission angle, determined by the current topography.

COV - Coverage, the fraction of the landmark covered by the image.

ILL - Illumination, the fraction of the landmark that is not in shadow.

RES - Resolution, the image resolution divided by the GSD.

Often times the RES value will be slightly different than what would be calculated by hand. I suspect this is the case because the picture is orthorectified before determining the image resolution; hence, the image resolution listed in PICINFO.TXT (from RESIDUALS) is only valid at the center of the image. If I am correct, then the image resolution effectively decreases towards the edges of the image.

#LMK - Number of landmarks added to that picture.

PHASE - Phase angle of the image.

INV - Percentage of pixels that are "invisible", which means the pixel cannot be seen because it is blocked, such as the bottom of a crater in an oblique view. This is listed as parts per thousand, so 2.7% would display as "27".

+/- - Contains an * if the image resolution is more than three times higher or lower than the maplet scale.

Here are the choices from the submenu:

c. Continue - Same as entering 'q'.

a. Auto remove - Displays a grid like this:

     1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
  0  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
  2  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
  4  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
  6  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
  8  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 10  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 12  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 14  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 16  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 18  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 20  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 22  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 24  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 26  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 28  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 30  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 32  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 34  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 36  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 38  .  .  3  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 40  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 42  .  .  4  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 44  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 46  .  .  4  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 48  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 50  .  .  3  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 52  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 54  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 56  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 58  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 60  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 62  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 64  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 66  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 68  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 70  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 72  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 74  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 76  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 78  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 80  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 82  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 84  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 86  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 88  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
 90  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .

 Input INVLIM, SLIM, CLIM, ILIM, RSMN, RSMX

The grid contains these elements:

Rows - This the emission angle, and is based upon the current topography. If the topography is poor, you may eliminate pictures you want to keep and/or keep pictures you want to eliminate.
Columns - These are images with resolutions from 0 to 3 times the maplet scale (30 = 3 times maplet scale).
You will be prompted to Input INVLIM, SLIM, CLIM, ILIM, RSMN, RSMX. The standard input is '0,60,.25,.25,0,3'. Most permissible: '1000,90,0,0,0,inf' => does not throw any image away. Least permissible: '0,0,1,1,inf,0' => throws all away.
- INVLIM - Value that represents the maximum fraction of points in the image that can be "invisible". "Invisible" means that the pixel cannot be seen because it is blocked, such as the bottom of a crater in an oblique view. The number entered is thousandths of a fraction. For 2.7%, enter '27'. Typically this value is just set to 0.
- SLIM - Maximum emission angle that is allowed.
- CLIM - Coverage limit. Minimum fraction of maplet overlapped by image.
- ILIM - Illumination limit. Minimum fraction of maplet covered by illuminated image.
- RSMN - Minimum allowed ratio of image resolution (km/px) to maplet scale.
- RSMX - Maximum allowed ratio of image resolution (km/px) to maplet scale.

m. Manual remove Enter the image number you wish to remove.

$/!\$ DO NOT enter the picture number as it says! Enter the image number.

You can enter

a single image number followed by 'Enter' for each image
a range of numbers separated by commas. For example, '1,5' means delete images 1 through 5.
'0' followed by 'Enter' to quit.

Here is a sample of the inputs for m. Manual remove.

  input number of picture to remove.  0 to quit.
1,5
10
0

n. Auto remove (new pictures) - Same as Option a. Auto remove , but it only deletes images added while loading (i.e., input ["i"] followed by "y").

o. Remove low-correlation pix - If you have performed an alignment such as 1-0-1, this option can be used to remove all images that are below the user-entered threshold. For example, enter '0.2' to remove all images with a correlation below 0.2.

p. Prune landmark - Randomly eliminates images of forms specified in INIT_LITHOS.TXT if the landmark contains more than a set number of images.

v. Check peripheral visibility - Not typically used.

t. Auto change topo flags - Not typically used.

l. Change low-correlation topo flags - Not typically used.

Additional Reference

p. Prune landmark

[from LITHOS.f] - This has only been used for MESSENGER where the limit is typically about 500.

v. Check peripheral visibility

[from LITHOS.f] - Removes images in which part of the maplet is obscured by another part of the body.

t. Auto change topo flags

[from LITHOS.f] - Filters the images in the same way as options a and n, but instead of being eliminated, a flag is set in the landmark file that prevents the image from being used to determine the maplet topography. However, it is still used in the geometry solution for landmark location.

l. Change low-correlation topo flags

[from LITHOS.f] - Is similar to option t, except images whose correlation with the illuminated maplet is less than a specified value is flagged. [Taken from LITHOS.f]

(Compiled by JRW)

Picture status

(lithos Main Menu Option P. Picture status)

Description

This Main Menu option allows you to change how the picture is used by SPC.

Submenu

When you enter Option P. Picture status from the Main Menu, you will see this prompt and submenu:

Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH? p
 >p
 Input 12-character picture name.
P3T11L2H0201

 0. No change
 1. Tuck it away
 2. Ignore image in Vlm

Input 12-character picture name - Input the picture name.

0. No change - Returns to Main Menu.

1. Tuck it away - Use this to either tuck or untuck a picture. Tucking a picture strips all the landmark information from the SUMFILE and flags it with "!" in PICTLIST.TXT so lithos will ignore it when introducing new images.

2. Ignore image in Vlm: - Flags an image so that it will not participate in the determination of the landmark position Vlm (i.e., a "v1"), but will contribute to the determination of topography through its brightness variations.

(Compiled by JRW)

Turn off picture restriction

(lithos Main Menu Option L. Turn off picture restriction)

Description

This Main Menu option toggles on/off an alternative picture list.

Enter either 'L' or 'l' (lowercase ell] for this option.

Additional Reference

[From LITHOS.f] - At times it is useful to create a restricted list of images for the software to search. This restricted list PICTLISTR.TXT and its extended form PICTLISTRX.TXT may contain, for example, only higher resolution images. If we do not want to use these lists, we can set the Restricted Picture List flag RPLUSE to .FALSE. The default value is .TRUE. unless it is set by the line RPLUSE=.FALSE. in INIT_LITHOS.TXT. This toggle lets the user change the current setting without having to go elsewhere to do it.

(Compiled by JRW)

Find maplets containing surface point

(lithos Main Menu Option F. Find maplets containing surface point)

Description

This Main Menu option allows you to find a specific maplet that falls within a range of values that you input. This is useful for finding a maplet/bigmap based upon a picture, lat/long, or maplet/bigmap.

Prompts

When you enter Option F. Find maplets containing surface point from the Main Menu, you will see these prompts:

Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH? f
 >f
 pixlinpic (p) or ltdlng (l) or map p/l (m)?
p
 input picture name
P3T11L2H0203
 input px,ln
512 512

 Lat/Lon/Rad =     -7.929   262.742     0.267

 MAPLETS
EE0006    0.0001   73.5753   68.1750
EE0007    0.0001   36.7092   69.8093
EE0010    0.0001   74.1030   29.5836
EE0011    0.0001   36.6173   29.6914
EE0047    0.0000   89.3879   78.6963
EE0048    0.0000   51.2886   78.8508
EE0049    0.0000   14.9830   78.3710
EE0056    0.0000   89.9906   39.9955
EE0057    0.0000   51.1087   40.0120
EE0058    0.0000   15.1030   40.0903
EE0065    0.0000   89.9260    5.7837
EE0066    0.0000   51.7840    5.7497
EE0067    0.0000   14.3419    4.4848

 BIGMAPS
T11T10    0.0001  131.7704  123.8519
T11T05    0.0000  253.5390  237.7034
T11EV1    0.0000  964.3016  903.6361
T11EVB    0.0000 1139.3016 1078.6361
TEMP01    0.0000  342.7534  274.3991
T11MEP    0.0000  343.3013  273.6356

 Current landmark = TEST01
SCALE =  0.000100 QSZ =   49
 Lat/Lon/Rad =     -6.800   264.090     0.266
 Region = EE
Main Menu: Q 0123O IUCRSG NVAMBX DEPL FZH?

pixlinpic (p) or ltdlng (l) or map p/l (m)? - Selects one of these choices:

Entering 'p' prompts for a picture name, then a pixel/line location on that image. For example, on an image with a resolution of 1024X1024, '0 0' refers to the upper left of the picture and '512 512' refers to the center of the picture.
Entering 'l' (lowercase ell) prompts for the latitude and west longitude. This option uses the shape model for determining lat/lon.
Entering 'm' prompts for a landmark name, then a pixel/line location on that landmark. JRW edit 08 Nov 2021: '0 0' is the upper left, 'q q' is the center, and '2*q 2*q' is lower right. This is because Bob stores the matrix as -q to q, which includes 0.

The output of all 3 options is the same. It contains these elements:

Lat/Lon/Rad - Displays the Latitude/Longitude/Radius (in km) of the location you specified. These values come from the shape model.

Column 1 - The name of the maplet/bigmap.

Column 2 - GSD in km of the maplet/bigmap.

Column 3 - Pixel location of the specified lat/lon on the maplet.

Column 4 - Line location of the specified lat/lon on the maplet.

Additional Reference

[From LITHOS.f] - This process determines which maplets and maps include a given surface point. A surface point can be specified by its image-space location in an image, by its latitude and west longitude or by its coordinates in a map or maplet. It returns the latitude, west longitude and radius of the surface point and, for each maplet containing that point, the maplet scale and coordinates of the point.

(Compiled by JRW)

Use zoom display

(lithos Main Menu Option Z. Use zoom display)

Description

This formats the LMRK_DISPLAY*.pgm files to show 10 images per line. It makes it easier to count the images and identify which number an image is.

Additional Reference

[From LITHOS.f] - The ordinary image/maplet display is square. If there are fewer than 50 images containing the landmark it is easy to identify an image/maplet pair that has been flagged as needing work. This process turns on a display with ten image/maplet pairs per line with the number of the last pair in the line displayed to the right.

(Compiled by JRW)

Hide screen output

(lithos Main Menu Option H. Hide screen output)

Description

This Main Menu option is a toggle used mostly in batch processing to reduce the amount of data that is written to the OOT file.

Additional Reference

[From LITHOS.f] - This process toggles hiding screen output to reduce the size of output files in batch processing.

(Compiled by JRW)

Directories

BIGFILES

Description

This directory stores bigmap .LMK files output by bigmap.

BIGFILES/ is a required directory for the program bigmap. A bigmap .LMK file of the same form as a maplet's landmark file (see LMKFILES for further details) is output by bigmap and stored in BIGFILES/.

Here is a sample BIGMAP/BIGMAP.LMK file:

T11RFU   T      0.2500  0.0500                                 NAME, HFLAG, 
     200   0.0000100                                           SIZE, SCALE(KM)  
        -1        -1        -1        -1                       HORIZON          
    0.5000000000D-05    0.0000000000D+00                       SIGKM, RMSLMK    
   -0.3192561939D-01    0.2620033289D+00   -0.3602428203D-01   VLM              
    0.1295275799D-01   -0.1601986158D+00   -0.9869998123D+00   UX               
   -0.9967472254D+00   -0.8059136793D-01    0.0000000000D+00   UY               
   -0.7954366505D-01    0.9837893248D+00   -0.1607214063D+00   UZ               
    0.1000000000D-04    0.1000000000D-04    0.1000000000D-04   SIGMA_LMK        
PICTURES
P3T11U2H0665    451.96    554.55                               IMAGE, PIXEL/LINE LOCATION OF BIGMAP
P3T11U2H0666    451.96    554.55

P3T11U2H0848    533.59    474.26
P3T11U2H0849    523.75    488.41
P3T11U2H0850    523.75    488.41
P3T11U2H0851    523.75    488.41
P3T11U2H0852    523.75    488.41
MAP OVERLAPS
LIMB FITS
END FILE

(Compiled by DL)

DATA

Description

This directory stores the SPICE kernels used by SPC.

More information about the needed files to compute the spacecraft position and pointing in body fixed frame and the camera field of view can be found at the NAIF website.

http://naif.jpl.nasa.gov

(Compiled by KD)

IMAGEFILES

Description

IMAGEFILES/ stores images that will be used in SPC. These images are created by process_fits, which is different for every flight mission.

The data stored in each image file contained in the IMAGEFILES/ directory is a scaled unsigned integer (2 bytes or 16 bits), with the exclusion of values less than 0. Acceptable values are from 0 to 32767.

If the source is a real (or 32-bit float) value process_fits takes the original images' data float and calculates the maximum value. Then it scales the data to spread from 0 to 32767 to maximize the accuracy of the stored data.

(Compiled by KD)

LMKFILES

Description

This directory stores landmark files, or "lmkfiles" created by lithos.

Each landmark file contains all the pertinent information about that landmark:

name
resolution
half-size
body-fixed central radial vector
local orthogonal coordinate basis
pixel/line location for each image it occurs in.
Horizon is no longer used

By default, landmark files have the same name as their complimentary maplet files located in the MAPFILES directory. Maplets contain all of the topographical information, while landmark files contain all the corresponding position and pointing information.

Here is a sample of a landmark file:

EE0425   T                                                     NAME, HFLAG (lithos internal parameter)
      49   0.0000100                                           SIZE, SCALE(KM)
        -1        -1        -1        -1                       HORIZON
    0.5000000000D-05    0.0000000000D+00                       SIGKM, RMSLMK
   -0.2626299087D-01    0.2627170561D+00   -0.3160095548D-01   VLM
    0.6293765735D-02   -0.1377471387D+00   -0.9904474616D+00   UX
   -0.9982943535D+00   -0.5835403129D-01    0.1771996613D-02   UY
   -0.5804068595D-01    0.9887469411D+00   -0.1378794611D+00   UZ
    0.4293590936D-03    0.5209407279D-03    0.4297898945D-03   SIGMA_LMK
PICTURES
P3T11L2H0201    466.27    128.14
P3T11L2H0202    466.26    128.14
P3T11L2H0203    294.45    152.24
P3T11L2H0204    294.46    152.27
P3T11L2H0205    556.00    171.85
P3T11L2H0206    556.00    171.85
P3T11L2H0207    244.02    407.90
P3T11L2H0208    244.02    407.87
P3T11L2H0209    154.69    616.37
P3T11L2H0210    154.68    616.35
P3T11L2H0211    136.93    706.14
P3T11L2H0212    136.93    706.13
P3T11L2H0213    221.55    727.08
P3T11L2H0214    221.56    727.08
P3T11L2H0215    638.11    224.34
P3T11L2H0216    638.11    224.34
MAP OVERLAPS
EE0397        66.076       0.078      -0.250
EE0424         0.111      66.211       1.230
EE0426        -0.585     -66.961      -0.113
EE0453       -66.664      -0.151      -0.128
LIMB FITS
END FILE

MAP OVERLAP coordinate system (x, y, z) is in units of landmark GSD.

Figure 00: Landmark File Information Illustration

(Compiled by TC)

MAPFILES

Description

This directory contains all of the maplets and bigmaps that have been created.

mapfile Contents

Each mapfile contains a short header that looks like this:

 # Qsize           49
 # Scale    9.9999997473787516E-006
 # Vector   -2.6262991130352020E-002  0.26271706819534302       -3.1600955873727798E-002
 # Ux    6.2937657348811626E-003 -0.13774713873863220      -0.99044746160507202     
 # Uy  -0.99829435348510742       -5.8354031294584274E-002   1.7719966126605868E-003
 # Uz   -5.8040685951709747E-002  0.98874694108963013      -0.13787946105003357

The mapfile header outlines basic information about the maplet (half-size, scale, central vector, coordinate frame) as well as the height and albedo values for each maplet pixel.

The mapfile is made up of 72 byte records. The first record contains information describing the size, scale, orientation and position of the map as listed here:

bytes 1-6 - Unused
bytes 7-10 - Scale in km/pixel (real*4 msb)
bytes 11-12- qsz where map is 2*qsz+1 x 2*qsz+1 pixels (unsigned short lsb)
bytes 16-27 - map center body fixed position vector in km 3 x (real*4 msb)
bytes 28-39 - Ux body fixed unit map axis vector 3 x (real*4 msb)
bytes 40-51 - Uy body fixed unit map axis vector 3 x (real*4 msb)
bytes 52-63 - Uz body fixed unit map normal vector 3 x (real*4 msb)
bytes 64-67 - Hscale = maximum abs(height)/30000 (real*4 msb)*
byte 13255* - X position uncertainty unit vector component (byte) +
byte 14255* - Y position uncertainty unit vector component (byte) +
byte 15255* - Z position uncertainty unit vector component (byte) +
bytes 68-71 - magnitude of position uncertainty (real*4 msb) +
byte 72 - Unused

* heights are in units of map scale

+ these are pretty much unused as far as I can see--how to word?

The remaining records are made up of 3 byte chunks:

bytes 1-2 - height/hscale (integer*2 msb)
byte 3 - relative "albedo" (1-199) (byte)

If there is missing data at any point, both height and albedo are set to zero.

(Compiled by TC)

NOMINALS

Description

This directory stores the starting solution of an observation that is created from the executable make_sumfiles.

Each image has its own "nominal" file stored in the NOMINALS directory. These files have the image name with the suffix ".NOM". Nominal files do not update with the use of SPC (the "v 4" command in lithos), unlike sumfiles.

All vectors are in body fixed frame.

Nominals include:

Image name
Frame reference - Inertial s/c velocity unit vector that defines the downtrack direction. The label is the frame used for SIGMA_VSO.
SCOBJ - S/C to object vector -- [units km] (This can be in inertial frame, or body fix position.)
SIGMA_VSO - Error in S/C position -- [units km]
Cx, Cy, Cz - Camera pointing vectors in the body frame.
SIGMA_PTG - Error in camera pointing -- [units rad] There are entries for DYNAMICS that list the previous 2 and following 2 images' relative positions. These are used to condition the S/C position when running GEOMETRY, option 2.

Here is a sample of a nominal file:

S595057374F1
   -0.3635326241D+00   -0.9250382113D+00   -0.1102195033D+00   BOD_FRAME
    0.3071334125D+00    0.4756036668D+02   -0.3008768662D+01   SCOBJ
    0.1000000000D+01    0.1000000000D+01    0.1000000000D+01   SIGMA_VSO
    0.9685067274D+00    0.3109628683D-02    0.2489679684D+00   CX
    0.2486662018D+00   -0.6285289007D-01   -0.9665477920D+00   CY
    0.1264275161D-01    0.9980179580D+00   -0.6164670642D-01   CZ
    0.1000000000D-02    0.1000000000D-02    0.1000000000D-02   SIGMA_PTG
END FILE

Figure 00: Nominal File Illustrating the Starting Solution

(Compiled by KD)

SHAPEFILES

Description

This directory stores shape files. Out of the many shape files that can be stored in SHAPEFILES, SPC only uses one shape model at a time, SHAPE.TXT. It is the main shape model used throughout SPC.

The first line of SHAPE.TXT is the Q size (between 8 and 512 in a factor of 2 increments: 8, 16, 32, 64, 128, 256, 512). The shape is in the ICQ format, which is basically a 6-sided cube. The number of vertices in the shape file is 6 * (Q+1)^2, so the number of lines in the shape file will be one higher.

Each subsequent line gives the vector of the surface. The vectors are in Cartesian space (x, y, z).

SHAPE00.TXT is the "baseline" shape model. This can be used to keep track of how different it becomes from the starting shape. Usually, it is turned off partway through the mission by INIT_LITHOS.TXT.

Use a symbolic link to specify SHAPE.TXT. This way, you can keep a useful filename in the directory, but "link" it to SHAPE.TXT so that SPC runs properly.

Here is a sample set of commands to show how to set up a link:

cd SHAPEFILES
ln -s <realfile> SHAPE.TXT

Here is a sample of a shape model:

         512
  -278.04003   278.04003   268.57872
  -276.88948   278.59369   269.11354
  -275.73912   279.14388   269.64501
  -274.58894   279.69061   270.17314
  -273.43898   280.23391   270.69794
  -272.28923   280.77377   271.21943
  -271.13971   281.31022   271.73763
  -269.99043   281.84328   272.25255
  -268.84141   282.37296   272.76420
  -267.69265   282.89927   273.27260
...

(Compiled by KD)

SUMFILES

Description

This directory stores sumfiles.

A "sumfile" is created by the executable make_sumfiles. It contains the following information about its image:

camera data
target-relative position vectors
pointing vectors
uncertainty values
landmark info

There is only one sumfile for each image. SPC uses data from sumfiles throughout various executables such as lithos. As you use SPC to correlate images with lithos, you can update the sumfile vectors and landmark lists using the "v 4" command (see lithos).

Unlike nominals, sumfiles can change throughout SPC usage.

The sumfiles crated by make_sumfiles are named as <image name>.SUM and placed in a directory titled SUMFILES within the user's working directory.

Here is a sample of a sumfile:

W46908480918                                                                           # image name
2014 NOV 12 17:20:03.128                                                               # utc
  2048  2048   500 65535                                       NPX, NLN, THRSH         # pic size, lower and upper dn thresholds
    0.1356800000D+03    0.1044000000D+04    0.9380000000D+03   MMFL, CTR               # focal length, px/ln center (boresight/optical axis)
   -0.9665063720D+01    0.1326644487D+02   -0.6673084308D+01   SCOBJ                   # s/c-object vector (body fixed)
   -0.6442479111D+00   -0.1829032409D-01    0.7645979944D+00   CX                      # pixel unit vector (body fixed)
    0.5935707119D+00    0.6184779444D+00    0.5149357652D+00   CY                      # linel unit vector (body fixed)
   -0.4823053379D+00    0.7855892670D+00   -0.3875965231D+00   CZ                      # boresight unit vector (body fixed)
    0.7254908676D+00   -0.3292717307D+00    0.6043534796D+00   SZ                      # sun unit vector (body fixed)
  74.07410   0.00000   0.00000   0.00000  74.07410   0.00000   K-MATRIX         
    0.00000D+00    0.00000D+00    0.00000D+00    0.00000D+00   DISTORTION              # always zero these days (distortion comes in elsewhere)
    0.1007758363D-02    0.1482813397D-02    0.8902614968D-03   SIGMA_VSO               # formal scobj uncertainty
    0.3071768580D-04    0.3093941486D-04    0.1565302183D-04   SIGMA_PTG               # formal pointing uncertainty
LANDMARKS                                                                       
AO0001   2049.39    668.15                                                      
AO0002   2020.70    644.81                                                      
AO0003   2035.17    708.66                                                             # landmark px/ln centers
BD0009   1902.39    884.05                                                      
BD0010   1891.13    909.86                                                      
   ...
EK0022    675.73   1371.97                                                      
EQ0088    721.76    738.13                                                      
FI0002    727.77    220.40                                                      
LIMB FITS                                                                              # landmark-on-limb centers (none here)
END FILE

$/!\$ Comments (information after the #) were added here for clarification and are not included in an actual sumfile.

Here is another sample sumfile:

Figure 00: SUMFILES Information Illustration

(Compiled by KD)

TESTFILES

Description

This directory stores output display files for user inspection during batch processing.

The following table explains which script-makers and run scripts use the TESTFILES/ directory and the display files stored in the directory by their display file source programs:

Table 00: Listing of Scripts Using the TESTFILES Directory

Script-Maker	Run Script	Display File	Display File Source	Batch Processing Description
make_scriptA	run_script.b	LMRK_DISPLAY1.pgm for each image	autoregister	Batch autoregistration of images.
make_scriptF	run_script.b	LMRK_DISPLAY1.pgm for each landmark	lithos	Batch lithos processing of landmarks.
make_scriptR	run_script.b	LMRK_DISPLAY.pgm for each image	register	Batch registration of images.
make_scriptT	run_script.b	LMRK_DISPLAY1.pgm for each landmark	lithos	Tiling of a bigmap or shape with a suite of new landmarks.

(Compiled by DL)

TESTFILES1

Description

This directory stores display files for user inspection during batch processing.

The following table explains which script-makers and run scripts use the TESTFILES1/ directory and the display files stored in the directory by their display file source programs:

Table 00: Listing of Scripts Using the TESTFILES1 Directory

Script-Maker	Run Script	Display File	Display File Source	Batch Processing Description
make_scriptAP	run_scriptnn.b	LMRK_DISPLAYnn.pgm for each image	autoregisterP	Batch autoregistration of images using parallel processing.
make_scriptF	run_script.b	tmpl.pgm for each landmark	lithos	Batch lithos processing of landmarks.
make_scriptP	run_scriptnn.b	LMRK_DISPLAYnn.pgm for each landmark	lithosP	Batch iteration of landmarks using parallel processing.
make_scriptT	run_script.b	tmpl.pgm for each landmark	lithos	Tiling of a bigmap or shape with a suite of new landmarks.

(Compiled by DL)

Files

Input Files

BIGMAP.IN

Description

This user-created file contains the list of landmarks you want to use when creating a bigmap.

If BIGMAP.IN exists when the bigmap command is run, the only landmarks that will be used in the construction of the bigmap are taken from this list. This is useful when you want to use only specific landmarks, such as only those of a certain resolution.

$/!\$ BIGMAP.IN should be treated as a temporary file and either renamed or deleted after use.

Here is a sample of a BIGMAP.IN file:

EE0001
EE0002
EE0003
EE0004
EE0005
EE0006
EE0007
EE0008
EE0009
EE0010
EE0011
EE0012
EE0013
EE0014
EE0015
EE0016
END

(Compiled by TC)

CategoryInputFiles CategoryInputFiles

DYNAMICS.TXT

Description

This input file allows you to specify different uncertainty values in different coordinate frames for different segments of a mission. The program dynamics reads this file and assigned these values for images contained therein.

The file looks just like the PICTLIST.TXT file in that there is a space in the first column before the picture name.

Here is a sample of excerpts from a DYNAMICS.TXT file for DAWN at Vesta:

FRAME='BOD_FRAME' APPROACH
ETLM=  1800, 1.D-6
VSIG= 0.200, 0.200, 0.200
PSIG= 0.0001, 0.0001, 0.0001
 F11A0001225
 F11A0001241
 ...
 F21A0003895
 F21A0003910
FRAME='dxR_FRAME' SURVEY
ETLM=  1800, 1.D-6
VSIG= 0.100, 0.100, 0.040
PSIG= 0.0001, 0.0001, 0.0001
 F21A0003931
 F21A0003932
 ...
 F21A0032347
 F21A0032348
END

There were a number of parameter changes as the mission progressed from Approach to Survey to HAMO to LAMO to HAMO2 to Departure, with transitions between phases requiring parameters of their own.

(Compiled by TC)

IFRAME.TXT

Description

This text file contains the nominal spacecraft to object center vector and camera orientation all in inertial space (J2000) for each picture. IFRAME.TXT is created by the routine make_sumfiles.

In IFRAME.TXT, the SCOBJ vector is in meters. RA, DEC, and TWIST are in degrees. SRA and SDEC are the error in RA and DEC, respectively, in milli-arcseconds.

IFRAME.TXT used to be created by IFRAME.f with the understanding that, if it was needed, it would be run right after make_sumfiles. However, that was confusing and fraught with peril.

IFRAME.TXT is now used by OMEGA. It lets you get an approximate solution for the transformation from inertial to body-fixed and, if desired, to update the sumfile accordingly. Of course, since there are uncertainties in the nominal values, this isn't quite right, and you must run REGISTER to align with the current shape model.

Here is a sample IFRAME.TXT file:

    PICNM                  UTC                   SCOBJx              SCOBJy              SCOBJz            RA          DEC        TWIST       SRA         SDEC

P595033964F2    2018 NOV 09 11:11:36.008    0.1393877134D+03   -0.2052581418D+02   -0.9569192088D+01    -8.37947    -3.88812    88.65648   176.39833     2.27588
P595034390F2    2018 NOV 09 11:18:42.324    0.1393248422D+03   -0.2052504806D+02   -0.9564763229D+01    -8.37947    -3.88812    88.65648   176.40259     2.27349
P595034816F2    2018 NOV 09 11:25:48.640    0.1392619628D+03   -0.2052427823D+02   -0.9560332270D+01    -8.37947    -3.88812    88.65648   176.40685     2.27109
P595035242F2    2018 NOV 09 11:32:54.955    0.1391990760D+03   -0.2052351109D+02   -0.9555902818D+01    -8.38640    -3.88409    88.66071   176.41111     2.26869
...

(Compiled by KD)

CatregoryFiles CategoryInputFiles

INIT_LITHOS.TXT

Category B

Version 3.0.3

Description

This text file sets limits, definitions, and logicals for SPC.

Here is a sample to show the keywords used in INIT_LITHOS.TXT.

Operational settings for INIT_LITHOS.TXT. There are other options, but they are not needed or supported for the OSIRIS-REx mission. # as the first character denotes a comment.

USR= '0'
USRMX=12
BODY='RQ36'
IDCODE=2101955
#BFRAME='RQ36_FIXED'
BFRAME='IAU_BENNU'
PCK='DATA/naif0011.tls'
PCK='DATA/bennu_v10.tpc'
UNIT='METER'
ASIG= 0.05
SSIG= 0.15
CHI0= 1.0
BLIM= 0.5
MXSLP=0.6
BLOOM=0.2
SEED= 1.3827453
#REFLECT= 'VESTA'
NEWLIM=.TRUE.       find new limbs in LITHOSP
SOFTEN=1
MAPONLY=.FALSE.
#GEOPIC='pict1.txt'
RENAME=.FALSE.
REGFLG=.FALSE.
REG='J0'
KB=1
RPLUSE=.TRUE.
RECVR=.FALSE.
#RECVR=.TRUE.
ALPAD=.TRUE.
NEWLIM=.TRUE.
DISTORT= 'M###########' 'OWEN'  6
0.00000D+00        0.00000D+00    0.0000000-06    0.00000D+00    0.00000D+00    0.000000D-05   0.0000000D-07
DISTORT= 'P###########' 'OWEN'  6
0.00000D+00        0.00000D+00    0.000000D-06    0.00000D+00    0.00000D+00    0.000000D-07   0.0000000D-06
#SHAPERF= 'SHAPEFILES/SHAPE00.TXT'
#SIGMARF= .05
LMKWTS= 1, 1, 1, 0      WB, WO, WL, WR
PICWTS= 1, 1, 0, 1, 0      WB, WL, WC, WS, WT
LPCORLM= 0.2
ALCORLM= 0.3
GDCORLM= 0.3
HTCORLM= 0.2
CORRFLG= 3         0:LAP, 1:ALB, 2:GRD, 3:L+A
RESLM= 4           PIXEL<RESLM*SCALE [SCALE>PIXEL/RESLM]
PICLM=2
NUMLM=200
SIZLM= 1.5        ^ LOWERS PIXEL/SCALE
END

Explanation

USR	Not used
USRMX	When running any batch script program (make_scriptP, make_scriptAP), this value defines the number of processors that will be used
BODY	The is the name of the object
IDCODE	The is the number that NAIF uses to denote the object. Bennu's official asteroid designator is 2101955
BFRAME	Contains the variable used to define the body fixed coordinate frame. This is defined by NAIF and used in the kernels
PCK	These define the planetary constants for a variety of objects. naif0011.tls is for the whole solar system. bennu_v10.tpc is the current version for Bennu. Many programs will read these line to do SPICE function calls.
UNIT	Sets the units that the tables report out units. Options are KILOMETER and METER
ASIG	The weighting that is placed upon the albedo solution (a priori albedo sigma). Typical is 0.05. EDIT JRW 09 May 2017: This value determines how much to change albedo during 0-0-40. Setting it small (1e-10) means albedo won't change.
SSIG	The weighting that is placed upon the asteroid's topographic solution. (a priori slope sigma). Typical is 0.15
CHI0	Background limit. Typical is 1.0.
BLIM	Minimum overlap in LITHOS b option. Typical is 0.5.
MXSLP	Sets the limit for slope. Previous use at 0.6 ensures no vertical slopes. Suggest removing or 0 for Bennu and boulders.
BLOOM	Enables limb detection when blooming is present. Typical is 0.02.
SEED	The seed value used for the random function call.
REFLECT	What photometric model to use. If not defined, SPC uses McEwin .
SOFTEN	This decreases the weight of the change when a solution is found. Typical is 1.0.
MAPONLY	If .TRUE., we ignore mapless landmarks in GEOMETRY. Standard is FALSE
REGFLG	If .TRUE., it uses an alternate LANDMARK naming convention.
REG	If REGFLG=.TRUE., it uses these two characters as the lead character for LANDMARKS.
KB	Beginning number in sequence for LANDMARKS. Typical is 1
RPLUSE	Use PICTLISTX or PICLTLISTR for netpictures. Typical is .TRUE.
RECVR	If .TRUE., prevents high res maplets from effecting low-resolution topography. Typical is .FALSE.
ALPAD	Perform extra albedo solution after each iteration. Typical .TRUE.
NEWLIM	Tells lithosP to run the detect new limb routing when running an iteration.
DISTORT	Distortion matrix. It has four parameters. The first is an image name template where # is a wildcard. If the image name fits the template, then it will apply this distortion matrix. The next parameter is the distortion type. The third parameter is how many terms the distortion matrix has. The fourth parameter is the distortion matrix. (Note: The zeroth distortion matrix element is a fractional focal length change for the particular filter.)
SHAPEREF	If you want to constrain the model using a starting shape model (GEOMETRY option 1), that model is defined here. Typical is "SHAP00.TXT.
SIGMARF	Simga is km for above constraint. Typical is 0.5.
LMKWTS	Weights for generation for the LANDMARK position (GEOMETRY option 1). Typical is 1, 1, 1, 0 (see details below)
PICWTS	Weights for generation for the S/C position and pointing (GEOMETRY option 2). Typical is 1, 1, 1, 1, 0
LPCORLM	Correlation limit for laplacian cor. Typical is 0.2.
ALCORLM	Correlation limit for albedo cor. Typical is 0.3.
GDCORLM	Correlation limit for gradient cor. Typical is 0.3.
HTCORLM	Correlation limit for height cor. Typical is 0.2.
CORRFLG	Overlap correlation option. 0:LAP, 1:ALB, 2:GRD, 3:L+A. Typical is 3.
RESLM	PIXEL<RESLM*SCALE [SCALE>PIXEL/RESLM]. Limits image or maplet resolution in search. Typical is 4.
PICLM	Minimum number of images in a LANDMARK. If it doesn't this many, the LANDMARK is deleted. Typical is 6.
NUMLM	Number of images before RESLM kits in. If you have more that this number of images, don't add in resolutions ratios beyond RESLM. Typical is 200.
SIZLM	Minimum ratio of map to image sizes. MAPSIZE < SIZLM * PICSIZE. ^ LOWERS PIXEL/SCALE. Typical is 1.5.
BLEMISHES='FC2#########'	Reference to a template contained in BLEMISHES/ for masking bad pixels which are common to all FC2 images (example taken from DAWN). The template name is 12 characters, with the characters common to all affected images in the correct positions and '#' everywhere else. There may be multiple BLEMISH entries, each referring to BLEMISH template files.
PRNLM=100	Prune limit used by residuals to alert you if the number of pictures containing a landmark exceeds the limit. Landmarks exceeding the limit are listed in the output file PRUNE.TXT.

|| FTM || Frame transfer time. Allows you to change the default charge transfer time for PROCESS_FITS. If it is not there, it uses the default value in the source code (1.044).

Weighting values for landmark and picture calculations.

Within INIT_LITHOS.TXT, we have weighting that goes into the solution. The actual weight that is included is the sqrt of the value provided. Thus, if you want to double the weight, you would use 4.

LMKWTS -- Landmark Weights

These weights are used to influence the position of the central vector -- the middle of the landmark.

WB - Body. Use the position from the pixel/line location based on the images.
WO - Overlap. Condition the solution with the overlapping maplets
WL - Limbs. Use images that contain the current landmark on its limb to condition the solution
WR - Reference. If there is a reference object (SHAPEREF='SHAPEFILES/SHAPE00.TXT'), it will ensure the solution does not deviation too far from that baseline shape. This may be used at the start, but it is unlikely to be needed as the model gets more mature.

PICWTS -- Picture Weights

These weights are what is used when solving for the spacecraft position and camera pointing.

WB - Body. Body is where it uses the position of all the landmarks and minimizes the spacecraft pointing/position.
WL - Limbs. This uses landmarks that have detected that this image is on the limb to constrain its position.
WC - Camera. The uncertainty value for SIGMA_PTG in SUMFILES will constrain how far away the camera pointing solution can be from the value stored in NOMINALS
WS - SCOBJ. The uncertainty value for SIGMA-VSO in SUMFILES will constrain how far away the spacecraft object (SCOBJ) solution can be from the value stored in NOMINALS
WT - Trajectory. When dynamics is being used (the preceding two and trailing two images are stored in the NOMINALS file), this will constrain how far the spacecraft object can deviate from the nearby images.

(Compiled by KD)

INIT_LITHOS.TXT-3.0

CategoryPrograms CategoryThreeAlphaThree

LIMBLIST1.TXT

This list is a list of images and will be created by the user, and will be used by make_list. See make_list for further details.

Example of LIMBLIST1.TXT:

 P596675130F2
 P596675146F2
 P596675162F2
 P596675177F2
END

(Compiled by ??)

CategoryFiles CategoryInputFile

LMRKLIST.TXT

Category ?

Version 3.0

Description

This input file includes a list of landmarks that lithos will use.

LMRKLIST.TXT can be created by hand by listing the LMKFILES directory.

If it's present, LMRKLISTO.TXT is used to calculate overlaps, rather than LMRKLIST.TXT.

Here is a sample LMRKLIST.TXT file:

EE0001
EE0002
EE0003
EE0004
EE0005
EE0006
EE0007
EE0008
EE0009
EE0010
EE0011
EE0012
EE0013
EE0014
EE0015
END

To build a LMRKLIST.TXT file, enter the following at the command line:

cd LMKFILES
/bin/ls > ../LMRKLIST.TXT
cd ..
echo END >> LMRKLIST.TXT

Another important input file which should be read instead of LMRKLIST.TXT is LMRKLISTX.TXT. In the limit of a very large number of landmarks > 20 K, reading the LMRKLISTX.TXT file when you load a landmark into lithos will result in substantial time savings compared to reading the LMRKLIST.TXT file.

(Compiled by DL)

CategoryInputFiles CategoryInputFiles

LMRKLIST1.TXT

Description

This text file contains a list of newly created landmarks.

LMRKLIST1.TXT can be deleted at any time with no repercussions. However, it is useful for various things.

For example, if you delete LMRKLIST1.TXT right before tiling at 35cm, then after you have finished tiling you will have a list of all the landmarks at 35cm. You can then save this list in a different file and store it for future use.

Also, the landmarks in LMRKLIST1.TXT are read by EXPORT, and these are the only landmarks that get exported. If a program tries to use LMRKLIST1.TXT but it does not exist, that program creates an LMRKLIST1.TXT.

Another important input file which should be read instead of LMRKLIST.TXT is LMRKLISTX.TXT. In the limit of a very large number of landmarks > 20 K, reading the LMRKLISTX.TXT file when you load a landmark into lithos will result in substantial time savings compared to reading the LMRKLIST.TXT file.

(Compiled by JRW)

CatedgoryFiles CategoryInputFiles

LMRKLISTO.TXT

Description

This text file contains a list of all maplets that could possibly overlap a new map created in the same location used to make a bigmap.

If it's present, programs use LMRKLISTO.TXT to calculate overlaps, rather than using LMRKLIST.TXT. This enables lithos and lithosP to run faster because they only search for overlaps among a limited set of landmarks.

When bigmap runs, it keeps track of all the maplets that went into its construction and puts this list into USED_MAPS.TXT. If you want to use this reduced set of landmarks, you can get it from USED_MAPS.TXT after you run bigmap. Once it is complete, LMRKLISTO.TXT contains all the maplets that could possibly overlap a new map created in the same location used to make the bigmap. Moreover, as LITHOS creates new maplets, it automatically adds them to LMRKLISTO.TXT.

     cp USED_MAPS.TXT LMRKLISTO.TXT

(Compiled by JRW and EEP)

CategoryInputFiles CategoryInputFiles

LMRKLISTR.TXT

Description

This input file is a user created file that is a restricted list (hence the "R" in LMRKLISTR.TXT as compared to LMRKLIST.TXT.) Typically SPC uses all landmarks that have been created, but at times you may want to reduce the number of landmarks that are used, which is why you would create a restricted list of landmarks. This must be used with caution, because most programs will check for the LMRKLISTR.TXT and use it if it exists.

$/!\$ If you don't remove the LMRKLISTR.TXT file once you're done with it, you'll be working with a partial dataset.

This file is used by various programs, if it exists. One program that uses LMRKLISTR.TXT is regres.

If LMRKLISTR.TXT does not exist, then the program uses LMRKLIST1.TXT or LMRKLIST.TXT.

(Compiled by JRW)

LMRKLISTX.TXT

Description

This input file is output by make_lmrklistX. LMRKLISTX.TXT summarizes the following landmark information (in column order):

lmrk name
Q size
number of images containing the lmrk
VLM - lmrk position vector from the center of the body to the center of the lmrk
scale (km)

lithosP uses LMRKLISTX.TXT to quickly determine what landmark files need to be used for the overlap computation.

Here is a sample LMRKLISTX.TXT file:

EE0001   49  355   -0.789971D-02    0.260998D+00   -0.115266D-01    0.350000D-03
EE0002   49  360   -0.203250D-01    0.262210D+00   -0.116002D-01    0.350000D-03
EE0003   49  320   -0.328776D-01    0.260667D+00   -0.112363D-01    0.350000D-03
EE0004   49  298   -0.454681D-01    0.259987D+00   -0.111565D-01    0.350000D-03
EE0005   49  356   -0.782921D-02    0.261745D+00   -0.242790D-01    0.350000D-03
EE0006   49  359   -0.203874D-01    0.261724D+00   -0.242330D-01    0.350000D-03
EE0007   49  360   -0.328300D-01    0.262109D+00   -0.243155D-01    0.350000D-03
EE0008   49  360   -0.453950D-01    0.261565D+00   -0.241885D-01    0.350000D-03
EE0009   49  293   -0.787332D-02    0.258487D+00   -0.364896D-01    0.350000D-03
EE0010   49  358   -0.202152D-01    0.260056D+00   -0.365461D-01    0.350000D-03
EE0011   49  357   -0.328579D-01    0.261480D+00   -0.369930D-01    0.350000D-03
EE0012   49  360   -0.453167D-01    0.261334D+00   -0.369408D-01    0.350000D-03
EE0013   49  150   -0.100607D-01    0.261914D+00   -0.139179D-01    0.180000D-03
EE0014   49  165   -0.170069D-01    0.262132D+00   -0.138891D-01    0.180000D-03
EE0015   49  150   -0.239728D-01    0.262338D+00   -0.138081D-01    0.180000D-03
END

(Compiled by DL)

make_sumfiles.in

Category B

Version 3.0.1

Description

This text file is a list of the image files needed by make_sumfiles to create SUMFILES and NOMINALS. It is created by process_fits an becomes an input for make_sumfiles.

make_sumfiles.in contains these 6 columns:

image name loaded into process_fits
spacecraft time of each image
camera number that took the image
spacecraft number for mission
bin
UTC time of each image

The vectors in the sumfiles and nominals are calculated directly from the kernels in make_sumfiles.txt by using the time for each image obtained from make_sumfiles.in.

The following sample make_sumfiles.in is from OSIRIS_REx.

$/!\$ This sample is in the format necessary for the OSIRIS-OREx mission. Spacecraft time is needed to use CK kernels while epoch time is needed for spk kernels. Spacecraft, UTC, and epoch time can be transformed into one another pretty easily using spice, which SPC uses.

P596924821J3    3/0596924726.30615          3    1    1    -25.50       270     20181201T082552S75100Z_pol_L0_V002.fits
P601296494J3    1/0601296429.38732          3    1    1    -25.50       270     2019-01-20T22-47-05.541_PCAM_L0b_V004.fits
...

Column Definitions

PICNM	CLK	NC	NS	SCL	TC	NQ	FITSNM
SPC-OREx Naming	UTC or ET	Camera 1-5	Spacecraft Number	Binning (none)	Temperature in C	Filter/Focal	Source filename

Camera Number [NC]
1. SamCam
2. MapCam
3. PolyCam
4. NavCam
5. NFTCam

Filter Number -- MapCam has filters based upon its position -- in degrees

Position	Filter Number
0	0
720	0
630	1
540	2
450	3
360	4
270	5
180	6
90	7
30	7

Filter Number --SamCam has filters based upon its position -- in degrees

Position	Filter Number
0	0
720	0
600	1
480	2
360	3
240	4
120	5

Focal Position -- PolyCam NQ=FLT

The motor position, 0 to 17,400

where:

d is the distance the camera is focused at in m

For practical reasons the infinity setting we use in the lab is actually
~4.3 km (PolyCam step 17,400) not actual infinity. At that setting we
measured the effective focal length 627.8mm. Based on the formula above
it means our CBE for finf is 628.9mm so until we get a better number from
post launch calibration images we should use

f(d) = 628.9 - 2684 * d ^ -0.9376

(Compiled by EP)

old - make_sumfiles.in-3.0A2

CategoryThreeOhOne

make_sumfiles.txt

Category ?

Version 3.0

Description

This configuration file contains basic camera distortion data and a list of available SPICE kernels. It is used by make_sumfiles as a configuration file when generating SUMFILES and NOMINALS. At this time, make_sumfiles.txt is created by hand.

Creating make_sumfiles.txt

Here is a sample make_sumfiles.txt file. Annotations on the right indicate what the data elements are.

4                                                         NCAM
'ORX_OCAMS_MAPCAM'
1024  1024                                                NPXB, NLNB
125.0  512.5  512.5                                       MMFLB, PX0B, LN0B
117.647, 0, 0, 0, 117.647, 0                              KMATB
 -1, -2, 3                                                  PROJECT CAMERA AXES
5, 16383                                                  T1,T2
'ORX_OCAMS_SAMCAM'
1024  1024                                                NPXC, NLNC
24.0  512.5  512.5                                        MMFLC, PX0C, LN0C
117.647, 0, 0, 0, 117.647, 0                              KMATC
 1, 2, 3                                                  PROJECT CAMERA AXES
5, 16383                                                    T1,T2
'ORX_OCAMS_POLYCAM'
1024  1024                                                NPXA, NLNA
611.0  512.5  512.5                                       MMFLA, PX0A, LN0A
117.647, 0, 0, 0, 117.647, 0                              KMATA
 -1, -2, 3                                                  PROJECT CAMERA AXES
5, 16383                                                     T1,T2
'ORX_NAVCAM'
2592   1944                                               NPXC, NLNC
7.6  1296.5 972.5                                         MMFLC, PX0C, LN0C
454.54, 0, 0, 0, 454.54, 0                                KMATC
 1, 2, 3                                                 PROJECT CAMERA AXES
5, 4096                                                    T1,T2
1                                                         NSC
-64                                                       ORX
1.d0  1.d0  1.d0                                          sigV0
1.d-3  1.d-3  1.d-3                                       sigPT
2101955                                                   BENNU
'IAU_BENNU'                                               BFRAME
'NONE'                                                    ABCORR
'../ORex/DATA/'                    PREFIX
KERNELS
sb-101955-76.bsp
bennu_v10.tpc
de421.bsp
naif0011.tls
orex_ocams_v02.ti
orx_aux_v01.ti
orx_v03.tf
pck00010.tpc
ApproachPrelim_Perturbed.bsp
DetailedSurvey_Perturbed.bsp
OrbitalB_Perturbed.bsp
ORX_SCLKSCET.00000.example.tsc
F3A_AllObs_20181109T000000_20181118T000000_Perturbed.bc
F3A_BD_AllObs_20190113T000000_20190122T120000_p.bc
F3A_ES_Obs1_20190127T094200_20190127T161200_p.bc
F3A_ES_Obs2_20190203T094300_20190203T161300_p.bc
F3A_ES_Obs3_20190210T100500_20190210T163500_p.bc
...
END_KRNLS

Description of codes

NCAM	Number of cameras in the file
NPXV, NLNB or NPXC, NLNC, or NPXA, NLNA	Number of pixels and lines for the camera image
MMFLB, PX0B, LN0B	focal length and center pixel/line of the camera
PROJECT CAMERA AXIS	The axis of the camera mounted onto the spacecraft. This is the same thing that is described in all the frame kernels
T1, T2	The min and maximum value of "accepted" values for the image's DN. Below and above this threshold, it denotes no data
ORX	NAIF base code for the spacecraft
sigV0	The default value for the spacecraft object uncertainty, in km. Can be overwritten by DYNAMICS
sigPT	The default value for the camera pointing uncertainty, in Rad. Can be overwritten by DYNAMICS
BENNU	Asteroid number for the object. Used for SPICE Calls
BFRAME	Object that defines the body fixed frame to be used in SPC
ABCORR	Correction needed for adjustment for light speed (Aberration correction indicates the aberration corrections to be applied to the state of the target body to account for one-way light time and stellar aberration.)
KERNELS	Here one lists all of the kernels that are needed to properly project spacecraft camera pointing onto the body-fixed surface

The make_sumfiles.txt file consists of three sections:

Camera Data Definitions

Enter the number of cameras that the file maintains (NCAM). List the following for each camera:

Camera Name
Pixels (sample and rows)
Focal length, center pixel (x/y)
K Matrix - distortion matrix
Min and max expected DN for this data type

Enter sigV0 - The uncertainty of the spacecraft position [km] Enter sigPt - The uncertainty of the camera pointing [Rad]

The PROJECT CAMERA AXIS relates to how the camera is mounted to the spacecraft (it's orientation). I *think* this could be handled by frame kernels, but it isn't done that way right now. Thus, we have to put in a camera orientation matrix. From my testing, it appears that there are 4 orientations that valid.

1 2 3
-1 -2 3
-2 1 3
2 -1 3

Target Information

Enter the follow three rows:

the names of the ID of the target body
body fixed frame in the kernels
aberration correction desired

Kernel List

If the SPICE kernels are not in your working directory, give the path to the kernels (PREFIX).

Start the SPICE kernels list with these two rows:

```
 KERNELS
 #
```

List each kernel on a separate row.

$/!\$ When in doubt, list all the available kernels.

Here is a list of kernels that are known to make make_sumfiles work:

SPK kernels (.bsp) - for spacecraft and target object - ephemeris
CK kernels (.bc) - orientation/attitude of spacecraft and other structures (like camera)
SCLK kernels (.tsc) - spacecraft clock coefficients
IK kernels (.ti) - instrument geometry for camera taking pictures
LSK kernels (.tls) - leap seconds
FK kernels (.tf) - reference frame specifications
PCK kernels (.tpc) - text form of planetary/asteroidal constants

End the kernels list with this row:

```
 END_KRNLS
```

When processing make_sumfiles

If you get the "NOFRAMECONNECT" error (display says, "At epoch...") - You likely need a CK Kernel (<filename>.bc). Additional questions can be answered by referencing NAIF's SPICE website. http://naif.jpl.nasa.gov
If you get the "SPKINSUFFDATA" error (display says, "Insufficient...") - You likely need a SPK Kernel (<filename>.bsp).

Additional Reference

Here is the same make_sumfiles.txt but with additional comments:

make_sumfiles.txt.jpg

Figure 00: Illustration of make_sumfiles.txt File with Explanations

(Compiled by KD)

MAPLIST.TXT

This is a user created text file that is a list of all the maplets. This is created from the *.MAP files, but doesn't contain the ".MAP" at the end. Requires an "END" on the last line.

Example MAPLIST.TXT

AA0001
AA0002
AA0003
AA0004
AA0005
AA0006
AB0001
AB0002
AB0003
AB0004
AB0005
...
IQ0001
IQ0002
IQ0003
IQ0004
IR0001
IR0002
IR0003
IR0004
END

These programs use MAPLIST.TXT.

(Compiled by JRW)

PICTLISTR.TXT

Description

This is a restricted version of PICTLIST.TXT. The user creates this file by pairing down PICTLIST.TXT to only process a subset of pictures in lithos or regres.

For information on its structure, see PICTLIST.TXT.

(Compiled by JW)

PICTLIST.TXT

Category ?

Version 3.0

Description

This text file contains the core list of images that SPC will use. make_sumfiles creates or adds to PICTLIST.TXT when it runs and it lists all the images from make_sumfiles.in. The file terminates with the keyword "END" at the end. The image name starts on column 2, allowing for special characters to be placed in column 1. A space is the normal character before the image name, allowing it to be used.

In SPC, this file would contain all of the images in the entire system. This file is not designed to be changed by hand, but various tools within SPC will make modifications to it. If the image has the symbol # or ! as the first character (rather than a space), that image will be skipped.

lithos will update this file if the command "tuck" is used. Tuck will add or remove a "!" as the first character of an image. This routine is used if there are problems with the image and you don't want to ever use the image (i.e. all SPC routines will ignore this image).

$/!\$ Warning. If it's present, PICTLISTX.TXT is used before PICTLIST.TXT.

This file is used to make things run faster. However, you must be it is updated with make_pictlistX when new images are added (or tucked). If not, then the old list of images will be used rather than the updated PICTLIST.TXT.

When you run lithos, if you are using PICTLIST.TXT, it will limit images with an emission angle less than 75 degrees.

 N585107273F3
 N585107729F3
 N585107957F3
 N585108413F3
 N585108641F3
...


...
 N585109097F3
 N585109325F3
!N585109781F3
!N585110009F3
END

Creating PICTLIST.TXT

If necessary, you can create PICTLIST.TXT by hand by listing the IMAGEFILES directory. This should not normally be needed, and is only likely to be needed if a user mistakenly deleted the original one.

$/!\$ If you create the file by hand, you must add a space as the first character on each line. Without the leading space, SPC will read the image name wrong, neglecting the first character. You can use "sed" to fix this by using the substitute pattern of "s/^/ /", which is before the 1st character, add a space.
SPC uses "!" as the first character to indicate "don't use this image" (also known as a "tucked" image).

The following set of commands show an easy way to create a PICTLIST.TXT file:

cd IMAGES
/bin/list > ../PICTLIST.TXT
cd ..
echo END >> PICTLIST.TXT
vi PICTLIST.TXT
:%s/^/ /
:wq

Here is a sample PICTLIST.TXT file:

 FC11A0001225
 FC11A0001241
 FC11A0001257
 FC11A0001258
 FC11A0001259
 FC11A0001260
...
END

(Compiled by KD)

PICTLISTS.TXT

Description

PICTLISTS.TXT is a user-generated alternative list of picture names used by residuals and geometry. If PICTLISTS.TXT exists then residuals and geometry will use it instead of PICTLIST.TXT to obtain the picture set to work on.

Example PICTLIST.TXT

 FC11A0001225
 FC11A0001241
 FC11A0001257
 FC11A0001258
 FC11A0001259
 FC11A0001260
END

$/!\$ Note: A space must be included before the picture name and the list must end with the end-of-file identifier, END.

(Compiled by DL)

PICTLISTX.TXT

Description

This text file exists in order to precompute metadata so that other programs run faster. The precomputing is done via make_pictlistX, and only when run explicitly by the user.

make_pictlistX uses PICTLIST.TXT to create PICTLISTX.TXT.

If it's present, PICTLISTX.TXT is used before PICTLIST.TXT.

When you run lithos, if you are using PICTLISTX.TXT, it will limit images with an emission angle less than 85 degrees.

Here is a sample PICTLISTX.TXT file:

 FC11A0001225    0.93497E+03  0.998 -0.656  0.439 -0.614 -0.569  0.365 -0.737
 FC11A0001241    0.93563E+03  0.998 -0.628  0.520 -0.579 -0.554  0.441 -0.706
 FC11A0001257    0.93631E+03  0.998 -0.589  0.599 -0.542 -0.527  0.518 -0.674
 FC11A0001258    0.93699E+03  0.998 -0.540  0.673 -0.505 -0.490  0.590 -0.642
 FC11A0001259    0.93770E+03  0.998 -0.482  0.741 -0.467 -0.443  0.659 -0.608
 FC11A0001260    0.93845E+03  0.998 -0.412  0.805 -0.428 -0.385  0.725 -0.572
...
END

The data included are:

column 1 - Picture name
column 2 - Range from spacecraft to body center
column 3 - Cosine of half the maximum field of view
column 4 - First component of the unit vector from spacecraft to the targets center in BF frame
column 5 - Second component of the unit vector from spacecraft to the targets center in BF frame
column 6 - Third component of the unit vector from spacecraft to the targets center in BF frame
column 7 - First compost of the unit bore sight vector belonging to the camera in BF frame
column 8 - Second compost of the unit bore sight vector belonging to the camera in BF frame
column 9 - Third compost of the unit bore sight vector belonging to the camera in BF frame

(Compiled by KD)

PICTLISTRX.TXT

Description

This user-created file contains a subset (restricted list) of the images in PICTLISTX.TXT. It is similar to PICTLISTR.TXT.

For information on its structure, see PICTLIST.TXT.

(Compiled by JW)

Output Files

check.txt

Description

This text file lists landmarks and overlaps/limbs output by residuals for landmarks whose linear residual is greater than the user-specified limit.

check.txt is output by residuals for any landmark whose linear residual is greater than PLIM 2, the second residuals argument. check.txt contains every overlapping landmark and limb listed in the suspect landmark's LMKFILE.

The accompanying veto.txt file contains the lithos seed file for detaching the suspect landmark from all overlapping landmarks and limbs. You can use this to "veto" its influence on overlapping landmarks.

Here is a sample check.txt file:

EE0001   <- landmark with residual standard deviation greater than user-specified limit
EE0005   <- overlapping landmark
EE0001   <- landmark with residual standard deviation greater than user-specified limit
EE0006   <- overlapping landmark
EE0001   <- landmark with residual standard deviation greater than user-specified limit
EE0009   <- overlapping landmark
END

(Compiled by DL)

EMPTY.TXT

Description

This text file is a lithos seed file output by residuals used for batch deletion of landmarks.

EMPTY.TXT contains the lithos commands required to batch delete landmarks listed in LMRKLIST.TXT that are not contained in any pictures or limbs.

Here is a sample EMPTY.TXT file:

d          <- delete or disconnect landmark
EE0001     <- landmark name
1          <- delete
y          <- delete entirely
d          <- as above
EE0002
1
y
q          <- quit lithos

(Compiled by DL)

FLATLIST.TXT

Description

This text file lists "flat maps", which are maps that do not have topography (have no attached MAPFILE or images).

FLATLIST.TXT is output by residuals based on the following landmark HFLAG status:

HFLAG = T - The landmark has topography--it has an associated MAPFILE and images
HFLAG = F - The landmark is a flat map--it has neither an associated MAPFILE nor attached images

residuals inspects the .LMK files for each landmark stored in LMRKLIST.TXT and collects the landmark name and scale (km) for every landmark whose HFLAG is NOT set to 'T'. It stores these landmark details in FLATLIST.TXT.

Here is a sample FLATLIST.TXT file:

LANDMARK name  resolution [km]
EE0001         0.00010
EE0002         0.00010
EE0003         0.00010
END

(Compiled by DL)

INSIDE.TXT

Description

This text file, an output from bigmap, lists all of the maplets that were used by bigmap the last time it was run. This list includes only the maplets that fall completely inside the borders of the bigmap that was created.

$/!\$ INSIDE.TXT is different from USED_MAPS.TXT, which lists all of the maplets that are contained in the bigmap that was created, some of which may only partially fall in the bigmap.

Here is a sample INSIDE.TXT file:

(Compiled by TC)

LIMINFO.TXT

Description

This text file lists limb information output by residuals.

residuals searches the LIMBFILES/ directory for a .LIM file for each picture listed in PICTLISTS.TXT. If PICTLISTS.TXT does not exist, it uses PICTLIST.TXT. If a .LIM file exists, various data are computed for inclusion in LIMINFO.TXT.

LIMINFO.TXT is no longer generated by the v3.0 software and will not be generated during OSIRIS REx.

(Compiled by DL)

LMKVECS.TXT

Description

This text file lists landmark vectors output by residuals for every landmark contained in LMRKLIST.TXT.

For each landmark listed in LMRKLIST.TXT that is contained in at least one picture or limb residuals lists this information:

Columns 1 to 3: VLM - Landmark center to body center vector.
Column 4: Landmark name
Column 5: HFLAG - 'F' indicates that the landmark is a flat map. 'T' indicates that the landmark has topography--an associated MAPFILE and image set.

Here is a sample LMKVECS.TXT file:

   -0.2713710561D-01    0.2626967758D+00   -0.3116810853D-01    EE0001 T
   -0.3094370945D-01    0.2625129653D+00   -0.3121141969D-01    EE0002 T
   -0.3474824700D-01    0.2622791972D+00   -0.3118245307D-01    EE0003 T
END

(Compiled by DL)

MAPCHK.TXT

Description

This text file lists maplets that meet either of these conditions:

The difference between their predicted and observed pixel/line locations in attached images is greater than a user-specified limit.
They have two or fewer overlaps attached to them.

MAPCHK.TXT is output by residuals based on this process:

The first parameter input to residuals is the user-specified pixel shift limit.
If a landmarks shows a difference between its predicted and observed pixel/line locations in attached images that is greater than this pixel shift limit, it is added to MAPCHK.TXT.
If the number of overlaps attached to a landmark is two or fewer, the landmark is listed in MAPCHK.TXT with an 'o' beside it.

The following sample MAPCHK.TXT file shows landmarks listed for each of these reasons:

EE0009         <- diff observed, predicted location greater than user-specified limit
EE0017 o       <- landmark has two or fewer overlaps
EE0019 o
EE0022
EE0023
EE0024 o
EE0027 o
EE0082 o
EE0084
EE0085
EE0086 o
EE0087
EE0088
EE0089 o
END

(Compiled by DL)

MAPINFO.TXT

Description

This text file provides details about each map you have in the SPC system. You can use MAPINFO.TXT to identify problems, similar to the ways you use RESIDUALS.TXT.

MAPINFO.TXT is created by residuals.

The symbols that may show up in the Flag column are based on the parameters passed into residuals.

Here is a sample MAPINFO.TXT file. Elements of the data in each of the three sections are explained below.

IA2_05    0.0200     49.1713    113.4101     11.7471       9       0       0     34.64   >>  10.36
IA3_01    0.0200     56.7760     84.8686     13.0224       3       0       0     34.64   **  11.00
IA3_05    0.0200     13.1041     95.9594     12.1615       4       0       0     34.64   >>   9.95
IA3_3G    0.0200     35.8062     91.8462     11.6549       7       0       0     34.64   >>   8.45


.........

 RMS POSITION UNCERTAINTY =    48.694768136505374
 NUMBER OF LANDMARKS =         4295

    A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R
A   1   1   2   1   2   1   1   1   1   1   1   1   1   1   1   1   1   1
B   1   1   1   1   1   1   1   1   1   1   1   1   1   1   1   1   1   1
C   1   1   1   1   1   1   1   1   1   1   1   1   1   1   1   1   1   1
D   2   2   2   1   1   1   1   2   1   1   1   1   1   1   1   1   2   2
E  66   1   2   1   1   1   1   1   1   1   1   2   1   1   2  28   1   2
F  30   5   1   1   1   1   1   1   1   1   1   2   1   1   1   2   2   2
G   1   1   1   1   1   1   1   1   1   1   1   1   1   1   1   1   1   1
H   1   2   2   1   1   1   1   1   1   1   1   1   1   1   1   1   1   1
I   1   1   1   1   1   1   1   1   1   1   1   1   1   1   1   1   1   1

Section 1

The columns in the first set of output contain this information:

Column 1 - landmark name
Column 2 - landmark resolution
Columns 3-5 - lat, lon, radius
Column 6 - number of images contributing to landmark
Column 7 - number of maplets the landmark overlaps
Column 8 - number of images with landmark on limb
Column 9 - magnitude of formal uncertainty in meters
Column 10 - Flag, which may be:
- >> - Flag showing landmarks that are below the pixel threshold
$/!\$ You might want to look at these further.
- ** - Flag indicating fewer than 3 images were included
Column 11 - RMS pixel/line vector residual of the nominals and position

Section 2

The two lines in this section present

the RMS of all the maplet's position uncertainty
the number of landmarks in use
$/!\$ The landmark residual is in kilometers unless you include the line UNIT='METER' in INIT_LITHOS.TXT.

Section 3

This matrix plots the number of landmarks in each region of the surface. It uses 10-degree bins with vertical from 90 to -90 (A-I) and horizontal from 0-360 (A-R). The maplet name is defined by this gridded region.

(Compiled by KD)

MAPRES.TXT

Description

This text file lists maplet resolution information for maplets contained in at least one picture or limb.

MAPRES.TXT is output by the program residuals. For each landmark listed in LRMKLIST.TXT, which is contained in at least one picture or contains at least one limb appearance, residuals outputs information to MAPRES.TXT.

Here is a sample MAPRES.TXT file:

LMKNM    NPIX     SCALE      RESAV/SCL   RESSD/SCL   RESMN/SCL   RESMX/SCL      

EE0001    24     0.00010       0.246       0.010       0.233       0.261
EE0002    24     0.00010       0.246       0.009       0.234       0.259
EE0003    24     0.00010       0.246       0.007       0.236       0.256

The columns contain these data:

LMKNM - landmark name
NPIX - number of pictures containing the landmark, plus the number of limb appearances for the landmark
SCALE - scale in km/pixel
RESAV/SCL - average image resolution per unit scale
RESSD/SCL - standard deviation image resolution per unit scale
RESMN/SCL - minimum image resolution per unit scale
RESMX/SCL - maximum image resolution per unit scale
RES/SCL = the number of pixels or lines moved in image-space for a change in location of a point on a maplet as the point moves in the maplet frame.

(Compiled by DL)

New_Limbs.in

Description

This lithos seed file is output by residuals and used to attach maps to limbs for every landmark contained in LMRKLIST.TXT.

New_Limbs.in contains the lithos commands to process each landmark listed in LMRKLIST.TXT where the landmark has an associated MAPFILE and an image set.

Here is a sample New_Limbs.in file annotated with explanations of the commands:

o                   <- attach map to maps or limbs
EE0001              <- load landmark
n a                 <- don't reset all
3                   <- attach map to limbs
n b                 <- don't clear
1,3,5               <- expansion (1), res/scale limit (3), d_hgt limit (5)
o                   <- as above
EE0002
n a
3
n b
1,3,5
q                   <- quit lithos

(Compiled by DL)

NEW_LIST.TXT

Description

This text file lists new landmarks created during batch make_scriptT tiling. NEW_LIST.TXT is output by find_nofitT.

Here is a sample NEW_LIST.TXT file:

EP0001
EP0002
EP0003
EP0004
EQ0001
EQ0002
EQ0003
EQ0004
END

(Compiled by DL)

no_update.txt

Description

This text file lists landmarks output by residuals whose associated pictures are not listed by increasing mission time in the .LMK file.

residuals checks the .LMK file for each landmark listed in LMRKLIST.TXT for pictures that are not listed in ascending order. Since the image name is based on ephemeris time, ascending order is a proxy for increasing time. Therefore, deviations from ascending name order show images that are not listed based on increasing mission time. These landmarks are then listed in no_update.txt.

Here is a sample of a .LMK file for which the landmark would be listed in no_update.txt:

AA0001   T
      49   0.0007500                                           SIZE, SCALE(KM)
        -1        -1        -1        -1                       HORIZON
    0.3750000000D-03    0.1214487940D+01                       SIGKM, RMSLMK
    0.7845141366D-01   -0.6632264386D-03    0.2427257052D+00   VLM
    0.9282163978D+00   -0.8567629848D-03   -0.3720397949D+00   UX
    0.2888872521D-02    0.9999837875D+00    0.4904716741D-02   UY
    0.3720295727D+00   -0.5627413746D-02    0.9282038212D+00   UZ
    0.5042866483D-03    0.6426026485D-03    0.7961719021D-03   SIGMA_LMK
PICTURES
M595949305F0    353.33    622.34
M595950583F0    696.83    359.79
P595903597F2    515.00     48.11            <- pic i
P595902930F2    469.34    648.70            <- pic j, where pic i > pic j
P595904281F2    592.68    701.12
P595905631F2    843.77    699.42
P595917125F2    373.73     74.35
MAP OVERLAPS
AA0002        35.828      61.211     -13.055
AB0001       -31.293     -53.362     -12.772
AQ0001       -40.032      54.114      -7.907
BR0001       -68.967       0.419      -8.536
AA0003       -29.647     -40.296      -2.588
AB0003       -42.646     -86.024     -15.244
AA0005        79.965     -14.195     -20.941
AB0004       -41.996     -97.707     -27.672
AA0004        43.500     -45.868     -11.332
AQ0003       -32.438     111.053     -22.030
BA0011       -21.858      11.659       0.651
AR0001        40.218      -0.211      -1.871
BA0008       -86.245      11.935       0.408
AR0002        18.762      67.900      -6.085
BA0010       -86.779     -35.178      -1.890
BR0007       -94.579      41.748      -6.321
BR0009       -52.030      31.489      -4.354
LIMB FITS
P595033964F2    537.92    388.59      0.05
P595034390F2    537.07    389.95      0.05
P595034816F2    537.03    391.94      0.05
P595035242F2    546.43    389.48      0.05
END FILE

The resulting no_update.txt file looks like this:

AA0001

no_update.txt is no longer generated by v3.0 software and will not be used during OSIRIS REx.

(Compiled by DL)

OVERLAPS.TXT

Description

This file is a debugging file that is not used in normal operations. OVERLAPS.TXT is generated by the OVERLAPS subroutine and is specific to a particular landmark. It is read by LITHOS.f and DISCONNECT_LMFILE.f.

Additional Reference

[From OVERLAPS.f]

This subroutine creates a file OVERLAPS.TXT that LITHOS uses to search
for maplets that overlap a given one (LMKNM).  It searches a list of
maplets in an input list (INFILE).  If a maplet has a resolution times
lower than LMKNM it is excluded.  If the maplet center differs in position
by more than twice the sum of its half width and that of LMKNM, it is
excluded as well.  The remaining maplets are those over which the overlap
searches will be made.

The input file is generally LMRKLIST.TXT, but this can be very large.
In some circumstances, such as when we are dealing with maplets that are
completely inside a BIGMAP, a file USED_MAPS.TXT generated by the BIGMAP
program that has all maplets used to construct the BIGMAP can be copied
into LMRKLISTO.TXT.  This will be read as the input file for this
subroutine, and it is guaranteed that only maplets in that file should be
in OVERLAPS.TXT.

(Compiled by JRW)

PICINFO.TXT

Description

This text file is a report generated by residuals that provides information about how well SPC performed for pictures included in PICTLISTS.TXT, if it exists, or PICTLIST.TXT.

PICINFO.TXT provides details about each map you have in the system and is used to identify problems.

Here is a sample PININFO.TXT file. Elements of the data in each of the three sections are explained below.

B2_01           2012 NOV 29 18:26:07.573    0.0015        11         0       >c   673.642       0.000 km       0.000 km       0.000 km       0.000 km      -0.000 mr       0.000 mr      -0.000 mr
B2_03           2012 NOV 29 18:27:21.732    0.0013        20         0       >c   426.441       0.001 km       0.000 km       0.001 km       0.000 km      -0.000 mr       0.000 mr      -0.000 mr
B2_04           2012 NOV 29 18:28:00.100    0.0013        21         0       >c   370.338       0.001 km      -0.000 km       0.000 km       0.000 km      -0.000 mr      -0.000 mr       0.000 mr
B2_05           2012 NOV 29 18:28:37.172    0.0014        15         0       >c   304.426       0.000 km       0.000 km      -0.000 km      -0.000 km       0.000 mr       0.000 mr      -0.000 mr
B3_01           2012 NOV 29 18:19:17.944    0.0014         5         0       >c   303.385       0.000 km       0.000 km      -0.000 km      -0.000 km       0.000 mr       0.000 mr       0.000 mr
B3_03           2012 NOV 29 18:20:15.713    0.0013        14         0       >c   293.049       0.000 km       0.000 km      -0.000 km       0.000 km       0.000 mr       0.000 mr       0.000 mr
B3_05           2012 NOV 29 18:21:13.451    0.0013         9         0       >c   262.659       0.000 km      -0.000 km      -0.000 km       0.000 km       0.000 mr      -0.000 mr      -0.000 mr
C3_05
C3_06
C3_07


.........


    SIGcx(mr)     SIGcy(mr)     SIGcz(mr)     DLTpt(mr)     DLTcz(mr)     SIGV0(km)     DLTV0(km)
    0.1000E+03    0.1000E+03    0.1000E+03    0.6685E-04    0.2529E-04    0.1732E-03    0.4265E-03

    0     1     2     3     4     5     6     7     8     9    10     x    0.10 m
    20    20    20    20    20    20    20    20    20    20    20
       0     0     0     0     0     0     0     0     0     0

Section 1

The columns in the first set of output contain this information:

Column 1 - image name
Column 2 - date image was taken, UTC(derived from GPS)
A more recent version (Feb 2014) does not put the date in col 2 of the file.
Column 3 - resolution
Column 4 - number of landmarks in image
Column 5 - number of landmarks on image lit limb
Column 6 - code:
- c indicates body fixed SCOBJ sigmas
- b indicates trajectory relative SCOBJ sigmas
- * indicates 3 or fewer landmarks for the image
- > indicates pixel residual greater than limit
- # indicates image for topography solution only
Column 7 - RMS pixel residual (RMS in pixels)
Column 8 - the magnitude displacement of the SUMFILE solution from the NOMINALS
Column 9, 10, 11 - The specific dx, dy, dz offset between the SUMFILE solution and the NOMINALS (SCOBJ)
The units of measure for numbers in these columns are based on INIT_LITHOS.TXT and the parameters passed into residuals.

Column 12, 13, 14 - The angular error in pointing between the SUMFILES and the NOMINALS

Section 2

These lines report the standard deviations of the positions in the coordinate system listed.

Section 3

These lines give a histogram of the number of images in each resolution bin. This is defined by the units listed: you multiple the bin number by the bin size.

(Compiled by KD)

PRUNE.TXT

Description

PRUNE.TXT is output by residuals. residuals checks the number of pictures containing each landmark listed in LMRKLIST.TXT. If the number of pictures exceeds the limit PRNLM (default PRNLM=500), the landmark is listed to alert the user. You may set the variable PRNLM in INIT_LITHOS.TXT so that you are alerted at a different limit.

The default limit of 500
The user-specified limit, PRNLM, as set in INIT_LITHOS.TXT

For example, the following line in INIT_LITHOS.TXT sets the limit at 100:

PRNLM=100              <- parameter in INIT_LITHOS.TXT

Here is a sample PRUNE.TXT file:

EE0001
EE0002
EE0003
END

(Compiled by DL)

RANGES_SOLVED.TXT

Description

This text file includes date and range information output by residuals for each picture listed in PICTLISTS.TXT or PICTLIST.TXT.

residuals checks each picture listed in PICTLISTS.TXT, if it exists, or PICTLIST.TXT. If the picture name does not include a prefix of # or !, it lists date and range information in RANGES_SOLVED.TXT.

Here is a sample RANGES_SOLVED.TXT file:

       -202607939.82    0.1747612145D+01        P3T11S2H0409
       -202607939.82    0.1747612144D+01        P3T11S2H0410
       -202607939.82    0.1747612144D+01        P3T11S2H0411
       -202607939.82    0.1747612144D+01        P3T11S2H0412

The output contains this information:

Column 1 - Date picture was taken in Ephemeris Time, expressed as ephemeris seconds past J2000
Column 2 - Distance of spacecraft to center of body in km
Column 3 - Picture name

(Compiled by DL)

redo.txt

Description

This text file lists landmarks that met one of these criteria following lithos or lithosP batch processing:

Terminated in error
Did not correlate with at least one image
Correlated weakly with at least one image

redo.txt is output by both find_nofit and find_nofitP, which are discussed separately below.

find_nofit

The batch processes initiated by make_scriptF produce output files LMKNM.OOT. These outputs are basically listings of the lithos standard output for each input landmark. find_nofit searches these output files for each landmark listed in the make_script.in file to identify landmarks that may need further work. The following instances cause the landmark to be listed in redo.txt:

!  cat LMKNM.OOT - process still running or terminated in error.
*  cat LMKNM.OOT - maplets not correlating with at least one image.
+  cat LMKNM.OOT - maplets correlating weakly with at least one image.

Here is a sample redo.txt file output by find_nofit:

* EE0017              <- maplets not correlating with at least one image
+ EE0034              <- maplets correlating weakly with at least one image
* EE0042
* EE0044
+ EE0045
EE0051                <- process still running or terminated in error
EE0053
+ EE0054
EE0063
END

find_nofitP

The batch processes initiated by make_scriptP produce output files <LMKNM>.OOT. These outputs are basically listings of the lithosP standard output, for each input landmark. find_nofitP searches these output files for each landmark listed in the make_script.in file to identify landmarks that may need further work. The following instances cause the landmark to be listed in redo.txt:

!  cat LMKNM.OOT - process still running or terminated in error.
*  cat LMKNM.OOT - maplets not correlating with at least one image.

Here is a sample redo.txt file output by find_nofit:

* EE0017              <- maplets not correlating with at least one image
* EE0042
* EE0044
EE0051                <- process still running or terminated in error
EE0053
EE0063
END

(Compiled by DL)

REMOVED.TXT

Description

This text file lists landmarks that were eliminated from at least one picture for one of these reasons following register, autoregister, or autoregisterP batch processing:

low correlation
no correlation

The batch processes initiated by make_scriptR, make_scriptA, and make_scriptAP produce output files PICNM.OOT. These outputs are basically listings of the register, autoregister, or autoregisterP standard output for each input picture. find_nofit searches these output files for each picture listed in the make_script.in file to identify pictures that may need further work. The following instances cause the picture to be listed in REMOVED.TXT:

cat PICNM.OOT - image not correlating with at least one maplet.

Here is a sample REMOVED.TXT file:

AA0001                <- maplet eliminated from an image for low or no correlation
AF0023

(Compiled by DL)

RESIDUALS.TXT

Description

This text file is created by residuals to report on landmarks that have residual values above the criteria set when the program was run.

RESIDUALS.TXT captures and reports three types of information:

The post-fit residuals between predicted and actual control point positions in all images.
The post-fit residuals between predicted and actual control point difference between adjacent, overlapping maplets.
Outliers in both quantities are flagged automatically based on input threshold criteria.

Here is a sample RESIDUALS.TXT file. Elements of the data in each of the four sections are explained below.

..................................................
IA1_01 T      0.0200     56.5481    140.8124     13.6146      <- Section 1
..................................................
    A1_01                 8.139    -6.853    10.640   0.01091 <- Section 2
    A2_05               -28.427    49.215    56.835   0.04250
    B1_01                -3.517    52.347    52.465   0.04857
    B1_03               -18.475   -57.091    60.006   0.05509
IA1_01     42.78                                              <- Section 3

..................................................
IA1_03 T      0.0200     36.4771    136.8269     11.4593
..................................................
    A1_03               -29.498   -12.161    31.906   0.04002
    A2_03               -71.840    23.961    75.731   0.07142
    A2_04                -3.885    -4.689     6.089   0.00643
    A2_05               -34.754    95.249   101.392   0.10527
    B1_01                64.895   -21.470    68.354   0.07337
    B1_03                11.000    59.329    60.340   0.06832
    B2_04                97.637    29.005   101.855   0.11002
    B2_05                42.109    41.562    59.165   0.07455
IA1_03     75.45


.........

 Observation # =       360180                                 <- Section 4

 RMS Residual (m) =   0.78928860594347106

Section 1

Row between the dot rows includes:

Column 1 - The name of a landmark
Column 2 - T = landmark has a map with it; F = flat landmark, no image
Column 3 - Resolution
Column 4 - Lat of landmark
Column 5 - Wlon of landmark
Column 6 - Radius

Section 2

Rows below the second dot row with the landmark name above include:

For each image:
- Column 1 - picture name
- Column 2 - PX residual (# of pixels in image resolution)
- Column 3 - LN residual (# of pixels in image resolution)
- Column 4 - magnitude of PX and LN residuals (# of pixels in image resolution)
- Column 5 - the estimate linear residual (km)
For each overlap:
- Column 1 - overlap name
- Column 2 - X residual (km)
- Column 3 - Y residual (km)
- Column 4 - Z residual (km)
- Column 5 - estimate linear residual (km)
For each limb apperation:
- Column 1 - picture name
- Column 2 - PX residual (# of pixels in image resolution)
- Column 3 - LN residual (# of pixels in image resolution)
- Column 4 - magnitude of PX and LN residuals (# of pixels in image resolution)
- Column 5 - the estimate linear residual (km)

Section 3

Row below the images, overlaps, and limbs list for a landmark includes:

Column 1 - landmark name
Column 2 - RMS linear residual for landmark (m)

Section 4

Rows below the single dot row at the very bottom for each image includes:

Observations - how many IMAGEFILES, overlaps, and limbs for all landmarks
RMS RESIDUAL - overall RMS linear residual in meters.

Residuals are the difference between observed landmark positions and those predicted by the solution (SPC).

Observed landmark positions are positions of a landmark calculated by the code when it inputs pictures from the spacecraft of the object.

Predicted landmark positions are those calculated by SPC. When it inputs, it generates a solution (map) from all the pictures collected.

During iteration and refinement of the SPC solution, the position and attitude of the spacecraft are slightly changed over and over until the maps match the images until an optimum solution has been converged upon. At the end of each iteration, SUMFILES are then updated for the new attitude and position.

When the RMS between landmark residuals is as low as possible, ..., it indicates no futher processing will improve the solution. This means that the updated SUMFILE is the new estimate for spacecraft position and attitude.

(Compiled by KD)

SHAPE.TXT

Description

This text file is the shape model that SPC uses. SHAPE.TXT is output by densify.

The shape is in the ICQ format, which is basically a 6-sided cube. Q size (resolution) values are between 8 and 512 in increments of factors of 2: 8, 16, 32, 64, 128, 256, 512.

densify generates this file, usually by taking an existing shape model, increasing the scale of the vertices by a factor of two and calculating the height of the average maplet the passes through that vector. The program dumber will downscale the shape model to a lower resolution.

ICQ Format Description

The global topography models (GTM) are presented here in an implicitly connected quadrilateral (ICQ) format. The vertices are labeled as though they were grid points on the faces of a cube

                        0 --------- I --------- Q                             
                     0  .  .  .  .  .  .  .  .  .                             
                     |  .  .  .  .  .  .  .  .  .                             
                     |  .  .  .  .  .  .  .  .  .                             
                     |  .  .  .  .  .  .  .  .  .                             
                     J  .  .  .  . F.  .  .  .  .                             
                     |  .  .  .  .  .  .  .  .  .                             
                     |  .  .  .  .  .  .  .  .  .                             
                     |  .  .  .  .  .  .  .  .  .                             
                     Q  .  .  .  .  .  .  .  .  .

so that each of the six faces (F) contains (Q+1)^2 vertices v(I,J,F) (I=0,Q; J=0,Q) and Q^2 facets f(I,J,F) (I=0,Q-1; J=0,Q-1).

The facet f(I,J,F) implicitly has the vertices v(I,J,F), v(I,J+1,F), v(I+1,J+1,F), v(I+1,J,F).

If the cube is unfolded, the six faces are arranged as

                                           -----------                        
                                           |         |                        
                                           |    1    |                        
                                           |         |                        
             -----------------------------------------                        
             |         |         |         |         |                        
             |    5    |    4    |    3    |    2    |                        
             |         |         |         |         |                        
             -----------------------------------------                        
                                           |         |                        
                                           |    6    |                        
                                           |         |                        
                                           -----------

At each of the 12 edges of the cube, faces share common vertices so that, for example, the last row of face 1 has the same vertices as the first row of face 2. The common edge vertices are, with I=(0,Q),

                v(I,Q,6)=v(Q-I,Q,4)                                           
                v(I,0,6)=v(I,Q,2)                                             
                v(I,0,5)=v(Q,Q-I,1)                                           
                v(I,0,4)=v(Q-i,0,1)                                           
                v(I,0,3)=v(0,I,1)                                             
                v(I,0,2)=v(I,Q,1)                                             
                v(q,I,6)=v(I,Q,5)                                             
                v(q,I,5)=v(0,I,4)                                             
                v(q,I,4)=v(0,I,3)                                             
                v(q,I,3)=v(0,I,2)                                             
                v(0,I,6)=v(Q-I,Q,3)                                           
                v(0,I,5)=v(Q,I,2)

and the eight corners share vertices from three faces:

                v(0,0,1) = v(0,0,3) = v(Q,0,4)                                
                v(0,Q,1) = v(0,0,2) = v(Q,0,3)                                
                v(Q,0,1) = v(0,0,4) = v(Q,0,5)                                
                v(Q,Q,1) = v(0,0,5) = v(Q,0,2)                                
                v(0,0,6) = v(0,Q,2) = v(Q,Q,3)                                
                v(0,Q,6) = v(0,Q,3) = v(Q,Q,4)                                
                v(Q,0,6) = v(0,Q,5) = v(Q,Q,2)                                
                v(Q,Q,6) = v(0,Q,4) = v(Q,Q,5)

Thus of the 6(Q+1)^{2 labeled vertices, only 6Q}2+2 are independent.

File Structure

The file structure is quite simple. The first line contains the value of Q, and is followed by 6(Q+1)^2 lines containing the vertices. A piece of Fortran code for reading the file would look like:

                READ(10,*) Q                                                  
                DO F=1,6                                                      
                DO J=0,Q                                                      
                DO I=0,Q                                                      
                  READ(10,*) (V(K,I,J,F), K=1,3)                              
                ENDDO                                                         
                ENDDO                                                         
                ENDDO

Here the vertices are represented by three-vectors. In some cases extra components are added representing albedo, color, surface gravity, or other surface characteristics. Since the labeling scheme implicitly contains the connectivity, no facet table is necessary.

The quadrilateral facets in the model are not necessarily flat, since there is no guarantee that the four vertices are coplanar. The facet normals are defined by the cross product of their diagonals. This approximation presents no real difficulty because the spacings of the vertices are very small compared to the size of the body. The standard form (Q=512) has 1.57 million vertices.

Although it is not necessary, it is convenient to take Q to be a power of 2. Because of this choice, it is easy to 'dumb down' a model by increasing the spacing by factors of 2. Vertices of the form v(2I,2J,F) are retained and the others discarded. Because of the quadrilateral facet structure, the models can also be 'densified' through bilinear interpolation.

Example

Here is a sample SHAPE.TXT file:

         128
  -218.72182    -8.78589   136.89489
  -217.94953    -6.10207   138.09736
  -217.59664    -3.46244   139.74751
  -216.83911    -0.75086   140.98874
  -216.04842     1.95086   142.19411
  -215.34667     4.53459   143.49143
  -214.06968     7.13078   144.16124
  -212.35048     9.69145   144.34511
  -210.62577    12.23122   144.54863
  -209.47201    14.69014   145.33889
  -208.85169    17.21845   146.67393
  -208.58685    19.86090   148.37467
.....

Q Value

Q	Vertices
4	151
8	487
16	1735
32	6534
64	25351
128	99846
256	396294
512	1579014

The output values are:

Line 1 - Q (resolution). This gives the number of nodes for i and j. Multiple Q by 6 coordinate vector spaces to fill out the entire region.

Q*Q*6 is the total number of nodes, and line entries in this file.
A Q of 512 is the largest that we represent. It contains 1.5 million vertices and is 56 MB uncompressed.

Lines 2 and following - The location of a vertex in i, j, k space (Cartesian coordinates).

(Compiled by KD)

References

Gaskell, R.W., O. Barnouin-Jha, and D. Scheeres, Modeling Eros with Stereophotoclinometry, Abstract #1333, 38th LPSC, Houston, TX, 2007. [GASKELLETAL2007]

Gaskell R.W., Landmark navigation and target characterization in a simulated Itokawa encounter, AAS paper 05-289, AAS/AIAA Astrodynamics Specialists Conf., Lake Tahoe, CA, 2005. [GASKELL2005]

SIGMAS.TXT

Description

This text file contains the sigma values for each bigmap. SIGMAS.TXT is created and updated by bigmap. Every time a bigmap is made, the name and current sigma values are appended to SIGMAS.TXT.

Here is a sample SIGMAS.TXT file:

MTAG15                   0.001                   0.000
MTAG15                   0.001                   0.000
MTAG15                   0.001                   0.000
MTAG25                   0.001                   0.000
MTAG35                   0.001                   0.000
MTAG15                   0.001                   0.000
MTAG25                   0.001                   0.000
MTAG35                   0.001                   0.000
MREG01                   0.000                   0.000
MREG03                   0.000                   0.000

The output values are:

Column 1 - landmark name
Column 2 - maximum standard deviation of weighted heights (in km) at each pixel/line location
Column 3 - average standard deviation of weighted heights (in km) at each pixel/line location

(Compiled by TC)

SIGMA.TXT

Description

This text file is essentially a copy of the most recently made ICQ shape file SHAPE.TXT that includes an additional column of sigma values.

SIGMA.TXT is made by densify and is located in the SHAPEFILES/ directory.

Here is a sample SIGMA.TXT file:

         512
     0.00810     0.19764     0.13333         0.29844E-01
     0.00871     0.19742     0.13360         0.28206E-01
     0.00932     0.19721     0.13386         0.27425E-01
     0.00994     0.19700     0.13414         0.27743E-01
     0.01055     0.19677     0.13441         0.28415E-01
     0.01116     0.19655     0.13466         0.31917E-01
     0.01177     0.19633     0.13493         0.31631E-01
     0.01239     0.19615     0.13521         0.28469E-01
     0.01300     0.19594     0.13549         0.28856E-01

The output values are:

Line 1 - Q (resolution). This gives the number of nodes for i and j. Multiple Q by 6 coordinate vector spaces to fill out the entire region.

Q*Q*6 is the total number of nodes, and line entries in this file.
A Q of 512 is the largest that we represent. It contains 1.5 million vertices and is 56 MB uncompressed.

Lines 2 and following - The location of a vertex in i, j, k space (Cartesian coordinates).

Column 1 - Position in x

Column 2 - Position in y

Column 3 - Position in z

Column 4 - Sigma values - JRW edit: densify.f doesn't read INIT_LITHOS.TXT, and multiplies a value by 1000 right before writing out SIGMA.TXT, so I'm fairly confident that the units are always meters.

(Compiled by TC) (Updated by JRW) CategoryFiles CategoryOutputFiles

USED_MAPS.TXT

Description

This text file, an output from bigmap, lists all of the maplets that were used by bigmap the last time it was run. This list includes maplets contained completely by the bigmap as well as those that fall on the border.

$/!\$ USED_MAPS.TXT is different from INSIDE.TXT, which only lists maplets contained entirely inside the bigmap that was created.

Here is a sample USED_MAPS.TXT file:

(Compiled by TC)

USED_PICS.TXT

Description

This text file output by bigmap contains a list of all the images that were used in creating the most recently made bigmap.

Note: This file contains limb images in addition to images used for stereo and photoclinometry

Here is a sample USED_PICS.TXT file:

 P595733646F2
 P595733662F2
 P595467488F2
 P595467677F2
 P595467866F2
 P595468055F2
 P595652545F2
 P595652849F2
 P595653154F2
END

(Compiled by TC) (Edited by JRW)

veto.txt

Description

This lithos seed file is output by residuals and used to detach from landmarks and limbs any map with a linear residual greater than the user-specified limit.

veto.txt is created for any landmark whose linear residual is greater than PLIM 2, the second residuals argument. The seed file contains the lithos commands to process each landmark listed in LMKFILE that meets the criteria. veto.txt is ready for execution as a batch process.

The accompanying check.txt file lists suspect landmarks and affected overlapping landmarks and limbs. This file allows you to individually inspect each instance.

Here is a sample veto.txt file annotated with explanations of the commands:

o  a              <- attach map to maps or limbs
EE0001            <- landmark name
n                 <- don't reset all
4                 <- detach from limb or landmark
EE0005            <- landmark name (overlap)
0                 <- 0 to end
o  a              <- as above
EE0001
n
4
EE0006
0
o  a              <- attach map to maps or limbs
EE0001            <- landmark name
n
4
P00045000450      <- picture name (limb)
0
q                 <- quit lithos

(Compiled by DL)

Support Files

make_script.in

Description

This input file lists the set landmarks or images intended for batch processing.

make_script.in is used by these script-makers:

make_scriptA - a script-maker for batch autoregistering new images
make_scriptAP - a script-maker for batch autoregistering new images using parallel processing
make_scriptF - a script-maker for batch lithos processing
make_scriptP - a script-maker for batch standard iteration of landmarks using parallel processing
make_scriptR - a script-maker for batch registration of new images

Here is a sample make_script.in file used by make_scriptA, make_scriptAP, and make_scriptR:

 P00045000450
 P00045000451
 P00045000452
END

$/!\$ You must precede each image filename with a space when creating make_script.in files for these script-makers.

Here is a sample make_script.in file used by make_scriptF and make_scriptP:

EE0001
EE0002
EE0003
END

$/!\$ You must not precede each landmark filename with a space when creating make_script.in files for these script-makers.

(Compiled by DL)

make_scriptA.seed

Description

This seed file is used by make_scriptA, the script-maker for batch autoregistering new images.

Here is a sample make_scriptA.seed file annotated with explanations of the commands:

n              <- auto-eliminate new landmarks
0,50,.25,0,5   <- INVLIM, SLIM, CLIM, RSMN, RSMX
1              <- auto-align
2              <- spacing 2
n              <- no spacing change
0              <- shift by full amount
y              <- update landmark pixel locations
1              <- auto-align
1              <- spacing 1
n              <- no spacing change
0              <- shift by full amount
y              <- update landmark pixel locations
o              <- remove low-correlation landmarks
.5             <- correlation limit 0.5
1              <- auto-align
1              <- spacing 1
n              <- no spacing change
0              <- shift by full amount
y              <- update landmark pixel locations
4              <- change flags
b              <- use all
0              <- exit (image)
q              <- quit autoregister
END

(Compiled by DL)

make_scriptF.seed

Description

This seed file is used by make_scriptF, the script-maker for batch lithos processing. make_scriptR.seed contains the lithos commands for processing each landmark.

make_scriptF is a generic script maker for batch lithos processing tasks. You specify the set of landmarks to process in make_script.in and the sequence of commands to process in make_scriptF.seed.

make_scriptF generates the .INN files and run scripts to batch process the landmarks, and generates .OOT files and saves display files during processing for user inspection.

$/!\$ You should test the command sequence in lithos before running the script generated by make_scriptF.

Writing the make_scriptF.seed

lithos expects a sequence of start and end commands which must be contained in the seed file before and after the processing commands.

Here is a sample make_scriptF.seed file. The required start and end command sequences are explained below.

# Seed file to attach map to overlapping maps
#start commands
n                                                 <- don't check for more images
n                                                 <- don't include a single image
#processing commands
o
RECENT
y
1
o
RECENT
n
3
y
1, 3, 5 w
i
RECENT
n
n
v
1
u
1
o
RECENT
n
1
#end command
q                                                 <- quit
#end-of-file identifier
END                                               <- end-of-file

Start Commands

 Check for more images? y[n]
n
 Include a single image? y[n]
n

 Check for more images? y[n]
y

 Enter fractional width (0=center).
.5

 Reject invisibles? y[n]
n

When you create the make_scriptF.seed file, you must start with a sequence that deals with this set of options. In the sample, the Start Commands lines are annotated to indicate these responses.

End Command

make_scriptF expects you to quit lithos on completion of each landmark. The make_scriptF.seed file must contain the quit command q on the second-to-last-line.

End-Of-File Identifier

make_scriptF expects the seed file to end with the end-of-file identifier, END. Any commands following this will not be appended to the .INN file.

Comments

Use # at the beginning of any comment line you want to include. make_scriptF does not append these to the .INN file.

(Compiled by DL)

make_scriptP.seed

This seed file is used by make_scriptP for standard iteration of landmarks. make_scriptP.seed contains the lithosP commands for processing each maplet.

Here is an annotated sample make_scriptP.seed file:

# This script performs two maplet iterations in parallel mode. 
# It reinitializes slope and albedo.
# It recomputes maplet overlaps.
# It recomputes limb fits.
# It recomputes central maplet vector.
# Topography determination from slopes is conditioned by:
#   Initial topography, 
#   Overlapping topography, 
#   Shadowing, 
#   Differential stereo, 
#   Limb heghts. 
# Dataless area slopes are set from the shape model.
#
# The script hides most of the screen output.  In order to obtain the 
# full display replace H* by #H*.
#
# Modified 2011_12_31.  Header and comments added.
# Modified 2014_02_26.  Hide screen output added.
#
H*                                <- Toggle ON: suppress standard output
x                                 <- turn on extract filter
.025                              <- extract filter tolerance, 0.025
#
# Initialize slope and albedo.
#
a                                 <- reset albedo or slopes
y                                 <- reset slopes
y                                 <- reset albedos
#
# Begin first iteration.
#
0                                 <- find template (build template #1)
40                                <- number of iterations, 40
1                                 <- align landmarks
0                                 <- auto-align
1                                 <- auto-align spacing, 1
n                                 <- don't try new spacing
0                                 <- continue (full shift)
y                                 <- update landmark pixel locations
u                                 <- update landmark files
0                                 <- find template, as above (build template #2)
40
#
# Begin topo determination.
#
2                                 <- find heights (build topography #1)
8                                 <- fill no data with shape slope
2                                 <- include existing heights
.01                               <- existing heights, fraction of points, 0.01
7                                 <- include shadowing
.025                              <- shadowing, fraction of points, 0.025
1                                 <- auto-include neighboring maps
4                                 <- include limb vectors
1, 2.5, 3                         <- expansion (1), res/scale (2.5), d_hgt limit (3)
6                                 <- include differential stereo
y                                 <- use gradients / auto heights
0                                 <- begin integration
.025                              <- weight, 0.025
15                                <- number of iterations
0                                 <- end iterations
u                                 <- update landmark files
1                                 <- align landmarks (as above)
0
2                                 <- auto-align spacing, 2
n
0
y
1                                 <- align landmarks (as above)
0
1
n
0
y
u                                 <- update landmark files
#
# Begin second iteration.
#
0                                 <- find template (as above) (build template #3)
40
1                                 <- align landmarks (as above)
0
1
n
0
y
u                                 <- update landmark files
0                                 <- find template (as above) (build template #4)
40
#
# Begin topo determination.
#
2                                 <- find heights, as above (build topography #2)
8
2
.01
7
.025
1
4
1, 2.5, 3  
6
y
0
.025
15
0
u                                 <- update landmark files
1                                 <- align landmarks (as above)
0
2
n
0
y
H*                                <- Toggle OFF: suppress standard output
1                                 <- align landmarks (as above)
0
1
n
0
y
H*                                <- Toggle ON: suppress standard output
u                                 <- update landmark files
#
# Begin overlaps and limb fits.
#
o                                 <- attach map to maps or limbs
RECENT                            <- re-load most recent maplet
y                                 <- reset all
1                                 <- automatic
o                                 <- attach map to maps or limbs
RECENT                            <- re-load most recent maplet
n                                 <- don't reset all
3                                 <- attach map to limbs
y                                 <- clear
1, 3, 5                           <- expansion (1), res/scale limit (3), d_hgt limit (5)
#
# Central vector determination.
#
v                                 <- find V from Z and pointing (mini-geometry)
RECENT                            <- re-load most recent maplet        
q                                 <- quit lithosP
END

(Compiled by DL)

make_scriptR.seed

Description

This seed file is used by make_scriptR, the script-maker for batch registering new images.

Using make_scriptR.seed

The following annotated make_scriptR.seed file was used for registering 450 Vesta images to Zmaps:

         m                <- reference = map
         0                <- Auto-choose Zmap
         1.0              <- Scale = 1 km
         a                <- Turn off background
         3                <- Shift image
         y                <- Autocorrelate
         XSTOP            <- Stop on no correlation
         1                <- Change scale
         0.25             <- New scale = 250 m
         3                <- Shift image
         y                <- Autocorrelate
         XSTOP            <- Stop on no correlation
         0                <- Quit
         y                <- Save new .SUM data
         n                <- Don't save rotation history
         n                <- Don't save nominal
         q                <- Quit procedure
         END

XSTOP - This is a provision for the autocorrelation procedure to end gracefully in the event that the correlation fails.

If you enter
```
3
y
XSTOP
```
and then the correlation fails, the program will reset the .SUM data to the input values and then stop.

XSKIP# - Used to to activate the autocorrelate sequence.

If you enter
```
3
y
XSKIP# 
```
the program will skip # lines of the script, reset the .SUM data and ask you to input the next image.

$/!\$ The last two entries of 'n' are always so. The rotation history file was introduced to keep track of pointing errors in Clementine data during Lunar orbits in an attempt to quantify systematic shifts and it is rare that we want to set the nominal file equal to the .SUM solution.

(Compiled by DL)

Based on SPOC v3.02A PDF/LITHOSPHERE/REGISTER.f File Reference

make_scriptT.in

Description

This support file is used by make_scriptT, the script-maker for tiling a bigmap or shape.

Basic Tiling

Basic tiling involves tiling a bigmap which is located on the shape. For more details, refer to Basic_tiling.

Here is an annotated sample of a make_scriptT.in file used for basic tiling:

XXXXXX                <- For maplet locations, reference to temporary file containing the tiling bigmap
scripts/t11-10.seed   <- Reference to the make_scriptT.seed file
      50   50         <- bigmap pixel/line location for placement of the center of each new maplet
     100   50
     150   50
     200   50
      50  100
     100  100
     150  100
     200  100
      50  150
     100  150
     150  150
     200  150
      50  200
     100  200
     150  200
     200  200
END

XXXXXX - You must save the tiling bigmap to a temporary file for tiling using a command line like this:

cp MAPFILES/BGMAP1.MAP MAPFILES/XXXXXX.MAP

You then include the temporary filename as the first line of the file.

make_scriptT seed file - File containing the lithos commands for generating each new maplet. Refer to make_scriptT.seed for more information.

bigmap pixel/line locations - These are generated using the programs map_coverage and make_tilefile. Refer to those entries for details.

Lat/Long Tiling

Lat/Long tiling involves directly tiling a shape model. For more details, refer to LatLon_tiling.

Here is an annotated sample make_scriptT.in file used for lat/long tiling:

LATLON                <- For maplet locations, reference to shape model
SCRIPTS/XXX150.SEED   <- Reference to the make_scriptT.seed file
 00,    000           <- shape model lat/wlong for placement of the center of each new maplet
 00,    012
 00,    024
 00,    036
 00,    048
 00,    060
 00,    072
 00,    084
 ....
-84,    315
 90,    000
-90,    000
END

make_scriptT seed file - File containing the lithos commands for generating each new maplet. Refer to make_scriptT.seed for more information.

Image Tiling

The 1st line must be "IMAGES".
The 2nd line is the script name
Following lines are image name, sample and pixel
- Image name must be char 1-12. Sample and pixel are after that with any fortran format (space or comma delimited)
Ends with the statement "END"
# symbol will cause that entry to be skipped

Here is an annotated sample make_scriptT.in file used for tiling an image:

IMAGES                        <- For maplet locations, reference to shape model
TIL_eekingLimbsInImage.seed   <- Reference to the make_scriptT.seed file
D7175061248G 358 511          <- image name followed up pixel/line location 
D7175061210G 372 515
D7175061210G 387 513
D7175061210G 403 507
 ....
D7175061210G 566 887
END

(Compiled by DL)

make_scriptT.seed

Description

This seed file is used by make_scriptT, the script-maker for tiling a bigmap or shape with a suite of new maplets. make_scriptT.seed contains the lithos commands for processing each new maplet.

Here is an annotated sample make_scriptT.seed file:

0.00010,49       <- maplet ground sample distance and Q-size
g                <- turn on auto-rename (based on its shape model lat/wlon region)
i                <- input landmark
a                <- new landmark temporary name 'a', will immediately be auto re-named
y                <- check for more images
.5               <- fractional width, 0.5
n                <- don't reject invisibles
x                <- turn on extract filter
.025             <- extract filter tolerance, 0.025
0                <- find template
a                <- use all images
b                <- get heights from surrounding map
n                <- don't list all possibilities
XXXXXX           <- reference map name (temporary file which contains tiling bigmap)
n                <- find normal
2                <- find normal from heights
b                <- get heights from surrounding map (as above)
n
XXXXXX
u                <- update landmark files
1                <- save map
v                <- find V, Z, or PTG
2                <- find Z from V and pointing
e                <- eliminate images from landmark 
a                <- auto-remove
0,60,.25,.25,0,3 <- INVLIM, SLIM, CLIM, RSMN, RSMX
1                <- align landmarks
0                <- auto-align
3                <- auto-align spacing, 3
n                <- don't try new spacing
0                <- continue (full shift)
y                <- update landmark pixel locations
1                <- align landmarks (as above)
0
1                <- auto-align spacing, 1
n
0
y
0                <- find template
c                <- use correlated images
.5               <- correlation limit, 0.5
0                <- find template (build template #1)
0                <- continue
40               <- number of iterations, 40
1                <- align landmarks (as above)
0
3
n
0
y
1                <- align landmarks (as above)
0
1
n
0
y
e                <- eliminate images from landmark
o                <- remove low correlating images
.5               <- correlation limit, 0.5
0                <- find template
a                <- use all images
u                <- update landmark files (as above)
1
0                <- find template (as above) (build template #2)
0
40               <- number of iterations, 40
2                <- find heights (build topography #1)
8                <- fill with shape
2                <- include existing heights
.01              <- existing heights, fraction of points, 0.01
1                <- auto-include neighboring maps
4                <- include limb vectors
1, 2.5, 3        <- expansion (1), res/scale (2.5), d_hgt limit (3)
6                <- include differential stereo
y                <- use gradients
y                <- use auto heights 
0                <- begin iteration
.025             <- weight, 0.025
30               <- number of iterations
0                <- end iterations
u                <- update landmark files (as above)
1
v                <- find V, Z, or PTG
1                <- find V from Z and pointing
1                <- align landmarks (as above)
0
1
n
0
y
u                <- update landmark files (as above)
1
0                <- find template (as above) (build template #3)
0
40
1                <- align landmarks (as above)
0
2
n
0
y
1                <- align landmarks (as above)
0
1
n
0
y
e                <- eliminate images from landmark (as above)
o
.5
u                <- update landmark files (as above)
1
0                <- find template (as above) (build template #4)
0
40
2                <- find heights (build topography #2)
8
2
.01
1
4
1, 2.5, 3  
6
y
y
0
.025
30
0
u                <- update landmark files (as above)
1
v                <- find V, Z, or PTG (as above)
1
1                <- align landmarks (as above)
0
1
n
0
y
u                <- update landmark files (as above)
1
o                <- attach map to maps or limbs
RECENT           <- re-load most recent maplet
y                <- reset all
1                <- automatic
o                <- attach map to maps or limbs
RECENT           <- re-load most recent maplet
n                <- don't reset all
3                <- attach map to limbs
y                <- clear
1, 3, 5          <- expansion (1), res/scale limit (3), d_hgt limit (5)
i                <- input landmark
RECENT           <- re-load most recent maplet
n                <- don't check for more images
n                <- don't include single image
v                <- find V, Z, or PTG (as above)
1
u                <- update landmark files (as above)
1
v                <- find V, Z, or PTG
4                <- find PTG/SCOBJ from Z and V (current images) - update S/C position and pointing
o                <- attach map to maps or limbs
RECENT           <- re-load most recent maplet
n                <- don't reset all
1                <- automatic
q                <- quit lithos
END

(Compiled by DL)