Training notes for JAXA session in support of MMX

Goals

• Bring the students to the "SPC Training Level 2" TrainingLevels

  • Provide enough SPC hand-on skills that basic shape models can be built
  • Provides enough background so that additional practice and instruction can occur
  • It will be insufficient to fully train new personal to a level in which they could run an entire mission without support
• Specific things to learn
  • Be able to create landmarks and add images
  • Basic trouble shooting and fixing mis-registration
  • Perform tiling (both globally and BIGMAP)
  • Do iterations
  • Run residuals, geometry
  • Register images to shape model or maps
  • Autoregister
• Practice. A key component of this training is to practice. The practice allows for key concepts to become understood at a sufficient level to allow for more advanced concepts to make sense.

Student Prep

Because class time is limited, it is important to get the software and data installed before you show up to the conference. I will be available during the conference to help troubleshoot problems and help get your system functional before the class starts Wednesday morning. Once the class starts, I won't be able to ignore everyone else in the class to fix an install.

To maximize your learning in the class, I provide some information that will be beneficial to review.

• Stuff to read (links below)

  • Palmer et al., 2022

  • Gaskell's 2008

Required Tasks To Complete Before Class Starts

• Sign the Licensing Agreement. This must be on file before the software can be distributed. //Complete//

• Download and install SPC software via GitHub

  • Installing SPC Instructions

  • SPC-GUI-tools - The web tools

• Download sample data. The data volume is large, so it is important to do it ahead of time. Some of the files need to be expanded and moved.
  • Day 1 - Ryugu
  • Day 2 - Ryugu
  • Day 3A - Ryugu
  • Day 3B - Phobos

  • Starting directory & SPICE (600MB)

    • You can put this directory anywhere. It is the base directory for the SPC work.
  • Images:

    • GitHub - https://github.com/StereoPhotoClinometry/SPC-Class-data

  • Support Tools:
    • Over time, I have found that there are many nice helpers for SPC that do well if organized into its own area. They include scripts, programs and image lists. I've included some here. I suggest putting these two directories in /opt/local/spc/

    • GitHUB - https://github.com/StereoPhotoClinometry/SPC-Class-data

Extra software that is useful

• Software - These are helpful tools. There are other tools you can use, but these are ones that we have found to be very useful.

  • gnuplot - Installing using MacPorts, "sudo port install gnuplot"

  • imagemagick Installing using MacPorts, "sudo port install ImageMagick"

• SPC tools - (TBD) This is a suite of tools that make measuring pixel/line locations and offsets easier. This is not required and class time won't be used for installing this. Install instructions are coming soon
  • apache -- The is installed as default for most UNIX (and Mac) systems.
  • spc_tool javascript libraries
  • updateDisplay.sh - script to convert SPC output to a web-accessible format

  • How to install and run - SPC-GUI-tools

Day 1

• Introductions
• Discussion of the Wiki/User’s manual

• Unix file layout and paths -- File System Setup

  • executables
  • source code
  • helpers
  • scripts
  • support
• SPC files
  • working
  • mapfile/landmark files
  • kernels
  • images

• Previous presentation on, Theory of SPC -- https://sbib.psi.edu/spc_wiki/Training_JAXA_Aug2016?action=AttachFile&do=view&target=Lesson_1.pdf

Day 1 Practical - It's all about LITHOS

• Topics
  • display landmark
  • landmark management
    • create
    • delete
    • rename
  • images
    • add images
    • remove images - auto and manual
    • select useable, correlation and manual
    • adjust image position, auto, manual
  • global shift
  • build template
  • find height
    • options

The core of SPC is lithos. That tool lets you create landmarks, associate images, align images, determine the 3D position of the landmark and create topography.

Fixing landmarks, using Input landmark

Aligning landmarks, using Align landmarks

Building a landmark Create new landmark and How To Build A Landmark

Template

• Find template

Topography

Once all the images are aligned (the center pixel of every image is at the exact same feature of the surface), then you can build topography using photoclinometry with some conditions. Find heights

toposcript

State

A key diagnostic tool for SPC is understanding the state of the system. By state, I mean what are the conditions (the health or quality) of the landmark. There is no one parameter that tells you all of this, but it is looking at a wide set of details that tells you if there are problems.

Align, Extra and Solve (AES) Iteration

Because SPC is an iterative process, each time the AES process is done, more data is extracted from the images and the solution moves towards a stability point.

Block 5 - Iterate v2

See Notes from day 1 -- These are things brought up in class or requested from the previous class on SPC. They are provided here because they are useful, but don't fit in another category.

Day 2

New files for today

Use branch "B-register" from GitHUB. If you are using GitHUB Desktop, it will ask to if you should bring the changes over or stash them. Select stash. If you are downloading this as a separate file (such as a .zip), then just do your work in that new directory.

Clean some of the landmarks

See toDoB in the working directory. Clean the landmarks listed at the top of the file.

"Clean" means to check the state of the landmark and fix any problems.

• Input the landmark into lithos "i"
• Check the alignment of the landmarks (use 1 0 1 n 0 n) and look for any images that do not correlate
• Align any images that are off
  • You can do automatic, " 0. Auto align" to let the computer try to find a good fit. Typically try a space (search radius) from 1 to 4.
  • You can do manual, "1. Individual shift". Use SPC Web Tools or count pixels to identify the x/y that is needed to get the image close. Once it is close, you can use Auto align to snap it into place.
  • You can do other picture, "3. Align with picture". This lets you select one image that is very good and get the other images to align to it. Note, if you use then, you have to use option "0 Find Template" to turn all of the images back on.
• Check to see if all of the images are selected for building the template -- i.e. when you go into option 0. Find template, none of the images have a star by their name.
  • If images have a star, then toggle them if they are aligned.

• If you've made changes, then run the toposcript to pull the updated data into the shape model.

• Save the model (u 1)

Bring in Images

• Converting images into SPC format

  • process_fits -- the generic information

  • PROCESS_FITS_MMX -- Will be written soon

  • make_sumfiles.in -- This file has a line for each image. It contains the FITS name and the SPC name.

• Converting geometric information into body-fixed frame

  • make_sumfiles -- This program creates a SUMFILES and NOMINALS for each image, and adds the image name to PICTLIST.TXT

Register

• Each image should be aligned with the shape model at a course level.

  • Run register.

  • Provide it the image name
  • When asked for "reference", select "s" for shape
  • When asked to "enter scale (km/px)", use ".1"
• You will then see the register menu. You should look at "TEMPFILE.pgm" and "TEMPFILE.ppm" to determine if the image is aligned to the shape model at that scale.
  • For SPC tools, you run the "register" link and "Reload" the window. You should see the image next to the model.
• If you need to make a correction:
  • Select 3. Shift unknown (LEFT/RED) image
  • It will ask for "Autocorrelate? (y/n)". If the two a far apart (more than a few pixels), then autocorrelate won't work, but you can try. Typically, say "n". If you try to autocorrelate, and it doesn't work, you will just continue as if you said 'n'
  • If it didn't autocorrelate or you selected "n", then you give it a delta X, delta Y to shift the image.
    • This is where SPC Web Tools is very useful. You click on the same feature in both the left hand side (image) and the right hand side (model) and it will tell you the values to enter in.
  • Once you have it well aligned at the current resolution, increase the resolution (we started with .1, then try: .01, .005, .002)
    • Select menu: 1. Change scale
    • Type in the next scale value (such as .01).
  • Now, you can go back to evaluating if the image and model is align and adjusting like you did. Continue until you have the model as aligned as possible. In this case, keep improving the alignment and resolution until it is good at .002 km)
  • In order to save what you have done, select: 0. Quit
    • It will ask you: Accept shift? (y/n) -- type "y"
    • It will ask you: Update/Create rotation history file? (y/n) -- type "n"
    • It will ask you: Update nominal file? (y/n) -- type "n"

• register has a lot of options to support a variety of difficult and complex problems. There are options to let it automatically register when you have a partial object in the field of view, when you are zoomed in very close. You can align to other images and even bigmaps.

Now register the images that are listed in the toDoB.

Autoregister

autoregister takes an image and assigns landmarks to it. This is the opposite of lithos which adds images to a landmark. When you start autoregister, you give it an image name and then tell it if you want to try to add more landmarks. Most times, the answer is yes, but sometimes you want to use the abilities of autoregister without adding more landmarks -- that is done when you've eliminated some landmarks that SPC thinks is value but they are not ready to be used for that image.

* Prepare the quick lookup file LMRKLISTX.TXT

• Run MAKE_LMRKLISTX -- It will just read all of the landmarks and generate LMRKLISTX.TXT. More info is make_lmrklistX

* Run autoregister

• Provide it with an image name
  • It will list the landmarks that is currently associated with that image
• When asked: Add landmarks? (y/n), select "y"
• When asked: enter fractional width (0=center), select "0.5"
• When asked: Reject invisibles? (y/n), select "y"

* This will take you to the main menu. You will want to removed images that fall out of parameters (emission angle, coverage, resolution limits)

• Select: n. Auto remove new only

• Type: "0 60 .5 0 4". The details for these parameters are listed in autoregister. This will remove landmarks that: Are hidden from view, that have more than a 60 degree emission angle, that have less than 50% illuminated and covered by the image, and have a resolution ratio of greater than 4.

* Now, you will want to check the status of the list of landmarks (review the correlation scores)

• Select: 1. Auto align

• When asked: enter spacing -- type 1. This will list the correlation scores for each landmark just like lithos. Note any landmarks that lack correlation values (i.e. 0.0000)

• Review LMRK_DISPLAY1.pgm for any troublesome landmarks.
• Fix landmarks, You can use the auto align routine with higher spacing (search radius) or you can no accept changes and use the manual align option.

  • Auto align. Select a larger value for spaceing (search radius) from 1-5 and see if it snaps the landmarks into place. When done, you will say "n 0 y" like in lithos

  • Exit the auto align routine, either with keeping the changes or discarding them.
    • When asked: new spacing? (y/n) -- select "n"
    • When asked to continue -- select 0. continue.
    • When asked: update landmark pixel locations? (y/n) -- select that option you want. This will take you to the main menu.
• Manually fix landmarks.
  • If you need to manually move landmarks, you can count pixels or use SPC tools to help. If you use SPC tools, you look at the image that you want to fix. You click on a feature in the top image (which gets marked in red) and then click on the same feature in the lower rendered-image (which gets marked in green). The top window will tell you the delta x/y you need.
  • From the main menu, select: 2. Manual align
    • Choose the landmark
    • Provide the x/y
    • Select 0 to end
• Continue these options to align the landmark until they are all correlating.

* Set the image to be used (i.e. remove the star) for all the landmarks

• From the main menu, select: 4. Change flags
• Input number to change (a chg all, b use all, 0 to end) -- select b

* Exit autoregister

• From the main menu: 0. Exit
• When prompted with: input 12-character picture name. q to quit -- select 0

Now practice autoregister the images that are listed in the toDoB.

AES Iterate

Now that we've pulled in extra information, we need to iterate to get the information propagated to all the files

This is the first time you're working with batch processing, so a few comments:

• First, you need a "seed" file which are the commands that will be fed into whichever program you are running. Typically, it will be called make_scriptP.seed or something similar with a different letter (P, R, A, F, T, AP, RP).

• Second, you (normally) need a list of landmarks or images that will be processed. That is stored in make_script.in. There are many ways to make this list of landmarks/images that you will use. Just be sure of two things. A -- Have the word "END" at the end of the file as the last line. B -- If you are processing images, there *MUST* be a space in front of the image name (PICTLIST.TXT has this structure, so you can copy that)

• Third, you will run one of the "script makers" to create a bunch of input files (<filename>.INN) and a file called "run_script.b". The run_script.b contains the commands to batch run all of the individual files. In the case of the parallel processing (multiple threads at once), you will get a bunch of run_script#.b (e.g. run_script1.b, run_script2.b, etc.)

• Fourth, run_script.b is a unix shell script, but because it is made by FORTRAN, it is not an executable so it will not run by itself. This can be handled one of two ways:
  • Make the file executable: chmod u+x run_script.b
  • Run the command using the "sh" command: sh run_script.b
  • For an AES iteration, I suggest using using the output of make_scriptP into a file, then running that. That way, all of the run_script#.b will start (see the procedures)
• Steps/Procedures for AES iteration
  • Setup

    • INIT_LITHOS.TXT -- Update the number of processors on your computer. You set USRMX=4

    • MAKE_LMRKLISTX -- This makes the LMRKLISTX.TXT which pre-generates the positions of landmarks to make SPC run faster

    • tail -30 LMRKLIST.TXT > LIST.TXT

      • Normal procedure would be, "cp LMRKLIST.TXT LIST.TXT" but that will take too long, so we are going to do a shortened version

    • duplicates - This reads list, sorts the file, removes duplicates and creates make_script.in

    • ln -s scripts/Piterate1ShSt.seed make_scriptP.seed

    • make_scriptP > run.sh

  • Running
    • sh run.sh -- Starts the AES iteration
  • Finished
    • find_nofitP -- When the AES iteration is done, use this to review for landmarks that need to be fixed.

    • iterateEval.sh -- An additional tool that provides different information extracted from the outputs files (<landmarkname>.OOT)

Create a higher resolution

Here we want to cover an entire region (a bigmap) with landmarks. We will use a pre-made bigmap that is located in the lsupport directory -- lsupport is local support where you can put local and temporary files.

This is the second batch process we will be using. Much of it is similar the the others with one big exception. The seed file does not have a standard format, but is defined within make_scriptT.in.

Tiling is the one procedure that requires you do know a bit more about the structure of the control files than most of the other programs. In the other programs, you make a list of items and you do a make_scriptP command and all the input files are created.

For tiling, we use the file make_scriptT.in. This file contains the name of the BIGMAP that provides the location reference. It also contains the name of the seed file. Then it has a list of all of the x/y position in which to create landmarks, typically every 50 pixels. Note, if an entry has a # symbol, that is a comment and that location will be skipped. The top part of an example file is below:

make_scriptT.in

BIGEQ1
lsupport/bigmap-XXX120.seed
     100  150
#    150  150
     200  150
     250  150
#    300  150
     350  150
...

When you run make_scriptT it will generate a bunch of inputs files (starting with 001.INN and counting up) and the run_script.b that you need to run it. For this work, I will email a file to be used as for both make_scriptT.in and the seed file. Put both of the files into "lsupport".

For this special case of tiling, we will be using a bigmap named "BIGEQ1" that we will have to create. We will run the bigmap routine and view it. Once done, we will use the pregenerated files so you can see how it works and let it run overnight.

• Steps/Procedures
  • Setup
    • Create the bigmap. Run:

      • bigmap < lsupport/BIGEQ1.in

      • This will run for about 30 seconds. What it is doing is using all of the maplets that fall within the lat/lon boundaries and combine them into a large square map files. In this case, it is 401 x 401 pixels large.
    • Link the bigmap to a generic name so SPC will use it.
      • cd MAPFILES
      • ln -s BIGEQ1.MAP XXXXXX.MAP
      • cd ..
    • Review the bigmap. Before we run, we can check that things are ready to go by making an image of the bigmap. Run the following command:
      • showmap
      • XXXXXX
      • Review XXXXXX.pgm

    • Set the make_scriptT.in file to be the input that we want.

      • ln -s lsupport/tile-120-input
    • Generate the input files by running

      • make_scriptT

      • You will generate a large number of input files for lithos, starting at 001.INN and going up.
  • Running
    • sh run_script.b
      • This will take a long time to run.
      • You can review the progress by looking at the LMRK_DISPLAY1.pgm or SPC Web tools

      • You can watch the output by running "tail -f <file>.OOT"

    • When complete, you can review for errors

      • find_nofitT

      • This will tell you if you have misaligned images or if landmarks couldn't get enough images

Tiling by BIGMAP

Block 6B - Bigmap Tiling v2

• Making a bigmap

  • Criteria for size, scale
    • Lat: -10
    • Lon: 350
    • Q size: 500
    • GSD: 25

  • Create support/RPI001.in

  Note - we use XXXXXX.MAP to allow for scripting. I use symbolic links to aid in keeping track of progress. By running showmap after building and linking the bigmap, you can prove that you have the correct map.

  bigmap < support/BIG001.in
  cd MAPFILES
  ln -s RPI001.MAP XXXXXX.MAP
  cd ..
  echo XXXXXX | SHOWMAP
  convert XXXXXX.pgm lowMap.jpg

Checking for existing maplets

  map_coverage
  XXXXXX
  0 .0005
  convert coverage_m.pgm preCoverage.jpg

Building the make_scriptT.in file

• Build the make_scriptT.in file

  • This includes some shell commands to make something you can copy/paste. Or you can use a text editor to build the make_scriptT.in, just make sure it follows the correct format for map-based referencing.

  echo N | make_tilefile > tmp
  echo XXXXXX > support/bigmap_tile.in
  echo scripts/XXX035.seed >> support/bigmap_tile.in
  sed 1d tmp >> support/bigmap_tile.in
  ln -s support/bigmap_tile.in make_scriptT.in

Run Tiling

• Run the tiling script. Once you make the INN files, you can track the progress *.OOT files.

    make_scriptT
    sh run_script.b
    find_nofitT

Evaluation of the bigmap

Now that it is done, you can rebuild the bigmap and see the difference

  bigmap < support/BIG001.in
  echo BIG001 | SHOWMAP
  convert BIG001.pgm highMap.jpg

map_coverage
BIG001
0 .0005
convert coverage_m.pgm postCoverage.jpg

• SIGMAS.TXT

• SIGMAS.pgm

Build a shape model

• ICQ format
• DENSIFY.TXT

• densify

• dumber

• buildShape.sh - runs all of the commands as needed

Blocks

We have provided some procedural blocks for different tasks. They include some additional log and configuration that will be different from you, but the main SPC steps are the same. Additionally, Bob has some "PROCEDURES" directory with his source code. There are instructions there and copy/paste commands.

SPC Blocks, V2

Batch Processing

Batch Register

• register

  • Practice
  • Batch

    • Clear out old TESTFILES and TESTFILES1

      • rm TESTFILES*/*

    • make_script.in

      • This must be created from the new list of images
      • Make a file of new image names and write them into make_script.in (with a proceeding space and the last line "END")
    • ln -s scripts/make_scriptR_01.seed make_scriptR.seed

    • make_scriptR

    • sh run_script.b
    • find_nofit

Batch Autoregister

• Batch associate existing landmarks to new images

  • When you bring in new images, they have no landmarks. While you can add them into landmarks using lithos, that is not very productive. Thus, we use a program autoregister that loads all of the landmarks into the image you are working with.

  • autoregister

    • make_lmrklistX

    • Practice -
  • Batch

    • make_script.in -- This must be created from the new list of images

    • ln -s scripts/make_scriptA.seed make_scriptA.seed

    • make_scriptA

    • sh run_script.b

System Evaluation

• RESIDUALS.TXT

• MAPINFO.TXT

• PICINFO.TXT

Support Files

• Review metadata and data files

  • IMAGEFILES

    • format -- 8bit, 16bit, 32bit

  • NOMINALS

  • SUMFILES

  • make_sumfiles.txt

  • INIT_LITHOS.TXT

  • LMKFILES

AES Iterate over region

This uses the fact that you recently made a bigmap as inputs for running a region-specific iteration. Remember, duplicates takes whatever list of landmarks in LIST.TXT, sorts them, removes duplicates and replaced make_script.in. USED_MAPS.TXT is created by bigmap, along with USED_PICTS.TXT. This contains all of the mapfiles that were used in building the bigmap.

  make_lmrklistX
  rm TESTFILES*/*
  cp USED_MAPS.TXT LIST.TXT
  duplicates
  make_scriptP > run.sh
  sh run.sh
  find_nofitP