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:

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:

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.

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.

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.

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

make_scriptA.seed - For batch processing using make_scriptA.

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).5Reject invisibles? (y/n)n 7 EE0007 0.00 8 EE0008 0.00 9 EE0009 0.00 10 EE0010 0.00 11 EE0011 0.00 12 EE0012 0.00 13 EE0013 0.00 14 EE0014 0.00 15 EE0015 0.00 16 EE0016 0.00

Enter the image name that is stored in IMAGEFILES.

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

The program produces a list of existing landmarks, if any, creates the TEMPFILE.pgm and displays the kb and kk values.

(!) kb and kk are de-bugging flags relating to the generation of TEMPFILE.pgm and are not discussed here.

Enter 'q' as the image name to quit.

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

Input the value for Fractional width . Normally this is '0.5'. This value allows images that overlap any part of a window that is half the size of the maplet window.

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

Typically, enter 'n' for Reject invisibles? unless the object is bizarre, such as Eros. (!) If you respond 'y', the program uses the current shape to determine whether there is topography blocking the camera's view of the landmark center.

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

Figure 00: Comparison of Landmarks and Associated Maps

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)

OptionalFiles

make_scriptA.seed - for batch processing using make_scriptAP

OutputFiles

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.TXTto 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 lithoswhere images are not added to landmarks until the landmark file is updated.

/!\Alignment changes are immediately accepted (i.e., there is no save/revert option).

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

Using autoregisterP

Initial Inputs

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

input 12-character picture name. q to quit.P3T11S2H0409 1 EE0001 * 2 EE0002 * 3 EE0003 * 4 EE0004 * 5 EE0005 * 6 EE0006 * gc TEMPFILE.pgm kb = 1 kk = 1 Add landmarks? (y/n)y enter fractional width (0=center).5 Reject invisibles? (y/n)n 7 EE0007 0.00 8 EE0008 0.00 9 EE0009 0.00 10 EE0010 0.00 11 EE0011 0.00 12 EE0012 0.00 13 EE0013 0.00 14 EE0014 0.00 15 EE0015 0.00 16 EE0016 0.00

Enter a 2-character USR name to distinguish between processes.

Enter the 12-character picture name.

The program produces a list of existing landmarks, if any, creates the TEMPFILE.pgm and displays the kb, and kk values.

If you wish to add more landmarks, respond 'y'. An initial filter for added images is set in INIT_LITHOS.TXT:

RESLM - the maximum ratio of the image resolution to the maplet scale

SIZLM - the maximum ratio of the linear maplet size to the image size

NUMLM - sets the minimum number of maplets found in the image before the other two filters come into play

Input the value for Fractional width . Normally this is '0.5'. This value allows images that overlap any part of a window that is half the size of the maplet window.

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

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

(!) If you respond 'y', the program uses the current shape to determine whether there is topography blocking the camera's view of the landmark center.

/!\When landmarks are added in autoregisterP, they immediately populate the image’s SUMFILE. Further processing must be conducted if you wish to remove the image from any of the landmarks. This is different from lithoswhere 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:

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.

OptionalFiles

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 nameP00045000455 gc TEMPFILE.pgm b. Block s. Spot q. Quit

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

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

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

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

Figure 00: Image Prior to Applying Mask

Block Blemish Options

Input pxmn, pxmx, lnmn, lnmx512 612 250 350 gc TEMPFILE.pgm b. Block s. Spot q. Quit

After you choose b. Block you must specify:

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

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

This sample shows the image after block masking was applied:

Figure 00: Image after Applying Blemish Mask

Spot Blemish Options

Input bad px/ln center, half-size. threshold.512 250 25 100 gc TEMPFILE.pgm b. Block s. Spot q. Quit

After you choose s. Spot you must specify:

px/ln center: Vector with element values in the range ([1:NPX],[1:NLN]) (where NPX is the number of pixels in image, NLN is the number of lines in image)

half-size: Half-size of masked area in pixels, e.g. a half-size of 2 will result in a masked area of 4 pixels x 4 pixels.

threshold: Digital Number (DN) representing the lowest threshold for brightness in the range, where 0 is dark, and will result in all brightnesses being masked. Note: The DN within BLEMISHES has been rescaled by 255/(Brightness DN). So if the original DN is 398 and the max is 1410, then the new DN will be 71 because the number is truncated. So if you want to mask 398, you need to enter 70 for the threshold.

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

Figure 00: Image Displaying Blemish Mask Options

Quit Blemishes Option

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

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

BLEMISH Templates

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

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

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

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

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

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

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

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

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

(Compiled by DL) (Updated by JRW)

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

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

LMRKLIST.TXT - List of all landmarks to be used

LMKFILES/ - Directory of .LMK files for each maplet

MAPFILES/ - Directory of .MAP files

SHAPEFILES/ - Directory of built shapes

Optional Files

LMRKLISTR.TXT - Specific list of landmarks desired

Output Files

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

Shape file in ICQ format

Using densify

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

~/bin/densify < tmpRun.txt

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

SHAPEFILES/PreviousShapeFile (input shape)2 100 1.67773 (K (power of 2), search range (km), random seed)SHAPEFILES/CurrentShapeFile (output shape) <--At this point the map-averaged shape at a higher resolution is made1 (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 integration11111111111110 (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

LMRKLIST.TXT - List of all landmarks to be used

LMKFILES/ - Directory of .LMK files for each maplet

MAPFILES/ - Directory of .MAP files

SHAPEFILES/ - Directory of built shapes

Optional Files

LMRKLISTR.TXT - Specific list of landmarks desired

Output Files

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

Shape file in ICQ format

Using densifyA

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

~/bin/densify < tmpRun.txt

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

SHAPEFILES/PreviousShapeFile (input shape)2 100 1.67773 (K (power of 2), search range (km), random seed)SHAPEFILES/CurrentShapeFile (output shape)1 (more iteration).005 (fraction of points used for conditioning).025 (conditioning weight)1 (more iterations)11111111111110 (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.

OutputFiles

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

Using duplicates

Create Input File

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

Run duplicates

duplicates processes landmark names as follows:

For every landmark listed in LMRKLIST.TXT, duplicates

checks that the MAPFILE exists

obtains the maplet's Q-size and Ground Sample Distance (GSD) from the LMKFILE

sorts the list by decreasing GSD and increasing name (lat/wlong identifier and numeric identifier)

discards duplicate entries

For every landmark listed in LIST.TXT, duplicates

checks that the landmark is also listed in LMRKLIST.TXT; if it is, the landmark is included in the output

duplicates writes the sub-set of ordered landmarks to make_script.in.

(!) The LANDMARK and MAP files for the landmarks included in LMRKLIST.TXT must exist in LMKFILES/ and MAPFILES/.

(!) duplicates only considers landmarks contained in LIST.TXT, that are also contained in LMRKLIST.TXT.

Here is a sample LMRKLIST.TXT file:

EE0001EE0002EE0003EE0004EE0005EE0006EE0007EE0008EE0009EE0010EF0001EF0002EF0003EF0004EF0005EF0006EF0007EF0008EF0009EF0010END

Here is a sample LIST.TXT file:

EF0006EF0006EF0006FF0006EE0004FF0009EE0007EE0010EE0009EE0006EF0010EF0004EE0005EF0005EF0008FF0008EE0008FF0005FF0010EF0009EF0007FF0004FF0007END

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

EE0004EE0005EE0006EE0007EE0008EE0009EE0010EF0004EF0005EF0006EF0007EF0008EF0009EF0010END

(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

DYNAMICS.TXT

NOMINALS/

SUMFILES/

INIT_LITHOS.TXT

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' APPROACHETLM= 1800, 1.D-6VSIG= 0.200, 0.200, 0.200PSIG= 0.0001, 0.0001, 0.0001 F11A0001225 F11A0001241 ... F21A0003895 F21A0003910 FRAME='dxR_FRAME' SURVEYETLM= 1800, 1.D-6VSIG= 0.100, 0.100, 0.040PSIG= 0.0001, 0.0001, 0.0001 F21A0003931 F21A0003932 ... F21A0032347 F21A0032348END

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_FILESdoes not exist, you must create NEW_FILES, as well as NEW_FILES/LMKFILES and NEW_FILES/MAPFILES.

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

Export

Required Files

MAPFILES/ - a directory containing the full suite of maplets

LMKFILES/ - a directory containing the full suite of landmarks

LMRKLIST1.TXT - a list of the new landmarks

Output Files

EXPORT.TXT - Script that will execute the EXPORT.B script and clean up the previous version of NEW_FILES

EXPORT.B - Script that will cp new maplet and landmark files to NEW_FILE

Using Export

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

Make EXPORT.B and the script EXPORT.TXT. Note that EXPORT.TXT will run the script EXPORT.B.

/!\You must ensure that LMRKLIST1.TXT only has the recently created landmarks.If it has older ones, trim the top of the file.

/!\You should also ensure that there aren't any maplets or landmarks remaining in NEW_FILES. If NEW_FILESdoes not exist, you must create NEW_FILES, as well as NEW_FILES/LMKFILES and NEW_FILES/MAPFILES.

Enter the following at the command line:

mkdir -p NEW_FILESmkdir -p NEW_FILES/LMKFILESmkdir -p NEW_FILES/MAPFILES/usr/local/bin/EXPORT

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

The script EXPORT.TXT looks this:

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

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

sh EXPORT.TXT

Change the name of NEW_FILES.tar to something distinctive like

new_<bigmapName>.tar

Transfer the tar file to the other computer.

Import

Required Files

NEW_FILES/LMRKLIST.TXT - List of new landmarks

NEW_FILES/MAPILES/ - a directory containing the new maplets

NEW_FILES/LMKFILES/ - a directory containing the new landmarks

Output Files

MAPFILES/ - a directory containing the full suite of maplets

LMKFILES/ - a directory containing the full suite of landmarks

LMRKLIST.TXT - updated landmark list

NEWLIST.TXT - list of new landmarks with the new name

Using Import

1. Untar to recover NEW_FILES directory.

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

tar -xvf NEW_FILES.TAR

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

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

/usr/local/bin/IMPORT

This will import the new landmarks.

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

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

cp NEWLIST.TXT make_script.in

For make_scriptF.seed use:

nngu1oRECENTn1qEND

Copy into window:

./rem_script.brm -f ./TESTFILES/*rm -f ./TESTFILES1/*make_scriptFsh ./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

make_script.in - input file for batch processes such as make_scriptF, make_scriptR, make_scriptA or make_scriptAP.

Either:

<LMRKNM>.OOT files - output by a batch process such as make_scriptF.

Or:

<PICNM>.OOT files - output by a batch process such as make_scriptR, make_scriptA or make_scriptAP.

Output Files

Either:

redo.txt - list of landmarks that

terminated in error

do not correlate with at least one image, OR

correlate weakly with at least one image

Or:

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

Using find_nofit

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

For lithos

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

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

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

For register

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

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

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

Here is an annotated sample output from find_nofit :

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

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

* EE0017 <- maplets not correlating with at least one image+ EE0034 <- maplets correlating weakly with at least one image* EE0042* EE0044+ EE0045EE0051 <- process still running or terminated in errorEE0053+ EE0054EE0063END

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

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

(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

make_script.in - input file for batch processing using make_scriptP

<LMKNM>.OOT files - lithosP standard output listings

Output Files

redo.txt - list of landmarks that

terminated in error

do not correlate with at least one image, OR

correlate weakly with at least one image.

Using find_nofitP

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

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

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

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

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

0.28 (~2/7) otherwise

Here is an annotated sample output from find_nofitP :

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

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

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

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 overlapEP0002: 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 imageEN0004: * cat 009.OOT 010 deleted ! cat 010.OOT <- insufficient data to create a maplet at that pointEM0003: cat 011.OOT EM0004: * cat 012.OOT

Here is a sample NEW_LIST.TXT from find_nofitT :

EP0001EP0002EP0003EP0004EQ0001EQ0002EQ0003EQ0004END

(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

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

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

User Warning

{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'orGEOMAP='filename2'

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

Additional Reference

Geometry Estimation Terms

Spacecraft State - Position and orientation of spacecraft affects size and location of the body in an image. Errors are reflected IN offsets of extracted image data from maplets for all maplets in the image.

Control Point Location - An error in the body-fixed control point location is reflected by offsets of extracted image data for all images containing the maplets.

Rotation - An error in the transformation from inertial to body fixed frames is reflected in time-dependent offsets in extracted image data for all maplets in all images.

Differential Stereo - Errors in the maplet heights relative to the center are reflected by differential shifts of features within the extracted image data in addition to displacements from the maplets themselves.

Figure 00: Examples of Offset and Orientation Errors

More Detailed Description of Geometry

Global solution for camera position and pointing and body-fixed maplet location.

Iterative process:

Weighted least-squares solution of landmarks (control points) based on:

Position of the landmark relative to the spacecraft

Relative landmark-to-landmark location

Limb position

An initial starting object

Weighted least-squares solution of camera position and pointing based on landmark location

Nominal camera pointing

Nominal camera position

Limb position

Position of the landmark relative to the spacecraft

The observations before and after each observation

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

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

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

Figure 00: Illustration of Iterative Process for Updating Geometry

(Compiled by TC)

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

LMRKLISTO.TXT - If present, LMRKLISTO.TXT is used to calculate overlaps instead of LMRKLIST.TXT. This action enables lithos and lithosP to run faster by searching for overlaps among a limited set of landmarks.

LMRKLISTX.TXT - Extended landmark list containing .LMK file information that speeds up processing by eliminating the need to open individual .LMK files multiple times.

PICTLISTR.TXT - User-generated restricted list of pictures for processing.

PICTLISTX.TXT - Picture information similar in concept to LMRKLISTX.TXT. This file will be used if PICTLISTRX.TXT does not exist.

PICTLISTRX.TXT - User-generated restricted extended picture list, i.e. a sub-set from PICTLISTX.TXT.

Using lithos

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

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

...MAIN MENU...

Q. Quit LITHOS

LANDMARK/MAPLET CONSTRUCTION

0. Find template

1. Align landmarks

2. Find heights

O. Attach map to maps or limbs

LANDMARK/MAPLET I/O AND CREATION

I. Input landmark

U. Update landmark files

C. Create new landmark

R. Replicate or Rename landmark

S. Change scale, qsz or orientation

G. Turn on rename

ADJUST INPUT DATA AND NOMINALS

N. Find normal

V. Find V, Z or PTG

A. Reset albedo or slopes

M. Get heights from shape model

B. Get heights from surrounding map

X. Turn on extract filter

DELETE, ELIMINATE OR IGNORE FILES

D. Delete or Disconnect landmark

E. Eliminate pictures from landmark

P. Picture status

L. Turn off picture restriction

INFORMATION AND DISPLAY

F. Find maplets containing surface point

Z. Use zoom display

H. Hide screen output

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

Current landmark = EE0001SCALE = 0.000100 QSZ = 49 Lat/Lon/Rad = -6.800 264.090 0.266 Region = EE gc LMRK_DISPLAY0.pgm gc LMRK_DISPLAY1.pgm check displayMain 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.

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 .

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

LIMBLIST1.TXT - List of images that show limbs.

LMRKLIST.TXT - List of landmarks.

Output Files

LIST.TXT -

Using make_list

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

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

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

Additional Reference

[From make_list.f]

Filename I/O Description---------------------------- --- -------------------------------LIMBLIST1.TXT I List of images to be match w/ images in landmark filesLMRKLIST.TXT I List of current landmarks<LMRKNM>.LMK I Landmark files whose PICTURES entries will be matched w/ images in LIMBLIST1.TXTLIST.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

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

Output Files

LMRKLISTX.TXT - LMKFILE information.

Using make_lmrklistX

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

(Compiled by DL)

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

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 :

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

processed files :

INIT_LITHOS - make_scriptAP reads the USRMX (maximum number of core processors) value.

TESTFILES1/ - Directory in which to store copies of LMRK_DISPLAYnn.pgm (output by autoregisterP) for each image.

/!\ autoregisterP requires a number of directories and files. Refer to autoregiserP for more information.

Output Files

make_scriptAP outputs :

run.sh - Controlling run script for batch image auto registration using parallel processing.

run script for each core processor:

run_script01.b

run_script02.b

etc..

.INN files - autoregisterP seed file for each image.

rem_script.b - Script for removal of temporary files (working directory clean-up)

run_script nn .b output :

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

processed files outputs :

TESTFILES1/ - A copy of LMRK_DISPLAYnn.pgm (output by autoregisterP) is saved for each image.

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

LMKFILES/ - Image names are added to the LMKFILES.

User Warnings

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

Using make_scriptAP

Create Input Files

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

P00045000450 P00045000451 P00045000452END

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

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

a0,65,.25,0,312n0no.54b0qEND

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.P00045000450a0,65,.25,0,312n0no.54b0qEND

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.OOTcp LMRK_DISPLAY01.pgm ./TESTFILES1/P00045000450.pgmrm -f P00045000452.OOT/usr/local/bin/AUTOREGISTERP < P00045000451.INN > P00045000451.OOTcp LMRK_DISPLAY01.pgm ./TESTFILES1/P00045000451.pgm

Batch Autoregister Images Using Parallel Processing

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

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

sh run.sh

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

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

Clean Working Directory

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

Here is a sample rem_script.b file:

rm -f *.INNrm -f *.OOTrm -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 :

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

processed files :

TESTFILES/ - Directory in which to store copies of LMRK_DISPLAY1.pgm (output by lithos) for each landmark.

TESTFILES1/ - Directory in which to store copies of tmpl.pgm (output by lithos) for each landmark.

/!\ lithos requires a number of directories and files. Refer to lithos for more information.

Output Files

make_scriptF outputs :

run_script.b - Run script for batch processing.

.INN files - lithos command seed file for each landmark.

rem_script.b - Script for removal of temporary files (working directory clean-up).

run_script.b outputs :

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

processed files outputs :

TESTFILES/ - A copy of LMRK_DISPLAY1.pgm (output by lithos) is saved for each landmark.

TESTFILES1/ - A copy of tmpl.pgm (output by lithos) is saved for each landmark.

SUMFILES/ - S/C and camera information are updated by lithos if image shifts occur.

LMKFILES/ - LMKFILES for each landmark are updated by lithos.

MAPFILES/ - MAPFILES for each landmark are updated by lithos.

/!\ Several information text and display files in the working directory are modified by lithos. Refer to the entries for those files for more information.

User Warnings

/!\ The make_scriptF.seed file must start with a set of commands which deal with the lithos Check for more images? y[n] option sequence.

/!\ The make_scriptF.seed file must end with the lithos quit command, q , and the end-of-file identifier, END .

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

Using make_scriptF

1. Create Input Files

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

EE0001EE0002EE0003END

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 commandsn <- don't check for more imagesn <- don't include a single image#processing commandsoRECENTy1oRECENTn3y1, 3, 5 wiRECENTnnv1u1oRECENTn1#end commandq <- quit#end-of-file identifierEND <- 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 :

iEE0001n 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.OOTcp LMRK_DISPLAY1.pgm ./TESTFILES/EE0001.pgmcp tmpl.pgm ./TESTFILES1/EE0001.pgmrm -f EE0002.OOT/usr/local/bin/LITHOS < EE0002.INN > EE0002.OOTcp LMRK_DISPLAY1.pgm ./TESTFILES/EE0002.pgmcp tmpl.pgm ./TESTFILES1/EE0002.pgmrm -f EE0003.OOT/usr/local/bin/LITHOS < EE0003.INN > EE0003.OOTcp LMRK_DISPLAY1.pgm ./TESTFILES/EE0003.pgmcp 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 *.INNrm -f *.OOTrm -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 P3T11S2H0411END

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

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

s203yXSTOP1103yXSTOP0ynnq

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 :

P3T11S2H0409s 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.OOTcp TEMPFILE.pgm ./TESTFILES/P3T11S2H0409.pgmrm -f P3T11S2H0410.OOT/usr/local/bin/REGISTER < P3T11S2H0410.INN > P3T11S2H0410.OOTcp TEMPFILE.pgm ./TESTFILES/P3T11S2H0410.pgmrm -f P3T11S2H0411.OOT/usr/local/bin/REGISTER < P3T11S2H0411.INN > P3T11S2H0411.OOTcp 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 :

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

processed file :

TESTFILES/ - Directory in which to store copies of LMRK_DISPLAY1.pgm (output by lithos) for each landmark.

TESTFILES1/ - Directory in which to store copies of tmpl.pgm (output by lithos) for each landmark.

/!\ lithos requires a number of directories and files. Refer to lithos for more information.

Output Files

make_scriptT outputs :

run_script.b - Run script for maplet creation.

.INN files - lithos seed file for each new maplet.

rem_script.b - Run script to clean out the directory of make_scriptT working files once tiling is complete and user has quality checked the resulting suite of maplets.

run_script.b output :

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

PROCESSED FILES OUTPUTS :

TESTFILES/ - A copy of LMRK_DISPLAY1.pgm (output by lithos) is saved for each landmark.

TESTFILES1/ - A copy of tmpl.pgm (output by lithos) is saved for each landmark.

SUMFILES/ - S/C and camera information are updated by lithos as image shifts are accepted because the "v 4" command in lithos is used. New landmarks and limb fits are added to the SUMFILEs.

LMKFILES/ - LMKFILES for each new maplet are created and populated by lithos.

MAPFILES/ - MAPFILES for each new maplet are created and populated by lithos.

/!\ Several information text and display files in the working directory are modified by lithos. Refer to the entries for those files for more information.

User Warnings

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

XXXXXXscripts/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 200END

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

0.00010,49giay.5nx.0250abnXXXXXXn2bnXXXXXXu1v2ea0,60,.25,.25,0,3103n0y...u1oRECENTy1oRECENTn3y1, 3, 5 wiRECENTnnv1u1v4oRECENTn1qEND

2. Run make_scriptT

make_scriptT generates a .INN file for each new maplet.

Here is a sample .INN file for maplet 001 :

camXXXXXX 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.OOTcp LMRK_DISPLAY1.pgm ./TESTFILES/001.pgmcp tmpl.pgm ./TESTFILES1/001.pgmrm -f 002.OOT/usr/local/bin/LITHOS < 002.INN > 002.OOTcp LMRK_DISPLAY1.pgm ./TESTFILES/002.pgmcp tmpl.pgm ./TESTFILES1/002.pgmrm -f 003.OOT/usr/local/bin/LITHOS < 003.INN > 003.OOTcp LMRK_DISPLAY1.pgm ./TESTFILES/003.pgmcp tmpl.pgm ./TESTFILES1/003.pgmetc ...

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 *.INNrm -f *.OOTrm -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 50END

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 200END

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

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

Output Files

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

Using MAKE_TILES

The standard input includes these elements:

resolution (pix/km)

Q size

seed

maximum maplet resolution that can be included in the bigmap being created

Here is a sample input:

0.02500 500 1.23400 5.00000

Here is a sample MAPLIST.TXT file:

ZN0000ZN0001ZN0002ZN0003ZN0004ZN0005ZN0006ZN0007ZN0008ZN0009ZN0010ZN0011END

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

l 0 0 0.02500 500 1.23400 5.00000ZN00001.005.025111111100

(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

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

Output Files

<map_name>.INN files - Inputs for bigmapL

<MAKE_TILES##>.b files -

Using MAKE_TILESP

Here is a sample of the screen output from MAKE_TILESP :

chmod +x MAKE_TILES01.bchmod +x MAKE_TILES02.bchmod +x MAKE_TILES03.bchmod +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

Input the filename of a bigmap:

ZN0204

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

0,.001

Here is a sample output from map_coverage :

Figure 00: Example of map_coverage Output

Compiled by KD

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

Temperature is calculated (see below) using DN2TEMP.TXT and written out in make_sumfiles.in

Motor Position is taken directly from keyword MTR_POS regardless of PolyCam or MapCam. make_sumfiles handles the differences between cameras.

User Warning

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

Level 0

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

ECR Changes from 3.0A2

Support OREx level 0 images

Trim the second channel from the image to make it 1024x1024

Remove dark/bias -- This comes from the shielded overscan region

Correct the flat field

Desmear the image

Additional Required Files

DATA/DN2TEMP.TXT

DATA/FLATFILES.TXT

Level 0 Processing Steps

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

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

Output to the terminal

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

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

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

OCAMS

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

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

DN2TEMP.TXT

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.

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.

The OCAMS Instrument Team will provide the final weighting during operations.

There is no ICD or SIS for the information, so it will have to be done via email and documented as a memo.

Reduce Size - SPC will read the second image of the file, which includes the overscan regions. It will take the main 1024x1024 pixels for the image DN, loading the other portions into Flat and Dark variables for calibration. If the label doesn't match the image, it will output "INCONSISTENCY"; otherwise, it will show "OKAY".

Dark bias - The chip has four overscan regions that are averaged to calculate a day. The chip is broken into a left and a right half, and the darks are calculated accordingly. SPC will average all of the overscan pixels in each half, then print: Dark Left, Dark Right, Std Dev Left, Std Dev Right, Max.

DN(i,j) -= DK(i,j)

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

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

Flat field correction - FLATFILES.TXT contains a list of flat files for each camera and filter. process_fits will read in the relevant file for the camera/filter and apply it to the image's DN. If FLATFILES.TXT does not exist, process_fits will error and quite. If the referenced file doesn't exist, SPC will just throw a warning (NO FLATFILE) and continue without applying a flat.

/!\ The code has a part that calculates and prints min and max, as well as scaling the flat: flat(i,j) /= max. However, it does not appear to be run because a boundary test ends the loop early.

DN (i,j) *= FLAT(i,j)

Scale - Normal SPC prefers to keep the data in unsigned integers; however, to do these corrections, the data had to be converted into real (float) values. Because SPC stores the image data as unsigned integers, the real values must be rounded into integers. Because this results in a 1 DN addition of noise for no value, for this project, the integer values are scaled using 216 / 2 14 (65535/16384 otherwise known as 4). This reduces the impact of rounding floating point numbers into integers, and because SPC does a normalized cross correlation, it has no impact on SPC's performance.

TAGCAMS (NavCam / NFTCam)

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

Temperature Calculation - Using DN2TEMP.TXT, apply the polynomial coefficients to convert from DN to a temperature in C. Once that is done, then use the last four columns of DN2TEMP.TXT to calculate an effective temperature for the optical path. This is implemented just as for OCAMS (see above).

temp = C1 * DN^3 + C2 * DN^2 + C3 * DN + C4

Reduce Size - Remove the black borders on the NavCam/NFTCam images. The TAGGACS suite (NavCam and TAGCam) contain overscan regions on all portions. SPC removes these to output a single array (stored in IMAGEFILES) that is 2592 x 1944.

Top

50

Top boundary

4

left

134

left boundary

6

bottom

2

bottom boundary

4

right

10

right boundary

10

Darks - NavCam and TAGCam darks are calculated from region 4 of the CCD. They are grouped into 8 bins, four on one row and four on the next. SPC calculates the dark (average) and the standard deviation for each pixel bin. It prints out each of the eight bins and the sum of all eight standard deviations. Then SPC removes the darks by simple subtraction. For TAGGAMS, this value is typically 150-180 DN. SPC checks, and if needed sets to zero, any negative values. Then it prints the minimum DN value after dark correction.

DN(i,j) -= DK(i,j)

Flat field correction - SPC will multiple every DN by a flat field correction that was read in from the FLATFILES.TXT. Flat files are implemented the same way as OCAMS (see above).

DN (i,j) *= FLAT(i,j)

Scale - Normal SPC prefers to keep the data in unsigned integers; however, to do the calibration, the data had to be converted into real (float) values. Because SPC stores the image data as unsigned integers, the real values must be rounded into integers. Because this results in a 1 DN addition of noise for no value, for this project, the integer values are scaled using 216 / 2 12 (65535/4096 otherwise known as 16). This reduces the impact of rounding floating point numbers into integers, and because SPC does a normalized cross correlation, it has no impact of SPC's performance.

Level 1

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

Using process_fits

process_fits can be run in two modes:

Single file - just give the FITS filename at the prompt

Batch mode

If the file newpix.txt exists, then process_fits will search through ../OSIRIS_REx/NEW_IMAGES_YYYY_DDD to find the image and process.

/!\ The built-in search only goes from 2015 to 2022 directories. The files don't actually have to be in the correct directories, it is just good practice for organization. SPC will search all directories from 2015/001 to 2022/365.

Here is a sample of the standard input:

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

Old - process_fits-3.0A2

(Compiled by EP)

CategoryThreeOhOne

register

Category B	Version 3.0.3

Description

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

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

Required Files

IMAGEFILES/ - a directory containing the image .DAT files

NOMINALS/ - a directory containing the image .NOM files (starting solution image, S/C and camera information)

SUMFILES/ - a directory containing the image .SUM files (updated solution image, S/C and camera information, lmrks and limbs)

MAPFILES/ - required for comparison with a reference map

SHAPEFILES/ - required for comparison with a shape model

Optional Files

make_scriptR.seed - for batch processing using make_scriptR

Output Files

NOMINALS/ - If you select the option to update the NOMINAL file, starting S/C and camera information will be updated (an option not typically selected)

SUMFILES/ - S/C and camera information are updated as image shifts are made. You can discard these changes upon quit.

TEMPFILE.pgm - A side by side view of the image (left) and the reference (right)

TEMPFILE.ppm - A red/cyan composite of the two items (red is image, cyan is reference)

User Warnings

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

/!\Since the SUMFILE is updated in realtime, an uncontrolled exit from registerwill result in the SUMFILE remaining modified.

Using register

Initial Inputs

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

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

input 12-character picture name. q to quit.

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

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

s = shape i = reference image m = reference map

2. Enter the object to align with.

s = shape - to use the current shape model

i = image - select an already registered image; you will be prompted for an image name

m = map - use a maplet/bigmap; you will be prompted for a map name

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

enter scale (km/px)

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

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

The output will look like this:

gc TEMPFILE.pgm gc TEMPFILE.ppm

TEMPFILE.pgm - A side by side view of the new image (left) and the reference (right)

TEMPFILE.ppm - A red/cyan composite of the two items (new is red, cyan is reference)

Here is a sample TEMPFILE.pgm file image:

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

Here is a sample TEMPFILE.ppm file image:

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

(!) The display and the arrays of image and reference data are not the actual imaging data; instead, they are that data projected on a substrate.

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

(!) If the reference is also an image, this data is projected on the same substrate as the image being registered.

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

Main Menu

The Main Menu of register looks like this:

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

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

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

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

Option 3 : This is the most often used option.

The new image is on the left or in red.

Values entered (delta x, delta y) are the number of pixels by which the image will be shifted (as per the current scale).

(!) This isn't the same as moving the "window" as in lithos; instead, it updates the image's camera position and pointing.

After you enter option 3, you will input responses like these:

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

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

If the correlation gives a good match (greater than a preset limit, default=0.25), autocorrelate will shift the image and go back to the menu.

Otherwise, autocorrelate will ask for a manual input.

The preset limit can be changed with Option c .

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

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

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

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

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

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

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

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

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

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

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

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

Option v Fix center = 0.

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

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

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

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

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

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

The following sample shows standard inputs and outputs from register :

Figure 00: Sample Registration of an Image with a Shape

Figure 00: Sample Registration of an Image with a BigMap

Figure 00: Illustration of Options using Register

(Compiled by DL)

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

PICTLIST.TXT or PICTLISTR.TXT

LMRKLISTR.TXT

NOMINALS/

SUMFILES/

INIT_LITHOS.TXT

make_sumfiles.txt

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 2017PARTIALS UNITS: PX/KM, PX/DEGN599562509F0 IMAGE ID2018-12-31T21:07:21.000_NCAM_L0b_V005.fits ORIGINAL NAMEORX_NAVCAM1 CAMERA ID -64 SPACECRAFT ID 2101955 TARGET IDLT+S ABCORR2018 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-MATRIXCamera temperature (deg C) = N/A CAMERA TEMPDistortion type = OPENCV DISTORT BEGINParameters: DISTORT CONTINUEP( 0) = 0.0000000D+00 DISTORT CONTINUEP( 1) = -0.5357300D+00 DISTORT CONTINUEP( 2) = 0.3611700D+00 DISTORT CONTINUEP( 3) = -0.1534700D-06 DISTORT CONTINUEP( 4) = 0.0000000D+00 DISTORT CONTINUEP( 5) = 0.0000000D+00 DISTORT CONTINUEP( 6) = 0.0000000D+00 DISTORT CONTINUEP( 7) = 0.0000000D+00 DISTORT CONTINUEP( 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 MATRIXLITHOS 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 VECTORLANDMARKS:END LANDMARKSKERNEL LISTatt_nte2_m3a-m4a_truth.bcORX_SCLKSCET.00000.example.tscnaif0012.tlsorx_ocams_v05.tiorx_181215_190112_190108_od012_v1.bsporx_v06rwg.tfde424.bspbennu_nte2_truth.tpcpck00010.tpcEND 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 INFILEmake_script.in INPUT DONEFILEdone.txt INPUT OUTFILEFlyingMonkies.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

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

Output Files

MAPINFO.TXT

PICINFO.TXT

LIMINFO.TXT

RESIDUALS.TXT

check.txt - List of landmarks and overlaps for landmarks whose linear residual is greater than the user-specified limit.

EMPTY.TXT - lithos seed file for batch deletion of landmarks which are not contained in any pictures or limbs.

FLATLIST.TXT - List of flat maps (landmarks containing no topography).

LMKVECS.TXT - Landmark vectors for every landmark contained in LMRKLIST.TXT.

MAPCHK.TXT - List of maplets whose difference between predicted and observed pixel/line locations in attached images is greater than a user-specified limit, or who have two or fewer overlaps attached to them.

MAPRES.TXT - Maplet resolution information for maplets contained in at least one picture or limb.

New_Limbs.in - lithos seed file to attach map to limbs for every landmark contained in LMRKLIST.TXT.

no_update.txt - List of landmarks whose associated pictures are not listed by increasing mission time in the .LMK file.

PRUNE.TXT - List of landmarks for which the number of pictures in which they are contained exceeds the default limit of 500, or the user-specified limit, PRNLM, set within INIT_LITHOS.TXT.

RANGES_SOLVED.TXT - Date and range information for each picture listed in PICTLISTS.TXT or PICTLIST.TXT.

veto.txt - lithos seed file to detach from landmarks and limbs a map with a linear residual greater than the user-specified limit.

Using residuals

After you invoke the program, it prompts:

enter 3 values (px,km,km)

value 1 - the value of the pixel residual limit. Images and maplets are flagged for a pixel residual limit greater than this.

(!) An image in a landmark will be flagged if the RSS of the pixel and line residuals in units of image pixels exceeds the input value

value 2 - the value of the linear residual beyond which images and maplets are flagged.

(!) An image in a landmark will be flagged if the RSS of the pixel and line residuals in metric units (km) exceeds the input value

value 3 - the max scale (km/px) that sets the scale for the histogram at the end of PICINFO.TXT.

(!) The two criteria, km and pixels, allow flexibility when there are images of great range in resolution in the same landmark. These criteria also apply for outliers in the limb apparitions of images in landmarks and in the case of the metric criterion, second input parameter, for the map-to-map overlaps. The limb and overlaps outliers are collected in the file veto.txt and you can delete them from the landmarks by running lithos with veto.txt as input.

Here is a sample of inputs for residuals :

10, 0.01, 0.01

Here is a sample MAPINFO.TXT file:

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

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

Figure 00: Results from Using Residuals to Improve Processing

Additional Reference

Qualitative Checks

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

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

Verify that the quantitative error estimates are believable.

Render a single maplet, or a DEM synthesized by a collection of maplets, at the same geometry and illumination conditions as the images themselves.

Determine if all the features in the images appear in the DEM.

Determine if the smallest discernible features in the images (e.g., boulders, craters etc.) are visible in the DEM as well.

Determine if the relative albedo solution is such that the relative brightness of adjacent image features matches that of the DEM.

Determine if the heights solution is such that the length and overall appearance of the shadows in the DEM match those of the image.

How Uncertainties are Introduced in the Data

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

S/C trajectory, camera pointing, image timestamp

Manifest themselves mostly in the projection of image template onto the surface.

Corrected by global geometry solution.

Image noise, artifacts, smear, overall image quality

Manifest themselves in predicted image template brightness and in its fit to the extracted image brightness.

Photometric model and reflectance function models

Show up in slopes and heights integration

Poor choice of a-priori parameters and data weights

Are evident at the end of each estimation step. Data won’t fit well.

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

Notes

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

(Compiled by KD)

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-01Area = 0.77755D+00Offset = 0.95893D-03 -0.34589D-03 -0.91561D-03 2.33664 -0.00537 -0.00069I/M = -0.00537 2.38540 -0.00717 x 10 ^ -2 -0.00069 -0.00717 2.59532dPM = 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

MAPFILES -

LMRKLIST.TXT -

LMKFILES -

Output Files

standard out -

<shapefile>.TXT -

LMKFILES -

MAPFILES -

Using shift

/!\ When you shift a shape file, only input the root name. Do not put in the fullpath or .TXT extension.

/!\ shift will continue to ask you "Shape shift?" until you enter 'n'. Do not enter 'y' more than once unless you want to shift more than once.

Here is a sample set of inputs for shift :

Enter C0(i), i=1,30.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 GEOMETRY201nn

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:

Figure 00: Albedo Output from spheremapsB

Figure 00: Color DTM Output from spheremapsB

Figure 00: Grayscale DTM Output from spheremapsB

Additional Reference

[From spheremapsB.f]

C This procedure re-samples the surface vectors providid ba a set of C BIGMAPs onto a sphere with a radius characteristic of the body. Id C does so one outputline at a time so that arbitrarily large maps can C be produced.CC 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.CC 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:CC 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)CC The last entry is a search limit in case one of the maps has some bad data in itC and is displaced too far from the expected height.CC 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:CC a. orthographicC b. stereographicC c. equirectangularCC 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 CC 2*Q*scale=R0*cos(Rlat)*DLON*pi/180CC 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.CC After deciding on the type of projection and its parameters, the user is asked:CC a. 8 bit DTMC b. 16 bit DTMCC where if the latter is chosen the data will be "unsigned short" (MSB). The next C choice is:CC Fix hmin, hmax? (y/n)CC 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.CC Set max slope (deg)CC 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:CC Lat/Lon markings? (y/n)CC 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.CC 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 P5C #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 8641C 65535CC where the lines without # specify the .pgm format. For orthographic and stereographic C projections, the heaer looks like:CC P5C #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 10401C 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.

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 EE0001Lat = -6.819Lon = 264.131Rad = 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 iterations40 rms brightness residual = 9.30908314089276545E-003 rms brightness residual = 9.27805039374508290E-003... rms brightness residual = 8.68283596819066118E-003 rms brightness residual = 8.67799102637487052E-003 slope sigma = 5.30813855279686289E-002 -0.03482 0.11297 -0.03439 0.00162 -0.04342 0.04161 gc tmpl.pgm

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

q Quit - go back to the Main Menu

Hidden Suboptions

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

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

For example:

'2', then "Enter"

If you enter an image number, the program will toggle the "selected" flag (*).

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

Using Option 0. Find Template

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

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

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

Typically, you do an alignment to make sure the images are correctly aligned. If they are not, you'll want to exclude them from the "Find template" calculation.

Most of the time it will be an auto-align. If an image does not correlate well or it shows a predicted landmark location that cannot be auto-aligned it may have the be a manual alignment

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

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

From the Main Menu, enter in '0', 'c', '0.5'.

This will toggle off all images that had a correlation below 0.5, then bring you back to the Main Menu. To see the result of toggling off those images, you'll have to go back into the "Find template" menu.

Enter 0 again. The display output looks like this:

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

There were 7 images from the auto-align that had a correlation below 0.5. Now 7 images have a * by them. Also note that lithos has moved the images with a correlation below 0.5 to the bottom of the list. In other words, those image values have changed.

For typical iterations, use 0, 0, 40.

The text output will look similar to the sample above from "0 end/continue"

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

Figure 00: LMRK_DISPLAY1 Output for Well Aligned Images

Additional Reference

From LITHOS.f

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

The process produces a table with entries:

k

chi

lambda

phi

res

pflag

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

(Compiled by JRW)

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.

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.

Respond to each of these suboptions:

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.

Update landmark pixel locations? y[n]

'y' saves the new position and returns to the Main Menu

'n' discards the changes and returns to the Main Menu

'Enter' defaults to 'n'

1. Individual shift - Shifts an individual image.

Enter the Image number (i.e., "k" value) that you want to shift.

Enter the number of pixels to shift

the x distance (positive moves to the right

the y distance (positive moves down)

Enter the next Image number (i.e,. "k" value) and proceed as before.

When you're finished with the individual shifts

Enter "0" to quit to the Main Menu.

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

Enter the x and y pixel shifts.

You will then be asked:

Update vector? (y/n) Choose 'y' if you want to do a "v1" (from Find_V_Z_or_PTG).

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

First, enter the number associated with the image you want to align to.

Enter spacing as in "Option 0" above. This is used sometimes when auto-align isn't working and you don't want to align pictures by hand.

(!) This option doesn't always work because of differing illumination conditions. Note that using this option will move the reference image to position #1 and will flag or "turn off" all the other images. You will need to perform a 0-a from the Main Menu to add them all back.

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

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

q. Quit - Quit to the Main Menu.

Typical Example

The following sample shows the screen output from entering:

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. Quit0 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 spacing1 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 = EE0001SCALE = 0.000100 QSZ = 49 Lat/Lon/Rad = -6.800 264.090 0.266 Region = EE gc LMRK_DISPLAY0.pgm gc LMRK_DISPLAY1.pgm check displayMain 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:

Weight for the conditioning heights - Always use .025.

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

Number of iterations - Typically use 30.

After the iterations are finished, enter one of these choices:

'0' to go back to the Main Menu

'1' to input more iterations

'2' to change the weight

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

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

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

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

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

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

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

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

You have to input a map name and a fraction of points just like when using editing heights.

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

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

After you enter this option, respond to these prompts:

use gradients - enter 'y'

autoheights - enter 'y'

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

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

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

Q. Exit - Exit to the Main Menu.

Typical Example

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

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

2 <- Find heights option8 <- Fill w/ shape2 <- Include existing heights.01 <- weighting1 <- Include overlaps4 <- Include limbs1, 2.5, 3 <- inputs for limbs7 <- Include extended shadowing6 <- include stereoy <- use gradientsy <- use auto heights0 <- Begin integration.025 <- weighting30 <- number of iterations0 <- 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 iterations30 -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 weight0 -8.18594598952327801E-006 Current landmark = EE0001SCALE = 0.000100 QSZ = 49 Lat/Lon/Rad = -6.800 264.090 0.266 Region = EE gc LMRK_DISPLAY0.pgm gc LMRK_DISPLAY1.pgm check displayMain 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,

load the landmark of interest

enter the following inputs

oRECENTy1oRECENTn3y1, 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.0031EE0001 -0.0107 -0.0742 0.7028 0.9995 -0.0058 -0.0063 0.7082 0.9995 -0.0024 -0.0004 0.7082 0.9995 -0.0004 0.0002 0.7080 0.9995 -0.0193 -0.0807 0.0060

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

The overlapping maplet (LMK1) is projected into the coordinate system of the maplet-of-interest (LMK0).

A correlation is found by shifting LMK1.

The LMK0 central vector is updated.

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

Lines 1-4 are outputs for each iteration:

Column 1 - pixel shift

Column 2 - line shift

Column 3 - correlation

Correlation depends on the INIT_LITHOS.TXT CORRFLAG parameter:

0 - Laplacian; 1 - albedo; 2 - gradient; 3 - Laplacian/albedo

Column 4 - height correlation.]

Line 5:

Column 1 - Total pixel shift;

Column 2 - Total line shift;

Column 3 - Average delta height.

Unsuccessful overlap

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

Here are three samples of unsuccessful overlaps :

EE0126 4.0764 -4.0374 0.2320 0.9825 4.0366 -3.9734 0.2779 0.9730 0.0072 0.0071 0.2842 0.9720 0.0032 0.0021 0.2850 0.9720 8.1234 -8.0016 -0.5042EE0026 No fit. Below height correlation limit HCOR = 7.1556346300126000E-002

EE0153 No fit. Below albedo correlation limit ACOR = 0.29595196946445101EE0043 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 = EE0001SCALE = 0.000100 QSZ = 49 Lat/Lon/Rad = -6.800 264.090 0.266 Region = EE gc LMRK_DISPLAY0.pgm gc LMRK_DISPLAY1.pgm check displayMain 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.TXTP3T11L2H0205 580.20 189.39...P3T11L2H0214 219.62 692.50 Current landmark = EE0001SCALE = 0.000100 QSZ = 49 Lat/Lon/Rad = -6.800 264.090 0.266 Region = EE gc LMRK_DISPLAY0.pgm gc LMRK_DISPLAY1.pgm check displayMain 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:

PICTLIST.TXT - the list of all images

PICTLISTR.TXT - a restricted PICTLIST created by the user

PICTLISTX.TXT - an extended pictlist containing additional data to speed up processing

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.

To add topography - use Main Menu Option B. Get heights from surrounding map

To load images,

Save the maplet

Load it again

Choose option 'y'

Suboptions

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

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

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

Enter a picture name (12 characters).

lithos will ask for a pixel/line location from the image.

'0, 0' would be the upper left pixel/line location of the image

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

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

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

Enter the maplet/bigmap name (6 characters).

Enter the pixel/line location.

'0, 0' selects the upper left of the maplet/bigmap

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

Enter scale (km/px), qsz

Enter the GSD in km - .001 is 1m

Enter the Q size - 49

(standard procedure)

(Compiled by JRW)

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 = NONEMain 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 >sSCALE = 0.000100 QSZ = 49 Enter scale (km/px), qsz, cc window rotation (deg) [0 0 0 to quit].00001 49 0

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

Enter the new GSD

Enter the new Q size

Enter the number of degrees you want to rotate the landmark

/!\ Limbfits and overlaps are cleared and the slopes and albedos are re-initialized.

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

Figure 00: Images Prior to Changing Scale and Orientation

Here is the sample after zooming out the scale.

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

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

(Compiled by JRW)

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

n2

(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 = EE0001SCALE = 0.000100 QSZ = 49 Lat/Lon/Rad = -6.806 264.097 0.266 Region = EE gc LMRK_DISPLAY0.pgm gc LMRK_DISPLAY1.pgm check displayMain 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)nEE0002 0.0001 0.6040EE0005 0.0001 0.6499T11T10 0.0001 0.7937T11T05 0.0000 0.7632T11EV1 0.0000 0.7456T11EVB 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 = EE0001SCALE = 0.000100 QSZ = 49 Lat/Lon/Rad = -6.806 264.097 0.266 Region = EE gc LMRK_DISPLAY0.pgm gc LMRK_DISPLAY1.pgm check displayMain 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. Quit1 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,5100

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 nameP3T11L2H0203 input px,ln512 512 Lat/Lon/Rad = -7.929 262.742 0.267 MAPLETSEE0006 0.0001 73.5753 68.1750EE0007 0.0001 36.7092 69.8093EE0010 0.0001 74.1030 29.5836EE0011 0.0001 36.6173 29.6914EE0047 0.0000 89.3879 78.6963EE0048 0.0000 51.2886 78.8508EE0049 0.0000 14.9830 78.3710EE0056 0.0000 89.9906 39.9955EE0057 0.0000 51.1087 40.0120EE0058 0.0000 15.1030 40.0903EE0065 0.0000 89.9260 5.7837EE0066 0.0000 51.7840 5.7497EE0067 0.0000 14.3419 4.4848 BIGMAPST11T10 0.0001 131.7704 123.8519T11T05 0.0000 253.5390 237.7034T11EV1 0.0000 964.3016 903.6361T11EVB 0.0000 1139.3016 1078.6361TEMP01 0.0000 342.7534 274.3991T11MEP 0.0000 343.3013 273.6356 Current landmark = TEST01SCALE = 0.000100 QSZ = 49 Lat/Lon/Rad = -6.800 264.090 0.266 Region = EEMain 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 PICTURESP3T11U2H0665 451.96 554.55 IMAGE, PIXEL/LINE LOCATION OF BIGMAPP3T11U2H0666 451.96 554.55P3T11U2H0848 533.59 474.26P3T11U2H0849 523.75 488.41P3T11U2H0850 523.75 488.41P3T11U2H0851 523.75 488.41P3T11U2H0852 523.75 488.41MAP OVERLAPSLIMB FITSEND 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_LMKPICTURESP3T11L2H0201 466.27 128.14P3T11L2H0202 466.26 128.14P3T11L2H0203 294.45 152.24P3T11L2H0204 294.46 152.27P3T11L2H0205 556.00 171.85P3T11L2H0206 556.00 171.85P3T11L2H0207 244.02 407.90P3T11L2H0208 244.02 407.87P3T11L2H0209 154.69 616.37P3T11L2H0210 154.68 616.35P3T11L2H0211 136.93 706.14P3T11L2H0212 136.93 706.13P3T11L2H0213 221.55 727.08P3T11L2H0214 221.56 727.08P3T11L2H0215 638.11 224.34P3T11L2H0216 638.11 224.34MAP OVERLAPSEE0397 66.076 0.078 -0.250EE0424 0.111 66.211 1.230EE0426 -0.585 -66.961 -0.113EE0453 -66.664 -0.151 -0.128LIMB FITSEND FILE

MAP OVERLAP coordinate system (x, y, z) is in units of landmark GSD.

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_PTGEND FILE

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. The number of vertices in the shape file is 6 * (Q+1)^2, so the number of lines in the shape file will be one higher.

Each subsequent line gives the vector of the surface. The vectors are in Cartesian space (x, y, z).

SHAPE00.TXT is the "baseline" shape model. This can be used to keep track of how different it becomes from the starting shape. Usually, it is turned off partway through the mission by INIT_LITHOS.TXT.

(!) Use a symbolic link to specify SHAPE.TXT. This way, you can keep a useful filename in the directory, but "link" it to SHAPE.TXT so that SPC runs properly.

Here is a sample set of commands to show how to set up a link:

cd SHAPEFILESln -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 name2014 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 uncertaintyLANDMARKS AO0001 2049.39 668.15 AO0002 2020.70 644.81 AO0003 2035.17 708.66 # landmark px/ln centersBD0009 1902.39 884.05 BD0010 1891.13 909.86 ...EK0022 675.73 1371.97 EQ0088 721.76 738.13 FI0002 727.77 220.40 LIMB FITS # landmark-on-limb centers (none here)END FILE

/!\ Comments (information after the #) were added here for clarification and are not included in an actual sumfile.

Here is another sample sumfile :

Figure 00: SUMFILES Information Illustration

(Compiled by KD)

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:

EE0001EE0002EE0003EE0004EE0005EE0006EE0007EE0008EE0009EE0010EE0011EE0012EE0013EE0014EE0015EE0016END

(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' APPROACHETLM= 1800, 1.D-6VSIG= 0.200, 0.200, 0.200PSIG= 0.0001, 0.0001, 0.0001 F11A0001225 F11A0001241 ... F21A0003895 F21A0003910FRAME='dxR_FRAME' SURVEYETLM= 1800, 1.D-6VSIG= 0.100, 0.100, 0.040PSIG= 0.0001, 0.0001, 0.0001 F21A0003931 F21A0003932 ... F21A0032347 F21A0032348END

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 SDECP595033964F2 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.27588P595034390F2 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.27349P595034816F2 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.27109P595035242F2 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=12BODY='RQ36'IDCODE=2101955#BFRAME='RQ36_FIXED'BFRAME='IAU_BENNU'PCK='DATA/naif0011.tls'PCK='DATA/bennu_v10.tpc'UNIT='METER'ASIG= 0.05SSIG= 0.15CHI0= 1.0BLIM= 0.5MXSLP=0.6BLOOM=0.2SEED= 1.3827453#REFLECT= 'VESTA'NEWLIM=.TRUE. find new limbs in LITHOSPSOFTEN=1MAPONLY=.FALSE.#GEOPIC='pict1.txt'RENAME=.FALSE.REGFLG=.FALSE.REG='J0'KB=1RPLUSE=.TRUE.RECVR=.FALSE.#RECVR=.TRUE.ALPAD=.TRUE.NEWLIM=.TRUE.DISTORT= 'M###########' 'OWEN' 60.00000D+00 0.00000D+00 0.0000000-06 0.00000D+00 0.00000D+00 0.000000D-05 0.0000000D-07DISTORT= 'P###########' 'OWEN' 60.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= .05LMKWTS= 1, 1, 1, 0 WB, WO, WL, WRPICWTS= 1, 1, 0, 1, 0 WB, WL, WC, WS, WTLPCORLM= 0.2ALCORLM= 0.3GDCORLM= 0.3HTCORLM= 0.2CORRFLG= 3 0:LAP, 1:ALB, 2:GRD, 3:L+ARESLM= 4 PIXEL<RESLM*SCALE [SCALE>PIXEL/RESLM]PICLM=2NUMLM=200SIZLM= 1.5 ^ LOWERS PIXEL/SCALEEND

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 P596675177F2END

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

EE0001EE0002EE0003EE0004EE0005EE0006EE0007EE0008EE0009EE0010EE0011EE0012EE0013EE0014EE0015END

To build a LMRKLIST.TXT file, enter the following at the command line:

cd LMKFILES/bin/ls > ../LMRKLIST.TXTcd ..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-03EE0002 49 360 -0.203250D-01 0.262210D+00 -0.116002D-01 0.350000D-03EE0003 49 320 -0.328776D-01 0.260667D+00 -0.112363D-01 0.350000D-03EE0004 49 298 -0.454681D-01 0.259987D+00 -0.111565D-01 0.350000D-03EE0005 49 356 -0.782921D-02 0.261745D+00 -0.242790D-01 0.350000D-03EE0006 49 359 -0.203874D-01 0.261724D+00 -0.242330D-01 0.350000D-03EE0007 49 360 -0.328300D-01 0.262109D+00 -0.243155D-01 0.350000D-03EE0008 49 360 -0.453950D-01 0.261565D+00 -0.241885D-01 0.350000D-03EE0009 49 293 -0.787332D-02 0.258487D+00 -0.364896D-01 0.350000D-03EE0010 49 358 -0.202152D-01 0.260056D+00 -0.365461D-01 0.350000D-03EE0011 49 357 -0.328579D-01 0.261480D+00 -0.369930D-01 0.350000D-03EE0012 49 360 -0.453167D-01 0.261334D+00 -0.369408D-01 0.350000D-03EE0013 49 150 -0.100607D-01 0.261914D+00 -0.139179D-01 0.180000D-03EE0014 49 165 -0.170069D-01 0.262132D+00 -0.138891D-01 0.180000D-03EE0015 49 150 -0.239728D-01 0.262338D+00 -0.138081D-01 0.180000D-03END

(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.fitsP601296494J3 1/0601296429.38732 3 1 1 -25.50 270 2019-01-20T22-47-05.541_PCAM_L0b_V004.fits...

Column Definitions

PICNM	CLK	NC	NS	SCL	TC	NQ	FITSNM
SPC-OREx Naming	UTC or ET	Camera 1-5	Spacecraft Number	Binning (none)	Temperature in C	Filter/Focal	Source filename

Camera Number [NC]

SamCam

MapCam

PolyCam

NavCam

NFTCam

Filter Number -- MapCam has filters based upon its position -- in degrees

Position	Filter Number
0	0
720	0
630	1
540	2
450	3
360	4
270	5
180	6
90	7
30	7

Filter Number --SamCam has filters based upon its position -- in degrees

Position	Filter Number
0	0
720	0
600	1
480	2
360	3
240	4
120	5

Focal Position -- PolyCam NQ=FLT

The motor position, 0 to 17,400

where:d is the distance the camera is focused at in mFor 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 wemeasured the effective focal length 627.8mm. Based on the formula aboveit means our CBE for finf is 628.9mm so until we get a better number frompost launch calibration images we should usef(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, NLNB125.0 512.5 512.5 MMFLB, PX0B, LN0B117.647, 0, 0, 0, 117.647, 0 KMATB -1, -2, 3 PROJECT CAMERA AXES5, 16383 T1,T2'ORX_OCAMS_SAMCAM'1024 1024 NPXC, NLNC24.0 512.5 512.5 MMFLC, PX0C, LN0C117.647, 0, 0, 0, 117.647, 0 KMATC 1, 2, 3 PROJECT CAMERA AXES5, 16383 T1,T2'ORX_OCAMS_POLYCAM'1024 1024 NPXA, NLNA611.0 512.5 512.5 MMFLA, PX0A, LN0A117.647, 0, 0, 0, 117.647, 0 KMATA -1, -2, 3 PROJECT CAMERA AXES5, 16383 T1,T2'ORX_NAVCAM'2592 1944 NPXC, NLNC7.6 1296.5 972.5 MMFLC, PX0C, LN0C454.54, 0, 0, 0, 454.54, 0 KMATC 1, 2, 3 PROJECT CAMERA AXES5, 4096 T1,T21 NSC-64 ORX1.d0 1.d0 1.d0 sigV01.d-3 1.d-3 1.d-3 sigPT2101955 BENNU'IAU_BENNU' BFRAME'NONE' ABCORR'../ORex/DATA/' PREFIXKERNELSsb-101955-76.bspbennu_v10.tpcde421.bspnaif0011.tlsorex_ocams_v02.tiorx_aux_v01.tiorx_v03.tfpck00010.tpcApproachPrelim_Perturbed.bspDetailedSurvey_Perturbed.bspOrbitalB_Perturbed.bspORX_SCLKSCET.00000.example.tscF3A_AllObs_20181109T000000_20181118T000000_Perturbed.bcF3A_BD_AllObs_20190113T000000_20190122T120000_p.bcF3A_ES_Obs1_20190127T094200_20190127T161200_p.bcF3A_ES_Obs2_20190203T094300_20190203T161300_p.bcF3A_ES_Obs3_20190210T100500_20190210T163500_p.bc...END_KRNLS

Description of codes

NCAM	Number of cameras in the file
NPXV, NLNB or NPXC, NLNC, or NPXA, NLNA	Number of pixels and lines for the camera image
MMFLB, PX0B, LN0B	focal length and center pixel/line of the camera
PROJECT CAMERA AXIS	The axis of the camera mounted onto the spacecraft. This is the same thing that is described in all the frame kernels
T1, T2	The min and maximum value of "accepted" values for the image's DN. Below and above this threshold, it denotes no data
ORX	NAIF base code for the spacecraft
sigV0	The default value for the spacecraft object uncertainty, in km. Can be overwritten by DYNAMICS
sigPT	The default value for the camera pointing uncertainty, in Rad. Can be overwritten by DYNAMICS
BENNU	Asteroid number for the object. Used for SPICE Calls
BFRAME	Object that defines the body fixed frame to be used in SPC
ABCORR	Correction needed for adjustment for light speed (Aberration correction indicates the aberration corrections to be applied to the state of the target body to account for one-way light time and stellar aberration.)
KERNELS	Here one lists all of the kernels that are needed to properly project spacecraft camera pointing onto the body-fixed surface

The make_sumfiles.txt file consists of three sections:

Camera Data Definitions

Enter the number of cameras that the file maintains (NCAM). List the following for each camera:

Camera Name

Pixels (sample and rows)

Focal length, center pixel (x/y)

K Matrix - distortion matrix

Min and max expected DN for this data type

Enter sigV0 - The uncertainty of the spacecraft position [km] Enter sigPt - The uncertainty of the camera pointing [Rad]

The PROJECT CAMERA AXIS relates to how the camera is mounted to the spacecraft (it's orientation). I *think* this could be handled by frame kernels, but it isn't done that way right now. Thus, we have to put in a camera orientation matrix. From my testing, it appears that there are 4 orientations that valid.

1

2

3

-1 -2

3

-2

1

3

2 -1

3

Target Information

Enter the follow three rows:

the names of the ID of the target body

body fixed frame in the kernels

aberration correction desired

Kernel List

If the SPICE kernels are not in your working directory, give the path to the kernels (PREFIX).

Start the SPICE kernels list with these two rows:

KERNELS #

List each kernel on a separate row.

/!\ When in doubt, list all the available kernels.

Here is a list of kernels that are known to make make_sumfiles work:

SPK kernels (.bsp) - for spacecraft and target object - ephemeris

CK kernels (.bc) - orientation/attitude of spacecraft and other structures (like camera)

SCLK kernels (.tsc) - spacecraft clock coefficients

IK kernels (.ti) - instrument geometry for camera taking pictures

LSK kernels (.tls) - leap seconds

FK kernels (.tf) - reference frame specifications

PCK kernels (.tpc) - text form of planetary/asteroidal constants

End the kernels list with this row:

END_KRNLS

When processing make_sumfiles

If you get the "NOFRAMECONNECT" error (display says, "At epoch...") - You likely need a CK Kernel (<filename>.bc). Additional questions can be answered by referencing NAIF's SPICE website. http://naif.jpl.nasa.gov

If you get the "SPKINSUFFDATA" error (display says, "Insufficient...") - You likely need a SPK Kernel (<filename>.bsp).

Additional Reference

Here is the same make_sumfiles.txt but with additional comments:

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

AA0001AA0002AA0003AA0004AA0005AA0006AB0001AB0002AB0003AB0004AB0005...IQ0001IQ0002IQ0003IQ0004IR0001IR0002IR0003IR0004END

These programs use MAPLIST.TXT .

Imager_MG

MAKE_TILES

spheremapsB

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

/!\ Warning. If it's present, PICTLISTX.TXT is used before PICTLIST.TXT.

This file is used to make things run faster. However, you must be it is updated with make_pictlistX when new images are added (or tucked). If not, then the old list of images will be used rather than the updated PICTLIST.TXT.

When you run lithos, if you are using PICTLIST.TXT, it will limit images with an emission angle less than 75 degrees.

N585107273F3 N585107729F3 N585107957F3 N585108413F3 N585108641F3...... N585109097F3 N585109325F3!N585109781F3!N585110009F3END

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.TXTcd ..echo END >> PICTLIST.TXTvi 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 FC11A0001260END

/!\ 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 limitEE0005 <- overlapping landmarkEE0001 <- landmark with residual standard deviation greater than user-specified limitEE0006 <- overlapping landmarkEE0001 <- landmark with residual standard deviation greater than user-specified limitEE0009 <- overlapping landmarkEND

(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 landmarkEE0001 <- landmark name1 <- deletey <- delete entirelyd <- as aboveEE00021yq <- 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.00010EE0002 0.00010EE0003 0.00010END

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

T00144T00145T00146T00160T00161T00162T00163END

(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 TEND

(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 limitEE0017 o <- landmark has two or fewer overlapsEE0019 oEE0022EE0023EE0024 oEE0027 oEE0082 oEE0084EE0085EE0086 oEE0087EE0088EE0089 oEND

(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.36IA3_01 0.0200 56.7760 84.8686 13.0224 3 0 0 34.64 ** 11.00IA3_05 0.0200 13.1041 95.9594 12.1615 4 0 0 34.64 >> 9.95IA3_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 RA 1 1 2 1 2 1 1 1 1 1 1 1 1 1 1 1 1 1B 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1C 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1D 2 2 2 1 1 1 1 2 1 1 1 1 1 1 1 1 2 2E 66 1 2 1 1 1 1 1 1 1 1 2 1 1 2 28 1 2F 30 5 1 1 1 1 1 1 1 1 1 2 1 1 1 2 2 2G 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1H 1 2 2 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1I 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.261EE0002 24 0.00010 0.246 0.009 0.234 0.259EE0003 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 limbsEE0001 <- load landmarkn a <- don't reset all3 <- attach map to limbsn b <- don't clear1,3,5 <- expansion (1), res/scale limit (3), d_hgt limit (5)o <- as aboveEE0002n a3n b1,3,5q <- quit lithos

(Compiled by DL)

CategoryFiles CategoryOutputFiles

NEW_LIST.TXT

Description

This text file lists new landmarks created during batch make_scriptT tiling. NEW_LIST.TXT is output by find_nofitT.

Here is a sample NEW_LIST.TXT file:

EP0001EP0002EP0003EP0004EQ0001EQ0002EQ0003EQ0004END

(Compiled by DL)

CategoryFiles CategoryOutputFiles

no_update.txt

Description

This text file lists landmarks output by residuals whose associated pictures are not listed by increasing mission time in the .LMK file.

residuals checks the .LMK file for each landmark listed in LMRKLIST.TXT for pictures that are not listed in ascending order. Since the image name is based on ephemeris time, ascending order is a proxy for increasing time. Therefore, deviations from ascending name order show images that are not listed based on increasing mission time. These landmarks are then listed in no_update.txt .

Here is a sample of a .LMK file for which the landmark would be listed in no_update.txt :

AA0001 T 49 0.0007500 SIZE, SCALE(KM) -1 -1 -1 -1 HORIZON 0.3750000000D-03 0.1214487940D+01 SIGKM, RMSLMK 0.7845141366D-01 -0.6632264386D-03 0.2427257052D+00 VLM 0.9282163978D+00 -0.8567629848D-03 -0.3720397949D+00 UX 0.2888872521D-02 0.9999837875D+00 0.4904716741D-02 UY 0.3720295727D+00 -0.5627413746D-02 0.9282038212D+00 UZ 0.5042866483D-03 0.6426026485D-03 0.7961719021D-03 SIGMA_LMKPICTURESM595949305F0 353.33 622.34M595950583F0 696.83 359.79P595903597F2 515.00 48.11 <- pic iP595902930F2 469.34 648.70 <- pic j, where pic i > pic jP595904281F2 592.68 701.12P595905631F2 843.77 699.42P595917125F2 373.73 74.35MAP OVERLAPSAA0002 35.828 61.211 -13.055AB0001 -31.293 -53.362 -12.772AQ0001 -40.032 54.114 -7.907BR0001 -68.967 0.419 -8.536AA0003 -29.647 -40.296 -2.588AB0003 -42.646 -86.024 -15.244AA0005 79.965 -14.195 -20.941AB0004 -41.996 -97.707 -27.672AA0004 43.500 -45.868 -11.332AQ0003 -32.438 111.053 -22.030BA0011 -21.858 11.659 0.651AR0001 40.218 -0.211 -1.871BA0008 -86.245 11.935 0.408AR0002 18.762 67.900 -6.085BA0010 -86.779 -35.178 -1.890BR0007 -94.579 41.748 -6.321BR0009 -52.030 31.489 -4.354LIMB FITSP595033964F2 537.92 388.59 0.05P595034390F2 537.07 389.95 0.05P595034816F2 537.03 391.94 0.05P595035242F2 546.43 389.48 0.05END FILE

The resulting no_update.txt file looks like this:

AA0001

{X} no_update.txt is no longer generated by v3.0 software and will not be used during OSIRIS REx.

(Compiled by DL)

CategoryFiles CategoryOutputFiles

OVERLAPS.TXT

Description

This file is a debugging file that is not used in normal operations. OVERLAPS.TXT is generated by the OVERLAPS subroutine and is specific to a particular landmark. It is read by LITHOS.f and DISCONNECT_LMFILE.f .

Additional Reference

[From OVERLAPS.f]

This subroutine creates a file OVERLAPS.TXT that LITHOS uses to searchfor maplets that overlap a given one (LMKNM). It searches a list ofmaplets in an input list (INFILE). If a maplet has a resolution timeslower than LMKNM it is excluded. If the maplet center differs in positionby more than twice the sum of its half width and that of LMKNM, it isexcluded as well. The remaining maplets are those over which the overlapsearches will be made.The input file is generally LMRKLIST.TXT, but this can be very large.In some circumstances, such as when we are dealing with maplets that arecompletely inside a BIGMAP, a file USED_MAPS.TXT generated by the BIGMAPprogram that has all maplets used to construct the BIGMAP can be copiedinto LMRKLISTO.TXT. This will be read as the input file for thissubroutine, and it is guaranteed that only maplets in that file should bein OVERLAPS.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)

CategoryFiles CategoryOutputFiles

PICINFO.TXT

Description

This text file is a report generated by residuals that provides information about how well SPC performed for pictures included in PICTLISTS.TXT, if it exists, or PICTLIST.TXT.

PICINFO.TXT provides details about each map you have in the system and is used to identify problems.

Here is a sample PININFO.TXT file. Elements of the data in each of the three sections are explained below.

B2_01 2012 NOV 29 18:26:07.573 0.0015 11 0 >c 673.642 0.000 km 0.000 km 0.000 km 0.000 km -0.000 mr 0.000 mr -0.000 mrB2_03 2012 NOV 29 18:27:21.732 0.0013 20 0 >c 426.441 0.001 km 0.000 km 0.001 km 0.000 km -0.000 mr 0.000 mr -0.000 mrB2_04 2012 NOV 29 18:28:00.100 0.0013 21 0 >c 370.338 0.001 km -0.000 km 0.000 km 0.000 km -0.000 mr -0.000 mr 0.000 mrB2_05 2012 NOV 29 18:28:37.172 0.0014 15 0 >c 304.426 0.000 km 0.000 km -0.000 km -0.000 km 0.000 mr 0.000 mr -0.000 mrB3_01 2012 NOV 29 18:19:17.944 0.0014 5 0 >c 303.385 0.000 km 0.000 km -0.000 km -0.000 km 0.000 mr 0.000 mr 0.000 mrB3_03 2012 NOV 29 18:20:15.713 0.0013 14 0 >c 293.049 0.000 km 0.000 km -0.000 km 0.000 km 0.000 mr 0.000 mr 0.000 mrB3_05 2012 NOV 29 18:21:13.451 0.0013 9 0 >c 262.659 0.000 km -0.000 km -0.000 km 0.000 km 0.000 mr -0.000 mr -0.000 mrC3_05C3_06C3_07......... SIGcx(mr) SIGcy(mr) SIGcz(mr) DLTpt(mr) DLTcz(mr) SIGV0(km) DLTV0(km) 0.1000E+03 0.1000E+03 0.1000E+03 0.6685E-04 0.2529E-04 0.1732E-03 0.4265E-03 0 1 2 3 4 5 6 7 8 9 10 x 0.10 m 20 20 20 20 20 20 20 20 20 20 20 0 0 0 0 0 0 0 0 0 0

Section 1

The columns in the first set of output contain this information:

Column 1 - image name

Column 2 - date image was taken, UTC(derived from GPS)

(!) A more recent version (Feb 2014) does not put the date in col 2 of the file.

Column 3 - resolution

Column 4 - number of landmarks in image

Column 5 - number of landmarks on image lit limb

Column 6 - code:

c indicates body fixed SCOBJ sigmas

b indicates trajectory relative SCOBJ sigmas

* indicates 3 or fewer landmarks for the image

> indicates pixel residual greater than limit

# indicates image for topography solution only

Column 7 - RMS pixel residual (RMS in pixels)

Column 8 - the magnitude displacement of the SUMFILE solution from the NOMINALS

Column 9, 10, 11 - The specific dx, dy, dz offset between the SUMFILE solution and the NOMINALS (SCOBJ)

(!) The units of measure for numbers in these columns are based on INIT_LITHOS.TXT and the parameters passed into residuals.

Column 12, 13, 14 - The angular error in pointing between the SUMFILES and the NOMINALS

Section 2

These lines report the standard deviations of the positions in the coordinate system listed.

Section 3

These lines give a histogram of the number of images in each resolution bin. This is defined by the units listed: you multiple the bin number by the bin size.

(Compiled by KD)

CategoryFiles CategoryOutputFiles

PRUNE.TXT

Description

PRUNE.TXT is output by residuals. residuals checks the number of pictures containing each landmark listed in LMRKLIST.TXT. If the number of pictures exceeds the limit PRNLM (default PRNLM=500), the landmark is listed to alert the user. You may set the variable PRNLM in INIT_LITHOS.TXT so that you are alerted at a different limit.

The default limit of 500

The user-specified limit, PRNLM, as set in INIT_LITHOS.TXT

For example, the following line in INIT_LITHOS.TXT sets the limit at 100:

PRNLM=100 <- parameter in INIT_LITHOS.TXT

Here is a sample PRUNE.TXT file:

EE0001EE0002EE0003END

(Compiled by DL)

CategoryFiles CategoryOutputFiles

RANGES_SOLVED.TXT

Description

This text file includes date and range information output by residuals for each picture listed in PICTLISTS.TXT or PICTLIST.TXT.

residuals checks each picture listed in PICTLISTS.TXT, if it exists, or PICTLIST.TXT. If the picture name does not include a prefix of # or ! , it lists date and range information in RANGES_SOLVED.TXT .

Here is a sample RANGES_SOLVED.TXT file:

-202607939.82 0.1747612145D+01 P3T11S2H0409 -202607939.82 0.1747612144D+01 P3T11S2H0410 -202607939.82 0.1747612144D+01 P3T11S2H0411 -202607939.82 0.1747612144D+01 P3T11S2H0412

The output contains this information:

Column 1 - Date picture was taken in Ephemeris Time, expressed as ephemeris seconds past J2000

Column 2 - Distance of spacecraft to center of body in km

Column 3 - Picture name

(Compiled by DL)

CategoryFiles CategoryOutputFiles

redo.txt

Description

This text file lists landmarks that met one of these criteria following lithos or lithosP batch processing:

Terminated in error

Did not correlate with at least one image

Correlated weakly with at least one image

redo.txt is output by both find_nofit and find_nofitP, which are discussed separately below.

find_nofit

The batch processes initiated by make_scriptF produce output files LMKNM.OOT. These outputs are basically listings of the lithos standard output for each input landmark. find_nofit searches these output files for each landmark listed in the make_script.in file to identify landmarks that may need further work. The following instances cause the landmark to be listed in redo.txt :

! cat LMKNM.OOT - process still running or terminated in error.* cat LMKNM.OOT - maplets not correlating with at least one image.+ cat LMKNM.OOT - maplets correlating weakly with at least one image.

Here is a sample redo.txt file output by find_nofit:

* EE0017 <- maplets not correlating with at least one image+ EE0034 <- maplets correlating weakly with at least one image* EE0042* EE0044+ EE0045EE0051 <- process still running or terminated in errorEE0053+ EE0054EE0063END

find_nofitP

The batch processes initiated by make_scriptP produce output files <LMKNM>.OOT. These outputs are basically listings of the lithosP standard output, for each input landmark. find_nofitP searches these output files for each landmark listed in the make_script.in file to identify landmarks that may need further work. The following instances cause the landmark to be listed in redo.txt :

! cat LMKNM.OOT - process still running or terminated in error.* cat LMKNM.OOT - maplets not correlating with at least one image.

Here is a sample redo.txt file output by find_nofit:

* EE0017 <- maplets not correlating with at least one image* EE0042* EE0044EE0051 <- process still running or terminated in errorEE0053EE0063END

(Compiled by DL)

CategoryFiles CategoryOutputFiles

REMOVED.TXT

Description

This text file lists landmarks that were eliminated from at least one picture for one of these reasons following register, autoregister, or autoregisterP batch processing:

low correlation

no correlation

The batch processes initiated by make_scriptR, make_scriptA, and make_scriptAP produce output files PICNM.OOT. These outputs are basically listings of the register, autoregister, or autoregisterP standard output for each input picture. find_nofit searches these output files for each picture listed in the make_script.in file to identify pictures that may need further work. The following instances cause the picture to be listed in REMOVED.TXT :

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

Here is a sample REMOVED.TXT file:

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

(Compiled by DL)

CategoryFiles CategoryOutputFiles

RESIDUALS.TXT

Description

This text file is created by residuals to report on landmarks that have residual values above the criteria set when the program was run.

RESIDUALS.TXT captures and reports three types of information:

The post-fit residuals between predicted and actual control point positions in all images.

The post-fit residuals between predicted and actual control point difference between adjacent, overlapping maplets.

Outliers in both quantities are flagged automatically based on input threshold criteria.

Here is a sample RESIDUALS.TXT file. Elements of the data in each of the four sections are explained below.

..................................................IA1_01 T 0.0200 56.5481 140.8124 13.6146 <- Section 1.................................................. A1_01 8.139 -6.853 10.640 0.01091 <- Section 2 A2_05 -28.427 49.215 56.835 0.04250 B1_01 -3.517 52.347 52.465 0.04857 B1_03 -18.475 -57.091 60.006 0.05509IA1_01 42.78 <- Section 3..................................................IA1_03 T 0.0200 36.4771 136.8269 11.4593.................................................. A1_03 -29.498 -12.161 31.906 0.04002 A2_03 -71.840 23.961 75.731 0.07142 A2_04 -3.885 -4.689 6.089 0.00643 A2_05 -34.754 95.249 101.392 0.10527 B1_01 64.895 -21.470 68.354 0.07337 B1_03 11.000 59.329 60.340 0.06832 B2_04 97.637 29.005 101.855 0.11002 B2_05 42.109 41.562 59.165 0.07455IA1_03 75.45......... Observation # = 360180 <- Section 4 RMS Residual (m) = 0.78928860594347106

Section 1

Row between the dot rows includes:

Column 1 - The name of a landmark

Column 2 - T = landmark has a map with it; F = flat landmark, no image

Column 3 - Resolution

Column 4 - Lat of landmark

Column 5 - Wlon of landmark

Column 6 - Radius

Section 2

Rows below the second dot row with the landmark name above include:

For each image:

Column 1 - picture name

Column 2 - PX residual (# of pixels in image resolution)

Column 3 - LN residual (# of pixels in image resolution)

Column 4 - magnitude of PX and LN residuals (# of pixels in image resolution)

Column 5 - the estimate linear residual (km)

For each overlap:

Column 1 - overlap name

Column 2 - X residual (km)

Column 3 - Y residual (km)

Column 4 - Z residual (km)

Column 5 - estimate linear residual (km)

For each limb apperation:

Column 1 - picture name

Column 2 - PX residual (# of pixels in image resolution)

Column 3 - LN residual (# of pixels in image resolution)

Column 4 - magnitude of PX and LN residuals (# of pixels in image resolution)

Column 5 - the estimate linear residual (km)

Section 3

Row below the images, overlaps, and limbs list for a landmark includes:

Column 1 - landmark name

Column 2 - RMS linear residual for landmark (m)

Section 4

Rows below the single dot row at the very bottom for each image includes:

Observations - how many IMAGEFILES, overlaps, and limbs for all landmarks

RMS RESIDUAL - overall RMS linear residual in meters.

Residuals are the difference between observed landmark positions and those predicted by the solution (SPC).

Observed landmark positions are positions of a landmark calculated by the code when it inputs pictures from the spacecraft of the object.

Predicted landmark positions are those calculated by SPC. When it inputs, it generates a solution (map) from all the pictures collected.

During iteration and refinement of the SPC solution, the position and attitude of the spacecraft are slightly changed over and over until the maps match the images until an optimum solution has been converged upon. At the end of each iteration, SUMFILES are then updated for the new attitude and position.

When the RMS between landmark residuals is as low as possible, ..., it indicates no futher processing will improve the solution. This means that the updated SUMFILE is the new estimate for spacecraft position and attitude.

(Compiled by KD)

CategoryFiles CategoryOutputFiles

SHAPE.TXT

Description

This text file is the shape model that SPC uses. SHAPE.TXT is output by densify.

The shape is in the ICQ format, which is basically a 6-sided cube. Q size (resolution) values are between 8 and 512 in increments of factors of 2: 8, 16, 32, 64, 128, 256, 512.

densify generates this file, usually by taking an existing shape model, increasing the scale of the vertices by a factor of two and calculating the height of the average maplet the passes through that vector. The program dumber will downscale the shape model to a lower resolution.

ICQ Format Description

The global topography models (GTM) are presented here in an implicitly connected quadrilateral (ICQ) format. The vertices are labeled as though they were grid points on the faces of a cube

0 --------- I --------- Q 0 . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . J . . . . F. . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . Q . . . . . . . . .

so that each of the six faces (F) contains (Q+1)^2 vertices v(I,J,F) (I=0,Q; J=0,Q) and Q^2 facets f(I,J,F) (I=0,Q-1; J=0,Q-1).

The facet f(I,J,F) implicitly has the vertices v(I,J,F), v(I,J+1,F), v(I+1,J+1,F), v(I+1,J,F).

If the cube is unfolded, the six faces are arranged as

----------- | | | 1 | | | ----------------------------------------- | | | | | | 5 | 4 | 3 | 2 | | | | | | ----------------------------------------- | | | 6 | | | -----------

At each of the 12 edges of the cube, faces share common vertices so that, for example, the last row of face 1 has the same vertices as the first row of face 2. The common edge vertices are, with I=(0,Q),

v(I,Q,6)=v(Q-I,Q,4) v(I,0,6)=v(I,Q,2) v(I,0,5)=v(Q,Q-I,1) v(I,0,4)=v(Q-i,0,1) v(I,0,3)=v(0,I,1) v(I,0,2)=v(I,Q,1) v(q,I,6)=v(I,Q,5) v(q,I,5)=v(0,I,4) v(q,I,4)=v(0,I,3) v(q,I,3)=v(0,I,2) v(0,I,6)=v(Q-I,Q,3) v(0,I,5)=v(Q,I,2)

and the eight corners share vertices from three faces:

v(0,0,1) = v(0,0,3) = v(Q,0,4) v(0,Q,1) = v(0,0,2) = v(Q,0,3) v(Q,0,1) = v(0,0,4) = v(Q,0,5) v(Q,Q,1) = v(0,0,5) = v(Q,0,2) v(0,0,6) = v(0,Q,2) = v(Q,Q,3) v(0,Q,6) = v(0,Q,3) = v(Q,Q,4) v(Q,0,6) = v(0,Q,5) = v(Q,Q,2) v(Q,Q,6) = v(0,Q,4) = v(Q,Q,5)

Thus of the 6(Q+1)2 labeled vertices, only 6Q 2+2 are independent.

File Structure

The file structure is quite simple. The first line contains the value of Q, and is followed by 6(Q+1)^2 lines containing the vertices. A piece of Fortran code for reading the file would look like:

READ(10,*) Q DO F=1,6 DO J=0,Q DO I=0,Q READ(10,*) (V(K,I,J,F), K=1,3) ENDDO ENDDO ENDDO

Here the vertices are represented by three-vectors. In some cases extra components are added representing albedo, color, surface gravity, or other surface characteristics. Since the labeling scheme implicitly contains the connectivity, no facet table is necessary.

The quadrilateral facets in the model are not necessarily flat, since there is no guarantee that the four vertices are coplanar. The facet normals are defined by the cross product of their diagonals. This approximation presents no real difficulty because the spacings of the vertices are very small compared to the size of the body. The standard form (Q=512) has 1.57 million vertices.

Although it is not necessary, it is convenient to take Q to be a power of 2. Because of this choice, it is easy to 'dumb down' a model by increasing the spacing by factors of 2. Vertices of the form v(2I,2J,F) are retained and the others discarded. Because of the quadrilateral facet structure, the models can also be 'densified' through bilinear interpolation.

Example

Here is a sample SHAPE.TXT file:

128 -218.72182 -8.78589 136.89489 -217.94953 -6.10207 138.09736 -217.59664 -3.46244 139.74751 -216.83911 -0.75086 140.98874 -216.04842 1.95086 142.19411 -215.34667 4.53459 143.49143 -214.06968 7.13078 144.16124 -212.35048 9.69145 144.34511 -210.62577 12.23122 144.54863 -209.47201 14.69014 145.33889 -208.85169 17.21845 146.67393 -208.58685 19.86090 148.37467.....

Q Value

Q	Vertices
4	151
8	487
16	1735
32	6534
64	25351
128	99846
256	396294
512	1579014

The output values are:

Line 1 - Q (resolution). This gives the number of nodes for i and j. Multiple Q by 6 coordinate vector spaces to fill out the entire region.

(!) Q*Q*6 is the total number of nodes, and line entries in this file.

(!) A Q of 512 is the largest that we represent. It contains 1.5 million vertices and is 56 MB uncompressed.

Lines 2 and following - The location of a vertex in i, j, k space (Cartesian coordinates).

(Compiled by KD)

References

Gaskell, R.W., O. Barnouin-Jha, and D. Scheeres, Modeling Eros with Stereophotoclinometry, Abstract #1333, 38th LPSC, Houston, TX, 2007. [GASKELLETAL2007]

Gaskell R.W., Landmark navigation and target characterization in a simulated Itokawa encounter, AAS paper 05-289, AAS/AIAA Astrodynamics Specialists Conf., Lake Tahoe, CA, 2005. [GASKELL2005]

CategoryFiles CategoryOutputFiles

SIGMAS.TXT

Description

This text file contains the sigma values for each bigmap. SIGMAS.TXT is created and updated by bigmap. Every time a bigmap is made, the name and current sigma values are appended to SIGMAS.TXT .

Here is a sample SIGMAS.TXT file:

MTAG15 0.001 0.000MTAG15 0.001 0.000MTAG15 0.001 0.000MTAG25 0.001 0.000MTAG35 0.001 0.000MTAG15 0.001 0.000MTAG25 0.001 0.000MTAG35 0.001 0.000MREG01 0.000 0.000MREG03 0.000 0.000

The output values are:

Column 1 - landmark name

Column 2 - maximum standard deviation of weighted heights (in km) at each pixel/line location

Column 3 - average standard deviation of weighted heights (in km) at each pixel/line location

(Compiled by TC)

CategoryFiles CategoryOutputFiles

SIGMA.TXT

Description

This text file is essentially a copy of the most recently made ICQ shape file SHAPE.TXT that includes an additional column of sigma values.

SIGMA.TXT is made by densify and is located in the SHAPEFILES/ directory.

Here is a sample SIGMA.TXT file:

512 0.00810 0.19764 0.13333 0.29844E-01 0.00871 0.19742 0.13360 0.28206E-01 0.00932 0.19721 0.13386 0.27425E-01 0.00994 0.19700 0.13414 0.27743E-01 0.01055 0.19677 0.13441 0.28415E-01 0.01116 0.19655 0.13466 0.31917E-01 0.01177 0.19633 0.13493 0.31631E-01 0.01239 0.19615 0.13521 0.28469E-01 0.01300 0.19594 0.13549 0.28856E-01

The output values are:

Line 1 - Q (resolution). This gives the number of nodes for i and j. Multiple Q by 6 coordinate vector spaces to fill out the entire region.

(!) Q*Q*6 is the total number of nodes, and line entries in this file.

(!) A Q of 512 is the largest that we represent. It contains 1.5 million vertices and is 56 MB uncompressed.

Lines 2 and following - The location of a vertex in i, j, k space (Cartesian coordinates).

Column 1 - Position in x

Column 2 - Position in y

Column 3 - Position in z

Column 4 - Sigma values - JRW edit: densify.f doesn't read INIT_LITHOS.TXT, and multiplies a value by 1000 right before writing out SIGMA.TXT, so I'm fairly confident that the units are always meters.

(Compiled by TC) (Updated by JRW) CategoryFiles CategoryOutputFiles

USED_MAPS.TXT

Description

This text file, an output from bigmap, lists all of the maplets that were used by bigmap the last time it was run. This list includes maplets contained completely by the bigmap as well as those that fall on the border.

/!\ USED_MAPS.TXT is different from INSIDE.TXT, which only lists maplets contained entirely inside the bigmap that was created.

Here is a sample USED_MAPS.TXT file:

T00144T00145T00146T00160T00161T00162T00163END

(Compiled by TC)

CategoryFiles CategoryOutputFiles

USED_PICS.TXT

Description

This text file output by bigmap contains a list of all the images that were used in creating the most recently made bigmap.

Note: This file contains limb images in addition to images used for stereo and photoclinometry

Here is a sample USED_PICS.TXT file:

P595733646F2 P595733662F2 P595467488F2 P595467677F2 P595467866F2 P595468055F2 P595652545F2 P595652849F2 P595653154F2END

(Compiled by TC) (Edited by JRW)

CategoryFiles CategoryOutputFiles

veto.txt

Description

This lithos seed file is output by residuals and used to detach from landmarks and limbs any map with a linear residual greater than the user-specified limit.

veto.txt is created for any landmark whose linear residual is greater than PLIM 2, the second residuals argument. The seed file contains the lithos commands to process each landmark listed in LMKFILE that meets the criteria. veto.txt is ready for execution as a batch process.

The accompanying check.txt file lists suspect landmarks and affected overlapping landmarks and limbs. This file allows you to individually inspect each instance.

Here is a sample veto.txt file annotated with explanations of the commands:

o a <- attach map to maps or limbsEE0001 <- landmark namen <- don't reset all4 <- detach from limb or landmarkEE0005 <- landmark name (overlap)0 <- 0 to endo a <- as aboveEE0001n4EE00060o a <- attach map to maps or limbsEE0001 <- landmark namen4P00045000450 <- picture name (limb)0q <- quit lithos

(Compiled by DL)

CategoryFiles CategoryOutputFiles

Support Files

make_script.in

Description

This input file lists the set landmarks or images intended for batch processing.

make_script.in is used by these script-makers:

make_scriptA - a script-maker for batch autoregistering new images

make_scriptAP - a script-maker for batch autoregistering new images using parallel processing

make_scriptF - a script-maker for batch lithos processing

make_scriptP - a script-maker for batch standard iteration of landmarks using parallel processing

make_scriptR - a script-maker for batch registration of new images

Here is a sample make_script.in file used by make_scriptA, make_scriptAP, and make_scriptR:

P00045000450 P00045000451 P00045000452END

/!\ You must precede each image filename with a space when creating make_script.in files for these script-makers.

Here is a sample make_script.in file used by make_scriptF and make_scriptP:

EE0001EE0002EE0003END

/!\ You must not precede each landmark filename with a space when creating make_script.in files for these script-makers.

(Compiled by DL)

CategoryFiles CategorySupportFiles

make_scriptA.seed

Description

This seed file is used by make_scriptA, the script-maker for batch autoregistering new images.

Here is a sample make_scriptA.seed file annotated with explanations of the commands:

n <- auto-eliminate new landmarks0,50,.25,0,5 <- INVLIM, SLIM, CLIM, RSMN, RSMX1 <- auto-align2 <- spacing 2n <- no spacing change0 <- shift by full amounty <- update landmark pixel locations1 <- auto-align1 <- spacing 1n <- no spacing change0 <- shift by full amounty <- update landmark pixel locationso <- remove low-correlation landmarks.5 <- correlation limit 0.51 <- auto-align1 <- spacing 1n <- no spacing change0 <- shift by full amounty <- update landmark pixel locations4 <- change flagsb <- use all0 <- exit (image)q <- quit autoregisterEND

(Compiled by DL)

CategoryFiles CategorySupportFiles

make_scriptF.seed

Description

This seed file is used by make_scriptF, the script-maker for batch lithos processing. make_scriptR.seed contains the lithos commands for processing each landmark.

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

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

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

Writing the make_scriptF.seed

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

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

# Seed file to attach map to overlapping maps#start commandsn <- don't check for more imagesn <- don't include a single image#processing commandsoRECENTy1oRECENTn3y1, 3, 5 wiRECENTnnv1u1oRECENTn1#end commandq <- quit#end-of-file identifierEND <- 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.

(Compiled by DL)

CategoryFiles CategorySupportFiles

make_scriptP.seed

This seed file is used by make_scriptP for standard iteration of landmarks. make_scriptP.seed contains the lithosP commands for processing each maplet.

Here is an annotated sample make_scriptP.seed file:

# This script performs two maplet iterations in parallel mode. # It reinitializes slope and albedo.# It recomputes maplet overlaps.# It recomputes limb fits.# It recomputes central maplet vector.# Topography determination from slopes is conditioned by:# Initial topography, # Overlapping topography, # Shadowing, # Differential stereo, # Limb heghts. # Dataless area slopes are set from the shape model.## The script hides most of the screen output. In order to obtain the # full display replace H* by #H*.## Modified 2011_12_31. Header and comments added.# Modified 2014_02_26. Hide screen output added.#H* <- Toggle ON: suppress standard outputx <- turn on extract filter.025 <- extract filter tolerance, 0.025## Initialize slope and albedo.#a <- reset albedo or slopesy <- reset slopesy <- reset albedos## Begin first iteration.#0 <- find template (build template #1)40 <- number of iterations, 401 <- align landmarks0 <- auto-align1 <- auto-align spacing, 1n <- don't try new spacing0 <- continue (full shift)y <- update landmark pixel locationsu <- update landmark files0 <- find template, as above (build template #2)40## Begin topo determination.#2 <- find heights (build topography #1)8 <- fill no data with shape slope2 <- include existing heights.01 <- existing heights, fraction of points, 0.017 <- include shadowing.025 <- shadowing, fraction of points, 0.0251 <- auto-include neighboring maps4 <- include limb vectors1, 2.5, 3 <- expansion (1), res/scale (2.5), d_hgt limit (3)6 <- include differential stereoy <- use gradients / auto heights0 <- begin integration.025 <- weight, 0.02515 <- number of iterations0 <- end iterationsu <- update landmark files1 <- align landmarks (as above)02 <- auto-align spacing, 2n0y1 <- align landmarks (as above)01n0yu <- update landmark files## Begin second iteration.#0 <- find template (as above) (build template #3)401 <- align landmarks (as above)01n0yu <- update landmark files0 <- find template (as above) (build template #4)40## Begin topo determination.#2 <- find heights, as above (build topography #2)82.017.025141, 2.5, 3 6y0.025150u <- update landmark files1 <- align landmarks (as above)02n0yH* <- Toggle OFF: suppress standard output1 <- align landmarks (as above)01n0yH* <- Toggle ON: suppress standard outputu <- update landmark files## Begin overlaps and limb fits.#o <- attach map to maps or limbsRECENT <- re-load most recent maplety <- reset all1 <- automatico <- attach map to maps or limbsRECENT <- re-load most recent mapletn <- don't reset all3 <- attach map to limbsy <- clear1, 3, 5 <- expansion (1), res/scale limit (3), d_hgt limit (5)## Central vector determination.#v <- find V from Z and pointing (mini-geometry)RECENT <- re-load most recent maplet q <- quit lithosPEND

(Compiled by DL)

CategoryFiles CategorySupportFiles

make_scriptR.seed

Description

This seed file is used by make_scriptR, the script-maker for batch registering new images.

Using make_scriptR.seed

The following annotated make_scriptR.seed file was used for registering 450 Vesta images to Zmaps:

m <- reference = map 0 <- Auto-choose Zmap 1.0 <- Scale = 1 km a <- Turn off background 3 <- Shift image y <- Autocorrelate XSTOP <- Stop on no correlation 1 <- Change scale 0.25 <- New scale = 250 m 3 <- Shift image y <- Autocorrelate XSTOP <- Stop on no correlation 0 <- Quit y <- Save new .SUM data n <- Don't save rotation history n <- Don't save nominal q <- Quit procedure END

XSTOP - This is a provision for the autocorrelation procedure to end gracefully in the event that the correlation fails.

If you enter

3yXSTOP

and then the correlation fails, the program will reset the .SUM data to the input values and then stop.

XSKIP# - Used to to activate the autocorrelate sequence.

If you enter

3yXSKIP#

the program will skip # lines of the script, reset the .SUM data and ask you to input the next image.

/!\ The last two entries of 'n' are always so. The rotation history file was introduced to keep track of pointing errors in Clementine data during Lunar orbits in an attempt to quantify systematic shifts and it is rare that we want to set the nominal file equal to the .SUM solution.

(Compiled by DL)

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

CategoryFiles CategorySupportFiles

make_scriptT.in

Description

This support file is used by make_scriptT, the script-maker for tiling a bigmap or shape.

Basic Tiling

Basic tiling involves tiling a bigmap which is located on the shape. For more details, refer to Basic_tiling.

Here is an annotated sample of a make_scriptT.in file used for basic tiling:

XXXXXX <- For maplet locations, reference to temporary file containing the tiling bigmapscripts/t11-10.seed <- Reference to the make_scriptT.seed file 50 50 <- bigmap pixel/line location for placement of the center of each new maplet 100 50 150 50 200 50 50 100 100 100 150 100 200 100 50 150 100 150 150 150 200 150 50 200 100 200 150 200 200 200END

XXXXXX - You must save the tiling bigmap to a temporary file for tiling using a command line like this:

cp MAPFILES/BGMAP1.MAP MAPFILES/XXXXXX.MAP

You then include the temporary filename as the first line of the file.

make_scriptT seed file - File containing the lithos commands for generating each new maplet. Refer to make_scriptT.seed for more information.

bigmap pixel/line locations - These are generated using the programs map_coverage and make_tilefile. Refer to those entries for details.

Lat/Long Tiling

Lat/Long tiling involves directly tiling a shape model. For more details, refer to LatLon_tiling.

Here is an annotated sample make_scriptT.in file used for lat/long tiling:

LATLON <- For maplet locations, reference to shape modelSCRIPTS/XXX150.SEED <- Reference to the make_scriptT.seed file 00, 000 <- shape model lat/wlong for placement of the center of each new maplet 00, 012 00, 024 00, 036 00, 048 00, 060 00, 072 00, 084 ....-84, 315 90, 000-90, 000END

make_scriptT seed file - File containing the lithos commands for generating each new maplet. Refer to make_scriptT.seed for more information.

Image Tiling

The 1st line must be "IMAGES".

The 2nd line is the script name

Following lines are image name, sample and pixel

Image name must be char 1-12.

Sample and pixel are after that with any fortran format (space or comma delimited)

Ends with the statement "END"

# symbol will cause that entry to be skipped

Here is an annotated sample make_scriptT.in file used for tiling an image:

IMAGES <- For maplet locations, reference to shape modelTIL_eekingLimbsInImage.seed <- Reference to the make_scriptT.seed fileD7175061248G 358 511 <- image name followed up pixel/line location D7175061210G 372 515D7175061210G 387 513D7175061210G 403 507 ....D7175061210G 566 887END

(Compiled by DL)

CategoryFiles CategorySupportFiles

make_scriptT.seed

Description

This seed file is used by make_scriptT, the script-maker for tiling a bigmap or shape with a suite of new maplets. make_scriptT.seed contains the lithos commands for processing each new maplet.

Here is an annotated sample make_scriptT.seed file:

0.00010,49 <- maplet ground sample distance and Q-sizeg <- turn on auto-rename (based on its shape model lat/wlon region)i <- input landmarka <- new landmark temporary name 'a', will immediately be auto re-namedy <- check for more images.5 <- fractional width, 0.5n <- don't reject invisiblesx <- turn on extract filter.025 <- extract filter tolerance, 0.0250 <- find templatea <- use all imagesb <- get heights from surrounding mapn <- don't list all possibilitiesXXXXXX <- reference map name (temporary file which contains tiling bigmap)n <- find normal2 <- find normal from heightsb <- get heights from surrounding map (as above)nXXXXXXu <- update landmark files1 <- save mapv <- find V, Z, or PTG2 <- find Z from V and pointinge <- eliminate images from landmark a <- auto-remove0,60,.25,.25,0,3 <- INVLIM, SLIM, CLIM, RSMN, RSMX1 <- align landmarks0 <- auto-align3 <- auto-align spacing, 3n <- don't try new spacing0 <- continue (full shift)y <- update landmark pixel locations1 <- align landmarks (as above)01 <- auto-align spacing, 1n0y0 <- find templatec <- use correlated images.5 <- correlation limit, 0.50 <- find template (build template #1)0 <- continue40 <- number of iterations, 401 <- align landmarks (as above)03n0y1 <- align landmarks (as above)01n0ye <- eliminate images from landmarko <- remove low correlating images.5 <- correlation limit, 0.50 <- find templatea <- use all imagesu <- update landmark files (as above)10 <- find template (as above) (build template #2)040 <- number of iterations, 402 <- find heights (build topography #1)8 <- fill with shape2 <- include existing heights.01 <- existing heights, fraction of points, 0.011 <- auto-include neighboring maps4 <- include limb vectors1, 2.5, 3 <- expansion (1), res/scale (2.5), d_hgt limit (3)6 <- include differential stereoy <- use gradientsy <- use auto heights 0 <- begin iteration.025 <- weight, 0.02530 <- number of iterations0 <- end iterationsu <- update landmark files (as above)1v <- find V, Z, or PTG1 <- find V from Z and pointing1 <- align landmarks (as above)01n0yu <- update landmark files (as above)10 <- find template (as above) (build template #3)0401 <- align landmarks (as above)02n0y1 <- align landmarks (as above)01n0ye <- eliminate images from landmark (as above)o.5u <- update landmark files (as above)10 <- find template (as above) (build template #4)0402 <- find heights (build topography #2)82.01141, 2.5, 3 6yy0.025300u <- update landmark files (as above)1v <- find V, Z, or PTG (as above)11 <- align landmarks (as above)01n0yu <- update landmark files (as above)1o <- attach map to maps or limbsRECENT <- re-load most recent maplety <- reset all1 <- automatico <- attach map to maps or limbsRECENT <- re-load most recent mapletn <- don't reset all3 <- attach map to limbsy <- clear1, 3, 5 <- expansion (1), res/scale limit (3), d_hgt limit (5)i <- input landmarkRECENT <- re-load most recent mapletn <- don't check for more imagesn <- don't include single imagev <- find V, Z, or PTG (as above)1u <- update landmark files (as above)1v <- find V, Z, or PTG4 <- find PTG/SCOBJ from Z and V (current images) - update S/C position and pointingo <- attach map to maps or limbsRECENT <- re-load most recent mapletn <- don't reset all1 <- automaticq <- quit lithosEND

(Compiled by DL)

CategoryFiles CategorySupportFiles