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

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.

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

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

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

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.

autoregister

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)
.5
Reject invisibles? (y/n)
n

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

1. Enter the image name that is stored in IMAGEFILES.

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

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

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

5. Enter 'q' as the image name to quit.

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

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

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

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

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

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

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

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

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

   When landmarks are added in autoregister, they immediately populate the image’s SUMFILE. Further processing must be conducted if you wish to remove the image from any of the landmarks. This is different from lithos where images are not added to landmarks until the landmark file is updated.

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

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

autoregister Main Menu

 ...     MAIN MENU     ...

 0. Exit

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

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

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

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

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

REMOVE MAPLETS Options

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

• # - landmark number

• LMKNM - landmark name

• EMISS - emission angle

• COV - maplet-image overlap

• RES - image resolution/maplet scale

• INV - 1000 x invisible fraction of maplet

• #PIC - number of images in maplet

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

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

• SLIM - maximum emission angle.

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

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

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

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

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

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

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

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

IMAGE/MAPLET ALIGNMENT Options

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

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

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

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

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

 new spacing? (y/n)
n

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

 update landmark pixel locations? (y/n)

• Enter Spacing - Enter the size of the search area for the correlation. Enter '1' to search a 5x5 pixel area, '2' for 10x10 and so on.

  The Auto-alignment routine output table includes these columns:

  • column 1 - landmark number

  • column 2 - landmark name

  • column 3 - the pixel shift predicted by the correlation

  • column 4 - the line shift predicted by the correlation

  • column 5 - the correlation value

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

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

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

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

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

  When you are satisfied with the correlation, enter 'n'. Then choose from these options:

  • 0. continue - Shifts all the maplets by the amount determined by the correlation.

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

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

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

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

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

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

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

• Option 2 is only used occasionally.

LANDMARK ADJUSTMENTS Options

Enter one of these 3 options:

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

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

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

Here is a sample showing the output from Option 4.

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

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

There are three sub-options to option 4.

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

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

  0 to end -- quit without changing

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

Batch Processing

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

Additional Reference

LMRK_DISPLAY1.pgm

Figure 00: Comparison of Landmarks and Associated Maps

Figure 00: Illustration of Autoregister and Landmark Options

(Compiled by DL)

CategoryPrograms

autoregisterP

Description

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

Like autoregister, autoregisterP

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

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

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

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

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

Required Files

• IMAGEFILES/ - a directory containing the image .DAT files

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

• MAPFILES/ - a directory containing the full suite of maplets

• LMKFILES/ - a directory containing the full suite of landmarks

• LMRKLIST.TXT - a list of the landmarks contained in the solution

• LMRKLISTX.TXT - landmark information (size, scale, position vector, number of images containing the lmrk)

Optional Files

• make_scriptA.seed - for batch processing using make_scriptAP

Output Files

• SUMFILES/ - Landmarks are added to the image's SUMFILE. Spacecraft/camera position/attitude are updated once you accept the alignment shifts.

• LMKFILES/ - LMKFILES are updated to contain the image you are working with.

• LMRK_DISPLAY1.pgm - - 100x100 pixel display of images (odd rows) and maplets (even rows). Unlike lithos, each pair is a separate landmark consisting of a completely different location on the surface and image.

• TEMPFILE.pgm - A pgm image of the image that you are working with.

User Warnings

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

  When landmarks are added in autoregisterP, they immediately populate the image’s SUMFILE. Further processing must be conducted if you wish to remove the image from any of the landmarks. This is different from lithos where images are not added to landmarks until the landmark file is updated.

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

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

Using autoregisterP

Initial Inputs

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

 input 12-character picture name. q to quit.

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

 gc TEMPFILE.pgm
 kb =            1      kk =            1

 Add landmarks? (y/n)
y

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

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

1. Enter a 2-character USR name to distinguish between processes.
2. Enter the 12-character picture name. The program produces a list of existing landmarks, if any, creates the TEMPFILE.pgm and displays the kb, and kk values.

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

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

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

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

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

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

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

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

   When landmarks are added in autoregisterP, they immediately populate the image’s SUMFILE. Further processing must be conducted if you wish to remove the image from any of the landmarks. This is different from lithos where images are not added to landmarks until the landmark file is updated.

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

autoregisterP Main Menu

 ...     MAIN MENU     ...

 0. Exit

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

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

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

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

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

(Compiled by DL)

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

CategoryPrograms

bigmap

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

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

Description

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

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

Required Files

• BLEMISHES/ - Directory containing BLEMISH files for individual images and BLEMISH templates for multiple affected images.

• IMAGEFILES/ - Directory containing the .DAT file for the image; this program displays the image with masking for user inspection, and reads the Digital Number (DN) of pixels of interest.

• SUMFILES/ - Directory containing the SUMFILE for the image to mask; this program reads NPX (number of pixels), and NLN (number of lines);

• INIT_LITHOS.TXT - this program reads the parameter BLEMISH (if it exists), which references any existing template for masking bad pixels common to multiple images.

  • BLEMISHES/TEMPLATENAME.BLM - template BLEMISH file for each INIT_LITHOS BLEMISH entry.

Optional Files

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

Output Files

• TEMPFILE.pgm - Display of the image with masking applied.

• BLEMISHES/PICNAME.BLM - Generated or edited BLEMISH (.BLM) file.

User Warnings

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

Using blemishes

Initial Inputs

 Input 12-character picture name
P00045000455
 gc TEMPFILE.pgm

 b. Block
 s. Spot
 q. Quit

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

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

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

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

Figure 00: Image Prior to Applying Mask

Block Blemish Options

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

 b. Block
 s. Spot
 q. Quit

After you choose b. Block you must specify:

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

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

This sample shows the image after block masking was applied:

Figure 00: Image after Applying Blemish Mask

Spot Blemish Options

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

 b. Block
 s. Spot
 q. Quit

After you choose s. Spot you must specify:

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

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

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

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

Figure 00: Image Displaying Blemish Mask Options

Quit Blemishes Option

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

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

BLEMISH Templates

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

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

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

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

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

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

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

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

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

(Compiled by DL) (Updated by JRW)

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

CategoryPrograms

densify

Description

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

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

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

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

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

Required Files

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

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

• MAPFILES/ - Directory of .MAP files

• SHAPEFILES/ - Directory of built shapes

Optional Files

• LMRKLISTR.TXT - Specific list of landmarks desired

Output Files

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

• Shape file in ICQ format

Using densify

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

~/bin/densify < tmpRun.txt

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

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

The input commands are:

• line 1 - The input SHAPE file

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

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

• line 3 - The output SHAPE file

• line 4 - 1 = an iteration

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

• line 6 - The conditioning weight

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

• last line - 0 = end program

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

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

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

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

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

     0. end program
     1. proceed to iteration

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

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

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

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

If you enter '1', the program prompts:

     input fraction

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

The program prompts:

     input weight

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

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

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

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

By tradition, usually use:

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

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

     cp SHAPEFILES/SHAPEX.TXT SHAPEFILES/SHAPE2.TXT

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

     cp SHAPEFILES/SHAPEX.TXT SHAPEFILES/SHAPE3.TXT

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

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

At the command line enter:

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

Interactive

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

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

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

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

(Compiled by TC)

CategoryPrograms

densifyA

Description

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

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

densifyA is identical to densify except that it uses albedo.

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

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

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

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

Required Files

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

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

• MAPFILES/ - Directory of .MAP files

• SHAPEFILES/ - Directory of built shapes

Optional Files

• LMRKLISTR.TXT - Specific list of landmarks desired

Output Files

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

• Shape file in ICQ format

Using densifyA

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

~/bin/densify < tmpRun.txt

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

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

The input commands are:

• line 1 - The input SHAPE file

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

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

• line 3 - The output SHAPE file

• line 4 - 1 = an iteration

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

• line 6 - The conditioning weight

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

• last line - 0 = end program

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

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

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

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

     0. end program
     1. proceed to iteration

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

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

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

If you enter '1', the program prompts:

     input fraction

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

The program prompts:

     input weight

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

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

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

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

By tradition, usually use:

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

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

     cp SHAPEFILES/SHAPEX.TXT SHAPEFILES/SHAPE2.TXT

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

     cp SHAPEFILES/SHAPEX.TXT SHAPEFILES/SHAPE3.TXT

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

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

At the command line enter:

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

Interactive

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

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

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

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

(Compiled by TC)

CategoryPrograms

duplicates

Description

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

The duplicates program serves two functions:

• First, some lists of landmarks to be processed may contain duplicate names. The files check.txt and MAPCHK.TXT produced by residuals are examples. duplicates outputs only one of each to the file make_script.in.

• Second, in iterating a set of landmarks, it is believed to be more reliable to proceed from lower to higher resolution maplets. Duplicates does this ordering using the Heapsort algorithm (Numerical Recipes, p. 231) as part of the process.

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

Required Files

• LMRKLIST.TXT - Full list of landmarks, appended with 'END'.

• LIST.TXT - Temporary list of the subset of landmarks which the user wishes to process appended with 'END', for sorting and removal of duplicates using this program.

• LMKFILES/ - Directory containing all the LMKFILES listed in LMRKLIST.TXT.

• MAPFILES/ - Directory containing all the MAPFILES for landmarks listed in LMRKLIST.TXT.

Output Files

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

Using duplicates

1. Create Input File

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

2. Run duplicates

duplicates processes landmark names as follows:

• For every landmark listed in LMRKLIST.TXT, duplicates

  • checks that the MAPFILE exists
  • obtains the maplet's Q-size and Ground Sample Distance (GSD) from the LMKFILE
  • sorts the list by decreasing GSD and increasing name (lat/wlong identifier and numeric identifier)
  • discards duplicate entries

• For every landmark listed in LIST.TXT, duplicates

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

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

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

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

Here is a sample LMRKLIST.TXT file:

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

Here is a sample LIST.TXT file:

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

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

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

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

(Compiled by DL)

CategoryPrograms

dynamics

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' APPROACH
ETLM=  1800, 1.D-6
VSIG= 0.200, 0.200, 0.200
PSIG= 0.0001, 0.0001, 0.0001
 F11A0001225
 F11A0001241
 ...
 F21A0003895
 F21A0003910
 
FRAME='dxR_FRAME' SURVEY
ETLM=  1800, 1.D-6
VSIG= 0.100, 0.100, 0.040
PSIG= 0.0001, 0.0001, 0.0001
 F21A0003931
 F21A0003932
 ...
 F21A0032347
 F21A0032348
END

A typical ETLIM= record is:

ETLM=  1800, 1.D-6

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

FRAME= has these three choices:

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

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

• dxR_FRAME uses the radial direction (R) as prime for the third component with the second component being the cross track direction (X) and the first component, roughly in the downtrack direction completing the right-handed coordinate system. This is used in orbital operations around large bodies, where the radial component is well known from the Doppler data.

• Dxr_FRAME is used during approach where the downtrack velocity is best known. The "radial" (impact parameter) direction is crossed with the downtrack to give the crosstrack direction.

• BOD_FRAME simply uses the components in the body-fixed frame, generally with equal uncertainties in each direction.

The VSIG= record has three components:

VSIG= 0.100, 0.100, 0.040

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

The PSIG= record has three components:

PSIG= 0.0003, 0.0003, 0.0005

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

(Compiled by TC)

CategoryPrograms

Export and Import

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

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

User Warnings

• You must ensure that LMRKLIST1.TXT only has the recently created landmarks (i.e., contains only the LMKs you wish to export and import into a new model). If LMRKLIST1.TXT has other LMKs you don't wish to bring into a different model, remove them from the top of the LMRKLIST1.TXT.

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

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

Export

Required Files

• MAPFILES/ - a directory containing the full suite of maplets

• LMKFILES/ - a directory containing the full suite of landmarks

• LMRKLIST1.TXT - a list of the new landmarks

Output Files

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

Using Export

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

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

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

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

2. Enter the following at the command line:

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

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

The script EXPORT.TXT looks this:

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

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

sh EXPORT.TXT

4. Change the name of NEW_FILES.tar to something distinctive like

   • new_<bigmapName>.tar

5. Transfer the tar file to the other computer.

Import

Required Files

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

Output Files

• MAPFILES/ - a directory containing the full suite of maplets

• LMKFILES/ - a directory containing the full suite of landmarks

• LMRKLIST.TXT - updated landmark list

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

Using Import

1. Untar to recover NEW_FILES directory.

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

tar -xvf NEW_FILES.TAR

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

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

/usr/local/bin/IMPORT

• This will import the new landmarks.

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

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

cp NEWLIST.TXT make_script.in

For make_scriptF.seed use:

n
n
g
u
1
o
RECENT
n
1
q
END

Copy into window:

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

Check progress with:

find_nofit

(Modified by JRW from text written by EEP)

CategoryPrograms

find_nofit

Description

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

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

Required Files

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

• Either:

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

• Or:

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

Output Files

Either:

• redo.txt - list of landmarks that

  • terminated in error
  • do not correlate with at least one image, OR
  • correlate weakly with at least one image

Or:

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

Using find_nofit

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

For lithos

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

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

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

For register

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

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

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

Here is an annotated sample output from find_nofit:

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

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

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

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

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

(Compiled by DL)

CategoryPrograms

find_nofitP

Description

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

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

Required Files

• make_script.in - input file for batch processing using make_scriptP

• <LMKNM>.OOT files - lithosP standard output listings

Output Files

• redo.txt - list of landmarks that

  • terminated in error
  • do not correlate with at least one image, OR
  • correlate weakly with at least one image.

Using find_nofitP

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

• See find_nofit to identify the flags thrown by find_nofitP.

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

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

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

• 0.28 (~2/7) otherwise

Here is an annotated sample output from find_nofitP:

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

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

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

Compiled by KD CategoryPrograms

find_nofitT

Description

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

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

Required Files

• <NNN>.OOT files - lithos standard output listings

Output Files

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

Using find_nofitT

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

The find_nofitT procedure identifies:

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

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

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

Here is an annotated sample output from find_nofitT:

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

Here is a sample NEW_LIST.TXT from find_nofitT:

EP0001
EP0002
EP0003
EP0004
EQ0001
EQ0002
EQ0003
EQ0004
END

(Compiled by KD)

CategoryPrograms

geometry

• BACK UP YOUR WORK BEFORE RUNNING GEOMETRY!

Description

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

Required Files

• LMKFILES/ - A directory containing the full suite of landmarks.

• PICTLIST.TXT - A list of picture names generated by make_sumfiles.

• LMRKLIST.TXT - A list of the landmarks contained in the solution.

• LMRKLIST1.TXT - A file containing default values to be read in by SPC toolkit.

• MAPFILES/ - A directory containing the full suite of maplets.

• INIT_LITHOS.TXT - A text file setting limits, definitions, and logicals for SPC.

• SHAPE.TXT - The shape model stored in directory SHAPEFILES/.

• NOMINALS/ - A directory containing the image .NOM files.

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

Output Files

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

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

• MAPFILES/ - This directory is also updated because the landmark vector in the header of the MAPFILE is also updated

Optional Files

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

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

User Warning

• ALWAYS BACK UP YOUR WORK BEFORE USING GEOMETRY.

Using geometry

The inputs for geometry are:

• input operation list - Use these values:

  • 1: landmark vectors.
  • 2: camera pointing, scobj
  • 0: end.

  enter number of iterations - Input desired number. use limbs for pointing? (y/n) - Choose whether to use limbs in determining camera pointing. continue? (y/n) - Choose whether to do it all over again.

Here are two annotated samples that show geometry inputs:

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

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

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

If INIT_LITHOS.TXT contains a record

GEOPI='filename1'

or

GEOMAP='filename2'

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

Additional Reference

Geometry Estimation Terms

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

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

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

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

Figure 00: Examples of Offset and Orientation Errors

More Detailed Description of Geometry

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

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

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

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

Figure 00: Illustration of Iterative Process for Updating Geometry

(Compiled by TC)

CategoryPrograms

lithos

Description

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

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

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

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

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

Required Files

• DATA/ - data specific to each mission

• IMAGEFILES/ - a directory containing the image .DAT files

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

• MAPFILES/ - a directory containing the full suite of maplets

• LMKFILES/ - a directory containing the full suite of landmarks

• BIGFILES/ - a directory containing all the bigmaps

• NOMINALS/ - a directory containing the full suite of nominals

• SHAPEFILES/ - a directory containing the shapemodel

• LMRKLIST.TXT - a list of the landmarks contained in the solution

• PICTLIST.TXT - a list of the pictures contained in the solution

  • Will be used if PICTLISTX.TXT and PICTLISTRX.TXT do not exist.

• BIGLIST.TXT - a list of all the bigmaps that have been created

• INIT_LITHOS.TXT - file containing default values to be read in by SPC toolkit

Output Files

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

Optional Files

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

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

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

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

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

Using lithos

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

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

• ... MAIN MENU ...

• Q. Quit LITHOS
• LANDMARK/MAPLET CONSTRUCTION

• 0. Find template

• 1. Align landmarks

• 2. Find heights

• O. Attach map to maps or limbs

• LANDMARK/MAPLET I/O AND CREATION

• I. Input landmark

• U. Update landmark files

• C. Create new landmark

• R. Replicate or Rename landmark

• S. Change scale, qsz or orientation

• G. Turn on rename

• ADJUST INPUT DATA AND NOMINALS

• N. Find normal

• V. Find V, Z or PTG

• A. Reset albedo or slopes

• M. Get heights from shape model

• B. Get heights from surrounding map

• X. Turn on extract filter

• DELETE, ELIMINATE OR IGNORE FILES

• D. Delete or Disconnect landmark

• E. Eliminate pictures from landmark

• P. Picture status

• L. Turn off picture restriction

• INFORMATION AND DISPLAY

• F. Find maplets containing surface point

• Z. Use zoom display

• H. Hide screen output

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

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

 gc LMRK_DISPLAY0.pgm
 gc LMRK_DISPLAY1.pgm


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

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

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

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

Description

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

Required Files

• LIMBLIST1.TXT - List of images that show limbs.

• LMRKLIST.TXT - List of landmarks.

Output Files

• LIST.TXT -

Using make_list

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

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

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

Additional Reference

[From make_list.f]

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

(Compiled by JW)

CategoryPrograms

make_lmrklistX

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

(Compiled by DL)

CategoryPrograms

make_scriptAP

Description

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

Required Files

input file:

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

seed file:

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

processed files:

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

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

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

Output Files

make_scriptAP outputs:

• run.sh - Controlling run script for batch image auto registration using parallel processing.
  • run script for each core processor:
    • run_script01.b
    • run_script02.b
    • etc..

• .INN files - autoregisterP seed file for each image.

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

run_scriptnn.b output:

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

processed files outputs:

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

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

• LMKFILES/ - Image names are added to the LMKFILES.

User Warnings

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

Using make_scriptAP

1. Create Input Files

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

 P00045000450
 P00045000451
 P00045000452
END

• You must precede each image filename with a space.

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

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

2. Run make_scriptAP

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

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

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

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

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

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

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

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

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

4. Clean Working Directory

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

Here is a sample rem_script.b file:

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

(Compiled by DL)

CategoryPrograms

make_scriptF

Description

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

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

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

• You should test the command sequence in lithos before running the script generated by make_scriptF.

Required Files

input file:

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

seed file:

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

processed files:

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

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

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

Output Files

make_scriptF outputs:

• run_script.b - Run script for batch processing.

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

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

run_script.b outputs:

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

processed files outputs:

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

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

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

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

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

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

User Warnings

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

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

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

Using make_scriptF

1. Create Input Files

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

EE0001
EE0002
EE0003
END

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

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

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

Start Commands

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

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

 Check for more images? y[n]
y

 Enter fractional width (0=center).
.5

 Reject invisibles? y[n]
n

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

End Command

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

End-Of-File Identifier

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

Comments

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

2. Run make_scriptF

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

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

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

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

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

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

3. Execute the Run Script

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

sh run_script.b

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

nohup sh run_script.b &

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

4. Quality Check the New Maplets

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

5. Clean Working Directory

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

Here is a sample rem_script.b file:

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

(Compiled by DL)

CategoryPrograms

make_scriptR

Description

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

Required Files

input file:

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

seed file:

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

processed files:

• TESTFILES/ - Directory in which to store copies of LMRK_DISPLAY.pgm (output by register) for each image.

  register requires a number of directories and files. Refer to register for more information.

Output Files

make_scriptR outputs:

• run_script.b - Run script for batch image registration.

• .INN files - register seed file for each image.

run_script.b output:

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

processed files outputs:

• TESTFILES/ - A copy of LMRK_DISPLAY.pgm (output by register) is saved for each image.

• NOMINALS/ - If the seed file includes the option to update the NOMINAL file, starting S/C and camera information will be updated. (This option is not typically selected).

• SUMFILES/ - S/C and camera information are updated as image shifts are made.

Using make_scriptR

1. Create Input Files

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

 P3T11S2H0409
 P3T11S2H0410
 P3T11S2H0411
END

• You must precede each image filename with a space.

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

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

2. Run make_scriptR

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

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

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

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

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

3. Batch Register Images

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

sh run_script.b

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

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

(Compiled by DL)

CategoryPrograms

make_scriptT

Description

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

Required Files

input file:

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

seed file:

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

processed file:

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

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

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

Output Files

make_scriptT outputs:

• run_script.b - Run script for maplet creation.

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

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

run_script.b output:

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

PROCESSED FILES OUTPUTS:

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

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

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

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

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

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

User Warnings

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

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

Using make_scriptT

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

1. Create Input Files

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

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

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

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

...

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

2. Run make_scriptT

make_scriptT generates a .INN file for each new maplet.

Here is a sample .INN file for maplet 001:

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

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

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

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

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

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

3. Tile Bigmap with New Maplets

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

sh run_script.b

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

nohup sh run_script.b &

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

4. Quality Check New Maplets

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

5. Clean Working Directory

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

Here is a sample rem_script.b file:

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

(Compiled by DL) CategoryPrograms

make_tilefile

Description

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

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

Required Files

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

Output Files

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

Using make_tilefile

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

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

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

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

Here are two samples showing each of these responses:

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

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

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

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

echo "N" | make_tilefile > out

• Use a text editor to discard the first line of output before you append it to the make_scriptT.in. See make_scriptT.in for additional details.

  make_tilefile is set to make the pixel and line coordinates in intervals of 50 because maplets have a 99 by 99 pixel dimension. This means that the center will always be at the (50,50) coordinate with respect to a maplet. Thus, when a maplet is made at the same resolution as the bigmap, the maplet center coordinates will be multiples of 50.

(Compiled by DL)

CategoryPrograms