autoregister

Description

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

autoregister

• adds landmarks to a single image, adding the image name to all relevant LMKFILEs and adding the landmark names to the SUMFILE
• provides basic tools for aligning the landmarks, cross-correlating new images to existing maplets, eliminating landmarks and setting image flags
• updates the S/C position and pointing in the SUMFILE when the user accepts the changes from the auto-align (or manually aligns)

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

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

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

Required Files

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

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

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

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

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

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

Optional Files

• make_scriptA.seed - For batch processing using make_scriptA.

Output Files

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

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

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

• TEMPFILE.pgm - A pgm image of the image that the user is working with.

User Warnings

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

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

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

Using autoregister

Initial Inputs

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

 input 12-character picture name. q to quit.

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

 gc TEMPFILE.pgm
 kb =            1      kk =            1

 Add landmarks? (y/n)
y

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

autoregister Main Menu

 ...     MAIN MENU     ...

 0. Exit

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

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

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

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

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

REMOVE MAPLETS Options

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

• # - landmark number

• LMKNM - landmark name

• EMISS - emission angle

• COV - maplet-image overlap

• RES - image resolution/maplet scale

• INV - 1000 x invisible fraction of maplet

• #PIC - number of images in maplet

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

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

• SLIM - maximum emission angle.

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

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

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

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

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

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

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

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

IMAGE/MAPLET ALIGNMENT Options

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

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

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

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

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

 new spacing? (y/n)
n

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

 update landmark pixel locations? (y/n)

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

  The Auto-alignment routine output table includes these columns:

  • column 1 - landmark number

  • column 2 - landmark name

  • column 3 - the pixel shift predicted by the correlation

  • column 4 - the line shift predicted by the correlation

  • column 5 - the correlation value

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Option 2 is only used occasionally.

LANDMARK ADJUSTMENTS Options

Enter one of these 3 options:

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

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

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

Here is a sample showing the output from Option 4.

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

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

There are three sub-options to option 4.

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

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

  0 to end -- quit without changing

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

Batch Processing

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

Additional Reference

LMRK_DISPLAY1.pgm

Figure 00: Comparison of Landmarks and Associated Maps

Figure 00: Illustration of Autoregister and Landmark Options

(Compiled by DL)

CategoryPrograms