autoregister
Category B |
Version 3.0 |
Description
This program is used to register existing maplets with imaging data from a single image.
autoregister
- adds landmarks to a single image, adding the image name to all relevant LMKFILEs and adding the landmark names to the SUMFILE
- provides basic tools for aligning the landmarks, cross-correlating new images to existing maplets, eliminating landmarks and setting image flags
- updates the S/C position and pointing in the SUMFILE when the user accepts the changes from the auto-align (or manually aligns)
autoregister aligns existing maplets with imaging data from a single image and uses subroutine IPL2SCOBJPTG to update the camera pointing and spacecraft-object vector in the corresponding SUMFILE.
autoregister is similar to register, but it can handle 3 degrees of freedom, orientation, and twist.
![/!\](/wiki/classic/img/alert.png "/!\")
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.00Enter the image name that is stored in IMAGEFILES.
Some versions of process_fits will make some changes to the filename, so it may not be the "original name". - The program produces a list of existing landmarks, if any, creates the TEMPFILE.pgm and displays the kb and kk values.
- kb and kk are de-bugging flags relating to the generation of TEMPFILE.pgm and are not discussed here.
- Enter 'q' as the image name to quit.
If you wish to add more landmarks, enter 'y'. An initial filter for added images is set in INIT_LITHOS.TXT:
RESLM - the maximum ratio of the image resolution to the maplet scale
SIZLM - the maximum ratio of the linear maplet size to the image size
NUMLM - sets the minimum number of maplets found in the image before the other two filters come into play
Input the value for Fractional width. Normally this is '0.5'. This value allows images that overlap any part of a window that is half the size of the maplet window.
If you enter '0.0', the image must contain the landmark center. Typically, enter 'n' for Reject invisibles? unless the object is bizarre, such as Eros.
If you respond 'y', the program uses the current shape to determine whether there is topography blocking the camera's view of the landmark center. - Responding 'y' is very restrictive in that it will discard landmarks whose maps are only partially occulted. It is also very time consuming.
- For convex bodies such as Eros or 67P Churyumov-Gerasimenko another solution is to respond 'n' but set the INVLM value not to 0.0 as is the usual input but a higher number, e.g. 100, so it will keep landmarks whose maps are 10% occulted.
When landmarks are added in autoregister, they immediately populate the image’s SUMFILE. Further processing must be conducted if you wish to remove the image from any of the landmarks. This is different from lithos where images are not added to landmarks until the landmark file is updated.
autoregister will generate a bitmap formatted file called TEMPFILE.pgm, as shown below. This has two images for each landmark. The top image is a subsection of the real images that is the landmark, but orthorectifed. The lower image is the shape model illuminated in the same conditions as the real image. The alignment between these features must be as accurate as possible (at least one pixel). The file will get updated each time the program prints out the Main Menu.
After you respond to these initial inputs, the Main Menu will open.
autoregister Main Menu
... MAIN MENU ... 0. Exit REMOVE MAPLETS a. Auto remove n. Auto remove new only m. Manual remove p. Check peripheral visibility o. Remove low-correlation lmks IMAGE/MAPLET ALIGNMENT 1. Auto align 2. Manual align LANDMARK ADJUSTMENTS 3. Repredict px/ln 4. Change flags l. Change repredict limit
Enter '0' to exit the processing of the current image and choose a new one.
Enter 'q' for the image name to quit the process altogether.
REMOVE MAPLETS Options
The first block of options removes landmarks according to a variety of filters. If you choose a, n, m or p, you will see a table with these column headers:
# - landmark number
LMKNM - landmark name
EMISS - emission angle
COV - maplet-image overlap
RES - image resolution/maplet scale
INV - 1000 x invisible fraction of maplet
#PIC - number of images in maplet
Options a and n remove landmarks according to one of these filters:
INVLIM - maximum fraction (in thousandths) of invisible points in the maplet according to the current topography. For example, an obliquely viewed maplet may have part of a crater bottom that can't be seen. An INVLIM of 27 represents 2.7%.
SLIM - maximum emission angle.
CLIM - coverage limit. Minimum fraction of maplet covered by illuminated image data.
RSMN - Minimum allowed ratio of image resolution (km/px) to maplet scale.
RSMX - Maximum allowed ratio of image resolution (km/px) to maplet scale.
Option a - Filters all landmarks. Option n filters only newly added ones. A display provided for the a and n options shows the number of images with resolutions from 0 to 3 times the maplet scale (column labels 00 - 30) and emission angles from 00 to 90 (rows).
Option m- Allows you to manually remove a list of landmarks. Type a list of images with a return after each one. At the end of the list, you must type 0 to finish the input. You can also remove a consecutive group of landmarks by typing start, end then a 0 on a new line. For example 2,10 will remove landmarks 2 through 10.
Option p - Removes images in the part of the maplet obscured by another part of the body.
Option o - Eliminates images whose correlation with the illuminated maplet is less than a specified value. Acceptable values are between 0 and 1.0.
- You must run Option 1. Auto align first to establish those correlation values.
IMAGE/MAPLET ALIGNMENT Options
This block of options aligns extracted imaging data with the corresponding illuminated maplets. The EXTRACT_DATA subroutines populate the landmark displays with image data projected onto the current maplet surface. We assume the maplet surfaces are correctly placed and oriented and have the correct topography. If the spacecraft position and camera pointing were correct at the image exposure time, then all maplets would align. If not all the maplets align, then the amount of misalignment can be used to correct the spacecraft state. This process performs the alignment, updating the pixel/line image-space landmark positions from their predicted values.
All windows in autoregister are 99x99 pixels. If a maplet has QSZ < 49, as sometimes happens very early in the SPC process, then there will be dark space surrounding it. If QSZ > 49, then only the central portion of the maplet will be aligned. QSZ is standard notation for the size of the Maplet. The overall width is 2*QSZ+1 in pixels.
Option 1. Auto align - Requires you to respond to several prompts. Here is a sample:
1
1 EE0001
2 EE0002
3 EE0003
4 EE0004
5 EE0005
6 EE0006
7 EE0007
8 EE0008
9 EE0009
10 EE0010
11 EE0011
12 EE0012
13 EE0013
14 EE0014
15 EE0015
16 EE0016
enter 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
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.
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)
autoregisterP
Category B |
Version 3.0 |
Description
This program registers existing maplets with imaging data from a single image using parallel processing (sequential image processing on a number of core processors).
Like autoregister, autoregisterP
- adds landmarks to a single image, adding the image name to all relevant LMKFILEs
- provides basic tools for aligning the landmarks, cross-correlating new images to existing maplets, eliminating landmarks and setting image flags
- updates the S/C position and pointing in the SUMFILE
autoregisterP is similar to register, but can handle 3 degrees of freedom, orientation, and twist.
autoregisterP is almost always run in a parallel batch mode, following a script set up by make_scriptAP. It uses lockout files to prevent two processes from reading or writing to a landmark file at the same time.
autoregisterP aligns existing maplets with imaging data from a single image and uses subroutine IPL2SCOBJPTG to update the camera pointing and spacecraft-object vector in the corresponding SUMFILE.
- autoregisterP uses the file LMRKLISTX.TXT to prescreen the maplets. If you have added or deleted maplets recently, you should run make_lmrklistX.
Required Files
IMAGEFILES/ - a directory containing the image .DAT files
SUMFILES/ - a directory containing the image .SUM files (updated solution image, S/C and camera information, lmrks and limbs)
MAPFILES/ - a directory containing the full suite of maplets
LMKFILES/ - a directory containing the full suite of landmarks
LMRKLIST.TXT - a list of the landmarks contained in the solution
LMRKLISTX.TXT - landmark information (size, scale, position vector, number of images containing the lmrk)
Optional Files
make_scriptA.seed - for batch processing using make_scriptAP
Output Files
SUMFILES/ - Landmarks are added to the image's SUMFILE. Spacecraft/camera position/attitude are updated once you accept the alignment shifts.
LMKFILES/ - LMKFILES are updated to contain the image you are working with.
LMRK_DISPLAY1.pgm - - 100x100 pixel display of images (odd rows) and maplets (even rows). Unlike lithos, each pair is a separate landmark consisting of a completely different location on the surface and image.
- TEMPFILE.pgm - A pgm image of the image that you are working with.
User Warnings
- autoregisterP uses the file LMRKLISTX.TXT to prescreen the maplets. If you have added or deleted maplets recently, you should run make_lmrklistX. When landmarks are added in autoregisterP, they immediately populate the image’s SUMFILE. Further processing must be conducted if you wish to remove the image from any of the landmarks. This is different from lithos where images are not added to landmarks until the landmark file is updated. Alignment changes are immediately accepted (i.e., there is no save/revert option). Some Main Menu options are only available in interactive mode and are therefore not used when running autoregisterP.
Using autoregisterP
Initial Inputs
The following shows the initial inputs necessary to get to the Main Menu:
input 12-character picture name. q to quit.
P3T11S2H0409
1 EE0001 *
2 EE0002 *
3 EE0003 *
4 EE0004 *
5 EE0005 *
6 EE0006 *
gc TEMPFILE.pgm
kb = 1 kk = 1
Add landmarks? (y/n)
y
enter fractional width (0=center)
.5
Reject invisibles? (y/n)
n
7 EE0007 0.00
8 EE0008 0.00
9 EE0009 0.00
10 EE0010 0.00
11 EE0011 0.00
12 EE0012 0.00
13 EE0013 0.00
14 EE0014 0.00
15 EE0015 0.00
16 EE0016 0.00- Enter a 2-character USR name to distinguish between processes.
- Enter the 12-character picture name. The program produces a list of existing landmarks, if any, creates the TEMPFILE.pgm and displays the kb, and kk values.
If you wish to add more landmarks, respond 'y'. An initial filter for added images is set in INIT_LITHOS.TXT:
RESLM - the maximum ratio of the image resolution to the maplet scale
SIZLM - the maximum ratio of the linear maplet size to the image size
NUMLM - sets the minimum number of maplets found in the image before the other two filters come into play
Input the value for Fractional width. Normally this is '0.5'. This value allows images that overlap any part of a window that is half the size of the maplet window.
- If you enter '0.0', the image must contain the landmark center.
Typically, enter 'n' for Reject invisibles? unless the object is bizarre, such as Eros.
- If you respond 'y', the program uses the current shape to determine whether there is topography blocking the camera's view of the landmark center. When landmarks are added in autoregisterP, they immediately populate the image’s SUMFILE. Further processing must be conducted if you wish to remove the image from any of the landmarks. This is different from lithos where images are not added to landmarks until the landmark file is updated.
After you respond to these initial inputs, the Main Menu will open.
autoregisterP Main Menu
... MAIN MENU ... 0. Exit REMOVE MAPLETS a. Auto remove n. Auto remove new only m. Manual remove <- only in interactive mode p. Check peripheral visibility o. Remove low-correlation lmks IMAGE/MAPLET ALIGNMENT 1. Auto align 2. Manual align <- only in interactive mode LANDMARK ADJUSTMENTS 3. Repredict px/ln 4. Change flags l. Change repredict limit <- only in interactive mode
autoregisterP is otherwise identical to autoregister. Refer to autoregister for detailed information and samples.
- Some Main Menu options are only available in interactive mode and are therefore not used when running autoregisterP.
(Compiled by DL)
Based on SPOC v3.02A PDF/LITHOSPHERE/AUTOREGISTERP.f File Reference
bigmap
Category B |
Version 3.0 |
Description
This procedure creates a large topographical/albedo map with the same file structure as a maplet.
The location of the map center is specified by one of three choices:
p - pixel/line location in a picture
l - latitude and west longitude
m - pixel line location in a bigmap or maplet
A second set of inputs contains:
- the bigmap scale in km/px
- the half-size (qsz)
- an integer random seed
- a maximum maplet scale in case lower resolution maplets are to be excluded
The program first determines the body-fixed vector to the map center and the approximate surface normal vector (Uz). It then projects the shape model onto this surface and determines a second approximation of Uz by fitting a plane to the heights. It repeats this process one more time. The new map coordinate frame is then oriented so that East is to the right.
The program checks to see if any these files exist:
- BIGMAP.IN
- LMRKLISTR.TXT
- LMRKLIST.TXT
It takes the maplets to be used from the first of these files that it finds.
If you include the line 'LMKLX=.TRUE.' in INIT_LITHOS.TXT, bigmap will read LMRKLISTX.TXT. This will speed up the program by determining which maplets will be used without opening their .LMK files.
The bigmap reference plane has (2*qsz+1)^2 points at locations:
p(i,j) = V + j*Ux +i*Uy (i,j = -qsz,qsz)
A line from each of these points in the normal (Uz) direction will pierce a number of maplets. For each i,j the program keeps track of:
- the weighted accumulation of the heights to the piercing points
- the squares of those heights
- the slopes and albedos of the maplets at the piercing points
Once these arrays are filled, bigmap computes the average heights and albedos at each point of the reference plane, as well as the standard deviation of the heights. This provides a convenient measure of the height uncertainty at each point. Displaying SIGMAS.pgm provides a quick means of identifying possible problem areas, as depicted in Figure 00.
Required Files
LMKFILES/ - Directory of .LMK files for each maplet.
LMRKLIST.TXT - Required. List of landmarks.
MAPFILES/ - Directory of .MAP files.
SHAPEFILES/ - Directory of built shapes.
BIGFILES/ - Directory of .LMK files for each of the required bigmaps. This directory must be created, but changes are made within.
SUMFILES/ - Info about the maplets.
Many files must be unique. All directories can be linked to a master.
Optional Files
BIGMAP.IN - A list of landmarks that you want to use for bigmap. This file allows you to reduce the number of files and avoid low resolution maps.
LMRKLIST.TXT - This also restricts the list of LANDMARKS, but this is used by more programs than just BIGMAP.
If neither of these files exists, the program will build the list of LANDMARKS based on the coverage.
Output Files
INSIDE.TXT - The maplets that fall completely within the planned bigmap. Created by bigmap.
USED_MAPS.TXT - All the maps used to create the bigmap.
BIGLIST.TXT - List of needed mapfiles (bigmaps) used to construct the working bigmap.
USED_PICS.TXT - List of all pictures used in the creation of most recent bigmap.
- bigmap - The name is based on the input (e.g., ZN0208.IN).
- slope.pgm - Image that shows the slope in both horizontal and vertical. This is useful for debugging and to provide a general idea of how the landmark is developing.
SIGMAS.TXT - Each time BIGMAP is run, it adds a line to this file showing the current sigma values.
- SIGMAS.pgm - Graphically shows the highest level of error (sigma) for maplets (see Figure 00).
Using bigmap
The input for bigmap consists of a long set of commands that are usually contained within a file.
- Longitude is in west longitude. You must use a negative to match what is used in spheremapB. The location of bigmap depends on your server. The default location is /usr/local/bin
Here is a sample input for bigmap:
~/bin/bigmap < ZN0208.IN
The following sample shows the normal format for the input file with some explanatory comments.
l (select location, 1 is lat/lon)
20 -40 (latitude, west longitude)
0.06250 500 1.23400 1000 (scale, qsz (number of pixels), seed, max maplet res)
ZN0208 (filename)
1 (end or integrate, 1 is integrate) <--- here begins the slope to heights integration
.005 (input fraction) <--- fraction of points as seed heights in slope to height integration
.025 (input weight)
1 (end, continue, or change weight, 1 is continue integrating)
1 (end, continue, or change weight, 1 is continue integrating)
1 (end, continue, or change weight, 1 is continue integrating)
1 (end, continue, or change weight, 1 is continue integrating)
1 (end, continue, or change weight, 1 is continue integrating)
1 (end, continue, or change weight, 1 is continue integrating)
1 (end, continue, or change weight, 1 is continue integrating)
0 (end, continue, or change weight, 0 is end iteration)
0 (no, square, or round template, 0 is No Template)Here is a sample of sigmas.pgm:
Figure 00: Output of SIGMAS Graphical Format
(Compiled by TC)
bigmapL
Category B |
Version 3.0 |
Description
This program is a "light" version of bigmap. It's designed to be run in parallel to make many bigmaps at once with the script maker MAKE_TILESP.
bigmapL is primarily used in the production of ZMAPS. ZMAPS is just a convention used to sub-divide a global surface into 5° bins.
For more detailed information, see bigmap.
(Compiled by TC)
blemishes
Category B |
Version 3.0 |
Description
This program generates BLEMISH files which mask bad pixels in individual or multiple images.
This procedure creates a blemish (.BLM) file for an image that lives in the BLEMISHES subdirectory.
Required Files
- BLEMISHES/ - Directory containing BLEMISH files for individual images and BLEMISH templates for multiple affected images.
IMAGEFILES/ - Directory containing the .DAT file for the image; this program displays the image with masking for user inspection, and reads the Digital Number (DN) of pixels of interest.
SUMFILES/ - Directory containing the SUMFILE for the image to mask; this program reads NPX (number of pixels), and NLN (number of lines);
INIT_LITHOS.TXT - this program reads the parameter BLEMISH (if it exists), which references any existing template for masking bad pixels common to multiple images.
BLEMISHES/TEMPLATENAME.BLM - template BLEMISH file for each INIT_LITHOS BLEMISH entry.
Optional Files
BLEMISH/PICNM.BLM - Existing image BLEMISH file for deletion or editing.
Output Files
- TEMPFILE.pgm - Display of the image with masking applied.
BLEMISHES/PICNAME.BLM - Generated or edited BLEMISH (.BLM) file.
User Warnings
- If the PICNM used to make the original blemish file is not consistent with the template, the program will say so and it will STOP. Otherwise, it will create the template file and, if necessary, remind you to define it in INIT_LITHOS.TXT.
Using blemishes
Initial Inputs
Input 12-character picture name P00045000455 gc TEMPFILE.pgm b. Block s. Spot q. Quit
Choose the option for the type of blemish you want to work with:
The b. Block option masks a square block of the image specified by a minimum and maximum pixel and line. This type of blemish is typically used for missing or hashy lines due to downlink errors.
The s. Spot option masks a small region around a pixel/line center (p,l) from p-k to p+k and l-k to l+k. An additional input is a brightness threshold (Note: See below for threshold information). If you enter this as zero, everything in the spot will be masked. However, if there is a bright blemish such as a cosmic ray hit in the spot, you can set the threshold to remove only the affected pixels. In this case, you can specify a large region (large k) and all the bright blemishes in that region will be masked without affecting the rest of the data.
Here is a sample TEMPFILE.pgm image before masking is applied:
Figure 00: Image Prior to Applying Mask
Block Blemish Options
Input pxmn, pxmx, lnmn, lnmx 512 612 250 350 gc TEMPFILE.pgm b. Block s. Spot q. Quit
After you choose b. Block you must specify:
pxmn, pxmx: must be in the range [1:NPX] (where NPX is the number of pixels in image)
lnmn, lnmx: must be in the range [1:NLN] (where NLN is the number of lines in image)
This sample shows the image after block masking was applied:
Figure 00: Image after Applying Blemish Mask
Spot Blemish Options
Input bad px/ln center, half-size. threshold. 512 250 25 100 gc TEMPFILE.pgm b. Block s. Spot q. Quit
After you choose s. Spot you must specify:
px/ln center: Vector with element values in the range ([1:NPX],[1:NLN]) (where NPX is the number of pixels in image, NLN is the number of lines in image)
half-size: Half-size of masked area in pixels, e.g. a half-size of 2 will result in a masked area of 4 pixels x 4 pixels.
threshold: Digital Number (DN) representing the lowest threshold for brightness in the range, where 0 is dark, and will result in all brightnesses being masked. Note: The DN within BLEMISHES has been rescaled by 255/(Brightness DN). So if the original DN is 398 and the max is 1410, then the new DN will be 71 because the number is truncated. So if you want to mask 398, you need to enter 70 for the threshold.
This sample shows the image with spot masking and DN threshold applied:
Figure 00: Image Displaying Blemish Mask Options
Quit Blemishes Option
Save blemish file? (y/n) y Create/change template file? (y/n) n
After you choose q. Quit you must specify whether to save the blemish file and whether to create or change a template file.
BLEMISH Templates
In the event that a camera has bad pixels common to all images, you can create a template that masks these pixels in all that camera's images. The template is specified in the INIT_LITHOS.TXT file with the key word BLEMISH.
- For example, DAWN has two framing cameras with image names starting with FC1 and FC2. FC2 images all have several blemishes in the same places. A template in INIT_LITHOS specified by BLEMISH='FC2#########' will correct all of these images without having thousands of individual blemish files. If an image contains additional blemishes it can have its own file with just those additional blemishes.
In order to create a TEMPLATE, you must create a blemish file for one of the affected images with only the common bad areas masked. The procedure will ask: 'Save blemish file? (y/n)' and then 'Create/change template file? (y/n)'. If you enter 'y' and 'y', you will be asked for a 12 character template name with the common characters of the image names in their proper positions and # everywhere else.
- If the PICNM used to make the original blemish file is not consistent with the template, the program will say so and it will STOP. Otherwise, it will create the template file and, if necessary, remind you to define it in INIT_LITHOS.TXT.
The following samples show this sequence of actions and the output file:
Save blemish file? (y/n) y Create/change template file? (y/n) y Input 12 character template P00045###### Add: BLEMISH='P00045######' to INIT_LITHOS.TXT
Example P00045######.BLM file:
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.
densify
Category B |
Version 3.0 |
Description
This program is used to increase the resolution of a shape model by interpolating heights between landmarks.
densify first constructs a reference surface by interpolating the surface points of a lower resolution shape model. At each point of the reference, there is a vector V0 from the model center to that point and a normal N0 to the surface. That normal is extended some distance until it pierces one or more of the ensemble of maplets, and the average A of those distances is taken to represent the piercing point on the new model's surface. The new surface vector is V = V0 + A*N0.
The picture below is a visual representation of the paragraph above.
___...-------...___ maplet
| |
| |A*N0
______|___________|_________ reference
\ /
\ / V0
\ /The new surface vector V will differ from V0 more noticeably when tiling at lower resolution because there are mismatches in maplet locations simply due to the formal uncertainties of the estimation process. Therefore, we have found it better to average the maplet normals N at each point, keeping a small randomly selected set of the A as conditioning heights.
Required Files
LMRKLIST.TXT - List of all landmarks to be used
LMKFILES/ - Directory of .LMK files for each maplet
MAPFILES/ - Directory of .MAP files
SHAPEFILES/ - Directory of built shapes
Optional Files
LMRKLISTR.TXT - Specific list of landmarks desired
Output Files
SIGMA.TXT - list of sigma values associated with the shape model (found in SHAPEFILES/)
- Shape file in ICQ format
Using densify
Although densify can be run interactively, the input commands are usually prearranged in a file (e.g., "tmpRun.txt") and you invoke the program from the command line like this:
~/bin/densify < tmpRun.txt
Here is an annotated sample "tmpRun.txt" file showing the input commands:
SHAPEFILES/PreviousShapeFile (input shape) 2 100 1.67773 (K (power of 2), search range (km), random seed) SHAPEFILES/CurrentShapeFile (output shape) <--At this point the map-averaged shape at a higher resolution is made 1 (more iteration) <--At this point we begin the slopes to heights integration .005 (fraction of points used for conditioning) <--These are sample heights we select for the slope->heights integration .025 (conditioning weight) 1 (more iterations) <--More slope to heights integration 1 1 1 1 1 1 1 1 1 1 1 1 1 0 (end program)
The input commands are:
line 1 - The input SHAPE file
line 2 - A multiplicative scaling factor K (usually 2), a limit (in km) specifying how far along the surface normal the program should search for a maplet, a random seed in the form of a large integer
- This random seed is superseded if you enter one on the command line after you invoke densify.
line 3 - The output SHAPE file
line 4 - 1 = an iteration
line 5 - The fraction of points used for conditioning (usually .005)
line 6 - The conditioning weight
line 7 ... - 1 = an iteration (as many as you need)
last line - 0 = end program
In most cases, the maplets will cover most of the surface. Where it is not covered, the normals to the input model provide the "slopes" and the integration proceeds without any randomly chosen conditioning heights from these areas.
In some cases, such as fast flybys of small bodies, only a small fraction of the surface is visible and vast areas are unknown. In these cases, conditioning heights are also taken from the input model as well. Specify this option by using a negative value for K (usually -2).
- In this case, use a negative value for K (-2) because, for every location in the shape model for which we don't have map coverage, densify will print on the screen. Setting the value to -2 will block printing to the standard output.
densify then determines the average height along each surface normal from each reference point of the densified shape. It also determines the average maplet surface normal and the standard deviation of the heights, used as a measure of uncertainty. It produces the output SHAPE file and a similar file called SIGMA.TXT that has an extra column representing the uncertainty. SIGMA.TXT can be displayed as an image to show areas that might need further work.
After it completes the commands in the file, densify gives these options:
0. end program
1. proceed to iterationIf 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 programIf 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 weightThe interim shape can be viewed to see whether you want to change the weight given to the conditioning heights using the procedure described below. Usually, you just continue iterating or, finally, exit the program.
By tradition, usually use:
- SHAPE0 for Q=64
- SHAPE1 for Q=128
- SHAPE2 for Q=256
- SHAPE3 for Q=512
If there have been no problems after you complete this run, at the command line enter:
cp SHAPEFILES/SHAPEX.TXT SHAPEFILES/SHAPE2.TXT
After another densification, when SHAPEX.TXT is Q=512, at the command line enter:
cp SHAPEFILES/SHAPEX.TXT SHAPEFILES/SHAPE3.TXT
SHAPE.TXT is also Q=512 and you need to update that as well.
- For historical reasons, some scripts change permissions on SHAPE.TXT to read only.
At the command line enter:
chmod +w SHAPE.TXT
cp SHAPEFILES/SHAPEX.TXT SHAPEFILES/SHAPE.TXT
Interactive
If you want to run densify interactively, the initial inputs are:
- the input SHAPE file
- the output SHAPE file
- scaling factor K (usually 2), limit (in km) , random seed (large integer) This random seed is superseded if you enter one on the command line after you invoke densify.
densify will then prompt you for the remaining inputs and iterations.
(Compiled by TC)
densifyA
Category B |
Version 3.0 |
Description
This program is used to increase the resolution of a shape model using albedo between landmarks.
The spatial resolution of the shape model will not increase. Adding albedo information allows for a better correlation between the shape model and landmark maps, especially when creating new landmarks.
densifyA is identical to densify except that it uses albedo.
densifyA first constructs a reference surface by interpolating the surface points of a lower resolution shape model. At each point of the reference, there is a vector V0 from the model center to that point and a normal N0 to the surface. That normal is extended some distance until it pierces one or more of the ensemble of maplets, and the average A of those distances is taken to represent the piercing point on the new model's surface. The new surface vector is V = V0 + A*N0.
The picture below is a visual representation of the paragraph above.
___...-------...___
| |
| |A*N0
______|___________|_________ reference
\ /
\ / V0
\ /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 iterationIf 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 programIf 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 weightThe 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)
duplicates
Category B |
Version 3.0 |
Description
This program writes an ordered list of unique landmark names to make_script.in, the .in file required by batch processes such as lithosP processing using make_scriptP. It also checks that the landmarks are included in LMRKLIST.TXT, and that LMKFILES and MAPFILES exist for each entry.
The duplicates program serves two functions:
First, some lists of landmarks to be processed may contain duplicate names. The files check.txt and MAPCHK.TXT produced by residuals are examples. duplicates outputs only one of each to the file make_script.in.
Second, in iterating a set of landmarks, it is believed to be more reliable to proceed from lower to higher resolution maplets. Duplicates does this ordering using the Heapsort algorithm (Numerical Recipes, p. 231) as part of the process.
The input file for duplicates is LIST.TXT, which consists of a list of landmark names followed by END as the final record. The output file make_script.in has the same form.
Required Files
LMRKLIST.TXT - Full list of landmarks, appended with 'END'.
- LIST.TXT - Temporary list of the subset of landmarks which the user wishes to process appended with 'END', for sorting and removal of duplicates using this program.
LMKFILES/ - Directory containing all the LMKFILES listed in LMRKLIST.TXT.
MAPFILES/ - Directory containing all the MAPFILES for landmarks listed in LMRKLIST.TXT.
Output Files
make_script.in - the .in file required by script-makers such as make_scriptP for generating the run scripts required for batch processing.
Using duplicates
- Create Input File
Create LIST.TXT, a list of landmark names for the landmarks intended for batch processing, appended with the end-of-file identifier, 'END'. See sample file below.
- Run duplicates
duplicates processes landmark names as follows:
For every landmark listed in LMRKLIST.TXT, duplicates
- checks that the MAPFILE exists
- obtains the maplet's Q-size and Ground Sample Distance (GSD) from the LMKFILE
- sorts the list by decreasing GSD and increasing name (lat/wlong identifier and numeric identifier)
- discards duplicate entries
For every landmark listed in LIST.TXT, duplicates
checks that the landmark is also listed in LMRKLIST.TXT; if it is, the landmark is included in the output
duplicates writes the sub-set of ordered landmarks to make_script.in.
The LANDMARK and MAP files for the landmarks included in LMRKLIST.TXT must exist in LMKFILES/ and MAPFILES/. duplicates only considers landmarks contained in LIST.TXT, that are also contained in LMRKLIST.TXT.
Here is a sample LMRKLIST.TXT file:
EE0001 EE0002 EE0003 EE0004 EE0005 EE0006 EE0007 EE0008 EE0009 EE0010 EF0001 EF0002 EF0003 EF0004 EF0005 EF0006 EF0007 EF0008 EF0009 EF0010 END
Here is a sample LIST.TXT file:
EF0006 EF0006 EF0006 FF0006 EE0004 FF0009 EE0007 EE0010 EE0009 EE0006 EF0010 EF0004 EE0005 EF0005 EF0008 FF0008 EE0008 FF0005 FF0010 EF0009 EF0007 FF0004 FF0007 END
- Note that the sample LIST.TXT contains a disordered list of landmark names and many duplicate entries. Also, the FF* landmarks are not included in the sample LMRKLIST.TXT and the sample LIST.TXT does not include any landmarks ending in 1, 2, or 3. (This scenario is included for illustrative purposes only.)
Here is a sample make_script.in file generated using duplicates:
EE0004 EE0005 EE0006 EE0007 EE0008 EE0009 EE0010 EF0004 EF0005 EF0006 EF0007 EF0008 EF0009 EF0010 END
(Compiled by DL)
dynamics
Category B |
Version 3.0 |
Description
This program augments the nominals file by appending the nominal inertial space position differences between the current image and up to four images before and after. This information is used to constrain the solution so that the spacecraft position solution does not deviate too much from a dynamically realistic state. This program also allows for different mission phases to have different "sigmas" via DYNAMICS.TXT.
In version 3.1, the number of images that is used before/after is set in INIT_LITHOS.TXT with keyword DYNO.
Dynamics will useINIT_LITHOS.TXT to set the parameters for SPICE. This is set with keyword PCK. Typically, we set the leap second kernel and the PCK.
If you want to have these the images before/after impact the location of the spacecraft, then the PICWTS option 5 (WT) must be set to 1 (or a non-zero value) in INIT_LITHOS.TXT
Required Files
Output Files
- Updated NOMINALS file
Using dynamics
Input for the program in DYNAMICS.TXT includes values for 3 parameters and lists of nominals to which they apply. For additional information, see DYNAMICS.TXT.
The following sample is based on excerpts from a DYNAMICS.TXT file for DAWN at Vesta:
FRAME='BOD_FRAME' APPROACH ETLM= 1800, 1.D-6 VSIG= 0.200, 0.200, 0.200 PSIG= 0.0001, 0.0001, 0.0001 F11A0001225 F11A0001241 ... F21A0003895 F21A0003910 FRAME='dxR_FRAME' SURVEY ETLM= 1800, 1.D-6 VSIG= 0.100, 0.100, 0.040 PSIG= 0.0001, 0.0001, 0.0001 F21A0003931 F21A0003932 ... F21A0032347 F21A0032348 END
A typical ETLIM= record is:
ETLM= 1800, 1.D-6
ETLIM= gives a maximum time difference in seconds that limits the neighboring images to be used. The images that are included in dynamics are limited by both this number, as well as number of images. Dynamics will stop including images when either of these limits are reached. The second number in ETLM is an estimate of the velocity uncertainty that goes into an uncertainty estimate included in the added records. This velocity uncertainty is used to determine the sigma in position associated with dynamics. A typical value is 1 mm/s; the same as in the example. A larger value will weight the dynamics solution less, while I a smaller value will weight the dynamics solution more.
FRAME= has these three choices:
FRAME= ['dxR_FRAME', 'Dxr_FRAME', 'BOD_FRAME']
FRAME= specifies how to interpret the sigmas in spacecraft position found in the nominals file.
dxR_FRAME uses the radial direction (R) as prime for the third component with the second component being the cross track direction (X) and the first component, roughly in the downtrack direction completing the right-handed coordinate system. This is used in orbital operations around large bodies, where the radial component is well known from the Doppler data.
Dxr_FRAME is used during approach where the downtrack velocity is best known. The "radial" (impact parameter) direction is crossed with the downtrack to give the crosstrack direction.
BOD_FRAME simply uses the components in the body-fixed frame, generally with equal uncertainties in each direction.
The VSIG= record has three components:
VSIG= 0.100, 0.100, 0.040
VSIG= allows the user to change the position sigmas from those in the original nominals file. The record in the sample, sets the uncertainties in the three components to 100 m, 100 m and 40 m respectively. If, during another mission phase, these sigmas change, another VSIG= record would be added to affect subsequent nominals files.
The PSIG= record has three components:
PSIG= 0.0003, 0.0003, 0.0005
PSIG= allows the user to change the pointing sigmas in the nominal files, which are in rad. The three components refer to rotations about the three camera axes. The sample shows the approximate values expected for OSIRIS_REx with a larger twist uncertainty since there is only one star tracker.
(Compiled by TC)
Export and Import
Category B |
Version 3.0 |
These two programs will allow you to export landmarks from multiple machines, which can then be added to another machine. Instead of merging two or more datasets, you can achieve a similar result by adding all landmarks to a "main" or "head" machine.
While this is useful for combining data from multiple users, it was originally intended to allow a user to tile an object/bigmap simultaneously on multiple machines and then combine the results onto a single machine. Hence it uses LMRKLIST1.TXT, which is a list of newly added landmarks.
User Warnings
- You must ensure that LMRKLIST1.TXT only has the recently created landmarks (i.e., contains only the LMKs you wish to export and import into a new model). If LMRKLIST1.TXT has other LMKs you don't wish to bring into a different model, remove them from the top of the LMRKLIST1.TXT. You should also ensure that there aren't any maplets or landmarks remaining in NEW_FILES. If NEW_FILES does not exist, you must create NEW_FILES, as well as NEW_FILES/LMKFILES and NEW_FILES/MAPFILES. The imported landmarks will be renamed based upon region! This renaming procedure ensures that no existing landmarks will be overwritten. It also means you may end up with duplicate landmarks if you didn't make sure to exclude them when you created LMRKLIST1.TXT.
Export
Required Files
MAPFILES/ - a directory containing the full suite of maplets
LMKFILES/ - a directory containing the full suite of landmarks
LMRKLIST1.TXT - a list of the new landmarks
Output Files
- EXPORT.TXT - Script that will execute the EXPORT.B script and clean up the previous version of NEW_FILES
- EXPORT.B - Script that will cp new maplet and landmark files to NEW_FILE
Using Export
To run export, you must generate a script that will copy the new landmarks and put them into a tar ball.
- Make EXPORT.B and the script EXPORT.TXT. Note that EXPORT.TXT will run the script EXPORT.B. You must ensure that LMRKLIST1.TXT only has the recently created landmarks. If it has older ones, trim the top of the file. You should also ensure that there aren't any maplets or landmarks remaining in NEW_FILES. If NEW_FILES does not exist, you must create NEW_FILES, as well as NEW_FILES/LMKFILES and NEW_FILES/MAPFILES.
- Enter the following at the command line:
mkdir -p NEW_FILES mkdir -p NEW_FILES/LMKFILES mkdir -p NEW_FILES/MAPFILES /usr/local/bin/EXPORT
This will populate NEW_FILES with copies of the newly created mapfiles and landmarks.
The script EXPORT.TXT looks this:
cp LMRKLIST1.TXT NEW_FILES/LMRKLIST.TXT cd NEW_FILES/LMKFILES rm -f *.LMK cd ../.. cd NEW_FILES/MAPFILES rm -f *.MAP cd ../.. chmod +x EXPORT.b ./EXPORT.b tar -cf NEW_FILES.tar NEW_FILES rm -f LMRKLIST1.TXT
- Run this script by entering the following at the command line:
sh EXPORT.TXT
- Change the name of NEW_FILES.tar to something distinctive like
new_<bigmapName>.tar
- Transfer the tar file to the other computer.
Import
Required Files
- NEW_FILES/LMRKLIST.TXT - List of new landmarks
- NEW_FILES/MAPILES/ - a directory containing the new maplets
- NEW_FILES/LMKFILES/ - a directory containing the new landmarks
Output Files
MAPFILES/ - a directory containing the full suite of maplets
LMKFILES/ - a directory containing the full suite of landmarks
LMRKLIST.TXT - updated landmark list
- NEWLIST.TXT - list of new landmarks with the new name
Using Import
1. Untar to recover NEW_FILES directory.
- If you didn't rename the tar file, from the working directory type the following at the command line:
tar -xvf NEW_FILES.TAR
- This will create the directory NEW_FILE if it doesn't already exist. If you are concerned about overwriting data in the current directory, use "tar" to check the location the data will be written to.
2. Once you have confirmed that you will be writing to an empty directory, type the following at the command line of the working directory:
/usr/local/bin/IMPORT
- This will import the new landmarks. The imported landmarks will be renamed based upon region! This renaming procedure ensures that no existing landmarks will be overwritten. It also means you may end up with duplicate landmarks if you didn't make sure to exclude them when you created LMRKLIST1.TXT.
3. Import will update and move all the files to be integrated into the SPC working directory. However, it needs an iteration to run the renaming portion and connect the overlaps with the existing maplets.
cp NEWLIST.TXT make_script.in
For make_scriptF.seed use:
n n g u 1 o RECENT n 1 q END
Copy into window:
./rem_script.b rm -f ./TESTFILES/* rm -f ./TESTFILES1/* make_scriptF sh ./run_script.b &
Check progress with:
find_nofit
(Modified by JRW from text written by EEP)
find_nofit
Category B |
Version 3.0 |
Description
This program searches batch processing output files to identify landmarks or images which may need further work.
find_nofit is a useful utility for identifying landmarks which may require further work following batch processing tasks such as those that use make_scriptF or make_scriptR.
Required Files
make_script.in - input file for batch processes such as make_scriptF, make_scriptR, make_scriptA or make_scriptAP.
- Either:
<LMRKNM>.OOT files - output by a batch process such as make_scriptF.
- Or:
<PICNM>.OOT files - output by a batch process such as make_scriptR, make_scriptA or make_scriptAP.
Output Files
Either:
redo.txt - list of landmarks that
- terminated in error
- do not correlate with at least one image, OR
- correlate weakly with at least one image
Or:
REMOVED.TXT - list of landmarks that have been eliminated from at least one image due to low or no correlation.
Using find_nofit
The batch processes initiated by make_scriptF, make_scriptR, make_scriptA and make_scriptAP produce output files <LMKNM>.OOT or <PICNM>.OOT. These are basically listings of the outputs of procedures lithos, register, autoregister and autoregisterP respectively for each input landmark or image. find_nofit looks through these output files for each landmark or picture listed in the make_script.in file to identify landmarks or images that may need further work.
For lithos
If the entries in the make_script.in file are landmarks (make_script.in for lithos runs), the find_nofit procedure identifies:
! cat <LMKNM>.OOT - process still running or terminated in error. * cat <LMKNM>.OOT - maplets not correlating with at least one image. + cat <LMKNM>.OOT - maplets correlating weakly with at least one image. . cat <LMKNM>.OOT - no correlation for at least one overlap. cat <LMKNM>.OOT - low correlation for at least one overlap.
The cat <LMKNM>.OOT produces a listing of the output file for more complete diagnostics. The program also produces a redo.txt file listing those landmarks that failed one of the first three tests. The limit for weak correlation is set by the 'NOFIT=' keyword in INIT_LITHOS.TXT.
For register
If the entries in the make_script.in file are images (make_script.in for register, autoregister and autoregisterP runs), the find_nofit procedure identifies:
. cat <PICNM>.OOT image not correlating with at least one maplet.
The cat <PICNM>.OOT will produce a listing of the output file for more complete diagnostics. The program also produces a REMOVED.TXT file listing those landmarks that were eliminated from one of the images for low or no correlation.
Here is an annotated sample output from find_nofit:
* cat EE0017.OOT <- maplets not correlating with at least one image cat EE0019.OOT <- low correlation for at least one overlap cat EE0022.OOT . cat EE0027.OOT <- no correlation for at least one overlap + cat EE0034.OOT <- maplets correlating weakly with at least one image * cat EE0042.OOT * cat EE0044.OOT + cat EE0045.OOT ! cat EE0051.OOT <- process still running or terminated in error ! cat EE0053.OOT + cat EE0054.OOT cat EE0055.OOT ! cat EE0063.OOT cat EE0067.OOT cat EE0069.OOT cat EE0081.OOT
Here is an annotated sample redo.txt file from find_nofit:
* EE0017 <- maplets not correlating with at least one image + EE0034 <- maplets correlating weakly with at least one image * EE0042 * EE0044 + EE0045 EE0051 <- process still running or terminated in error EE0053 + EE0054 EE0063 END
Here is an annotated sample REMOVED.TXT file from find_nofit:
AA0001 <- maplet eliminated from an image for low or no correlation AF0023
(Compiled by DL)
find_nofitP
Category B |
Version 3.0 |
Description
This program searches batch processing output files to identify landmarks or images which may need further work.
find_nofitP is a useful utility for identifying landmarks which may require further work following the batch iteration task set up using make_scriptP.
Required Files
make_script.in - input file for batch processing using make_scriptP
<LMKNM>.OOT files - lithosP standard output listings
Output Files
redo.txt - list of landmarks that
- terminated in error
- do not correlate with at least one image, OR
- correlate weakly with at least one image.
Using find_nofitP
The batch process initiated by make_scriptP produces output file <LMKNM>.OOT that contains listings of the lithosP standard outputs for each input landmark. find_nofitP searches the <LMKNM>.OOT files for each landmark listed in make_script.in to identify landmarks which may need further work.
- See find_nofit to identify the flags thrown by find_nofitP.
The command 'cat <LMKNM>.OOT' provides a listing of the output file for more complete diagnostics. find_nofitP also produces a redo.txt file that lists those landmarks that failed one of the first three tests.
The limit for weak correlation is set by the 'NOFIT=' keyword in INIT_LITHOS.TXT. The limit for weak correlation is fixed by the display from the CORRELATE subroutine in LITHOSP at either
0.43 (~3/7) if NOFIT>0.35, OR
- 0.28 (~2/7) otherwise
Here is an annotated sample output from find_nofitP:
! cat EE0004.OOT <- process still running or terminated in error cat EE0005.OOT <- low correlation for at least one overlap . cat EE0006.OOT <- no correlation for at least one overlap cat EE0007.OOT * cat EE0008.OOT <- maplets not correlating with at least one image * cat EE0009.OOT . cat EE0010.OOT * cat EE0011.OOT cat EE0013.OOT cat EE0017.OOT ! cat EE0022.OOT
Here is an annotated sample redo.txt file from find_nofitP:
EE0004 <- process still running or terminated in error * EE0008 <- maplets not correlating with at least one image * EE0009 * EE0011 EE0022 END
Compiled by KD CategoryPrograms
find_nofitT
Category B |
Version 3.0 |
Description
This program searches batch processing output files to identify landmarks or images which may need further work.
find_nofitT is a useful utility for identifying landmarks which may require further work following the batch tiling task set up using make_scriptT.
Required Files
<NNN>.OOT files - lithos standard output listings
Output Files
NEW_LIST.TXT - List of new landmarks generated during the tiling process.
Using find_nofitT
The batch process initiated by make_scriptT produces output file <NNN>.OOT that contains listings of the outputs of procedure lithos for each created landmark during a tiling run. find_nofitT looks through these output files to find places where the landmarks or images may need further work. During tiling, each new landmark is given a 6-character name <LMKNM>. The original landmark designation is a three-digit number <NNN>.
The find_nofitT procedure identifies:
<NNN> ! cat <NNN>.OOT: process still running or terminated in error. <NNN> deleted: insufficient data to create a maplet at that point. <LMKNM> * cat <NNN>.OOT: maplet correlating weakly or not at all with at least one image. <LMKNM> cat <NNN>.OOT: low or no correlation for at least one overlap.
The command 'cat <NNN>.OOT' provides a listing of the output file for more complete diagnostics. The surviving landmark names are included at the beginning of the output to make re-processing easier.
The limit for weak correlation is set by the 'NOFIT=' keyword in INIT_LITHOS.TXT.
Here is an annotated sample output from find_nofitT:
EQ0004: cat 004.OOT <- low or no correlation for at least one overlap EP0002: cat 005.OOT EP0003: cat 006.OOT EO0003: cat 007.OOT EN0003: * cat 008.OOT <- maplet correlating weakly or not at all with at least one image EN0004: * cat 009.OOT 010 deleted ! cat 010.OOT <- insufficient data to create a maplet at that point EM0003: cat 011.OOT EM0004: * cat 012.OOT
Here is a sample NEW_LIST.TXT from find_nofitT:
EP0001 EP0002 EP0003 EP0004 EQ0001 EQ0002 EQ0003 EQ0004 END
(Compiled by KD)
geometry
Category B |
Version 3.0 |
BACK UP YOUR WORK BEFORE RUNNING GEOMETRY!
Description
This program makes a surface by solving for the spacecraft position, spacecraft pointing, and landmark locations. This procedure iterates the solutions for camera pointing and landmark vectors sequentially.
Required Files
LMKFILES/ - A directory containing the full suite of landmarks.
PICTLIST.TXT - A list of picture names generated by make_sumfiles.
LMRKLIST.TXT - A list of the landmarks contained in the solution.
LMRKLIST1.TXT - A file containing default values to be read in by SPC toolkit.
MAPFILES/ - A directory containing the full suite of maplets.
INIT_LITHOS.TXT - A text file setting limits, definitions, and logicals for SPC.
SHAPE.TXT - The shape model stored in directory SHAPEFILES/.
NOMINALS/ - A directory containing the image .NOM files.
SUMFILES/ - A directory containing the image .SUM files (updated solution image, S/C and camera information; lmrks and limbs).
Output Files
SUMFILES/ - Landmarks are added to the image's SUMFILE. Spacecraft/camera position/attitude are updated upon user acceptance of alignment shifts.
LMKFILES/ - Directory LMKFILES/ is updated to contain the image the user is working with.
MAPFILES/ - This directory is also updated because the landmark vector in the header of the MAPFILE is also updated
Optional Files
PICTLISTS.TXT - User-generated list of picture names.
geometry will only use this file instead of PICTLIST.TXT if you specify it in INIT_LITHOS.TXT with GEOPIC='PICTLISTS.TXT'. LMRKLISTR.TXT - User-generated restricted list of landmark names.
geometry will only use this file instead of LMRKLIST.TXT if you specify it in INIT_LITHOS.TXT with GEOMAP='LMRKLISTR.TXT'.
User Warning
- ALWAYS BACK UP YOUR WORK BEFORE USING GEOMETRY.
Using geometry
The inputs for geometry are:
input operation list - Use these values:
- 1: landmark vectors.
- 2: camera pointing, scobj
- 0: end.
enter number of iterations - Input desired number. use limbs for pointing? (y/n) - Choose whether to use limbs in determining camera pointing. continue? (y/n) - Choose whether to do it all over again.
Here are two annotated samples that show geometry inputs:
GEOMETRY 120<- do 1 followed by 2 30 <- do them 30 times y <- use limbs for pointing n <- stop when done GEOMETRY 20 <- do 2 only 10 <- do it 10 times n <- don't use limbs for pointing n <- stop when done
The default is to do these operations for all landmarks in LMRKLIST.TXT and all images in PICTLIST.TXT.
If INIT_LITHOS.TXT contains a record
GEOPI='filename1' or GEOMAP='filename2'
then the files used are reduced. "filename1" is used instead of PICTLIST.TXT and "filename2" is used instead of LMRKLIST.TXT.
Additional Reference
Geometry Estimation Terms
Spacecraft State - Position and orientation of spacecraft affects size and location of the body in an image. Errors are reflected IN offsets of extracted image data from maplets for all maplets in the image.
Control Point Location - An error in the body-fixed control point location is reflected by offsets of extracted image data for all images containing the maplets.
Rotation - An error in the transformation from inertial to body fixed frames is reflected in time-dependent offsets in extracted image data for all maplets in all images.
Differential Stereo - Errors in the maplet heights relative to the center are reflected by differential shifts of features within the extracted image data in addition to displacements from the maplets themselves.
Figure 00: Examples of Offset and Orientation Errors
More Detailed Description of Geometry
- Global solution for camera position and pointing and body-fixed maplet location.
- Iterative process:
- Weighted least-squares solution of landmarks (control points) based on:
- Position of the landmark relative to the spacecraft
- Relative landmark-to-landmark location
- Limb position
- An initial starting object
- Weighted least-squares solution of camera position and pointing based on landmark location
- Nominal camera pointing
- Nominal camera position
- Limb position
- Position of the landmark relative to the spacecraft
- The observations before and after each observation
- Weighted least-squares solution of landmarks (control points) based on:
The output covariances from one iteration become the input covariances for the next iteration so the schematic for updating sumfiles, and lmkfiles, should include the update of their uncertainties.
The typical use is a series of steps such as 120, and 3 or more iterations. Assume we created some new landmarks. The above steps mean that we first use the a priori position and pointing information to solve for the landmarks. Then, since there is some error in the a priori position and pointing inputs we use the landmarks to solve for position and pointing and so on until the corrections have converged, typically 3 iterations. However, if we are in a situation where we believe that the landmarks are correct and the camera pointing/position are incorrect then we simply run option 2 only. This is what autoregister does, when we add new images to an existing landmark database. If we are in a scenario where we believe the camera position/pointing are correct and not the landmarks then we run option 1 only.
Another consideration is the relative contribution of each constraint in the landmark/position/pointing solution via the additional weights in INIT_LITHOS.TXT, LMKWTS and PICWTS. For instance, if the shape model is too coarse for the resolution of maps we are working with, we may want to reduce the influence of the shape model as a constraint in the solution of the landmarks by reducing the value of WR in INIT_LITHOS.TXT. If we believe that the S/C state is very well known compared to the landmarks, we may want to not allow the landmarks to change the camera position much, by either using a very small position uncertainty in the nominals or in addition by reducing the value of WB in PICWTS.
Figure 00: Illustration of Iterative Process for Updating Geometry
(Compiled by TC)
lithos
Category B |
Version 3.0 |
Description
This program aligns maplets to the current shape model and provides slight changes to the shape (stored in MAPFILES).
lithos is the key for SPC. It works on a single landmark, which defines the associated maplet. This landmark must be created (i.e., fully defined) and all the images it includes must be shifted so that everything is aligned. Once those steps are done, you can calculate the topography, which includes identifying other maps that overlap, creating a template, and then solving the whole system.
The outputs from make_scriptT and make_scriptP are used as input to lithos and lithosP for batch processing. The make_script program will create an entry for each landmark in the script.b. You will then process it as input, like this: 'lithos < LAND01.INN > LAND01.OOT'
Throughout LITHOS, you can simply hit 'Enter' for the default selection, which is usually indicted by brackets.
- For instance, in the case of "Do you wish to continue? y[n]" hitting 'Enter' key will default to the 'n' selection.
- When editing a seed file, a blank line will act as if the 'Enter' key was pressed at the command prompt.
Required Files
DATA/ - data specific to each mission
IMAGEFILES/ - a directory containing the image .DAT files
SUMFILES/ - a directory containing the image .SUM files (updated solution image, S/C and camera information; lmrks and limbs)
MAPFILES/ - a directory containing the full suite of maplets
LMKFILES/ - a directory containing the full suite of landmarks
BIGFILES/ - a directory containing all the bigmaps
NOMINALS/ - a directory containing the full suite of nominals
SHAPEFILES/ - a directory containing the shapemodel
LMRKLIST.TXT - a list of the landmarks contained in the solution
PICTLIST.TXT - a list of the pictures contained in the solution
- Will be used if PICTLISTX.TXT and PICTLISTRX.TXT do not exist.
BIGLIST.TXT - a list of all the bigmaps that have been created
INIT_LITHOS.TXT - file containing default values to be read in by SPC toolkit
Output Files
- tmpl.pgm - Temporary pgm amp file convert by RAW2PGM
- seeds.pgm - Temporary pgm amp file convert by RAW2PGM
- LMRK_DISPLAY0.pgm - Temporary pgm amp file convert by RAW2PGM (See below.)
- LMRK_DISPLAY1.pgm - Temporary pgm amp file convert by RAW2PGM (See below.)
Optional Files
LMRKLISTO.TXT - If present, LMRKLISTO.TXT is used to calculate overlaps instead of LMRKLIST.TXT. This action enables lithos and lithosP to run faster by searching for overlaps among a limited set of landmarks.
LMRKLISTX.TXT - Extended landmark list containing .LMK file information that speeds up processing by eliminating the need to open individual .LMK files multiple times.
PICTLISTR.TXT - User-generated restricted list of pictures for processing.
PICTLISTX.TXT - Picture information similar in concept to LMRKLISTX.TXT. This file will be used if PICTLISTRX.TXT does not exist.
PICTLISTRX.TXT - User-generated restricted extended picture list, i.e. a sub-set from PICTLISTX.TXT.
Using lithos
lithos is an interactive program that runs from a Main Menu. To access the Main Menu from anywhere within lithos, type '?' at the user prompt.
For information about each of the Main Menu options, click on its link in the Main Menu sample below:
... MAIN MENU ...
- Q. Quit LITHOS
- LANDMARK/MAPLET CONSTRUCTION
2. Find heights
- LANDMARK/MAPLET I/O AND CREATION
- ADJUST INPUT DATA AND NOMINALS
N. Find normal
- DELETE, ELIMINATE OR IGNORE FILES
- INFORMATION AND DISPLAY
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)
Link to original one page version (renamed 1/13/16): Old_lithos_text
lithosP
Category B |
Version 3.0 |
Description
lithosP is essentially lithos, but it is designed to be run in parallel.
- This guide assumes that you are familiar with lithos. Some of the options found in lithos have been cut, and other options have been streamlined. Only the differences are presented here.
Required Files
IMAGEFILES/ - a directory containing the image .DAT files
SUMFILES/ - a directory containing the image .SUM files (updated solution image, S/C and camera information; lmrks and limbs)
MAPFILES/ - a directory containing the full suite of maplets
LMKFILES/ - a directory containing the full suite of landmarks
BIGFILES/ - a directory containing all the bigmaps
SHAPEFILES/ - a directory containing the shape model
TESTFILES/ - a directory containing diagnostic files output by lithosP
LMRKLIST.TXT - a list of the landmarks contained in the solution
INIT_LITHOS.TXT - file containing default values for be read in by SPC toolkit
Optional Files
LMRKLISTO.TXT - If present, LMRKLISTO.TXT is used to calculate overlaps instead of LMRKLIST.TXT. This action enables lithos and lithosP to run faster by searching for overlaps among a limited set of landmarks.
LMRKLISTX.TXT - Extended landmark list containing .LMK file information that speeds up processing by eliminating the need to open individual .LMK files multiple times.
Output Files
- tmpl.pgm - Temporary pgm amp file convert by RAW2PGM
- seeds.pgm - Temporary pgm amp file convert by RAW2PGM
- LMRK_DISPLAY0.pgm - Temporary pgm amp file convert by RAW2PGM. See below.
- LMRK_DISPLAY1.pgm - Temporary pgm amp file convert by RAW2PGM. See below.
Using lithosP
lithosP is designed to be run in parallel. The following shows the Main Menu:
- ... MAIN MENU ...
- Q. Quit LITHOS
- LANDMARK/MAPLET CONSTRUCTION
- 0. Find template
- 1. Align landmarks
- 2. Find heights
- O. Attach map to maps or limbs
- LANDMARK/MAPLET I/O AND CREATION
- I. Input landmark
- U. Update landmark files
- ADJUST INPUT DATA AND NOMINALS
- N. Find normal
- V. Solve for V
- Z. Predict px/ln
- A. Reset albedo or slopes
- M. Get heights from shape model
- B. Get heights from surrounding map
- X. Turn on/off extract filter
- INFORMATION AND DISPLAY
- H. Hide/Show screen output
- Some of the Main Menu options found in lithos have been cut, and other options have been streamlined. Only the differences are presented here.
0. Find template - None of the sub-options exist.
- From the Main Menu, enter '0-40' to iterate 40 times.
1. Align landmarks - None of the sub-options exist.
- From the Main Menu, you can still use '1-0-1', but that is only because the "0" is interpreted as 0 spacing and lithosP asks you to enter the spacing again. Enter '1-1', '1-2', etc. as the "correct" commands to perform an auto-align.
2. Find heights - Only known difference is the "differential stereo" sub-option. Instead of being asked if you would like to reset entering gradients and auto heights, there is just a single 'y' or 'n'.
From Find heights, enter '6-y' instead of entering '6-y-y'.
O. Attach map to maps or limbs - There are some minor differences between lithosP and lithos within this option.
lithosP offers a subset of the lithos:o options - 1. Automatic; and 3. Limbs. The implementation of these options is the same as for lithos.
lithosP reduces the search for limbs by using only those limbs that have already been found spanning the maplet. If you want to do a full, include the line 'NEWLIM=.TRUE.' in INIT_LITHOS.TXT.
I. Input landmark - lithosP does not include an option to add more images to an existing landmark. Therefore, from the main menu, input 'i' and the landmark name. No further inputs are required. You will be returned to the main menu.
U. Update landmark files - Sub-options do not exist. The only option available is the "1" option, which is the full save.
- Enter 'u' from the Main Menu instead of entering 'u-1'.
N. Find normal - Sub-options do not exist. The only option available is the "2" option which is the most used option.
- Enter 'n' from the Main Menu instead of entering 'n-2'.
V. Solve for V - Sub-options do not exist. The only option available is the "1" option, which is the most used option.
- Enter 'v' from the Main Menu instead of entering 'v-1'.
Z. Predict px/ln - This options exists in the code, but there is no documentation for it. This option calls the sub-routine V2INGPL which determines the pixel/line location of a landmark in an image, but the resulting data isn't output to a file.
A. Reset albedo or slopes - No known differences.
M. Get heights from shape model - No known differences.
B. Get heights from surrounding map - No known differences.
X. Turn on/off extract filter - No known differences.
H. Hide/Show screen output - No known differences.
(Compiled by JRW)
make_list
Category B |
Version 3.0 |
Description
This program reads the image names from the LIMBLIST1.TXT file and documents any matches of those image names with the image names in LMRKLIST.TXT. The output consists of the landmark name and the number of matching images within LIMBLIST1.TXT.
Required Files
LIMBLIST1.TXT - List of images that show limbs.
LMRKLIST.TXT - List of landmarks.
Output Files
- LIST.TXT -
Using make_list
To run make_list, just type 'make_list' in the command prompt.
Here is a sample LIST.TXT file for a LIMBLIST1.TXT file that had 4 pictures:
BH0001 2 BK0001 1 CF0001 3 CG0001 3 CG0002 4 CG0003 3 CH0001 4 CH0002 4 CH0003 4 CI0001 3 CI0002 4 CI0003 1 CI0004 3
Additional Reference
[From make_list.f]
Filename I/O Description
---------------------------- --- -------------------------------
LIMBLIST1.TXT I List of images to be match w/
images in landmark files
LMRKLIST.TXT I List of current landmarks
<LMRKNM>.LMK I Landmark files whose PICTURES
entries will be matched w/
images in LIMBLIST1.TXT
LIST.TXT O List of landmarks that had
images that matches the images
in the LIMBLIST1.TXT and the
number of images that were
matched
(Compiled by JW)
make_lmrklistX
Category B |
Version 3.0 |
Description
This program reads the landmarks in the LMRKLIST.TXT file. Then, from the corresponding landmark files, it reads the size, scale, landmark position vector from the center of the body to center of the landmark and the number of pictures containing the landmark. It writes these values out to the LMRKLISTX.TXT.
Required Files
LMRKLIST.TXT - List of the full suite of LMKFILES.
Output Files
LMRKLISTX.TXT - LMKFILE information.
Using make_lmrklistX
Just type 'make_lmrklistX' in the command prompt to use.
(Compiled by DL)
Based on SPOC v3.02A PDF/UTILITIES/MAKE_LMRKLISTX.f File Reference
make_scriptAP
Category B |
Version 3.0 |
Description
This program generates the run script and .INN files required to batch autoregister new images using parallel processing.
Required Files
input file:
make_script.in - Text file containing the names of the images to batch autoregister.
seed file:
make_scriptA.seed - Text file containing the autoregisterP option commands for batch registering images.
processed files:
INIT_LITHOS - make_scriptAP reads the USRMX (maximum number of core processors) value.
TESTFILES1/ - Directory in which to store copies of LMRK_DISPLAYnn.pgm (output by autoregisterP) for each image.
autoregisterP requires a number of directories and files. Refer to autoregiserP for more information.
Output Files
make_scriptAP outputs:
- run.sh - Controlling run script for batch image auto registration using parallel processing.
- run script for each core processor:
- run_script01.b
- run_script02.b
- etc..
- run script for each core processor:
.INN files - autoregisterP seed file for each image.
- rem_script.b - Script for removal of temporary files (working directory clean-up)
run_scriptnn.b output:
.OOT files - Standard output from autoregisterP for each image.
processed files outputs:
TESTFILES1/ - A copy of LMRK_DISPLAYnn.pgm (output by autoregisterP) is saved for each image.
SUMFILES/ - Landmarks are added to the image's SUMFILE. Spacecraft/camera position/attitude are updated upon user acceptance of alignment shifts.
LMKFILES/ - Image names are added to the LMKFILES.
User Warnings
- You must set the correct number of core processors for USRMX, a variable contained in INIT_LITHOS. Refer to that entry for further information.
Using make_scriptAP
- Create Input Files
Here is a sample make_script.in file (see that entry for further information):
P00045000450 P00045000451 P00045000452 END
- You must precede each image filename with a space.
Here is a sample make_scriptA.seed file (see that entry for further information):
a 0,65,.25,0,3 1 2 n 0 n o .5 4 b 0 q END
Run make_scriptAP
make_scriptAP generates a .INN file for each image. It consists of the image filename followed by the autoregister options contained in the make_scriptA.seed file.
Here is an annotated sample .INN file for image P00045000450:
nn <- two character USR name to distinguish between processes. P00045000450 a 0,65,.25,0,3 1 2 n 0 n o .5 4 b 0 q END
make_scriptAP also generates the run.sh script. Here is a sample run script file for image POOO45000450:
chmod +x run_script01.b chmod +x run_script02.b ''etc..'' ./run_script01.b & ./run_script02.b & ''etc...''
make_scriptAP also generates the run_script01.b, run_script02.b files, which look like this:
rm -f P00045000450.OOT /usr/local/bin/AUTOREGISTERP < P00045000450.INN > P00045000450.OOT cp LMRK_DISPLAY01.pgm ./TESTFILES1/P00045000450.pgm rm -f P00045000452.OOT /usr/local/bin/AUTOREGISTERP < P00045000451.INN > P00045000451.OOT cp LMRK_DISPLAY01.pgm ./TESTFILES1/P00045000451.pgm
- Batch Autoregister Images Using Parallel Processing autoregister uses the file LMRKLISTX.TXT to prescreen the maplets. If you have added or deleted maplets recently, you should run make_lmrklistX.
Here is a sample command line for running run.sh:
sh run.sh
The autoregister standard output for each image is captured in the .OOT files. The LMRKDISPLAY1.pgm file output by autoregister is copied and stored in TESTFILES/ once an image has been processed. You must review the .OOT files to ascertain the success of the batch image autoregistration process.
- There is currently no find-nofit program for batch image autoregistration.
- Clean Working Directory
You can use rem_script.b to clean out the directory of make_scriptAP working files once autoregistration is complete and you have quality checked the image correlations.
Here is a sample rem_script.b file:
rm -f *.INN rm -f *.OOT rm -f run_script*
(Compiled by DL)
make_scriptF
Category B |
Version 3.0 |
Description
This program generates the run script and .INN files required for batch processing using lithos. You must also generate a seed file containing the required lithos commands.
make_scriptF is a generic script maker for batch lithos processing tasks. You specify the set of landmarks to process in make_script.in and the sequence of commands to process in make_scriptF.seed.
make_scriptF generates the .INN files and run scripts to batch process the landmarks, and generates .OOT files and saves display files during processing for user inspection.
- You should test the command sequence in lithos before running the script generated by make_scriptF.
Required Files
input file:
make_script.in - Text file containing the names of landmarks to be processed.
seed file:
make_scriptF.seed - Text file containing the lithos option commands intended during batch processing.
processed files:
TESTFILES/ - Directory in which to store copies of LMRK_DISPLAY1.pgm (output by lithos) for each landmark.
TESTFILES1/ - Directory in which to store copies of tmpl.pgm (output by lithos) for each landmark.
lithos requires a number of directories and files. Refer to lithos for more information.
Output Files
make_scriptF outputs:
- run_script.b - Run script for batch processing.
.INN files - lithos command seed file for each landmark.
- rem_script.b - Script for removal of temporary files (working directory clean-up).
run_script.b outputs:
.OOT files - standard output from lithos for each landmark.
processed files outputs:
TESTFILES/ - A copy of LMRK_DISPLAY1.pgm (output by lithos) is saved for each landmark.
TESTFILES1/ - A copy of tmpl.pgm (output by lithos) is saved for each landmark.
SUMFILES/ - S/C and camera information are updated by lithos if image shifts occur.
LMKFILES/ - LMKFILES for each landmark are updated by lithos.
MAPFILES/ - MAPFILES for each landmark are updated by lithos.
Several information text and display files in the working directory are modified by lithos. Refer to the entries for those files for more information.
User Warnings
- The make_scriptF.seed file must start with a set of commands which deal with the lithos Check for more images? y[n] option sequence. The make_scriptF.seed file must end with the lithos quit command, q, and the end-of-file identifier, END. You should test the make_scriptF.seed lithos command sequence before running the script generated by make_scriptF.
Using make_scriptF
1. Create Input Files
Here is a sample make_script.in file (see that entry for further information):
EE0001 EE0002 EE0003 END
lithos expects a sequence of start and end commands which must be contained in the seed file before and after the processing commands.
Here is an annotated sample make_scriptF.seed file. The required start and end command sequences are explained below.
# Seed file to attach map to overlapping maps #start commands n <- don't check for more images n <- don't include a single image #processing commands o RECENT y 1 o RECENT n 3 y 1, 3, 5 w i RECENT n n v 1 u 1 o RECENT n 1 #end command q <- quit #end-of-file identifier END <- end-of-file
Start Commands
The .INN file starts with the command i: input landmark, and the landmark name. lithos then asks you whether to check for more images. The following samples show the prompts and responses for both 'y' and 'n' responses to this prompt:
Check for more images? y[n] n Include a single image? y[n] n
Check for more images? y[n] y Enter fractional width (0=center). .5 Reject invisibles? y[n] n
When you create the make_scriptF.seed file, you must start with a sequence that deals with this set of options. In the sample, the Start Commands lines are annotated to indicate these responses.
End Command
make_scriptF expects you to quit lithos on completion of each landmark. The make_scriptF.seed file must contain the quit command q on the second-to-last-line.
End-Of-File Identifier
make_scriptF expects the seed file to end with the end-of-file identifier, END. Any commands following this will not be appended to the .INN file.
Comments
Use # at the beginning of any comment line you want to include. make_scriptF does not append these to the .INN file.
2. Run make_scriptF
make_scriptF generates a .INN file for each landmark listed in make_script.in.
Here is a sample .INN file for landmark EE0001.INN:
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)
make_scriptR
Category B |
Version 3.0 |
Description
This program generates the run script and .INN files required to batch register new images.
Required Files
input file:
make_script.in - Text file containing the names of the images to batch register.
seed file:
make_scriptR.seed - Text file containing the register option commands for batch registering images.
processed files:
TESTFILES/ - Directory in which to store copies of LMRK_DISPLAY.pgm (output by register) for each image.
register requires a number of directories and files. Refer to register for more information.
Output Files
make_scriptR outputs:
- run_script.b - Run script for batch image registration.
.INN files - register seed file for each image.
run_script.b output:
.OOT files - Standard output from register for each image.
processed files outputs:
TESTFILES/ - A copy of LMRK_DISPLAY.pgm (output by register) is saved for each image.
NOMINALS/ - If the seed file includes the option to update the NOMINAL file, starting S/C and camera information will be updated. (This option is not typically selected).
SUMFILES/ - S/C and camera information are updated as image shifts are made.
Using make_scriptR
1. Create Input Files
Here is a sample make_script.in file (see that entry for further information):
P3T11S2H0409 P3T11S2H0410 P3T11S2H0411 END
- You must precede each image filename with a space.
Here is a sample make_scriptR.seed file (see that entry for further information):
s 20 3 y XSTOP 1 10 3 y XSTOP 0 y n n q
2. Run make_scriptR
make_scriptR generates a .INN file for each image. It consists of the image filename followed by the register options contained in the make_scriptR.seed file.
Here is a sample .INN file for image P3T11S2H0409.INN:
P3T11S2H0409 s 20 3 y XSTOP 1 10 3 y XSTOP 0 y n n q
make_scriptR also generates the run_script.b script, which looks like this:
rm -f P3T11S2H0409.OOT /usr/local/bin/REGISTER < P3T11S2H0409.INN > P3T11S2H0409.OOT cp TEMPFILE.pgm ./TESTFILES/P3T11S2H0409.pgm rm -f P3T11S2H0410.OOT /usr/local/bin/REGISTER < P3T11S2H0410.INN > P3T11S2H0410.OOT cp TEMPFILE.pgm ./TESTFILES/P3T11S2H0410.pgm rm -f P3T11S2H0411.OOT /usr/local/bin/REGISTER < P3T11S2H0411.INN > P3T11S2H0411.OOT cp TEMPFILE.pgm ./TESTFILES/P3T11S2H0411.pgm
3. Batch Register Images
Here is a sample command line for running run_script.b:
sh run_script.b
The register standard output for each image is captured in the .OOT files. The LMRKDISPLAY.pgm file output by register is copied and stored in TESTFILES/ once an image has been processed. You must review the .OOT files to ascertain the success of the batch image registration process.
- There is currently no find-nofit program for batch image registration.
(Compiled by DL)
make_scriptT
Category B |
Version 3.0 |
Description
This program generates the run script and .INN files required to tile a bigmap or shape with a suite of new maplets.
Required Files
input file:
make_scriptT.in - text file containing references to the bigmap and make_scriptT.seed file, and the bigmap pixel/line locations for the centers of each new maplet.
seed file:
make_scriptT.seed - text file containing the lithos option commands for generating each maplet.
processed file:
TESTFILES/ - Directory in which to store copies of LMRK_DISPLAY1.pgm (output by lithos) for each landmark.
TESTFILES1/ - Directory in which to store copies of tmpl.pgm (output by lithos) for each landmark.
lithos requires a number of directories and files. Refer to lithos for more information.
Output Files
make_scriptT outputs:
- run_script.b - Run script for maplet creation.
.INN files - lithos seed file for each new maplet.
- rem_script.b - Run script to clean out the directory of make_scriptT working files once tiling is complete and user has quality checked the resulting suite of maplets.
run_script.b output:
- .OOT files - Standard output from lithos for each new maplet.
PROCESSED FILES OUTPUTS:
TESTFILES/ - A copy of LMRK_DISPLAY1.pgm (output by lithos) is saved for each landmark.
TESTFILES1/ - A copy of tmpl.pgm (output by lithos) is saved for each landmark.
SUMFILES/ - S/C and camera information are updated by lithos as image shifts are accepted because the "v 4" command in lithos is used. New landmarks and limb fits are added to the SUMFILEs.
LMKFILES/ - LMKFILES for each new maplet are created and populated by lithos.
MAPFILES/ - MAPFILES for each new maplet are created and populated by lithos.
Several information text and display files in the working directory are modified by lithos. Refer to the entries for those files for more information.
User Warnings
- YOU MUST FOLLOW SEVERAL PROCEDURES BEFORE RUNNING make_scriptT. Refer to the 'How-To': Basic_tiling You must copy the current bigmap to MAPFILES/XXXXXX.MAP, the temporary file used by the run scripts.
Using make_scriptT
YOU MUST FOLLOW SEVERAL PROCEDURES BEFORE RUNNING make_scriptT. Refer to the 'How-To': Basic_tiling
1. Create Input Files
Here is a sample make_scriptT.in file (see that entry for further information):
XXXXXX
scripts/t11-10.seed
50 50
100 50
150 50
200 50
50 100
100 100
150 100
200 100
50 150
100 150
150 150
200 150
50 200
100 200
150 200
200 200
ENDHere 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_TILES
Category B |
Version 3.0 |
Description
This program builds <sequence>.IN files that are used to make Z-maps with bigmapL. Z-maps are essentially a combination of bigmaps that, together, fully wrap around the shape model.
MAKE_TILES creates a <sequence>.IN file for every row in the input file MAPLIST.TXT.
- Be sure to include enough bigmap names to fully wrap around the surface (calculate with q-size and surface area of shape).
Required Files
MAPLIST.TXT - List of bigmap names you want to use.
Output Files
<sequence>.IN files - One for each row in MAPLIST.TXT
Using MAKE_TILES
The standard input includes these elements:
- resolution (pix/km)
- Q size
- seed
- maximum maplet resolution that can be included in the bigmap being created
Here is a sample input:
0.02500 500 1.23400 5.00000
Here is a sample MAPLIST.TXT file:
ZN0000 ZN0001 ZN0002 ZN0003 ZN0004 ZN0005 ZN0006 ZN0007 ZN0008 ZN0009 ZN0010 ZN0011 END
The following is a sample sequence.in file created from the above inputs:
l
0 0
0.02500 500 1.23400 5.00000
ZN0000
1
.005
.025
1
1
1
1
1
1
1
0
0
(Compiled by KD)
MAKE_TILESP
Category B |
Version 3.0 |
Description
This program is the same as MAKE_TILES, but it also creates <sequence>.INN files that can be run in parallel. In other words, MAKETILESP allows bigmapL to run all the <sequence>.INN files it has made at the same time rather than one at a time.
Like MAKE_TILES, MAKE_TILESP builds <sequence>.INN files that are used to make Z-maps with bigmapL. Z-maps are essentially a combination of bigmaps that, together, fully wrap around the shape model.
MAKE_TILESP creates a <sequence>.INN file for every row in the input file MAPLIST.TXT.
- Be sure to include enough bigmap names to fully wrap around the surface (calculate with q-size and surface area of shape).
Required Files
MAPLIST.TXT - List of bigmap names you want to use.
Output Files
<map_name>.INN files - Inputs for bigmapL
<MAKE_TILES##>.b files -
Using MAKE_TILESP
Here is a sample of the screen output from MAKE_TILESP:
chmod +x MAKE_TILES01.b chmod +x MAKE_TILES02.b chmod +x MAKE_TILES03.b chmod +x MAKE_TILES04.b ./MAKE_TILES01.b & ./MAKE_TILES02.b & ./MAKE_TILES03.b & ./MAKE_TILES04.b &
- Copy and paste the screen output into the terminal to create all the z-maps in parallel.
Each <MAKE_TILES##>.b file the following structure, containing one or more lines like this:
/usr/local/bin/bigmapL < F00001.INN > F00001.OOT
(Compiled by KD)
map_coverage
Category B |
Version 3.0 |
Description
This program generates coverage for a limited area (bigmap) of what has been tiled and processed. map_coverage produces a coverage_m.pgm file that shows areas on a bigmap that have been tiled at user specified resolutions. In the image, black means the area is not covered by a maplet while covered areas are bright. The brighter the area, the more maplets overlap that area.
Near the end of processing, there may be thousands of maplets. To speed things up, the routine will read in LMRKLISTO.TXT if it exists. This file speeds up map_coverage by telling the program exactly which maplets to show rather than having it search.
Input Files
bigmap - a name provided in stdin
Output Files
coverage_m.pgm - a regional map showing what has been tiled to the specified resolution
Using map_coverage
- Input the filename of a bigmap:
ZN0204
- Input the min and max resolution of tiles (maplets) to show:
0,.001
Here is a sample output from map_coverage:
Figure 00: Example of map_coverage Output
Compiled by KD
pole
Category B |
Version 3.0 |
Description
This program solves for the pole right ascension, declination and rotation rate for a body in principal axis rotation. The rotation rate is calculated in degrees/day while right ascension and declination are calculated in degrees.
If you "keep the result", then pole will translate the VLM (central vector) an UX, UY, UZ (normal vectors) of the landmarks, maplets, SUMFILES and NOMINALS. It will also update the information in POLE.TXT.
Input Files
- POLE.TXT - simple text file containing nominal pole RA (deg), DEC (deg), PM (deg), OMEGA (deg/day)
POLE.TXT and LMRKLIST.TXT must be in the working directory.
POLE.TXT is a single row file that contains the predicted pole RA (deg), DEC (deg), PM (deg), and OMEGA (deg/day). These values are given in the .tpc kernel file for the object. LMRKLIST.TXT contains a list of landmarks.
Using pole
When you run pole, it is expecting an initial value for POLE.TXT. If that file does not exist, the program will fail. To create the file, you can use the pole values from the current PCK (planetary constants kernel).
1. Input a time in UTC.
- Make sure the time is within the span supported by the kernels.
2018 NOV 16 13:09:54.824
2. Create a POLE.TXT file.
Here is a sample POLE.TXT file:
86 -65 89.00000000 2010.48945
3. Answer whether you want the rotation rate fixed (y for yes, n for no).
4. Enter
0 if you want to iterate
1 if you want to keep the result (this updates POLE.TXT)
2 if you want the previous result (this is nominal if on the first iteration)
In general you will want to do several iterations to help the inversion of the matrix converge. When the pole solution ceases to change, if you think that the solution is an improvement, you can keep it. At that point, it will change most of the files in the working directory.
Here is a sample output from the POLE.TXT input:
86.60062 -65.00002 90.42707 2009.99979311
0.05176 0.02171 0.00000001- The first row gives all the new pole parameters for POLE.TXT.
- The second row shows formal uncertainty (the diagonals of the covariance). These values should be multiplied a factor of 10 or 100.
Test Results
Testing using the NTE3A data set showed that picking different Epoch times over the time span of the images used (in this case 22 days) resulted in no change of RA, DEC, or rotation rate, and the PM at J2000 only change by 0.07 deg.
(Compiled by KD)
register
Category B |
Version 3.0.3 |
Description
This program is used to align new images with a known object.
register cross-correlates an image with existing data to update the knowledge of the spacecraft position/attitude. It is limited to 2 degrees of freedom.
Required Files
IMAGEFILES/ - a directory containing the image .DAT files
NOMINALS/ - a directory containing the image .NOM files (starting solution image, S/C and camera information)
SUMFILES/ - a directory containing the image .SUM files (updated solution image, S/C and camera information, lmrks and limbs)
MAPFILES/ - required for comparison with a reference map
SHAPEFILES/ - required for comparison with a shape model
Optional Files
make_scriptR.seed - for batch processing using make_scriptR
Output Files
NOMINALS/ - If you select the option to update the NOMINAL file, starting S/C and camera information will be updated (an option not typically selected)
SUMFILES/ - S/C and camera information are updated as image shifts are made. You can discard these changes upon quit.
- TEMPFILE.pgm - A side by side view of the image (left) and the reference (right)
- TEMPFILE.ppm - A red/cyan composite of the two items (red is image, cyan is reference)
User Warnings
- To undo all changes since the last quit, you must select 'n' from the Main Menu.
- Since the SUMFILE is updated in realtime, an uncontrolled exit from register will result in the SUMFILE remaining modified.
Using register
Initial Inputs
register provides an initial estimate for the spacecraft state (camera pointing and s/c-object vector) by aligning an image with a known object - either the shape model, a high resolution map or another (already registered) image.
The following shows the initial inputs necessary to get to the Main Menu:
input 12-character picture name. q to quit.
1. Enter the image name as stored in [[IMAGEFILES]].
- Some versions of process_fits will make some changes to the filename, so it may not be the "original" name.
s = shape i = reference image m = reference map
2. Enter the object to align with.
s = shape - to use the current shape model
i = image - select an already registered image; you will be prompted for an image name
m = map - use a maplet/bigmap; you will be prompted for a map name
- If you enter 0 for the map name, the program will search a set of "Zmaps" for the one most likely to overlap the image. Maps are only used after a detailed shape model and high-resolution maps have been constructed. At that time you are registering new images for navigation or improving the topography.
enter scale (km/px)
3. Enter the scale in km. The basic display for REGISTER is 600x600 pixels.
- For example, if the body is 500 m across and the scale is entered at 5 m (.005), the image will be 100 pixels across in the display.
The output will look like this:
gc TEMPFILE.pgm gc TEMPFILE.ppm
TEMPFILE.pgm - A side by side view of the new image (left) and the reference (right)
TEMPFILE.ppm - A red/cyan composite of the two items (new is red, cyan is reference)
Here is a sample TEMPFILE.pgm file image:
Figure 00: Side-by-Side Example of Registration Allowing Comparison of Initial State
Here is a sample TEMPFILE.ppm file image:
Figure 00: Color Differentiated Example of Registration Allowing Comparison of Initial State
- The display and the arrays of image and reference data are not the actual imaging data; instead, they are that data projected on a substrate. When you are just starting processing and looking at low-resolution images of the body, the substrate is simply a plane through the body center oriented parallel to the camera's focal plane. This flat 'f' substrate is the default value. Once a decent shape model is obtained and the images cover a small fraction of the body's surface, the substrate is taken to be that surface itself, either in the form of the shape 's' or a high-resolution map 'm'. In this case, the topography is represented as a DTM whose reference plane is the same as the flat substrate with heights in the negative camera bore sight direction. If the reference is also an image, this data is projected on the same substrate as the image being registered.
After you have entered the initial inputs, you will then see the Main Menu.
Main Menu
The Main Menu of register looks like this:
0. Quit 1. Change scale 2. Global shift 3. Shift unknown (LEFT/RED) image 4. Rotate unknown (LEFT/RED) image 5. Change reference 6. Change RANGE of (LEFT/RED) image 7. Revert to nominal 8. Change substrate (f) 9. Update nominal and quit F. Features to body rotation G. Get approach range from images O. Find OMEGA W. Write log a. Turn off bkg b. Turn off image for Vlm l. Turn on log c. Change correlation limit = 0.25 d. Fix scobj e. Fix pointing v. Fix center=0 t. Tuck picture
Options 1, 5 and 8: Allow you to change the scale, reference object and substrate, respectively.
Option 2: Sometimes when trying to align an image to a reference, the entire display is off center. Option 2 moves both the image and reference displays by the same amount so that you can more conveniently align them, usually at smaller scale. This option only changes the user's point of view, not the image's location.
Options 3, 4 and 6: Make changes to the .SUM file in camera pointing and/or cross line-of sight scobj, camera twist and s/c range, respectively.
Option 3: This is the most often used option.
- The new image is on the left or in red. Values entered (delta x, delta y) are the number of pixels by which the image will be shifted (as per the current scale).
- This isn't the same as moving the "window" as in lithos; instead, it updates the image's camera position and pointing.
- After you enter option 3, you will input responses like these:
Autocorrelate? (y/n)
y
0.00000 0.00000 0.27302
Enter px/ln IMAGE shiftIf you respond 'y', autocorrelate estimates the offset between the image and the reference. The three values displayed in the standard output are the delta x (pixels), delta y (lines), and the correlation score.
- If the correlation gives a good match (greater than a preset limit, default=0.25), autocorrelate will shift the image and go back to the menu.
- Otherwise, autocorrelate will ask for a manual input.
The preset limit can be changed with Option c.
Option 7: Populates the working .SUM file. This is sometimes a bailout procedure used when the .SUM file is screwed up in some way.
option 9 lets you save the current result as the nominal without changing the .SUM file from its original value. If, for example, the spacecraft range is out to lunch (as it was on Hayabusa), the working .SUM file can be populated with the nominal, a change made to the range with option 6, and the new nominal saved with option 9.
Option F Features to body rotation. This allows you to use two images (about 20deg rotation difference) to identify a pole. It uses x/y pairs between real and model. Register-find-pole-info
Option G Allows you to try different size scalings to see if the fit is better.
Option O Computes the RA, Dec and rotation rate based on the data provided by Option F. Provide the rotation rate in degrees per day.
Option W Writes out the log of the commands that are used.
Option a: When correlating small images to a nominal shape, we want to use all the data, so the space off the body counts just as much as the body itself. Option A wakes up with a "background" turned on so that this correlation can be performed. Entering 'a' toggles this background off, so that only the common topography is correlated between the image and the reference object.
Option b: Allows a flag to be set on the image that will enable its brightness variations to be used to determine topography but keeps it from participating in the geometry solution for the landmark vector. This is used to keep Mariner 10 images of Mercury, which have questionable nominals, from messing up the vector but still, with their sometimes unique sun angles, helping with the topography determination.
Option l: Turns on the logging function for register. This is mostly for finding size or pole.
Option c: Allows you to change the autocorrelation limit (default=0.25).
Options d and e: When an image shift has been determined, either manually or through autocorrelation, the camera pointing and spacecraft-object (scobj) vector in the .SUM file are changed in a manner weighted by their respective sigmas in the nominals (.NOM) file. If you want to keep one or the other unchanged, use the 'd' or 'e' option to fix it.
Option t: Allows an image to be tucked so it will not participate in the SPC process at all. It could be tucked from lithos, but it often happens that as register is used to cycle through new images, problems are easily seen and dealt with immediately.
Option v Fix center = 0.
0. Quit: This gives you the chance to save or discard changes, and then register the next image. All toggle options will persist until you Quit register.
Accept shift? (y/n) Update/Create rotation history file? (y/n) Update nominal file? (y/n)
Accept shift?: Note that the shift has already been applied (the SUMFILE is updated in real time).
- To undo all changes since the last quit, you must select 'n'.
Update/Create rotation history file?: Always enter 'n'. The rotation history file was introduced to keep track of pointing errors in Clementine data during Lunar orbits in an attempt to quantify systematic shifts.
Update nominal file?: Usually enter 'n'. Rarely, you may want to set the nominal file equal to the .SUM solution.
The following sample shows standard inputs and outputs from register:
Figure 00: Sample Registration of an Image with a Shape
Figure 00: Sample Registration of an Image with a BigMap
Figure 00: Illustration of Options using Register
(Compiled by DL)
Based on SPOC v3.02A PDF/LITHOSPHERE/REGISTER.f File Reference
regres
Category B |
Version 3.0.1 |
Description
This program generates a set of ascii interface files, one for each image, containing optical navigation observables, partials, and relevant ancillary information for use in the FDS navigation software suite(s). Both MIRAGE (KinetX) and GEODYN (GSFC) are currently ingesting these files. A file is created for each image in the restricted picture list, PICTLISTR.TXT, and only landmarks from a restricted landmark list, LMRKLISTR.TXT, are used. If the PICTLISTR.TXT file does not exist, the software defaults to PICTLIST.TXT.
Each interface file contains the following information:
- SPICE IDs, image epoch, camera parameters
- TITV matrix (inertial to camera frame transformation)
- TPMI matrix (body-fixed to inertial transformation)
- SPC solution for:
- Spacecraft-to-object vector
- Camera pointing (RA, Dec, Twist)
- Spacecraft position sigma
- Camera pointing and twist sigmas
- Nominal (a priori):
- Spacecraft-to-object vector
- Camera pointing (RA, Dec, Twist)
- Solar unit vector
- For each landmark identified in the image from SPC process:
- Landmark name
- Body-fixed control point vector
- Body-fixed control point sigma
- Observed landmark center in (pixel, line) image coordinates
- Predicted landmark center in (pixel, line) image coordinates based on nominal S/C position and SPC solution for camera pointing
- Partial derivatives for (pixel, line) w.r.t. spacecraft-body position vector (SCOBJ)
- Partial derivatives for (pixel, line) w.r.t. camera pointing (RA, Dec, Twist)
- List of all SPICE kernels used
regres requires the directory "REGRES_FILES" in the working directory. regres exports files for each picture (<PICTURE NAME>.TXT) to the "REGRES_FILES" directory.
regres uses all pictures in PICTLIST.TXT and landmarks in LMRKLISTR.TXT to make the exported regres files. However, if you have created a PICTLISTR.TXT, regres will only use the pictures from that file.
regres uses data from NOMINAL
Input Files
Output Files
<path to working directory>/REGRES_FILES/<picture name>.TXT
Using regres
If all required inputs are available in the working directory, simply execute regres to produce the output files.
Here is a sample output file from regres:
REGRES FILE. CREATED Tue Oct 3 14:47:34 2017
PARTIALS UNITS: PX/KM, PX/DEG
N599562509F0 IMAGE ID
2018-12-31T21:07:21.000_NCAM_L0b_V005.fits ORIGINAL NAME
ORX_NAVCAM1 CAMERA ID
-64 SPACECRAFT ID
2101955 TARGET ID
LT+S ABCORR
2018 DEC 31 21:07:21.000 UTC
0.5995625102D+09 ET SEC PAST J2000
2592 1944 1000 65535 NPX, NLN, THRSH
0.7680000000D+01 0.1296500000D+04 0.9725000000D+03 MMFL, CTR
454.5455 0.0000 0.0000 0.0000 -454.5455 0.0000 K-MATRIX
Camera temperature (deg C) = N/A CAMERA TEMP
Distortion type = OPENCV DISTORT BEGIN
Parameters: DISTORT CONTINUE
P( 0) = 0.0000000D+00 DISTORT CONTINUE
P( 1) = -0.5357300D+00 DISTORT CONTINUE
P( 2) = 0.3611700D+00 DISTORT CONTINUE
P( 3) = -0.1534700D-06 DISTORT CONTINUE
P( 4) = 0.0000000D+00 DISTORT CONTINUE
P( 5) = 0.0000000D+00 DISTORT CONTINUE
P( 6) = 0.0000000D+00 DISTORT CONTINUE
P( 7) = 0.0000000D+00 DISTORT CONTINUE
P( 8) = 0.0000000D+00 DISTORT END
0.5815432282D+00 -0.6754376338D+00 -0.4534219630D+00 ROW 1 TITV MATRIX
-0.8014742143D+00 -0.5712327735D+00 -0.1770090457D+00 ROW 2 TITV MATRIX
-0.1394509146D+00 0.4663444234D+00 -0.8735423980D+00 ROW 3 TITV MATRIX
0.8583303375D+00 -0.5130525373D+00 0.6791585157D-02 ROW 1 TPMI MATRIX
-0.4619122250D+00 -0.7668748603D+00 0.4455783264D+00 ROW 2 TPMI MATRIX
-0.2233967950D+00 -0.3855905115D+00 -0.8952171968D+00 ROW 3 TPMI MATRIX
LITHOS SOLUTION:
-0.1877903947D+00 0.1184174267D+01 -0.1797326337D+01 SC - OBJ VECTOR
0.1066482361D+03 -0.6087293551D+02 -0.2132491821D+02 CAMERA RA, DC, TW
0.1732050808D-01 S/C POSITION SIG
0.8102846845D-08 PNT SIGMA (DEG)
0.5729577951D-08 TWIST SIGMA (DEG)
NOMINAL STATE:
-0.1877903947D+00 0.1184174267D+01 -0.1797326337D+01 SC - OBJ VECTOR
0.1066482361D+03 -0.6087293551D+02 -0.2132491821D+02 CAMERA RA, DC, TW
-0.5629404130D+00 -0.7205839705D+00 -0.4047923329D+00 SOLAR UNIT VECTOR
LANDMARKS:
END LANDMARKS
KERNEL LIST
att_nte2_m3a-m4a_truth.bc
ORX_SCLKSCET.00000.example.tsc
naif0012.tls
orx_ocams_v05.ti
orx_181215_190112_190108_od012_v1.bsp
orx_v06rwg.tf
de424.bsp
bennu_nte2_truth.tpc
pck00010.tpc
END FILE(Compiled by KD)
rem_done
Category B |
Version 3.0 |
Description
This program's main purpose is to allow you to stop a parallel lithosP process and find out which landmarks in make_script.in have yet to be worked on. You should run rem_done if SPC crashes during a parallel process.
Input Files
make_script.in - Script for processing
- balzyWalzy.txt - List of landmarks processed (can be called anything)
- flyingMonkies.txt - List of landmarks not processed (can be called anything)
Output
- None, just stops the process.
Using rem_done
1. Determine which landmarks have been processed.
- In the working directory that contains .OOT and .INN files, enter this command line:
ls -1 *.OOT | cut -c -6 > balzyWalzy.txt
This puts all the .OOT filenames into the text file balzyWalzy.txt in the form of a column without the .OOT extension.
You must add 'END' as the last row of this text file.
2. Create a text file listing landmarks that have been processed and call it 'done.txt'.
Put the landmarks without an .OOT file (those not listed in Step 1) into the text file flyingMonkies.txt in the form of a column.
You must add 'END' as the last row of this text file.
INPUT INFILE make_script.in INPUT DONEFILE done.txt INPUT OUTFILE FlyingMonkies.txt
(Compiled by KD)
Script Makers Overview
Description
The script-maker routines are designed to help you set up batch processing of pictures or landmarks using the autoregister, autoregisterP, lithos, lithosP and register program suites. The following table summarizes the script-maker routines, input files, and programs invoked by the resulting run scripts. For further details, refer to the entry for a specific script maker.
Table 00: Summary of Script Maker Routines
Script-Maker |
Type of Files Processed |
Program Invoked |
input file |
seed file |
serial/parallel processing |
Description |
image files |
serial processing |
Generates the run script and .INN files required to batch autoregister new images. |
||||
image files |
parallel processing |
Generates the run script and .INN files required to batch autoregister new images using parallel processing. |
||||
landmark files |
serial processing |
Generates the run script and .INN files required for batch processing using lithos. The user generates a seed file containing the required lithos commands. |
||||
landmark files |
parallel processing |
Generates the run script and .INN files required to iterate maplets using lithosP. |
||||
image files |
serial processing |
Generates the run script and .INN files required to batch register new images. |
||||
new landmark files |
serial processing |
Generates the run script and .INN files required to tile a bigmap or shape with a suite of new maplets. |
(Compiled by DL)
shift
Category B |
Version 3.0 |
Description
This program adjusts an entire shape file by a deltaX, deltaY and deltaZ. shift is typically used to adjust the center of figure to center of mass.
shift can also deal with the fact that sometimes a shape model's center of figure can drift off the 0,0,0 coordinate center, i.e. the middle of the asteroid is no longer at the origin of the system. In such cases, you can run shape_info and use its Center of Figure offsets as the input for shift.
Required Files
For adjusting shape file
<shapefile>.TXT -
For adjusting landmarks
Output Files
Using shift
- When you shift a shape file, only input the root name. Do not put in the fullpath or .TXT extension. shift will continue to ask you "Shape shift?" until you enter 'n'. Do not enter 'y' more than once unless you want to shift more than once.
Here is a sample set of inputs for shift:
Enter C0(i), i=1,3 0.66624D-03 -0.24253D-03 -0.13943D-02 Shape shift? (y/n) y Input shape name (eg SHAPE2) TESTSHAPE Shape shift? (y/n) n Shift maplets? (y/n) y GEOMETRY 20 1 n n
The final 5 lines copy and paste to update the rest of the system (updating SCOBJ and C_vector).
- You must do this if you update the MAPLET positions.
(Compiled by EP)
spheremapsB
Category B |
Version 3.0 |
Description
This program transforms maplet data from DTM to common formats and map projections for export.
SpheremapB reads the Zmap files and makes the resulting map line by line, which is more robust than bigmap. It creates:
- a suite of data files for a bigmap (REFMAP)
- a raw (simple binary) file of a 2D matrix for the scaled albedo (sample_ALB) and the topography (DEM)
- images (pgm format) of the albedo, topography, and color scaled topography
Required Files
MAPFILES/ - a directory containing the full suite of maplets
MAPLIST.TXT - a file listing the map files. You must build this yourself.
- Note: You can only have 9,000 maplets in the file.
Output Files
<BIGMAP>_DTM.pgm - Bigmap pgm image file (grayscale)
<BIGMAP>_DTM.raw - Bigmap raw image file (simple binary) - same as the pgm, but without the header
<BIGMAP>_COL.ppm - Bigmap raw image file (colorized)
<BIGMAP>_ALB.pgm - Big albedo map pgm image file (grayscale)
<BIGMAP>_ALB.raw - Big albedo map raw image file (simple binary) - same as the pgm, but without the header
Using spheremapsB
The following sample shows the prompts and standard inputs for spheremapsB:
Note: "tolerance" below refers to how far away spheremapsB will look to find maplets. A value too big here may start grabbing maplets from the other side of the body.
input ltd (deg), elon (deg), scale (km/px), half-sizes (px/ln), ref radius (km), tolerance (km) 0, 0 0.06250 500, 500 265 50 input map name ZN0000 a. orthographic b. stereographic c. equirectangular c Enter reference latitude 0 a. 8 bit DTM b. 16 bit DTM a Enter i,j,h map shift (m) (eg map-lola) 10.098592111467099 20.849462131360269 0, 0, 0 Fix hmin, hmax? (y/n) n Set max slope (deg) 60 Lat/Lon markings? (y/n) n
Examples of different scales
Fill me out!!!
Object |
Size |
Scale |
Half-Size |
Ref Radius |
Tolerance |
Ceres |
1000 km global |
||||
Moon |
20km regional |
||||
Bennu |
0.5km global |
||||
Bennu |
50m regional |
The following samples show outputs from spheremapsB for each of the identified elements:
Figure 00: Albedo Output from spheremapsB
Figure 00: Color DTM Output from spheremapsB
Figure 00: Grayscale DTM Output from spheremapsB
Additional Reference
[From spheremapsB.f]
C This procedure re-samples the surface vectors providid ba a set of C BIGMAPs onto a sphere with a radius characteristic of the body. Id C does so one outputline at a time so that arbitrarily large maps can C be produced. C C The procedure produces three types of map. A simple digital C elevation map (DEM) that provides te height above (or below) the C reference sphere at each point in either 8- or 16-bit format, a C shaded relief map (color coded with shading), and a relative albedo C map. This latter should be taken with a grain of salt, since the C albedo solution from SPC is quite crude. The DEM and albedo map are C presented as both raw and as .pgm files, while the shaded relief is C a .ppm file. The raw files are included because they are easier to C ingest into other systems such as ISIS. The .pgm DEM file has a C header that includes the ancillary information for the projection. C It can be read by any text editor. C C Three types of projection are recognized by spheremapsB. Orthographic and C stereographis are usually used for polar projections while equirectangular C (cylindrical) is used for oher regions, including the global DEM. The program C first asks for: C C central latitude and east longitude in degrees, C the scale (km/px), C the half-sizes in pixel and line directions, C ref radius (km), C tolerance (km) C C The last entry is a search limit in case one of the maps has some bad data in it C and is displaced too far from the expected height. C C The user then enters a name for the map, MAPNM. Note that his does not have to be C 6-characters. Then the user chooses the projection: C C a. orthographic C b. stereographic C c. equirectangular C C If a or b is chosen, the user enters a cone angle. For example, if the cone angle C is 70 degrees and the central latitude is 90 degrees, then the map will cover from C 20 degrees north to the pole. If c is chosen, the user is asked for a reference C latitude. At that latitude, the pixels are square at a resolution equal to the C scale chosen above. Poleward, the pixels are at higher resolution in the east- C west direction. If the longitude range of the plot is to be DLON and Q is the C half-size in pixels in the east-west direction, then C C 2*Q*scale=R0*cos(Rlat)*DLON*pi/180 C C In particular, if we want a global DEM at, say 32 pixels per degree then DLON=360, C 2*Q=360*32 and if Rlat=0 then scale=R0*pi/32*180. C C After deciding on the type of projection and its parameters, the user is asked: C C a. 8 bit DTM C b. 16 bit DTM C C where if the latter is chosen the data will be "unsigned short" (MSB). The next C choice is: C C Fix hmin, hmax? (y/n) C C If 'n' is chosen, the minimum and maximum heights will be those found for the C entire map. On occasion, especially if multiple maps are used to cover the body, C we want to use the same values for all maps and if ''y is chosen we enter those C values next. C C Set max slope (deg) C C The shaded relief map MAPNM_COL.ppm has both color coded heights and slopes C determined by pixel differencing so the maps appear to be illuminated from the C left. The maximum slope, usually set to 45 degrees, sets the scale for the C apparent illumination. A final choice is: C C Lat/Lon markings? (y/n) C C If 'y' is chosen, the user inputs spacings for lines of constant latitude and longitude C to be marked in white on the MAPNM_COL.ppm. C C The MAPNM_DEM.pgm file has a header that includes ancillary information for the C projection. For equirectangular projection the header looks like: C C P5 C #PROJECTION = EQUIRECTANGULAR C #REFERENCE RADIUS = 255.00000 C #REFERENCE LATITUDE = 0.00000 C # -90.0000000464 0.0000000000 90.0000000464 MN, CT, MX LAT C # -180.0000000928 0.0000000000 180.0000000928 MN, CT, MX LON C # 17281 8641 IMAX, JMAX C # 0.9272061656D-01 0.1235028039D-02 SCL, HTSCL C # -0.4309964495D+02 0.3783668255D+02 HTMIN, HTMAX C # 0.2550000000D+03 0.0000000000D+00 0.0000000000D+00 VLM C # 0.0000000000D+00 0.0000000000D+00 -0.1000000000D+01 UX C # -0.0000000000D+00 0.1000000000D+01 0.0000000000D+00 UY C # 0.1000000000D+01 0.0000000000D+00 0.0000000000D+00 UZ C 17281 8641 C 65535 C C where the lines without # specify the .pgm format. For orthographic and stereographic C projections, the heaer looks like: C C P5 C #PROJECTION = STEREOGRAPHIC C #REFERENCE RADIUS = 250.00000 C # 10401 10401 IMAX, JMAX C # 0.1000000000D+00 0.1235079957D-02 SCL, HTSCL C # -0.3810336140D+02 0.4283636848D+02 HTMIN, HTMAX C # 0.0000000000D+00 0.0000000000D+00 0.2500000000D+03 VLM C # 0.1000000000D+01 0.0000000000D+00 0.0000000000D+00 UX C # 0.0000000000D+00 0.1000000000D+01 0.0000000000D+00 UY C # 0.0000000000D+00 0.0000000000D+00 0.1000000000D+01 UZ C 10401 10401 C 65535
JRW Notes after further testing:
- HTMIN and HTMAX is the min and max vertical distance of the DTM in km. These values are deviations from the reference radius entered (i.e. after the half sizes and before the tolerance). So if the reference radius is entered as the lowest radius of the map, then HTMIN will be zero (or near zero with rounding error).
- SCL is the distance in km you entered in for scale (i.e. the third number entered (i.e the one after lat and elon).
- HTSCL is determined by taking the total distance from HTMIN to HTMAX and dividing by the number of bytes (256 for 8-bit and 65536 for 16-bit)
JRW discussion with Bob Gaskell on 25 Aug 2020
- The HTMIN and HTMAX are determined from the min and max of the maplets; they are NOT the min and max of the final product, which is a weighted average of the maplets.
- The input option of "Fix hmin, hmax?" is usually "no", but would be "yes" if making multiple final products so that all products have the same min and max.
- DN of zero means "No Data"
- DN of 1 corresponds to HTMIN. If the HTMIN is less than the min of the final product (which is usually the case because of averaging), the smallest DN of the pgm is greater than 1.
- DN of 65535 (for 16-bit) corresponds to HTMAX. If the HTMAX is greater than the max of the final product (which is usually the case because of averaging), the largest DN of the pgm is less than 65535.
- To convert DN to height from "REFERENCE RADIUS", take (DN - 1 ) * HTSCL + HTMIN (HTSCL is already adjusted by spheremapsB for 8-bit versus 16-bit)
- When making global maps, Bob normally makes a stereographic map for each pole (60 to 90 deg for North and -60 to -90 deg for South) and an equirectangular map for 60 to -60 deg. This is an example of when you may want to "Fix hmin, hmax?"
- When making a global map, Bob usually adjusts the size to make 16 pixels per degree. You can go larger, but often the files become more cumbersome than it is worth.
(compiled by JRW from material by EEP)
Example
Target |
Sample Files |
Bennu |
Known Issues
Note: You can only have 9,000 maplets in the MAPLIST.TXT. The program will crash if you have more than 9,000.