Skip to content

Home

Jump to bottom
Eric E Palmer edited this page Oct 23, 2026 · 4 revisions

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 (epalmer@psi.edu) 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

Documentation

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.

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

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.

Help

Contact me with questions. Email: epalmer@psi.edu

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

Clone this wiki locally