Introduction

The Origins, Spectral Interpretation, Resource Identification, and Security–Regolith Explorer (OSIRIS-REx) mission will return the first pristine samples of carbonaceous material from the surface of a primitive asteroid. OSIRIS-REx’s target asteroid (101955) Bennu is the most exciting, accessible, volatile, and organic-rich remnant from the early solar system, as well as one of the most potentially hazardous asteroids known.

After launching in September 2016, OSIRIS-REx begins a two-year cruise to Bennu that includes an Earth flyby in September of 2017. OSIRIS-REx detects Bennu 60 days in advance of rendezvous and surveys its environment for natural satellites and other hazards. OSIRIS-REx then spends the next 7 months characterizing the surface and orbital environment of Bennu. Four candidate sample sites are characterized with OSIRIS-REx’s instrument suite and the Touch-And-Go (TAG) maneuver sequence is practiced. In October 2019, OSIRIS-REx executes the TAG maneuver and collects both bulk and surface samples. After a period of quiescent drifting away from Bennu, in March of 2021, OSIRIS-REx begins its return journey to the Earth. Following a 2.5 year return cruise, the Sample Return Capsule (SRC) is released, re-entering Earth’s atmosphere and landing at the Utah Test & Training Range in September of 2023.

SPOC Overview

The Science Processing and Operations Center (SPOC) is the centralized location for all OSIRIS-REx science data processing during the operational phases of the mission.

Spacecraft telemetry, science instrument data, and tracking information are received by the SPOC. The Ingest portion of the SPOC system ingests the raw science and engineering telemetry for all instruments via the Front End Data System (FEDS) interface. The Digest portion of the SPOC server then composes complete telemetry products, reassembles data packets into complete buffers, generates L0 and L1 engineering data products for all science instruments, processes L0 un-calibrated science data products into L2 products ready for analysis, and creates FDS OpNav deliverables. The science team develops science data products for site selection as well as long-term science, and places those in the SPOC repository. All data products are available on the SPOC data repository for storage, retrieval, and delivery to the PDS.

PART I. OVERVIEW

How SPC Works

SPC is a suite of software routines that uses both stereo imaging and photoclinometry to derive topography, referred to as "the shape model". The routines are able to generate topography with accuracy near the resolution of the source images. If the images have significant overlap, then it can produce a stereo derived topographic model. If the images have significantly different illumination conditions, then it can produce a photoclinometry-based model. However, with most planetary missions, there are many more images that do not qualify as stereo pairs, so a combination of the two methods provide topographic solutions based on a much wider base of images.

At its root, SPC is geometric stereo, meaning that it starts with geometry to calculate the height of individual control points on the surface using two or more images taken from different directions. The advantage of SPC is that it integrates both the albedo and shape of the surface in an iterative process to increase precision and resolution. If there is no change in illumination conditions, SPC is reduced to multi-image photogrammetry. If there is an insignificant stereo angle, SPC works as 2D photoclinometry with multiple images. For additional background, see Gaskell et al., 2008.

Data and Environment Requirements for the SPC Process

Observation and Data for Optimal SPC Results

Traditional stereo requires:

  • Images that are taken with similar lighting conditions
  • Stereo angle between 10 and 40°
  • Images have nearly identical image resolution

Stereophotoclinometry works best with:

  • A minimum of three images (typically >30, this study 4)

  • Two stereo images
  • Emission angles 45° (acceptable 35-48°, limit 5-60°)
  • Stereo angle 90° (acceptable 70-110°, limit 10-120°)
  • Incidence angle 0° (acceptable 0-20°, limit 0-60°)
  • Three photoclinometry images
  • Emission 0° (acceptable 0-20°, limit 0-60°)
  • Incidence angles 45° (acceptable 30-50°, limit 0-60°)
  • Variation in illumination geometry of 90° (acceptable 40-90°, limit 10-120°). This refers to having different positions of the Sun with respect to the observed target.

In general, geometric stereo is more accurate for long scale topography, while photoclinometry is better for short scale (Kirk 2003). SPC uses both of these components to mitigate the errors that are caused by each of them. Stereo creates a position in 3D space using 3-5 pixels from an image. SPC typically sets control points (called "landmarks") with a spacing of 30 pixels. Thus, the landmarks (or point clouds) have a spacing that is a factor of 10 lower than traditional geometric results.

SPC will use photoclinometry to calculate and fill in the heights of the points between the landmarks. The horizontal ground sample distance (referred to as "resolution") is typically on the order of the resolution of the images, and we have successfully generated topography at double the image resolution. The calculations of the points between landmarks are solved in 99x99 grids (or "maplets"), so most heights are solved by multiple maplets. The iterative solution is continued until the solutions for points common to multiple maplets agree, resulting in the accuracy of all of the topographic heights being controlled by stereo but generated by photoclinometry at a higher ground sample distance.

Computing Environment and Tools for SPC Process

The programs described in this document are written in FORTRAN and compose a toolkit that have been traditionally compiled and run within a UNIX or LINUX operating system. Most of these machines have been Apple computers . Specific computers and tools used in the SPC process are listed below.

Table 00: Required Resources and Ancillary Tools

Machines/Workstations

OS / Core SW Versions

Notes

ormacsrv1.lpl.arizona.edu

A 12-core Macintosh X-Server, to execute the SPC programs

cloud.psi.edu:

A 12-core Macintosh Pro Workstation, to execute the SPC programs

cloud9.psi.edu

A 12-core Macintosh Pro Workstation, to execute the SPC programs

ormacsrv1

Mac OSX 10.9.5

Access to ormacsrv1 via internet, to allow testers to run programs from their local facility

ormacsrv1/tape

Backup storage for test results, scripts, etc

Software Tools

Version

Notes

SPC Tools

3.0A2

As a set the complete tool kit is identified as release 3.0A2 but modules can have different revisions and are identified here.

Baseline

2.1A7

REGRES

3.0A0

GEOMETRY

3.0A0

PROCESS_FITS

3.0A2

Bash shell

awk

perl

rsync

xv

ImageMagick

vi

Graphics Converter

webserver

spc_align toolkit

SPC Process

SPC uses a three-step iterative process to derive a shape model:

  • register images
  • warp the model
  • update camera position/pointing

We start with an initial shape model that is very low resolution but that provides a starting point for SPC. This shape can come from limb measurements, a radar shape model, spherical harmonics or, if need be, can be derived via a mathematical representation of a tri-axial shape. In this case, it is set to a flat surface.

The following discussions explain each of these three steps in more detail.

Step 1. Register

The first step is to register the images to a reference frame. To do this, we use a large number of landmarks. For each landmark, we generate a small 99x99 pixel maplet. Each image that falls within one maplet is orthorectified and projected onto the shape model. Here is a sample:

spc_explained_fig1.jpg

Figure 00: Initial Shape with Maplet Overlay

Associated with each of these maplet views is the shape model with albedo, which is illuminated at the same solar geometry, as shown in the following sample:

spc_explained_fig2.jpg

Figure 00: Maplet with Variation in Solar Illumination

In these four images, there is significant variation in illumination conditions, resulting in a significantly different looking terrain. The bottom row are images based on the shape model, only illuminated with the space conditions as the corresponding image. By projecting all the images to the same orientation and scale, and illuminating the model accordingly, we can more precisely register images over a significantly wider range of emission angles, thus reducing topographic error. These maplets are 500 meters across.

We use both manual and automated tools to co-register the images within each maplet such that the center point of each maplet is in the same location as on all the rest. Because the images are orthorectified, we can have the same view of each of them, increasing our ability to match identical features, even if the original viewing geometry makes them hard to identify. There are minor improvements in the co-registration of images as the shape model improves because this reduces projection error and, correspondently, any mis-registration.

Step 2. Warp the Model

Once the landmarks are registered, we use that information to update the shape model. While the height of the center of the landmark is initially derived from geometric stereo, we use photoclinometry to solve for the heights of every pixel of the landmark. Simple photoclinometry is 1D and requires the albedo to be a constant so that the only variation in pixel intensity is the topography. For SPC, we have a full 3D model that includes albedo. As described previously, for each image within a maplet, we illuminate the shape model to correspond to it. Because we are fully controlling for topography and albedo, any variations in each image's pixel DN from its representative shape model DN is an error in the model. The deviations are turned into corrections for both albedo and topography. A configuration file within SPC provides weighting that is applied to the corrections for albedo and topography. For example, when working with a low relief surface with high contrast, the user puts more weight on changing the albedo rather than the topography, and vice versa. The weighting only affects how fast the model converges to a solution; it does not affect the solution itself. For example, if SPC has made an overcorrection to albedo, then when the terrain is processed again, the albedo will be corrected.

Step 3. Update Camera Position/Pointing

The next major step of SPC is to take the updated heights of the surface and use those to improve the actual position and pointing of the spacecraft. Within an image, each of these landmarks (in this context, they are working like a control point) provides the exact sample/line position of the landmark. This data, along with the angular field of view of each pixel, allows SPC to determine the position and pointing of the spacecraft. Note that a narrow field of view makes it difficult to break the degeneracy where a displacement can be either position or pointing. This is handled by weighting each of these terms based upon the calculated errors in positions and pointing. Typically, these estimates are provided by the navigation team. This correction of camera position/pointing and the assumptions made by those generating the topography account for the major differences between SPC and traditional stereogrammetry.

Additional Processing

As the shape model is processed, the steps of register/morph/update are iterated until the residuals of the solution approach a minimum. We use a variety of tools to evaluate mis-registration problems, image artifacts, or regions with insufficient image coverage (the worst of which occurs with a lack of stereo). The main tool is a program called RESIDUALS that reports deviations in distance (meters) or pixels. It calculates the position on the shape model of each landmark/image combination. For each landmark, it takes the deviation of position of each of its images to calculate the RMS error. The RMS error shows how close all of the image data is aligned to represent the surface of the object. It is a fully geometric solution based upon the registration of the landmarks (or control points) and the position of the spacecraft.

Output Products

The main output product for SPC is a shape model, a 3D set of position vectors that define the heights. This can be converted into a vector/plate model. The output from SPC for a bounded surface is called a BIGMAP. This product has a regular ground sample distance (resolution) and, for each point, it takes the average value of all the maplets that contain each point. The BIGMAP also contains a scaled albedo (or scaled average surface reflectance) for each point.

PART II. HOW TOS

Stage 1 - Initial Load

The first stage of building the shape model is to bring in the first set of images and generate landmarks from them. The following figure illustrates the general process of this stage.

stage1_figure.jpg

Figure 00: Block Diagram for Startup

First, the images are imported into the SPC system and converted into the SPC internal format. Then the alignment of the images is improved. Next, a set of initial landmarks is generated with a GSD of 120cm at a spacing of 20 degrees. Batch processing then generates the topography and improves the landmark registration.

The following table details the blocks, the procedures and the programs used to accomplish this stage:

Table 00: Procedures for Initial Start

Block

Procedure Name

Executables

Block 1

Setup Directory

Block 2

Ingest

process_fits, make_sumfiles

Block 3

Register

register, make_scriptR

Block 6A

Lat/Lon Tiling

make_scriptT, find_nofit

Block 5

Iterate

make_scriptP

Block 7

Clean

residuals, find_nofitP, map_coverage

Stage 2 - Adding Images

Most of the blocks in Stage 2 are similar to those in Stage 1. For those blocks, the commands will be the same. The major difference in Stage 2 is the use of autoregister. The following diagram shows the general process for Stage 2.

stage2_figure.jpg

Figure 00: Block Diagram for Adding Images

Autoregister loads existing landmarks into a new image. When you give it an image, it locates all landmarks that fall within its boundaries. Then you can use auto-align (just as in LITHOS). You can also do auto-eliminate and set the star flag for building a template. This generates LMRK_DISPLAY1.pgm which shows pairs of landmarks for the image.

The following table shows the blocks, the procedures and the programs used to complete Stage 2:

Table 00: Procedures for Adding Images

Block

Procedure Name

Executable

Block 2

Ingest

process_fits, make_sumfiles

Block 3

Register

register, make_scriptR

Block 4

Autoregister

autoregister

Block 5

Iterate

lithos, lithosP, make_scriptP

Block 7

Clean

residuals, densify

Once you have built the initial shape in Stage 1, it will replace the Nolan radar shape model stored in the SHAPEMODELS directory. This allows a more effective image projection and registration when ingesting new images.

Stage 3 - Increase Resolution

Here is an illustration of the general process of Stage 3.

stage3_figure.jpg

Figure 00: Block Diagram for Generation of Subregion Maps

In Stage 3 you will use several automated processes to craft subregions using bigmap, tile that bigmap with higher resolution maplets and then process them until the topography becomes stable (i.e., does not change much between iterations). Bigmaps are flat maps of a section of the shape model. They allow you to focus on a specific section of the shape, which decreases the number of data files being processed. Bigmaps are also 2D rather than 3D, allowing for easier display and analysis than the full shape model.

The following table shows the blocks, the procedures and the programs used to complete Stage 3:

Table 00: Procedures for Subregion Map Creation

Block

Procedure Name

Executable

Block 6B

Bigmap Tiling

bigmap, map_coverage, make_tilefile, make_scriptT, lithos

Block 5

Iterate

lithos, make_scriptP, lithosP

Block 7

Clean

residuals

The goal of stage 3 is to increase resolution, which requires creating numerous additional maplets. You do this by tiling a bigmap with more maplets. Typically, you define a region of the surface with a bigmap of 1000 x 1000 pixels (OSize = 500). The scripts then produce input files for lithos that create new maplets every 50, which generates about 360 new maplets. The resolution for the maplets is set to create at least 25-30% overlap.

You will iterate these products until the error among the maplets is low. Iteration consists of running Step 3-5 “Batch Topo” numerous times. Next, you will use the criteria in Step 3-6 “Evaluate” to indicate where there are problems with the shape model and what needs additional attention. When the residuals become small and the delta correction in the topography becomes small, or if met the navigation requirement, you will output the complete model. Maplets that have problems will go through Stage 4 - Problems.

PART III. REFERENCE

Programs

autoregister

Category B

Version 3.0

Description

This program is used to register existing maplets with imaging data from a single image.

autoregister

  • adds landmarks to a single image, adding the image name to all relevant LMKFILEs and adding the landmark names to the SUMFILE
  • 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 when the user accepts the changes from the auto-align (or manually aligns)

autoregister 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.

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

  • /!\ autoregister 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

Output Files

  • SUMFILES/ - Landmarks are added to the image's SUMFILE. Spacecraft/camera position/attitude are updated upon user acceptance of alignment shifts.

  • LMKFILES/ - LMKFILES is updated to contain the image the user is working with.

  • LMRK_DISPLAY1.pgm - 100x100 pixel display of images (odd rows) and maplets (even rows). Unlike in 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 the user is working with.

User Warnings

  • /!\ autoregister 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 autoregister, 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).


Using autoregister

Initial Inputs

The following sample 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
  1. Enter the image name that is stored in IMAGEFILES.

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

  3. The program produces a list of existing landmarks, if any, creates the TEMPFILE.pgm and displays the kb and kk values.
  4. (!) kb and kk are de-bugging flags relating to the generation of TEMPFILE.pgm and are not discussed here.

  5. Enter 'q' as the image name to quit.
  6. If you wish to add more landmarks, enter '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

  7. 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.

  8. 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.

    • /!\ Responding 'y' is very restrictive in that it will discard landmarks whose maps are only partially occulted. It is also very time consuming.

      • For convex bodies such as Eros or 67P Churyumov-Gerasimenko another solution is to respond 'n' but set the INVLM value not to 0.0 as is the usual input but a higher number, e.g. 100, so it will keep landmarks whose maps are 10% occulted.

    /!\ When landmarks are added in autoregister, 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.

autoregister will generate a bitmap formatted file called TEMPFILE.pgm, as shown below. This has two images for each landmark. The top image is a subsection of the real images that is the landmark, but orthorectifed. The lower image is the shape model illuminated in the same conditions as the real image. The alignment between these features must be as accurate as possible (at least one pixel). The file will get updated each time the program prints out the Main Menu.

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

autoregister Main Menu

 ...     MAIN MENU     ...

 0. Exit

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

 IMAGE/MAPLET ALIGNMENT
 1. Auto align
 2. Manual align

 LANDMARK ADJUSTMENTS
 3. Repredict px/ln
 4. Change flags
 l. Change repredict limit

Enter '0' to exit the processing of the current image and choose a new one.

Enter 'q' for the image name to quit the process altogether.

REMOVE MAPLETS Options

The first block of options removes landmarks according to a variety of filters. If you choose a, n, m or p, you will see a table with these column headers:

  • # - landmark number

  • LMKNM - landmark name

  • EMISS - emission angle

  • COV - maplet-image overlap

  • RES - image resolution/maplet scale

  • INV - 1000 x invisible fraction of maplet

  • #PIC - number of images in maplet

Options a and n remove landmarks according to one of these filters:

  • INVLIM - maximum fraction (in thousandths) of invisible points in the maplet according to the current topography. For example, an obliquely viewed maplet may have part of a crater bottom that can't be seen. An INVLIM of 27 represents 2.7%.

  • SLIM - maximum emission angle.

  • CLIM - coverage limit. Minimum fraction of maplet covered by illuminated image data.

  • RSMN - Minimum allowed ratio of image resolution (km/px) to maplet scale.

  • RSMX - Maximum allowed ratio of image resolution (km/px) to maplet scale.

Option a - Filters all landmarks. Option n filters only newly added ones. A display provided for the a and n options shows the number of images with resolutions from 0 to 3 times the maplet scale (column labels 00 - 30) and emission angles from 00 to 90 (rows).

Option m- Allows you to manually remove a list of landmarks. Type a list of images with a return after each one. At the end of the list, you must type 0 to finish the input. You can also remove a consecutive group of landmarks by typing start, end then a 0 on a new line. For example 2,10 will remove landmarks 2 through 10.

Option p - Removes images in the part of the maplet obscured by another part of the body.

Option o - Eliminates images whose correlation with the illuminated maplet is less than a specified value. Acceptable values are between 0 and 1.0.

  • /!\ You must run Option 1. Auto align first to establish those correlation values.

IMAGE/MAPLET ALIGNMENT Options

This block of options aligns extracted imaging data with the corresponding illuminated maplets. The EXTRACT_DATA subroutines populate the landmark displays with image data projected onto the current maplet surface. We assume the maplet surfaces are correctly placed and oriented and have the correct topography. If the spacecraft position and camera pointing were correct at the image exposure time, then all maplets would align. If not all the maplets align, then the amount of misalignment can be used to correct the spacecraft state. This process performs the alignment, updating the pixel/line image-space landmark positions from their predicted values.

All windows in autoregister are 99x99 pixels. If a maplet has QSZ < 49, as sometimes happens very early in the SPC process, then there will be dark space surrounding it. If QSZ > 49, then only the central portion of the maplet will be aligned. QSZ is standard notation for the size of the Maplet. The overall width is 2*QSZ+1 in pixels.

Option 1. Auto align - Requires you to respond to several prompts. Here is a sample:

1
    1   EE0001
    2   EE0002
    3   EE0003
    4   EE0004
    5   EE0005
    6   EE0006
    7   EE0007
    8   EE0008
    9   EE0009
   10   EE0010
   11   EE0011
   12   EE0012
   13   EE0013
   14   EE0014
   15   EE0015
   16   EE0016

 enter spacing
1
   1   EE0001        0.008     0.153     0.955 +++++
   2   EE0002        0.023     0.152     0.956 +++++
   3   EE0003        0.058     0.062     0.961 +++++
   4   EE0004        0.185    -0.056     0.960 +++++
   5   EE0005        0.006     0.029     0.967 +++++
   6   EE0006        0.002     0.009     0.966 +++++
   7   EE0007        0.043    -0.030     0.963 +++++
   8   EE0008        0.109    -0.038     0.963 +++++
   9   EE0009       -0.031     0.047     0.971 +++++
  10   EE0010       -0.021     0.014     0.969 +++++
  11   EE0011       -0.008    -0.048     0.958 +++++
  12   EE0012        0.069    -0.109     0.943 +++++
  13   EE0013       -0.352    -0.027     0.927 +++++
  14   EE0014       -0.175    -0.039     0.914 +++++
  15   EE0015        0.073    -0.058     0.913 +++++
  16   EE0016        0.371    -0.119     0.859 +++++
     0.147     0.076

 new spacing? (y/n)
n

 0.  continue.
 1.  halve shifts.
 2.  quarter shifts.
0

 update landmark pixel locations? (y/n)
  • Enter Spacing - Enter the size of the search area for the correlation. Enter '1' to search a 5x5 pixel area, '2' for 10x10 and so on.

    The Auto-alignment routine output table includes these columns:

    • column 1 - landmark number

    • column 2 - landmark name

    • column 3 - the pixel shift predicted by the correlation

    • column 4 - the line shift predicted by the correlation

    • column 5 - the correlation value

    • column 6 - the goodness of fit indicator that ranges from 0 to 5

    If there is no correlation result at all, columns 3 and 4 have values 0.0000. This value, with the extra decimal place, is recognized by some diagnostic programs.

    /!\ Depending on the search area, e.g., 1,2 etc, you may sometimes have a false positive of 1.0000 correlation when in fact there's no correlation at all.

    new spacing? (y/n) - Enter 'y' and the new spacing.

    • (!) You can repeat through several spacings until the correlation is satisfactory.

    When you are satisfied with the correlation, enter 'n'. Then choose from these options:
    • 0. continue - Shifts all the maplets by the amount determined by the correlation.

      1. halve shifts - Shifts all the maplets by half the amount determined by the correlation.

      2. quarter shifts - Shifts all the maplets by one-quarter the amount determined by the correlation.

    update landmark pixel locations? - Enter 'y' if you want to accept the shift. If you enter 'n' the program returns the parameters to the starting values. For the larger search area, the data is binned.

    /!\ After alignment is reached, you should always go back and run it again with a spacing of 1.

Here is an annotated set of typical keystrokes in a script for Option 1. Auto align:

 1  <- auto align
 3  <- spacing 3
 n  <- no spacing change
 0  <- shift by full amount
 y  <- keep shift
 1  <- auto align
 1  <- spacing 1
 n  <- no spacing change
 0  <- shift by full amount
 y  <- keep shift

Option 2. Manual align - This option can be used to align the problem image data to a maplet by hand by referencing LMRK_DISPLAY1.pgm. The process asks you to move the image window in pixels (+ right) and lines (+ down) in order to align it to the maplet.

  • (!) Option 2 is only used occasionally.

LANDMARK ADJUSTMENTS Options

Enter one of these 3 options:

Option 3 - Use this option to repredict the image-space landmark locations for all maplets. Because the maplets have different resolutions, some may correlate well and some not at all. autoregister only uses correlations greater than CORLIM, nominally set to 0.5, to determine the s/c state. After you have used Option 3, subsequent correlations calculated using Option 1 will be much better.

Option l - Use this option to choose a different value for CORLIM.

Option 4 - When images are added via autoregister, they are by default marked with a flag where they are not used for generation of LANDMARK templates. Use this option to adjust the flags of each landmark (.LMK) file.

Here is a sample showing the output from Option 4.

4
    1      EE0001     0.955     0   *
    2      EE0002     0.956     0   *
    3      EE0003     0.961     0   *
    4      EE0004     0.960     0   *
    5      EE0005     0.967     0   *
    6      EE0006     0.966     0   *
    7      EE0007     0.963     0   *
    8      EE0008     0.963     0   *
    9      EE0009     0.971     0   *
   10      EE0010     0.969     0   *
   11      EE0011     0.958     0   *
   12      EE0012     0.943     0   *
   13      EE0013     0.927     0   *
   14      EE0014     0.914     0   *
   15      EE0015     0.913     0   *
   16      EE0016     0.859     0   *

 Input number to change (a chg all, b use all, 0 to end).

There are three sub-options to option 4.

  • a chg all -- this toggles each entry -- seldom used

    b use all -- removes the no-use flag on all images -- normally used

    0 to end -- quit without changing

The one usually used is 'b'. It removes the * from the PICNM record for all landmarks.

Batch Processing

autoregister can be run in a batch mode, following a script set up by make_scriptA. . You would use make_scriptAP to build the batch script files to autoregister in parallel. The executable, autoregisterP, is an update to autoregister, but contains file-access deconfliction to avoid multiple processes from writing to the same file at the same time.


Additional Reference

LMRK_DISPLAY1.pgm

autoreg_disp.jpg

Figure 00: Comparison of Landmarks and Associated Maps

autoregister_example.jpg

Figure 00: Illustration of Autoregister and Landmark Options


(Compiled by DL)

CategoryPrograms

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

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
  1. Enter a 2-character USR name to distinguish between processes.
  2. 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.
  3. 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

  4. 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.

  5. (!) If you enter '0.0', the image must contain the landmark center.

  6. Typically, enter 'n' for Reject invisibles? unless the object is bizarre, such as Eros.

  7. (!) 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

CategoryPrograms

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:

sig2.jpg

Figure 00: Output of SIGMAS Graphical Format


(Compiled by TC)

CategoryPrograms

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)

CategoryPrograms

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. 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:

blemTEMPFILE_before-resized.jpg

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:

blemTEMPFILE-block-resized.jpg

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.

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

blemTEMPFILE-spot-resized.jpg

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:

   488   225
   489   225
   490   225
etc...
   534   275
   535   275
   536   275
   537   275
END

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


(Compiled by DL)

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

CategoryPrograms

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

Optional Files

Output Files

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

  • Shape file in ICQ format


Using densify

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

~/bin/densify < tmpRun.txt

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

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

The input commands are:

  • line 1 - The input SHAPE file

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

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

  • line 3 - The output SHAPE file

  • line 4 - 1 = an iteration

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

  • line 6 - The conditioning weight

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

  • last line - 0 = end program

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

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

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

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

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

     0. end program
     1. proceed to iteration

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

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

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

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

If you enter '1', the program prompts:

     input fraction

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

The program prompts:

     input weight

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

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

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

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

By tradition, usually use:

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

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

     cp SHAPEFILES/SHAPEX.TXT SHAPEFILES/SHAPE2.TXT

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

     cp SHAPEFILES/SHAPEX.TXT SHAPEFILES/SHAPE3.TXT

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

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

At the command line enter:

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

Interactive

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

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

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

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


(Compiled by TC)

CategoryPrograms

densifyA

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

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

Optional Files

Output Files

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

  • Shape file in ICQ format


Using densifyA

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

~/bin/densify < tmpRun.txt

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

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

The input commands are:

  • line 1 - The input SHAPE file

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

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

  • line 3 - The output SHAPE file

  • line 4 - 1 = an iteration

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

  • line 6 - The conditioning weight

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

  • last line - 0 = end program

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

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

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

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

     0. end program
     1. proceed to iteration

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

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

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

If you enter '1', the program prompts:

     input fraction

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

The program prompts:

     input weight

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

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

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

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

By tradition, usually use:

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

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

     cp SHAPEFILES/SHAPEX.TXT SHAPEFILES/SHAPE2.TXT

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

     cp SHAPEFILES/SHAPEX.TXT SHAPEFILES/SHAPE3.TXT

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

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

At the command line enter:

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

Interactive

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

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

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

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


(Compiled by TC)

CategoryPrograms

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

  1. 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.

  1. 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)

CategoryPrograms

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)

CategoryPrograms

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.

  1. 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.

  2. 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
  1. Run this script by entering the following at the command line:

sh EXPORT.TXT
  1. Change the name of NEW_FILES.tar to something distinctive like
    • new_<bigmapName>.tar

  2. 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)

CategoryPrograms

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

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)

CategoryPrograms

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

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)

CategoryPrograms

geometry

Category B

Version 3.0

  • {X} 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

User Warning

  • {X} 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.

geometry_imagedataoffset.jpg

geometry_errosfromincorrectdataoffset.jpg

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.

geometry_outline.jpg

Figure 00: Illustration of Iterative Process for Updating Geometry


(Compiled by TC)

CategoryPrograms

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

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:



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)

CategoryPrograms

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)

CategoryPrograms

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

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)

CategoryPrograms

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

Output Files


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

CategoryPrograms

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)

CategoryPrograms

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:

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:

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

  1. 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   
  1. 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
  1. 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.

  1. 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)

CategoryPrograms

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:

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:

i
EE0001
n                   
n                   
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                   
q                   

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)

CategoryPrograms

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)

CategoryPrograms

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:

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

  • {X} 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

{X} 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 &

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 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)

CategoryPrograms

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

Output Files


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)

CategoryPrograms

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

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)

CategoryPrograms

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

  1. Input the filename of a bigmap:

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

 0,.001 

Here is a sample output from map_coverage:

map_coverage.jpg

Figure 00: Example of map_coverage Output


Compiled by KD

CategoryPrograms

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

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

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

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.

  1. 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.
  2. 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".

  3. 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)
  4. 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.
  5. 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)
  6. 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 216 / 214 (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.

  1. 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
  2. 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

  3. 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)
  4. 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)
  5. 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 216 / 212 (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

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:

exTEMPFILEpgm.png

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

Here is a sample TEMPFILE.ppm file image:

exTEMPFILEppm.png

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:

register_AlignsNewImage.jpg

Figure 00: Sample Registration of an Image with a Shape

register_AlignsNewBigmaps.jpg

Figure 00: Sample Registration of an Image with a BigMap

register_example.jpg

Figure 00: Illustration of Options using Register


(Compiled by DL)

register-3.0

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

CategoryPrograms CategoryThreeAlphaThree

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)

CategoryPrograms

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

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:

residuals_controlpoint1.jpg

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

residuals_imageresiduals.jpg

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

residuals_WhatWentWrong.jpg

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)

CategoryPrograms

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)

CategoryPrograms

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


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)

CategoryPrograms

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:

sample_ALB.jpg

Figure 00: Albedo Output from spheremapsB

sample_COL.jpg Figure 00: Color DTM Output from spheremapsB

sample_DTM.jpg

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.

CategoryPrograms

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.

lithos_ExtractingImageData2.jpg

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.

lithos_ExtractingImageData2.jpg

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

  1. 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
  1. 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.
  2. 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.

lithos_PredictedBrightnessAfter40Iterations.jpg

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)

CategoryLithosMenu

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.

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

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

  1. 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:

  • 1
  • 0
  • 1
  • n
  • 0
  • y

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)

CategoryLithosMenu

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:

  1. 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.

  1. Number of iterations - Typically use 30.

  2. 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 exit.

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)

CategoryLithosMenu

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,

  1. load the landmark of interest
  2. 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:

  1. The overlapping maplet (LMK1) is projected into the coordinate system of the maplet-of-interest (LMK0).
  2. A correlation is found by shifting LMK1.
  3. 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)

CategoryLithosMenu

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)

CategoryLithosMenu

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.

  • {X} SAVE OFTEN! Use this option frequently to save work in progress.

q. Quit - Returns to Main Menu.


(Compiled by JRW)

CategoryLithosMenu

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.

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.

  1. Enter a picture name (12 characters).
  2. 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.

  1. 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.

  1. Enter the maplet/bigmap name (6 characters).
  2. 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

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


(Compiled by JRW)

CategoryLithosMenu

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)

CategoryLithosMenu

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) -

  1. Enter the new GSD
  2. Enter the new Q size
  3. 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:

before.jpg

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.

after.jpg

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


(Compiled by JRW)

CategoryLithosMenu

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)

CategoryLithosMenu

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)

CategoryLithosMenu

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)

CategoryLithosMenu

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)

CategoryLithosMenu

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)

CategoryLithosMenu

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)

CategoryLithosMenu

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)

CategoryLithosMenu

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)

CategoryLithosMenu

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.

    {X} 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)

CategoryLithosMenu

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)

CategoryLithosMenu

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)

CategoryLithosMenu

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)

CategoryLithosMenu

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)

CategoryLithosMenu

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)

CategoryLithosMenu

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)

CategoryDirectories

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)

CategoryDirectories

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)

CategoryDirectories

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.

LMKFILES_landmark.jpg

Figure 00: Landmark File Information Illustration


(Compiled by TC)

CategoryDirectories

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)

CategoryDirectories

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

lithos_nominal.jpg

Figure 00: Nominal File Illustrating the Starting Solution


(Compiled by KD)

CategoryDirectories

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.

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)

CategoryDirectories

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:

SummaryFile.jpg

Figure 00: SUMFILES Information Illustration


(Compiled by KD)

CategoryDirectories

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)

CategoryDirectories

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)

CategoryDirectories

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)

CategoryFiles 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)

CategoryInputFiles CategoryInputFiles

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)

CategoryFiles 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)

CategoryInputFiles CategoryInputFiles

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)

CategoryFiles CategoryInputFiles

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

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]

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)

CategoryFiles CategoryInputFiles

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)

CategoryFiles CategoryInputFiles

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)

CategoryFiles CategoryInputFiles

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).

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)

CategoryFiles CategoryInputFiles

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)

CategoryFiles CategoryInputFiles

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)

CategoryFiles CategoryInputFiles

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)

CategoryFiles CategoryInputFiles

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)

CategoryFiles CategoryOutputFiles

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)

CategoryFiles CategoryOutputFiles

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)

CategoryFiles CategoryOutputFiles

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:

T00144
T00145
T00146
T00160
T00161
T00162
T00163
END


(Compiled by TC)

CategoryFiles CategoryOutputFiles

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.

  • {X} LIMINFO.TXT is no longer generated by the v3.0 software and will not be generated during OSIRIS REx.


(Compiled by DL)

CategoryFiles CategoryOutputFiles

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)

CategoryFiles CategoryOutputFiles

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)

CategoryFiles CategoryOutputFiles

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)

CategoryFiles CategoryOutputFiles

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)

CategoryFiles CategoryOutputFiles

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)

CategoryFiles CategoryOutputFiles

NEW_LIST.TXT

Description

This text file lists new landmarks created during batch make_