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.3. bathy_plane_calc
  • 16.3.1. Example 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. Example 2 (using water height measurements)
  • 16.3.3. Example 3 (using a DEM and shapefile)
  • 16.3.4. Example 4 (pick a sample set of points at mask boundary)
  • 16.3.5. Acquisition of water height data
  • 16.3.6. 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
    • 16.5.1.6. 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. 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.6. cam2map4stereo.py
• 16.7. cam2rpc
  • 16.7.1. Examples
  • 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.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. Flags file
    • 16.12.1.1. Example
    • 16.12.1.2. Usage
    • 16.12.1.3. 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. Multiple images and cameras
  • 16.18.6. 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. Usage
  • 16.20.4. 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. Alternative approach
  • 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.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. hsv_merge
• 16.31. icebridge_kmz_to_csv
• 16.32. image2qtree
• 16.33. image_align
  • 16.33.1. Examples
  • 16.33.2. Application for alignment of DEMs
  • 16.33.3. Determination of ECEF transform
  • 16.33.4. Usage
  • 16.33.5. Command-line options for image_align
• 16.34. image_calc
  • 16.34.1. Examples
    • 16.34.1.1. Apply operation and save pixels as float32
    • 16.34.1.2. Apply a mask to an image
    • 16.34.1.3. Create a mask
    • 16.34.1.4. Invalidate values no more than a threshold
    • 16.34.1.5. Invalidate values no less than a threshold
    • 16.34.1.6. Create an image with random values
    • 16.34.1.7. Add a value to the geoheader metadata
    • 16.34.1.8. Subtract 360 degrees from the longitudes in a GeoTiff file
    • 16.34.1.9. Extract disparity bands respecting invalid disparities
  • 16.34.2. Usage
  • 16.34.3. Command-line options
• 16.35. image_mosaic
  • 16.35.1. Example
  • 16.35.2. Handling failure
  • 16.35.3. Usage
  • 16.35.4. Command-line options
• 16.36. image_subset
  • 16.36.1. Overview
  • 16.36.2. Background and example
  • 16.36.3. Validation
  • 16.36.4. Command-line options
• 16.37. ipfind
• 16.38. ipmatch
• 16.39. jitter_solve
  • 16.39.1. Limitations
  • 16.39.2. Ground constraints
    • 16.39.2.1. Intrinsic constraint
    • 16.39.2.2. Extrinsic constraint
    • 16.39.2.3. Ground control points
  • 16.39.3. Camera constraints
    • 16.39.3.1. Smoothness constraint
    • 16.39.3.2. Roll and yaw constraints
  • 16.39.4. Resampling the poses
  • 16.39.5. Interest point matches
  • 16.39.6. Anchor points
  • 16.39.7. Solving for intrinsics
  • 16.39.8. Example 1: CTX images on Mars
    • 16.39.8.1. Input images
    • 16.39.8.2. Reference datasets
    • 16.39.8.3. Uncorrected DEM creation
    • 16.39.8.4. Solving for jitter
    • 16.39.8.5. Multiple CTX images
  • 16.39.9. Example 2: WorldView-3 DigitalGlobe images on Earth
    • 16.39.9.1. Bundle adjustment
    • 16.39.9.2. Mapprojection
    • 16.39.9.3. Stereo
    • 16.39.9.4. Alignment
    • 16.39.9.5. Solving for jitter
    • 16.39.9.6. Redoing mapprojection and stereo
    • 16.39.9.7. Reusing a previous run
    • 16.39.9.8. Validation
  • 16.39.10. Example 3: Airbus Pleiades
    • 16.39.10.1. Creation of terrain model
    • 16.39.10.2. Correcting the jitter
  • 16.39.11. ASTER cameras
    • 16.39.11.1. Setup
    • 16.39.11.2. Initial stereo and alignment
    • 16.39.11.3. Solving for jitter
  • 16.39.12. Jitter with synthetic cameras and orientation constraints
  • 16.39.13. Constraining direction of jitter with real cameras
  • 16.39.14. Mixing linescan and frame cameras
  • 16.39.15. Rig constraints
    • 16.39.15.1. Rig configuration
    • 16.39.15.2. Assumptions
    • 16.39.15.3. Naming convention
    • 16.39.15.4. Example of sensors on a rig with a very small baseline
  • 16.39.16. Point cloud constraint
  • 16.39.17. Output files
    • 16.39.17.1. Optimized cameras
    • 16.39.17.2. Reprojection errors per camera
    • 16.39.17.3. Changes in camera positions
    • 16.39.17.4. Changes in triangulated points
    • 16.39.17.5. Reprojection errors per triangulated point
    • 16.39.17.6. Anchor points
    • 16.39.17.7. Reference terrain residuals
    • 16.39.17.8. Image and camera lists
    • 16.39.17.9. Other output files
  • 16.39.18. Command-line options for jitter_solve
• 16.40. lronac2mosaic.py
• 16.41. lvis2kml
• 16.42. mapproject
  • 16.42.1. Determination of projection
  • 16.42.2. Examples
    • 16.42.2.1. Earth image with auto projection
    • 16.42.2.2. Moon image with a custom projection
    • 16.42.2.3. RPC camera with bundle adjustment
    • 16.42.2.4. CSM camera
    • 16.42.2.5. Preexisting projection and grid size
    • 16.42.2.6. Multiple camera models
    • 16.42.2.7. Mapproject with no DEM
  • 16.42.3. Saved metadata
  • 16.42.4. Usage
  • 16.42.5. Command-line options
• 16.43. multi_stereo
  • 16.43.1. Examples
    • 16.43.1.1. Creation of camera models
    • 16.43.1.2. Running stereo and mesh creation
    • 16.43.1.3. Creating a textured mesh
  • 16.43.2. Handling issues
  • 16.43.3. Command-line options for multi_stereo
• 16.44. n_align
• 16.45. orbit_plot.py
  • 16.45.1. Satellite coordinate system
  • 16.45.2. Roll, pitch, and yaw angles
  • 16.45.3. Examples
    • 16.45.3.1. Plot one dataset
    • 16.45.3.2. Plot two datasets
    • 16.45.3.3. Plot two orbital groups, including linescan cameras
  • 16.45.4. Dependencies
  • 16.45.5. See also
  • 16.45.6. Command-line options
• 16.46. orbitviz
• 16.47. ortho2pinhole
• 16.48. otsu_threshold
• 16.49. pansharp
• 16.50. parallel_bundle_adjust
  • 16.50.1. Processing steps
  • 16.50.2. Use of results
  • 16.50.3. Parallelization
  • 16.50.4. Command-line options
• 16.51. parallel_sfs
• 16.52. parallel_stereo
  • 16.52.1. Processes and threads
  • 16.52.2. Output files
  • 16.52.3. Tiling
  • 16.52.4. Entry points
  • 16.52.5. Command-line options
• 16.53. parse_match_file.py
• 16.54. pc_align
  • 16.54.1. The input point clouds
  • 16.54.2. The max displacement option
  • 16.54.3. Alignment method
    • 16.54.3.1. ICP algorithms
    • 16.54.3.2. Nuth and Kaab
    • 16.54.3.3. FGR algorithm
    • 16.54.3.4. Feature-based alignment
    • 16.54.3.5. Correlation-based alignment
    • 16.54.3.6. Least squares
  • 16.54.4. File formats
    • 16.54.4.1. CSV
    • 16.54.4.2. LAS and COPC
  • 16.54.5. The alignment transform
  • 16.54.6. Applying an initial transform
  • 16.54.7. Applying an initial specified translation or rotation
  • 16.54.8. Interpreting the transform
  • 16.54.9. Error metrics and outliers
  • 16.54.10. Evaluation of aligned clouds
  • 16.54.11. Output point clouds and convergence history
  • 16.54.12. Manual alignment
  • 16.54.13. Regrid a DEM
  • 16.54.14. Applying a transform to cameras
  • 16.54.15. Troubleshooting
  • 16.54.16. Command-line options for pc_align
  • 16.54.17. Options for Nuth and Kaab
• 16.55. pc_filter
• 16.56. pc_merge
• 16.57. point2dem
  • 16.57.1. Determination of projection
  • 16.57.2. Examples
    • 16.57.2.1. Local stereographic projection
    • 16.57.2.2. Orthoimage and error image
    • 16.57.2.3. Specify a projection string
    • 16.57.2.4. Custom grid size with geographic projection
    • 16.57.2.5. Polar stereographic projection
    • 16.57.2.6. UTM projection
    • 16.57.2.7. CSV files
    • 16.57.2.8. LAS and COPC
    • 16.57.2.9. Multiple clouds
    • 16.57.2.10. Ground-level or projected data
  • 16.57.3. Comparing with MOLA
  • 16.57.4. Post spacing
  • 16.57.5. LAS or CSV clouds
  • 16.57.6. Output statistics
  • 16.57.7. Command-line options for point2dem
• 16.58. point2las
  • 16.58.1. Examples
  • 16.58.2. Validation
  • 16.58.3. Outlier removal
  • 16.58.4. Command-line options for point2las
• 16.59. point2mesh
  • 16.59.1. Examples
  • 16.59.2. 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. 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_gui
  • 16.70.1. Use as stereo front-end
  • 16.70.2. Use as an image viewer
  • 16.70.3. Other features
  • 16.70.4. Hillshading
  • 16.70.5. Displaying colorized images, with a colorbar and axes
  • 16.70.6. View scattered points
  • 16.70.7. Polygon editing and contouring
    • 16.70.7.1. Plain-text polygon files
    • 16.70.7.2. Application
  • 16.70.8. Finding pixel values and region bounds
  • 16.70.9. View interest point matches
    • 16.70.9.1. View matches for an image pair
    • 16.70.9.2. View pairwise matches for N images
    • 16.70.9.3. View all matches for N images
    • 16.70.9.4. View NVM files
    • 16.70.9.5. View ISIS control network files
  • 16.70.10. View GCP and .vwip files
  • 16.70.11. Edit interest point matches
  • 16.70.12. Creating GCP with with an orthoimage and a DEM
  • 16.70.13. Creating interest point matches using mapprojected images
  • 16.70.14. Image threshold
  • 16.70.15. Cycle through images
  • 16.70.16. Command line options for stereo_gui
• 16.71. texrecon
  • 16.71.1. Example
  • 16.71.2. Command-line options
• 16.72. theia_sfm
  • 16.72.1. Naming convention
  • 16.72.2. Configuration
  • 16.72.3. Flags file
  • 16.72.4. Examples
  • 16.72.5. Usage
  • 16.72.6. Output files
  • 16.72.7. Visualization
  • 16.72.8. Manipulating SfM solutions
    • 16.72.8.1. Command-line options for theia_sfm
• 16.73. undistort_image
• 16.74. view_reconstruction
• 16.75. voxblox_mesh
  • 16.75.1. Example
  • 16.75.2. Format of the inputs
  • 16.75.3. Command-line options for voxblox_mesh
• 16.76. wv_correct
  • 16.76.1. Note for WV-2 images
  • 16.76.2. Usage
  • 16.76.3. Examples
  • 16.76.4. Command-line options for wv_correct