WIKI for Bob Gaskell's StereoPC

General Info

Stereophotoclinometry is a suite of tools developed by Dr. Robert Gaskell that takes spacecraft images and allows the construction of pixel-for-pixel level shape models (Digital Terrain Models, DEM). This software is the intellectual property of the Planetary Science Institute (PSI). SPC is available for scientific research under a non-distribution licensing agreement to US citizens. Please contact Eric Palmer ([email protected]) for information of access, training and the fee schedule.

Development

This is a wiki of some of the key programs and support files for Stereophotoclinometry. The wiki contains information derived about SPC during the Dawn mission, the Mercator Project and the OSIRIS-REx mission. There are different versions of the software, so there may be things that are different or not supported in your version, depending on what your version is. If you have suggestions or wish to help improve this document, please contact Eric Palmer to give you access.

Short Cuts

OREx Software - Clearing house for specifics of OREx
Training_Notes - Eric's class notes and training guide
Error_evaluation - How to evaluate things for error and consistency
- Normalized Cross-Correlation Evaluation
- Normalized Cross-Correlation Evaluation - Naming Conventions
Working_directories - What is needed in a working directory and things that can be removed
Links_to_SPOC -- There are too many difficult-to-find links at the SPOC. Here's a list
DART - DART-specific programs and procedures

Documentation

SPOC v3.02A PDF
SPOC v3.02A html directory
User's Manual users_manual_3.0.pdf
Excerpt from submitted paper using SPC palmers_description.pdf
Software reference - Details about specific routines

Versions

1.0 -- Initial version of SPC
2.0 -- Version of SPC with the Common library created
2.1A7 -- This is the baseline version of Gaskell's software. SubComponent testing has been performed on this version
3.0 -- Core SPC baseline. Has been given Class B certification. It includes the following pieces
- 3.0A0 -- These have changed required in SPC to finish the SubComponent testing. It changed regres, process_fits and geometry
- 3.0A1 -- Released by Bob in support of Dawn @ Ceres and are not in the SPOC software branch.
- 3.0A1a -- Minor changes
- 3.0A2 -- process_fits that supports NavCam
3.0.1 -- SPC updated for processing OREx Level 0 images
3.0.2 -- SPC updated for a bug in autoregister
3.1 -- (in progress) Will have all code improvements from Rosetta and include Polar Wobble. Will receive regression testing.
configure_control
X-Files -- This is a branch of the SPC code used to support line-scanning imagers (LRO, MRO, MOC, etc.)

Support Tools

Support Tools - Useful tools that aid the SPC process developed by the OREx SPC team
updateDisplay - aid for landmark/maplet visualization
spc_tools - javascript suite of tools that provide a GUI for SPC

Procedures

These are the "standard" blocks (or procedures) that can be used to do the most typical SPC tasks.

General Procedures - Procedures to use for all objects (early version that needs more detail)
SPC Blocks, V2 - OSIRIS-REx Operatons
SPC Blocks, V1 - OSIRIS-REx Testing (F3)
Lunar_Procedures - How to process LRO
- Lunar DTM Status - What is the current status and holdings
Mercury Procedures - Procedure unique to Mercury
- Mercury DTM Status - What is the current status and holdings
CASSINI Procedures - How to work with CASSINI data
- CASSINI DTM Status - What is the current status and holdings
Convert MAP - Instructions on how to convert a MAP file to other formats
Convert ICQ - Instruction on how to convert an ICQ file to other formats
Archiving SPC - Instructions on tools and techniques to generate more general DTM products
Calibration - How to check for various image calibrations.

Programs

Lithosphere

Program	Category	Version	Description
autoregister	Cat B	v3.0	Adds groups of landmarks to an image.
autoregisterP	Cat B	v3.0	Adds groups of landmarks to an image using parallel processing.
blemishes	Cat B	v3.0	Masks regions of an image which contain blemishes due to, for example, downlink errors, bad pixels, or a cosmic ray hit.
dynamics	Cat B	v3.0	Appends inertial position deltas between consecutive images to NOMINALS used to constrain the spacecraft position.
geometry	Cat B	v3.0	Solves a surface using spacecraft position, camera pointing, and landmark location.
lithos	Cat B	v3.0	Aligns maplets to the current shape model and provides slight changes to the shape (stored in MAPFILES).
lithosP	Cat B	v3.0	A version of lithos intended to be used in batch processing (i.e. run in parallel).
make_sumfiles	Cat B	v3.0	Builds the NOMINALS and SUMFILES.
new_pole		v3.0	Updates landmark center locations and map frames, and the S/C position/pointing and Sun vector, for new (user input) RA, DEC, PM, and OMEGA.
omega		v3.0	Calculates the angular velocity of a body's rotation using the location of landmarks in consecutive images.
pole	Cat B	v3.0	Updates landmark center locations and map frames, and the S/C position/pointing and Sun vector, for new RA, DEC, PM, and OMEGA (found in input file POLE.TXT).
process_fits		v3.0	Converts FITS image files to .DAT files and generates the make_sumfiles.in file required by make_sumfiles.
register	Cat B	v3.0	Aligns a new image with a known object.
regres	Cat B	v3.0	Generates a set of ascii interface files containing optical navigation observables, partials, and relevant ancillary information for use in the FDS navigation software suite(s).
residuals	Cat B	v3.0	Calculates a number of statistics useful for assessing the performance of the DTM.
shift	Cat B	v3.0	Shifts the center-of-figure of a shape model.
limber	N/A	v3.0	Builds an initial shape model from a rotation movie.

Coverage

Program	Category	Version	Description
coverage	Cat D	v3.0	Shows the global coverage that has been processed by resolution.
map_coverage	Cat B	v3.0	Shows the coverage that has been processed by resolution.
coverage_p	N/A	v3.0	Shows the coverage of images over the whole surface.
map_coverage_p	N/A	N/A	Shows the coverage of images over a bigmap.

Imager

Program	Category	Version	Description
display	Cat D	v3.0	Generates an image that shows the location of landmarks on it.
image_map_mono
image_map_rgb	Cat D	v3.0	Renders a 3D image of a bigmap using red and blue.
image_map_stereo	Cat D	v3.0	Creates an image from a bigmap that shows the surface, using low-tech stereo.
Imager_MG	Cat D	v3.0	How to make images from maplets.
Imager_Grid	Cat D	v3.0	How to make images from shapemodel.
mosaic			Creates a mosaic of images registered to the shape model.
panaroma			Makes a 360 degree panaroma image from a big map.
showmap	Cat D	v3.0	Generates an image (.pgm) for a specific bigmap.
surface_imager			Makes an image using a surface point of view from a big map.
view_shape	Cat D	v3.0	Generates a point-of-view image of the shape model.
view_map_rgb	None		Shows a bigmap rendered with albedo, and you can set the sun angle.
view_map_stereo	None		Shows a bigmap rendered with albedo as two images -- cross your eyes.

Shaper

Program	Category	Version	Description
bigmap	Cat B	v3.0	Processes maplets to form a bigmap.
bigmapL	Cat B	v3.0	A 'bigmap lite', used in the production of Zmaps.
densify	Cat B	v3.0	Increases the resolution of a shape model by interpolating heights between landmarks.
densifyA	Cat B	v3.0	Increases the resolution of a shape model using albedo between landmarks.
shape_info	Cat B	v3.0	Generates DTM information.
spheremapsB	Cat B	v3.0	Transforms maplet data from DTM to common formats and map projections for export.

Script Makers

Script Makers Overview - User guide for the script-maker program suite

Program	Category	Version	Description
find_nofit	Cat B	v3.0	Searches batch processing output files to identify landmarks or images which may need further work.
find_nofitP	Cat B	v3.0	Searches make_scriptP output files to identify landmarks or images which may need further work.
find_nofitT	Cat B	v3.0	Searches make_scriptT output files to identify landmarks or images which may need further work.
make_scriptA	Cat B	v3.0	Generates the script that batch auto registers images using autoregister.
make_scriptAP	Cat B	v3.0	Generates the script for batch autoregistering images using parallel processing using autoregisterP.
make_scriptF	Cat B	v3.0	Generic script maker for user-generated batch processing jobs using lithos.
make_scriptP	Cat B	v3.0	Generates the script for iterating landmarks using lithosP.
make_scriptR	Cat B	v3.0	Generates the script that batch registers images using register.
make_scriptT	Cat B	v3.0	Generates the script that tiles (makes new maplets) using lithos.
MAKE_TILES	Cat B	v3.0	Generates the in file required to make Zmaps using bigmapL.
MAKE_TILESP	Cat B	v3.0	Generates the in files required to make Zmaps using bigmapL in parallel.

Recovery

Program	Category	Version	Description
refresh_sumfiles	Cat D	v3.0	Updates the sumfiles to match the maplets.

Utilities

Program	Category	Version	Description
duplicates	Cat B	v3.0	Generates the make_script.in file to accompany script makers such as make_scriptP, comprising an ordered list of unique landmark names.
Export_Import	Cat B	v3.0	Builds scripts to package up the new maplets/landmarks into a tar ball and to unpack maplets/landmarks and integrate into a master directory.
make_list	Cat B	v3.0	Looks for image names matches between LIMBLIST1.TXT and LMRKLIST.TXT.
make_lmrklistX	Cat B	v3.0	Generates LMRKLISTX.
make_pictlistX		v3.0	Builds the file PICTLISTX.TXT which makes things run faster.
make_tilefile	Cat B	v3.0	Generates the pixel/line maplet-center locations required to complete the tiling of a bigmap.
rem_done	Cat B	v3.0	Used to stop a parallel lithosP process and find which landmarks have yet to be worked on.
update_infiles			Generates a list of landmarks and headers for showing coverage.
trimmer	DART v1.0		Similar to limber but provides controls for adding and removing to the shape.
equalize	DART v1.0		Repositions vertices in a shape model to make them more evenly spaced.
shape_coverage	DART v1.0		Determines areas of the shape model covered by maplets meeting specific criteria.
stella	DART v1.0		Looks at stars.
distortion	DART v1.0		Solves for the distortion matrix.

Gravity

Notes_on_Gravity

Program	Category	Version	Description
Mgrav			Makes MGRAV.TXT and generates gravity images based on a map or bigmap.
Sgrav			Makes a file called SGRAV.TXT that is like SHAPE.TXT but with extra columns for surface acceleration, potential and laplacian (just as a check). Based on a shape model. This is for a non-rotating body with GM=1.
Sacc			Provided the correct GM and Omega, it will use SGRAV.TXT file to create the surface acceleration.
Selv			Provided the correct GM and Omega, it will use SGRAV.TXT file to create the surface elevation (same as geoid).
Slap			Provided the correct GM and Omega, it will use SGRAV.TXT file to create the surface laplacian.
Spot			Provided the correct GM and Omega, it will use SGRAV.TXT file to create the surface potential.
Sslpa			?

Directories

Directory	Description
BIGFILES	Directory for BIGMAP LMK files.
DATA	A place for the SPICE kernels.
IMAGEFILES	Directory that holds the image files, .DAT.
LMKFILES	Stores the actual landmarks, .LMK.
MAPFILES	Stores the maplets, .MAP.
NEW_IMAGES	Directory that holds the new, and unprocessed image files (in pgm format).
NEW_FILES	Directory that includes new maplets and landmarks files when using Export_Import
NOMINALS	Directory that holds the nominal files, .NOM.
SHAPEFILES	Holds the different types of shapefiles.
SUMFILES	Directory that holds the sumfiles, .SUM.
TESTFILES	Directory to store display files generated during batch processing jobs.
TESTFILES1	Directory to store display files generated during batch processing jobs.
UTILITIES	Programs that are specific for this project.

Key Input Files

File	Category	Version	Description
BIGLIST.TXT			List of all bigmaps contained the the BIGFILES directory created by bigmap.
INIT_LITHOS.TXT	Cat B	v3.0	Initialization file for lithos.
LMRKLIST.TXT			The full list of landmarks.
make_sumfiles.in			Image information generated by process_fits and required by make_sumfiles to generate NOMINALS and SUMFILES.
make_sumfiles.txt			User-generated SPICE configuration data required by make_sumfiles to generate NOMINALS and SUMFILES.
PICTLIST.TXT			List of the images that are in the model, required by lithos.

Support Files

Usually these files are used to run batch jobs or scripts.

File	Description
make_script.in	List of landmarks or pictures to process used by various script-makers for batch jobs.
make_scriptA.seed	Seed file for make_scriptA, the script-maker for batch autoregistering new images.
make_scriptF.seed	Seed file for make_scriptF, the script-maker for batch processing using lithos.
make_scriptP.seed	Seed file for make_scriptP, the script-maker for iterating landmarks using lithosP.
make_scriptR.seed	Seed file for make_scriptR, the script-maker for batch registering new images.
make_scriptT.in	Used by make_scriptT to build run_script.b.
MAPTRANS	Diagnostic tools to visualize maplet translations.

Other Input Files

File	Description
BIGMAP.IN	Optional file containing a list of landmarks for use with bigmap.
DYNAMICS.TXT	Contains different uncertainty values and coordinates frames for different mission phases.
GEOID.TXT	Gives the geoid in X, Y, Z position. A 3 column file.
IFRAME.TXT	Contains J2000 nominal spacecraft to object center vector and camera orientation, created by make_sumfiles.
LIMBLIST1.TXT	List of images required by make_list.
LMRKLIST1.TXT	List of newly created landmarks.
LMRKLISTO.TXT	List of landmarks that overlap a bigmap.
LMRKLISTR.TXT	User-generated restricted list of landmarks used by lithos.
LMRKLISTX.TXT	Summary of landmark information generated by make_lmrklistX and used by lithos and lithosP to find overlaps.
MAPLIST.TXT	User-generated list of maplets required by Imager_MG, MAKE_TILES and spheremapsB.
MGRAV.TXT	Produced by Mgrav.e. It contains vector position, potential, acceleration, slope and delta elevation.
MOSAIC.TXT	A list of images that mosaic uses to build a moasic.
OVERLAPS.TXT
PICTLISTR.TXT	User-generated restricted list of pictures used by lithos or regres.
PICTLISTRX.TXT	User-generated restricted set of data contained in PICTLISTX.TXT.
PICTLISTS.TXT	User-generated alternative list of images used by residuals and geometry.
PICTLISTX.TXT	List of the images that are in the model with precomputed metadata, generated by make_pictlistX.
SEEDS
SEEDS (by mission)
SGRAV.TXT	Produced from Sgrav.e. Similar to SHAPE.TXT with extra columns for surface acceleration, potential and laplacian (just as a check).
SHAPE.TXT	The shape model of the object. Done is 3 column format of vertex using x, y, z coordinates.
SHAPEC.TXT	Gives the height above the surface. A 4 column file.

OSIRIS-REx Specific Input Files

File	Description
DN2TEMP.TXT	Parameters to DN to physical temperature for process_fits
SCOBJ_SHIFT.TXT	Apply a spacecraft center-of-mass adjustment to focal plane for make_sumfiles
TMP2FOCLEN.TXT	Parameters to adjust the focal length based upon temperature for make_sumfiles
BIAS.TXT	Adjustment to the spacecraft in inertial space for make_sumfiles
FLATFILES.TXT	A list of the flatfiles for the calibration of Level 0 data

Key Diagnostic Files

File	Description
LMRK_DISPLAY1.pgm	Shows the paring between images and the illuminated shape model
INSIDE.TXT	List of only the maps that are inside of the most recent bigmap created.
LIMINFO.TXT	Limb information output by residuals.
MAPINFO.TXT	Maplet information output by residuals.
PICINFO.TXT	Picture information output by residuals.
RESIDUALS.TXT	Maplet and image error information output by residuals.
SIGMAS.TXT	Sigma values for bigmaps, output by bigmap.
SIGMA.TXT	ICQ format shape model with sigma values.
USED_MAPS.TXT	Maps used when making a bigmap, output by bigmap.
USED_PICS.TXT	Images used when making a bigmap, output by bigmap.

Other Output Files

File	Description
check.txt	List of landmarks and overlaps output by residuals for landmarks whose linear residual is greater than the user-specified limit.
EMPTY.TXT	lithos seed file output by residuals for batch deletion of landmarks which are not contained in any pictures or limbs.
FLATLIST.TXT	List of flat maps (landmarks containing no topography) output by residuals.
LMKVECS.TXT	Landmark vectors output by residuals for every landmark contained in LMRKLIST.TXT.
MAPCHK.TXT	List of maplets whose difference between predicted and observed pixel/line locations in attached images is greater than a user-specified limit, or who have two or fewer overlaps attached to them, output by residuals.
MAPRES.TXT	Maplet resolution information for maplets contained in at least one picture or limb, output by residuals.
New_Limbs.in	lithos seed file output by residuals to attach map to limbs for every landmark contained in LMRKLIST.TXT.
NEW_LIST.TXT	List output by find_nofitT of new landmarks created during batch make_scriptT tiling.
no_update.txt	List of landmarks output by residuals whose associated pictures are not listed by increasing mission time in the .LMK file.
OVERLAPS.TXT	Temporary file generated by lithos.
PRUNE.TXT	List of landmarks for which the number of pictures in which they are contained exceeds the default limit of 500, or the user-specified limit, PRNLM, set within INIT_LITHOS.TXT. File output by residuals.
RANGES_SOLVED.TXT	Date and range information output by residuals for each picture listed in PICTLISTS.TXT or PICTLIST.TXT.
redo.txt	List of landmarks output by find_nofit or find-nofitP which after batch lithos or lithosP processing either terminated in error, did not correlate with at least one image, or correlated weakly with at least one image.
REMOVED.TXT	List of landmarks output by find_nofit which after batch register, autoregister, or autoregisterP processing were eliminated from at least one picture due to low or no correlation.
SHAPE.TXT	ICQ format shape model output by densify.
veto.txt	lithos seed file output by residuals to detach from landmarks and limbs a map with a linear residual greater than the user-specified limit.

Deprecated

process_img - takes a list of files and creates make_sumfiles.in. Creates IMAGEFILE for each images
view_maps.in - A list of all the maplets to be used in view_maps. The first line isn't read. The file should be terminated with "END"
view_maps - This will do "paper mache" of all the maplets listed in view_maps.in.

Old_landing_page

Help

Contact me with questions. Email: <epalmer AT SPAMFREE psi DOT edu>

Links to wiki formatting and help https://moinmo.in/HelpOnMoinWikiSyntax

CategoryHomepage