16. Tools

This chapter provides a overview of the various tools that are provided as part of the Ames Stereo Pipeline, and a summary of their command line options.

• 16.1. add_spot_rpc
• 16.2. aster2asp
  • 16.2.1. Input formats
  • 16.2.2. Usage
  • 16.2.3. Output
  • 16.2.4. RPC height range
  • 16.2.5. References
  • 16.2.6. Command-line options
• 16.3. bathy_plane_calc
  • 16.3.1. Using a camera, a mask, and a DEM
    • 16.3.1.1. Preparation and running the program
    • 16.3.1.2. Handling adjusted cameras and alignment
  • 16.3.2. Using a DEM and an orthoimage mask
  • 16.3.3. Using a DEM and shapefile
  • 16.3.4. Using a DEM and lon-lat values
  • 16.3.5. Using a water-surface raster
  • 16.3.6. Using water height measurements
  • 16.3.7. Pick a sample set of points at the water-land boundary
  • 16.3.8. Acquisition of water height data
  • 16.3.9. Global tide models and water surface elevation
  • 16.3.10. Bathy plane definition and format
    • 16.3.10.1. Plain text bathy plane
    • 16.3.10.2. Georeferenced raster bathy plane
  • 16.3.11. Command-line options for bathy_plane_calc
• 16.4. bathy_threshold_calc.py
  • 16.4.1. Example usage
  • 16.4.2. Dependencies
  • 16.4.3. Command-line options for bathy_threshold_calc.py
• 16.5. bundle_adjust
  • 16.5.1. Examples
    • 16.5.1.1. ISIS cameras
    • 16.5.1.2. Maxar Earth cameras and GCP
    • 16.5.1.3. RPC cameras and image lists
    • 16.5.1.4. Pinhole cameras
    • 16.5.1.5. CSM cameras and outlier removal
    • 16.5.1.6. Bathymetry correction
    • 16.5.1.7. Other cameras
  • 16.5.2. Use of the results
  • 16.5.3. Camera adjustments and applying a transform
  • 16.5.4. Validation
  • 16.5.5. Handling failures
  • 16.5.6. Constraints
    • 16.5.6.1. Ground constraints
    • 16.5.6.2. Camera constraints
  • 16.5.7. Use cases
    • 16.5.7.1. Large-scale bundle adjustment
    • 16.5.7.2. Solving for intrinsics
    • 16.5.7.3. Well-distributed interest points
    • 16.5.7.4. Controlling where interest points are placed
    • 16.5.7.5. Using mapprojected images
  • 16.5.8. How bundle adjustment works
  • 16.5.9. Ground control points
    • 16.5.9.1. GCP file format
    • 16.5.9.2. Uses of GCP
    • 16.5.9.3. Effect on optimization
  • 16.5.10. Control network
    • 16.5.10.1. Match files
    • 16.5.10.2. ISIS control network
    • 16.5.10.3. NVM format
  • 16.5.11. Output files
    • 16.5.11.1. Reprojection errors per camera
    • 16.5.11.2. Camera position changes
    • 16.5.11.3. Changes in triangulated points
    • 16.5.11.4. Convergence angles
    • 16.5.11.5. Reprojection errors per triangulated point
    • 16.5.11.6. GCP report
    • 16.5.11.7. Image and camera lists
    • 16.5.11.8. Error propagation
    • 16.5.11.9. Camera positions and orientations
    • 16.5.11.10. Registration errors on the ground
  • 16.5.12. Format of .adjust files
  • 16.5.13. Command-line options
    • 16.5.13.1. General
    • 16.5.13.2. Interest point detection
    • 16.5.13.3. Interest point matching
    • 16.5.13.4. Match files and control networks
    • 16.5.13.5. Optimization
    • 16.5.13.6. Outlier filtering
    • 16.5.13.7. Camera and ground constraints
    • 16.5.13.8. Solving for intrinsics
    • 16.5.13.9. Camera initialization and transforms
    • 16.5.13.10. Mapprojection
    • 16.5.13.11. Error propagation
    • 16.5.13.12. Bathymetry correction
• 16.6. cam2map4stereo.py
• 16.7. cam2rpc
  • 16.7.1. Examples
    • 16.7.1.1. ISIS cub cameras for Mars
    • 16.7.1.2. Pinhole cameras and input DEM
    • 16.7.1.3. Datum for other planets
  • 16.7.2. Uses
  • 16.7.3. Validation
  • 16.7.4. Usage
  • 16.7.5. See also
  • 16.7.6. Command-line options
• 16.8. cam_gen
  • 16.8.1. Examples
    • 16.8.1.1. Pinhole cameras
    • 16.8.1.2. Optical bar cameras
    • 16.8.1.3. Fit a prior camera
    • 16.8.1.4. CSM Frame cameras
    • 16.8.1.5. CSM linescan cameras
    • 16.8.1.6. Fit CSM to Optical Bar
    • 16.8.1.7. Geodetic coordinates and angles
    • 16.8.1.8. Export RPC
  • 16.8.2. Further refinement
  • 16.8.3. Validation
  • 16.8.4. Command-line options
• 16.9. cam_test
  • 16.9.1. Examples
    • 16.9.1.1. CSM against itself
    • 16.9.1.2. Exact linescan vs RPC
    • 16.9.1.3. ISIS vs CSM
    • 16.9.1.4. DigitalGlobe exact vs RPC
    • 16.9.1.5. Pinhole model
    • 16.9.1.6. CSM ground-image roundtrip
    • 16.9.1.7. Bathymetry-corrected camera
  • 16.9.2. Usage
  • 16.9.3. Command-line options
• 16.10. camera_calibrate
  • 16.10.1. Overview
  • 16.10.2. Other tools
  • 16.10.3. Example
  • 16.10.4. How to use
  • 16.10.5. Command-line options
• 16.11. camera_footprint
  • 16.11.1. Save as shapefile
  • 16.11.2. Save as KML
  • 16.11.3. Project onto a datum
  • 16.11.4. Usage
  • 16.11.5. Command-line options
• 16.12. camera_solve
  • 16.12.1. Overview
  • 16.12.2. Flags file
  • 16.12.3. Example
  • 16.12.4. Usage
  • 16.12.5. Command-line options
• 16.13. CGAL tools
  • 16.13.1. Examples
• 16.14. colormap
  • 16.14.1. Using your own colormap
  • 16.14.2. Command-line options for colormap
• 16.15. convert_pinhole_model
  • 16.15.1. Usage
  • 16.15.2. Examples
  • 16.15.3. Validation
  • 16.15.4. Refinement
  • 16.15.5. Command-line options
• 16.16. corr_eval
• 16.17. Image correlator
• 16.18. dem2gcp
  • 16.18.1. ASP DEM creation
  • 16.18.2. Comparison with the reference DEM
  • 16.18.3. Running dem2gcp
  • 16.18.4. Solving for extrinsics and intrinsics
  • 16.18.5. Balancing GCP against other constraints
  • 16.18.6. Multiple images and cameras
  • 16.18.7. Transforming existing GCP files
  • 16.18.8. Command-line options
• 16.19. dem_geoid
  • 16.19.1. Supported geoids
  • 16.19.2. Custom geoids
  • 16.19.3. Examples
  • 16.19.4. Command-line options for dem_geoid
• 16.20. dem_mosaic
  • 16.20.1. Overview
  • 16.20.2. Examples
    • 16.20.2.1. Blend DEMs
    • 16.20.2.2. Priority blending
    • 16.20.2.3. Mean height DEM
    • 16.20.2.4. External weights
    • 16.20.2.5. Regridding
    • 16.20.2.6. Apply a blur
    • 16.20.2.7. Erosion
    • 16.20.2.8. Fill small holes
    • 16.20.2.9. Extrapolating a DEM
    • 16.20.2.10. Target aligned pixels
  • 16.20.3. Processing
  • 16.20.4. Usage
  • 16.20.5. Command-line options
• 16.21. dg_mosaic
• 16.22. disp2ip
  • 16.22.1. Procedure
    • 16.22.1.1. Stereo between filtered images
    • 16.22.1.2. SfM between the left raw images
    • 16.22.1.3. Running this program
  • 16.22.2. Use of results
  • 16.22.3. The input filter
  • 16.22.4. Command-line options
• 16.23. disparitydebug
  • 16.23.1. Examples
  • 16.23.2. Raw disparity extraction
  • 16.23.3. Command-line options
• 16.24. gcp_gen
  • 16.24.1. Examples
  • 16.24.2. Advanced usage
  • 16.24.3. Validation
  • 16.24.4. Command-line options
• 16.25. GDAL tools
• 16.26. geodiff
  • 16.26.1. Examples
    • 16.26.1.1. Absolute difference of two DEMs
    • 16.26.1.2. DEM 1 minus DEM 2
    • 16.26.1.3. DEM 2 minus DEM 1
    • 16.26.1.4. Difference of a DEM and a CSV file
  • 16.26.2. See also
  • 16.26.3. Command-line options
• 16.27. hiedr2mosaic.py
• 16.28. hillshade
  • 16.28.1. GDAL hillshade
  • 16.28.2. Command-line options
• 16.29. historical_helper.py
• 16.30. icebridge_kmz_to_csv
• 16.31. image2qtree
• 16.32. image_align
  • 16.32.1. Examples
    • 16.32.1.1. Interest point based alignment
    • 16.32.1.2. Disparity based alignment
  • 16.32.2. Application for alignment of DEMs
  • 16.32.3. Determination of ECEF transform
  • 16.32.4. Usage
  • 16.32.5. Command-line options for image_align
• 16.33. image_calc
  • 16.33.1. Examples
    • 16.33.1.1. Apply operation and save pixels as float32
    • 16.33.1.2. Apply a mask to an image
    • 16.33.1.3. Create a binary mask via thresholding
    • 16.33.1.4. Threshold and invalidate pixels below a value
    • 16.33.1.5. Threshold and invalidate pixels above a value
    • 16.33.1.6. Create an image with random values
    • 16.33.1.7. Add a value to the geoheader metadata
    • 16.33.1.8. Stretch and convert to 8-bit
    • 16.33.1.9. Subtract 360 degrees from the longitudes in a GeoTiff file
    • 16.33.1.10. Extract disparity bands respecting invalid disparities
  • 16.33.2. Usage
  • 16.33.3. Command-line options for image_calc
• 16.34. image_mosaic
  • 16.34.1. Example
  • 16.34.2. Handling failure
  • 16.34.3. Usage
  • 16.34.4. Command-line options
• 16.35. image_subset
  • 16.35.1. Overview
  • 16.35.2. Background and example
  • 16.35.3. Validation
  • 16.35.4. Command-line options
• 16.36. ipfind
• 16.37. ipmatch
  • 16.37.1. Example
  • 16.37.2. Plain text match files and inspections
  • 16.37.3. Match file format conversion
  • 16.37.4. Merging match files
  • 16.37.5. Naming convention
  • 16.37.6. Usage
  • 16.37.7. Command-line options
• 16.38. jitter_solve
  • 16.38.1. Limitations
  • 16.38.2. Ground constraints
    • 16.38.2.1. Triangulated point constraint
    • 16.38.2.2. Reference DEM constraint
    • 16.38.2.3. Ground control points
  • 16.38.3. Camera constraints
    • 16.38.3.1. Smoothness constraint
    • 16.38.3.2. Roll and yaw constraints
  • 16.38.4. Resampling the poses
  • 16.38.5. Interest point matches
  • 16.38.6. Anchor points
  • 16.38.7. Solving for intrinsics
  • 16.38.8. Example 1: CTX images on Mars
    • 16.38.8.1. Input images
    • 16.38.8.2. Reference datasets
    • 16.38.8.3. Uncorrected DEM creation
    • 16.38.8.4. Solving for jitter
    • 16.38.8.5. Multiple CTX images
  • 16.38.9. Example 2: WorldView-3 DigitalGlobe images on Earth
    • 16.38.9.1. Bundle adjustment
    • 16.38.9.2. Mapprojection
    • 16.38.9.3. Stereo
    • 16.38.9.4. Alignment
    • 16.38.9.5. Solving for jitter
    • 16.38.9.6. Redoing mapprojection and stereo
    • 16.38.9.7. Reusing a previous run
    • 16.38.9.8. Validation
  • 16.38.10. Example 3: Airbus Pleiades
    • 16.38.10.1. Creation of terrain model
    • 16.38.10.2. Correcting the jitter
  • 16.38.11. ASTER cameras
    • 16.38.11.1. Setup
    • 16.38.11.2. Initial stereo and alignment
    • 16.38.11.3. Solving for jitter
  • 16.38.12. Jitter with synthetic cameras and orientation constraints
  • 16.38.13. Constraining direction of jitter with real cameras
  • 16.38.14. Mixing linescan and frame cameras
  • 16.38.15. Rig constraints
    • 16.38.15.1. Rig configuration
    • 16.38.15.2. Assumptions
    • 16.38.15.3. Naming convention
    • 16.38.15.4. Example of sensors on a rig with a very small baseline
  • 16.38.16. Point cloud constraint
  • 16.38.17. Output files
    • 16.38.17.1. Optimized cameras
    • 16.38.17.2. Reprojection errors per camera
    • 16.38.17.3. Changes in camera positions
    • 16.38.17.4. Changes in triangulated points
    • 16.38.17.5. Reprojection errors per triangulated point
    • 16.38.17.6. Anchor points
    • 16.38.17.7. Reference terrain residuals
    • 16.38.17.8. Image and camera lists
    • 16.38.17.9. Other output files
  • 16.38.18. Command-line options for jitter_solve
• 16.39. lronac2mosaic.py
• 16.40. lvis2kml
• 16.41. mapproject
  • 16.41.1. Determination of projection
  • 16.41.2. Examples
    • 16.41.2.1. Earth image with auto projection
    • 16.41.2.2. Moon image with a custom projection
    • 16.41.2.3. RPC camera with bundle adjustment
    • 16.41.2.4. CSM camera
    • 16.41.2.5. Preexisting projection and grid size
    • 16.41.2.6. Multiple camera models
    • 16.41.2.7. Mapproject with no DEM
  • 16.41.3. Saved metadata
  • 16.41.4. Custom metadata
  • 16.41.5. ISIS compatibility
    • 16.41.5.1. Example with camera in cube file
    • 16.41.5.2. Example with CSM camera model
    • 16.41.5.3. Example with preexisting map
    • 16.41.5.4. Validation
    • 16.41.5.5. Running stereo
    • 16.41.5.6. Saved metadata
    • 16.41.5.7. Other cam2map options
    • 16.41.5.8. Grid snapping and output extent
  • 16.41.6. Usage
  • 16.41.7. Command-line options
• 16.42. multi_stereo
  • 16.42.1. Examples
    • 16.42.1.1. Creation of camera models
    • 16.42.1.2. Running stereo and mesh creation
    • 16.42.1.3. Creating a textured mesh
  • 16.42.2. Handling issues
  • 16.42.3. Command-line options for multi_stereo
• 16.43. n_align
• 16.44. orbit_plot.py
  • 16.44.1. Satellite coordinate system
  • 16.44.2. Roll, pitch, and yaw angles
  • 16.44.3. Examples
    • 16.44.3.1. Plot one dataset
    • 16.44.3.2. Plot two datasets
    • 16.44.3.3. Plot two orbital groups, including linescan cameras
  • 16.44.4. Dependencies
  • 16.44.5. See also
  • 16.44.6. Command-line options
• 16.45. orbitviz
• 16.46. ortho2pinhole
• 16.47. otsu_threshold
• 16.48. pansharp
• 16.49. parallel_bundle_adjust
  • 16.49.1. Processing steps
  • 16.49.2. Use of results
  • 16.49.3. Parallelization
  • 16.49.4. Command-line options
• 16.50. parallel_sfs
• 16.51. parallel_stereo
  • 16.51.1. Processes and threads
  • 16.51.2. Multiple machines
  • 16.51.3. Output files
  • 16.51.4. Tiling
  • 16.51.5. Resuming a run
  • 16.51.6. Output files
  • 16.51.7. Processing stages
  • 16.51.8. Command-line options
• 16.52. parse_match_file.py
  • 16.52.1. Examples
  • 16.52.2. File format
  • 16.52.3. Descriptors
  • 16.52.4. Command-line options
• 16.53. pc_align
  • 16.53.1. The input point clouds
  • 16.53.2. The max displacement option
  • 16.53.3. Alignment method
    • 16.53.3.1. ICP algorithms
    • 16.53.3.2. Nuth and Kaab
    • 16.53.3.3. FGR algorithm
    • 16.53.3.4. Feature-based alignment
    • 16.53.3.5. Correlation-based alignment
    • 16.53.3.6. Least squares
  • 16.53.4. File formats
    • 16.53.4.1. CSV
    • 16.53.4.2. LAS and COPC
  • 16.53.5. The alignment transform
  • 16.53.6. Applying an initial transform
  • 16.53.7. Applying an initial specified translation or rotation
  • 16.53.8. Interpreting the transform
  • 16.53.9. Error metrics and outliers
  • 16.53.10. Evaluation of aligned clouds
  • 16.53.11. Output point clouds and convergence history
  • 16.53.12. Manual alignment
  • 16.53.13. Regrid a DEM
  • 16.53.14. Applying a transform to cameras
  • 16.53.15. Troubleshooting
  • 16.53.16. Command-line options for pc_align
  • 16.53.17. Options for Nuth and Kaab
• 16.54. pc_filter
• 16.55. pc_merge
• 16.56. point2dem
  • 16.56.1. Determination of projection
  • 16.56.2. Examples
    • 16.56.2.1. Local stereographic projection
    • 16.56.2.2. Orthoimage and error image
    • 16.56.2.3. Specify a projection string
    • 16.56.2.4. Custom grid size with geographic projection
    • 16.56.2.5. Polar stereographic projection
    • 16.56.2.6. UTM projection
    • 16.56.2.7. CSV files
    • 16.56.2.8. LAS and COPC
    • 16.56.2.9. Multiple clouds
    • 16.56.2.10. Ground-level or projected data
  • 16.56.3. Comparing with MOLA
  • 16.56.4. Post spacing
  • 16.56.5. LAS or CSV clouds
  • 16.56.6. Output statistics
  • 16.56.7. Command-line options for point2dem
• 16.57. point2las
  • 16.57.1. Examples
  • 16.57.2. Validation
  • 16.57.3. Outlier removal
  • 16.57.4. Command-line options for point2las
• 16.58. point2mesh
  • 16.58.1. Examples
  • 16.58.2. Command-line options
• 16.59. refr_index
  • 16.59.1. Examples
  • 16.59.2. Methodology
    • 16.59.2.1. Spectral response
    • 16.59.2.2. Salinity and temperature
    • 16.59.2.3. Modeling
  • 16.59.3. Command-line options
• 16.60. rig_calibrator
  • 16.60.1. Capabilities
  • 16.60.2. Input data conventions
    • 16.60.2.1. File name convention
    • 16.60.2.2. Directory structure
    • 16.60.2.3. List format
    • 16.60.2.4. Assumptions about images
    • 16.60.2.5. Assumptions about the timestamp
    • 16.60.2.6. Depth data
  • 16.60.3. The reference sensor
  • 16.60.4. Configuration file
  • 16.60.5. Output files
  • 16.60.6. Examples
  • 16.60.7. Notes
  • 16.60.8. Constraints on rig transforms
  • 16.60.9. Constraints on cameras
  • 16.60.10. Constraints on triangulated points
  • 16.60.11. Determination of scale and registration
  • 16.60.12. Quality metrics
  • 16.60.13. Handling failures
  • 16.60.14. Point cloud file format
  • 16.60.15. Interfacing with bundle_adjust
  • 16.60.16. Usage
  • 16.60.17. Command-line options
• 16.61. ROS bag handling tools
  • 16.61.1. list_timestamps
  • 16.61.2. extract_bag
• 16.62. sat_sim
  • 16.62.1. Prior frame or linescan cameras
  • 16.62.2. Create nadir-pointing frame cameras
  • 16.62.3. Follow custom ground path with varying orientation
  • 16.62.4. Fixed camera orientation
  • 16.62.5. Pose and ground constraints
  • 16.62.6. Jitter modelling
    • 16.62.6.1. Specifying the jitter amplitude in meters
    • 16.62.6.2. Specifying the jitter amplitude in micro radians
  • 16.62.7. Linescan cameras
  • 16.62.8. Modeling a rig
  • 16.62.9. Adjusting a rig
  • 16.62.10. Modeling time
  • 16.62.11. Perturbing existing cameras
  • 16.62.12. Roll, pitch, and yaw
  • 16.62.13. Efficiency considerations
  • 16.62.14. Preparing the input DEM and orthoimage
  • 16.62.15. Output files
  • 16.62.16. Command-line options
• 16.63. sfm_merge
  • 16.63.1. Example
  • 16.63.2. Handling tracks
  • 16.63.3. Command-line options for sfm_merge
• 16.64. sfm_proc
  • 16.64.1. Command-line options
• 16.65. sfm_submap
  • 16.65.1. Examples
  • 16.65.2. Command-line options for sfm_submap
• 16.66. sfm_view
  • 16.66.1. Example
  • 16.66.2. See also
  • 16.66.3. Command-line options
• 16.67. sfs
  • 16.67.1. Illustration
  • 16.67.2. Usage
  • 16.67.3. Example
  • 16.67.4. Inputs
  • 16.67.5. Outputs
  • 16.67.6. Command-line options for sfs
• 16.68. sfs_blend
• 16.69. stereo
  • 16.69.1. Command-line options
• 16.70. stereo_dist
  • 16.70.1. Example with mapprojected images
  • 16.70.2. Example with raw images
  • 16.70.3. Workflow
  • 16.70.4. Command-line options
• 16.71. stereo_gui
  • 16.71.1. Use as stereo front-end
  • 16.71.2. Use as an image viewer
  • 16.71.3. Other features
  • 16.71.4. Hillshading
  • 16.71.5. Displaying colorized images, with a colorbar and axes
  • 16.71.6. View scattered points
  • 16.71.7. Polygon editing and contouring
    • 16.71.7.1. Plain-text polygon files
    • 16.71.7.2. Applications
  • 16.71.8. Finding pixel values and region bounds
  • 16.71.9. View interest point matches
    • 16.71.9.1. View matches for an image pair
    • 16.71.9.2. View pairwise matches for N images
    • 16.71.9.3. View all matches for N images
    • 16.71.9.4. View NVM files
    • 16.71.9.5. View ISIS control network files
  • 16.71.10. View GCP and .vwip files
  • 16.71.11. Edit interest point matches
  • 16.71.12. Creating GCP with with an orthoimage and a DEM
  • 16.71.13. Creating interest point matches using mapprojected images
  • 16.71.14. Image threshold
  • 16.71.15. Cycle through images
  • 16.71.16. See also
  • 16.71.17. Command line options for stereo_gui
• 16.72. stereo_sweep
  • 16.72.1. Example
  • 16.72.2. Workflow
  • 16.72.3. Command-line options
• 16.73. stereo_tile
  • 16.73.1. Command-line options
• 16.74. texrecon
  • 16.74.1. Example
  • 16.74.2. Command-line options
• 16.75. theia_sfm
  • 16.75.1. Naming convention
  • 16.75.2. Configuration
  • 16.75.3. Flags file
  • 16.75.4. Examples
  • 16.75.5. Usage
  • 16.75.6. Output files
  • 16.75.7. Visualization
  • 16.75.8. Manipulating SfM solutions
    • 16.75.8.1. Command-line options for theia_sfm
• 16.76. undistort_image
• 16.77. view_reconstruction
• 16.78. voxblox_mesh
  • 16.78.1. Example
  • 16.78.2. Format of the inputs
  • 16.78.3. Command-line options for voxblox_mesh
• 16.79. wv_correct
  • 16.79.1. Note for WV-2 images
  • 16.79.2. Usage
  • 16.79.3. Examples
  • 16.79.4. Command-line options for wv_correct