This user manual includes overviews, procedures and reference for executables, directories and files associated with the SPC (Stereophotoclinometry) software. This users manual was developed in part to fulfill the requirements defined in NASA Procedure Requirement 7150.2A and specifically Software CDRL SW10 explicitly called out in the OSIRIS-REx Project Software Management Plan 0007.
Tools and Installation
The SPC is FORTRAN toolkit to support optical navigation and scientific study of small bodies. The primary purposes of these executable programs are to:
- Ingest OSIRIS-REx camera images and characterize any errors in the camera pointing, spacecraft and asteroid position, asteroid control point location and/or rotational kinematics that may lead to navigation errors. These residuals or errors will be reformatted and written out to a file (REGRES file), which will be used as one of the inputs into the MIRAGE navigation program.
- Generate numerous data products that will be used for scientific research and analysis, such as the Bennu shape model and high-resolution terrain maps. These products will be used to aide in the sample site selection.
Building and installation of the software is described in UA-HBK-9.4.4-206_SPOC SPC Toolkit Build Instructions. That document describes the operating system, compiler and libraries needed to install SPC from source code. SPC executables can be used to process data without the install, but it is recommended that the directory structure laid out in the Toolkit Build Instructions be followed.
This manual applies to all SPC software versions up through 3.0, including the development versions 2.1A7, 3.0A0 and 3.0A2. The version 3.0A2 release is based on the 2.1A7 module versions with the exception of PROCESS_FITS, GEOMETRY, and REGRES which are at module release level of 3.0A0, 3.0A0, and 3.0A2 respectively. Future builds will bring all modules to a consistent release version to eliminate any confusion.
The SPC Users Manual is intended for trained users who have some supervised training and experience using the programs described here. This manual cannot take the place of experience and time with an instructor who has a deep knowledge of the program and its use. Capable users must develop intuition and insight into the process of building shape models with SPC through practice, and this manual alone cannot provide that insight.
This manual requires that the user have gone through the initial SPC training and have demonstrated Level 1 and Level 2 of the SPC User Skill Levels as described below.
SPC User Skill Levels
Level 1 - Introduction to SPC and the most basic tasks with landmarks.
- Create a landmark
- Add images
- Autoremove images
- Build template
- Select images
- Show which ones
- Align with image
- Align with gradients
- Just using defaults
Level 2 - Basic user - Basic ability to do SPC's most key functions. Can support operations under direct supervision of a fully-trained SPC user. Can run most key SPC functions, but requires help bridging gaps.
- Building workspaces
Lithos -> find
- Batch landmark generation
- Batch Run
Level 3 - Experienced User - Capable of doing all essential functions of SPC to process data and build shape model. Can run most of a project, but would need support for initial setup and trouble shooting.
- Establishing and Verifying Connections
- Build Shape
- ICQ format
- Ingesting images
- Makesumfile.txt -- adding kernels
- Advanced landmark techniques
- Setting normal
- Options for solving the height
- Landmark resize
- Replacing topo with map or shape
- Troubleshooting problem landmarks
- view_shape (geometry.in)
Level 4 - Expert User - Capable of executing all functions needed to run a SPC project, to include configuration, kernel management and navigation.
- Run a full project
- Define configuration files and keywords
- Setup SPICE
- Spacecraft uncertanity
- Distortion field
- Coordinate frames
- Integration with navigation
Level 5 - Expert Developer. Understands the internal structure of SPC's code and file format in order to make software changes.
- Advanced troubleshooting
- Modifications to SPC code
- Make updates to process_fits/img
- Creating SUMFILES/NOMINALS using non-SPICE geometric data
- Error propagation
This manual does not provide detailed trouble shooting assistance.
What This Manual Includes
Each procedure or reference entry
- provides a general description of the item
- lists related files, directories, or programs
- explains input, output, or contents
- shows samples of input, output, or contents
Some entries include additional references and more detailed information.
How This Manual Is Organized
Part I: Overview
This section provides an overview of SPC and the purpose of the software.
Part II: How Tos
This section organizes the common activities the software is used to achieve into blocks of specific procedures.
Part III: Reference
This part includes reference entries for executables, directories and files. It is arranged alphabetically and subdivided into these sections:
- Input Files
- Output Files
- Support Files
How Standard Items Are Identified
Throughout this manual, we have used these systems for marking the items we discuss:
Names of programs, directories, and files - These usually appear as hypertext links because they are entries in this manual. In the interactive version of the manual, you can click on the link to find out more specific information.
Names of programs, directories, and files - These appear in bold in the entry where they are discussed. This is used instead of hyperlinking to avoid circular references.
Names of DIRECTORIES - These are written in ALL CAPS followed by /.
Names of files - These may appear in ALL CAPS, mixed case, or all lower case, depending on how the filename appears in the software.
<XXXX> - This indicates that all or part of a filename or directory is required. The actual characters depend on your input or are automatically filled in by the program.
User keyboard inputs - These are shown in 'single' quotes. You should type what is in the 'single' quotes and then hit the Enter key. 'Enter' means just hit the Enter key as the input.
CRITICAL MESSAGES APPEAR LIKE THIS! You should pay particular attention to these to avoid data loss or other errors.
Warnings like this tell you actions you must take or information you should consider before you continue.
Information notes like this provide you with details and explanation that can help you understand the topic presented.