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

BIGEQ1lsupport/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 make_scriptT.in

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

Day 3

Please switch to D---postTiling branch of the repository.

Review Tiling

Yesterday, we launched a tasks that can run for a long time. I took steps to keep it from being too long, but the typical time needed to tile a medium sized BIGMAP with as many images as we have could be 5 hours. I have run the system and will review the results, which is in branch "D---postTiling".

We will look at the commands:

showmap -- This does a simple display of the bigmap. Save a copy

Check coverage -- This evaluates how much of the bigmap is covered at the requested scale. This lets you see if something was missed (maybe a landmark failed to be created or there is a gap between landmarks)

map_coverage

BIGEQ1 -- This is the name of the bigmap

0 .0015

-- These are the min/max values.

Any maplets that fall within this range will be counted.

You can look at the resulting image, coverage_m.pgm

open coverage_m.pgm

bigmap -- Rerun

bigmap < lsupport/BIGEQ1.in

Rerunning bigmap brings the new (and higher quality) data into the DTM. Now the bigmap is ready to be used for whatever is needed.

showmap -- See what changed changes.

view_map_rgb -- useful way to view a bigmap

view_map_stereo -- useful way to view a bigmap

USED_MAPS.TXT -- When you build a bigmap, it will give you a list of every landmark (maplet) that was used in the process

USED_PICTS.TXT -- When you build a bigmap, it will give you a list of every image that was used in the process

INSIDE.TXT -- When you build a bigmap, this is every landmark (maplet) that fits fully inside of the bigmap. None of these are on the edge.

You can see how many items are in each file by using:

It gives you an idea of how big things are.

wc USED_MAPS.TXT USED_PICTS.TXT INSIDE.TXT

Errors in SPC

There are times when SPC has a glitch and something needs to be fixed. I've created this page as a list of problems and known solutions. If you find things that should be added, please let me know.

Fixing Glitches in SPC

Daily Practice

File "toDo-clean" has a listof landmarks that need attention.

Please clean at least 5.

File "toDo-register" has a list of images that need to be registered.

Please register the first 3.

The others will be done in batch later.

Batch Processing

Batch Register

We are going to improve the registration of some of the images by running batch register. You will find the list in todo-register in branch D---postTiling.

Steps/Procedures

Clear out temp data from the old run

sh rem_script.b

rm TESTFILES*/*

You must make the make_script.in file

cp todo-register make_script.in

Now, edit make_script.in to have the word "END" at the bottom and only the images you want to use.

Now link the seed file you want to use to control register. Most scripts are in the "scripts" directory, but you may want to make mission-wide scripts, which I put in "support". For ones that I don't expect other people to need and don't think are worth letting everyone know about, I put those in "lsupport."

ln -s scripts/make_scriptR_01.seed make_scriptR.seed

Run the script making command

make_scriptR

Now it is ready to run

sh run_script.b

While it is running and then at the end, you can check how well it worked by running find_nofit

find_nofit

Batch Autoregister

We are not going to practice batch autoregister. These instructions are here so you can try it yourself. It is pretty straight forward and works just like batch [[register]

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

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.

Note: These were crafted for the OSIRIS-REx mission to ensure that the shape model was created with known and understood procedures. It is acceptable to deviate from them, but we wanted to have most of the work being done with established and tested procedures for consistency. Included in these blocks are specific data tracking steps that are not needed by SPC. They were put in so we recorded what the state was for the shape model as it progressed. These do not have to be done. However, many of these steps do provide a record for tracking what was done so that if there is an error, it can be identified and fixed.

SPC Blocks, V2

Build a shape model

Building the shape model, or global DEM, is one of main goals of SPC. Fundamentally, it is just resampling of the maplets that you've already created into a global model. SPC uses an uncommon, but highly efficient format called Interconnected Quadrangles(ICQ). Rather than the typical large set of vectors and triangular plates, these define a systematic series of rectangles in a much smaller file format.

ICQ format -- A description can be found: https://sbnarchive.psi.edu/pds4/non_mission/gaskell.ast-itokawa.shape-model_V1_1/document/icqm.txt

DENSIFY.TXT -- Dr. Gaskell will use a lot of copy/paste to run his programs.

You may find a file called DENSIFY.TXT in some of the working directories.

These contain blocks of text that can be copy/pasted into the unix command window, sometimes with changes that are needed.

I have written a script that does this for you called buildShape.sh which is in your extraBin directory.

densify -- Densify will increase the resolution of the shape model by a factor of two by resampling the maplet data.

dumber -- Dumber is a tool to reduce the resolution of the shape model. To start with, you have previously built a low resolution model using low resolution maplets. Now let's bring in the new data from the high resolution maplets. We want to start fresh and not carry any existing errors or artifacts into the new model. However, we need a starting point. Thus, we will reduce the quality of the model by several orders of magnitude, then built it one resolution level at a time.

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

This is a script that will reduce the resolution of the model (to a Q of 16) and then build it back up by a factor of two until it reaches the desired level (usually 5 times).

This file is in extraBin of the SPC-Class-data directory

Run the command by:

buildShape.sh <version>

Example:

buildShape spc-15

It creates shape models in SHAPFILES with the prefix shape-<version>-Q. Example: shape-spc15-512

System Evaluation

To evaluate the model run:

residuals

10 .05 .05

You will get the following output files

RESIDUALS.TXT

MAPINFO.TXT

PICINFO.TXT

There are many more "system" files.

FLAT.TXT -- These are landmarks without topography

EMPTY.TXT -- This is a list of landmarks without images

RANGES_SOLVED.TXT -- The ranges of the images

There are more, but these are the important ones

Conditioning of Solutions

In SPC, we can take a large number of inputs to help improve the solution of the location of the landmarks, the spacecraft and its pointing. I'm not going into this very much because it is a sophisticated concept, but more information about this can be found:

Solution Conditioning

Support Files

Review metadata and data files

IMAGEFILES

format -- 8bit, 16bit, 32bit

NOMINALS -- The original position and pointing of the spacecraft. It also includes associated images if DYNAMICS is used.

SUMFILES -- The current summary of the image parameters (position, pointing and associated landmarks/limbs)

make_sumfiles.txt -- A list of values needed to convert from inertial coordinates to body-fixed frame. It contains a camera model, spacecraft SPICE numbers and lists of SPICE kernels.

make_sumfiles.in -- A list of all of the fits images, SPC names and calibration parameters

INIT_LITHOS.TXT -- The main configuration file for SPC

LMKFILES -- The place where we store the .LMK files.

DYNAMICS.TXT -- Allows you to connect an image to the ones before and after it (in the same arc) so that the other images can help constrain the spacecraft solution. It also allows you to change the uncertainity of groups of images.

BIGLIST.TXT -- A list of all of the bigmaps that SPC knows about

BIGFILES -- A similar directory to LMKFILES except it hold the bigmaps. The .MAP files are all stored in MAPFILES

Demo of other tools

monitor and monitord blockFinish.sh uberLithos

Bonus -- Phobos

While working with Ryugu is great, our mission is to Phobos. Dr. Ernst and Dr. Daly have graciously provided us with a copy of their SPC main directory that includes all the images, SPICE files and the working directory. This allows us to continue their work where they left off. We will be getting much higher resolution data, but this provides an excellent opportunity to become familiar with SPC using the data we will be starting with.

I have added you all to a new repository called Phobos-2022. This is using their shape model data as of March 2022. This has already been given to the MMX project, but I can also provide the full copy. This system is very large -- too large to be easily used. As such, for this repository, I have removed much of the images, keeping them over one region that we can use for practice. This makes it so you can download and use it easily. Then, when you are ready, you can get the rest of the data and continue your training and testing.

https://github.com/StereoPhotoClinometry/Phobos-2022

I have provided a list of landmarks that need to be fixed (cleaned). They are called todo-landmarks. These are actual misalignments (or weak shape topography) that need some attention. I suggest that you use the skills you've learned here to practice on this.

Possible practice

Note, if you try to look at an image that I removed (anything that is not in USED_PICTS.TXT), it will show up blank. You would need the other 20GB of image data.

Fix the landmarks

Build the bigmap (the bigmap definition is stored in lsupport/PIT001.in)

Run an AES iteration (you would use the list of maplets from USED_MAPS.TXT that is created by bigmap

Run residuals in order to see how well the model matches all the data

Don't suggest running geometry because the cameras that were used required specific custom tools in SPC. MMX will not need these tools so they have been neglicted.