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)
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
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:
- 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
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
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.
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)
- Setup
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 make_scriptT.in
- Generate the input files by running
- You will generate a large number of input files for lithos, starting at 001.INN and going up.
- Create the bigmap. Run:
- 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
- This will tell you if you have misaligned images or if landmarks couldn't get enough images
- sh run_script.b
- Setup
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)
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.
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 old TESTFILES and TESTFILES1
- 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
- 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
- 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.
- Practice -
- Batch
make_script.in -- This must be created from the new list of images
- ln -s scripts/make_scriptA.seed make_scriptA.seed
- 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.
Tiling by BIGMAP
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.
- Criteria for size, scale
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
Build a shape model
System Evaluation
Support Files
- Review metadata and data files
- format -- 8bit, 16bit, 32bit