Updates to orbit_plot and other doc

NEWS.rst

@@ -69,7 +69,7 @@ sfs (:numref:`sfs`):
     (:numref:`image_subset`).
 
 orbit_plot (:numref:`orbit_plot`):
-  * Added the option ``--use-rmse``.
+  * Added the options ``--use-rmse``, ``--output-file``.
 
 cam2rpc (:numref:`cam2rpc`):
   * When a DEM is passed in, sample not just the DEM surface but its bounding

docs/examples/umbra_sar.rst

@@ -121,5 +121,8 @@ The transformed cloud can be gridded back to a DEM as::
     --t_srs "$proj"  \
     align/run-trans_reference.tif
     
-Here, the projection in ``$proj`` can be the same as for the DEM created earlier
+Here, the projection string in ``$proj`` can be the same as for the DEM created earlier
 (the ``gdalinfo -proj4`` command invoked on that DEM can print it). 
+
+The ``geodiff`` program can take the difference of the now-aligned DEMs.
+Other inspections can be done as discussed in :numref:`visualising`.

docs/next_steps.rst

@@ -470,7 +470,7 @@ Hole-filling and smoothing the input DEM
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 It is suggested to inspect and then hole-fill the input DEM
-(:numref:`dem_mosaic_extrapolate` and :numref:`dem_mosaic_fill`). 
+(:numref:`dem_mosaic_fill` and :numref:`dem_mosaic_extrapolate`).
 
 If the input DEM has too much detail, and those features do not agree with the
 images mapprojected on it, this can result in artifacts in the final DEM. A blur
@@ -1128,8 +1128,8 @@ The ``stereo_gui`` program (:numref:`stereo_gui`) is a very versatile
 viewer that can overlay hillshaded DEMs, orthoimages, interest point matches,
 ASP's report files in CSV format, polygons, etc.
 
-Produced DEMs can also be mosaicked (:numref:`dem_mosaic`), differenced,
-including with CSV files (:numref:`geodiff`), and aligned
+Produced DEMs can also be mosaicked (:numref:`dem_mosaic`), subtracted from
+other DEMs or CSV files (:numref:`geodiff`), aligned to a reference
 (:numref:`pc-align-example`), etc.
 
 .. _p19-osg:

docs/tools/bundle_adjust.rst

@@ -31,13 +31,15 @@ See :numref:`moc_tutorial` for an introduction to these cameras.
 
 ::
 
-     bundle_adjust --camera-weight 0               \
-       --tri-weight 0.1 --tri-robust-threshold 0.1 \
-       file1.cub file2.cub file3.cub -o run_ba/run
+     bundle_adjust --camera-weight 0 \
+       --tri-weight 0.1              \
+       --tri-robust-threshold 0.1    \
+       file1.cub file2.cub file3.cub \
+       -o run_ba/run
 
-The above choices for camera weight and triangulation weight are a recent
-implementation and suggested going forward, but not yet the defaults. These are
-helpful in preventing the cameras from drifting too far from initial locations.
+The above choices for camera weight and triangulation weight have in the
+meantime become the defaults. These are helpful in preventing the cameras from
+drifting too far from initial locations.
 
 .. _maxar_gcp:
 
@@ -94,12 +96,14 @@ Pinhole cameras
 
 ::
 
-     bundle_adjust file1.JPG file2.JPG              \
-        file1.tsai file2.tsai                       \
-        -t nadirpinhole --inline-adjustments        \
-        --camera-weight 0                           \
-        --tri-weight 0.1 --tri-robust-threshold 0.1 \
-        --datum WGS_1984                            \
+     bundle_adjust -t nadirpinhole \
+       --inline-adjustments        \
+        --camera-weight 0          \
+        --tri-weight 0.1           \
+        --tri-robust-threshold 0.1 \
+        --datum WGS_1984           \
+        file1.JPG file2.JPG        \
+        file1.tsai file2.tsai      \
         -o run_ba/run
 
 See :numref:`pinholemodels` for the pinhole camera model format.

docs/tools/jitter_solve.rst

@@ -455,6 +455,9 @@ If using camera position constraints (:numref:`jitter_camera`), it is
 suggested to be generous with the uncertainties. For CTX they are likely
 rather large.
 
+The report files mentioned in :numref:`jitter_out_files` can be very helpful
+in evaluating how well the jitter solver worked, even before rerunning stereo.
+
 The model states (:numref:`csm_state`) of optimized cameras are saved
 with names like::
 
@@ -796,6 +799,9 @@ Solve for jitter::
 See :numref:`jitter_camera` regarding camera constraints.
 See :numref:`jitter_anchor_points` regarding anchor points.
 
+The report files mentioned in :numref:`jitter_out_files` can be very helpful
+in evaluating how well the jitter solver worked, even before rerunning stereo.
+
 .. _fig_dg_jitter_pointmap_anchor_points:
 
 .. figure:: ../images/dg_jitter_pointmap_anchor_points.png
@@ -1061,6 +1067,9 @@ cameras were accurate enough, so these steps were skipped.
 See :numref:`jitter_camera` for a discussion of camera constraints.
 See :numref:`jitter_anchor_points` regarding anchor points.
 
+The report files mentioned in :numref:`jitter_out_files` can be very helpful
+in evaluating how well the jitter solver worked, even before rerunning stereo.
+
 Next, we invoke the solver with the same initial data, but with a constraint
 tying to the reference DEM, with the option ``--heights-from-dem ref-adj.tif``.
 Since the difference between the created stereo DEM and the reference DEM is on
@@ -1290,6 +1299,9 @@ This can be reduced to 5 meters, likely.
 See :numref:`jitter_camera` for a discussion of camera constraints,
 and :numref:`jitter_anchor_points` regarding anchor points.
 
+The report files mentioned in :numref:`jitter_out_files` can be very helpful
+in evaluating how well the jitter solver worked, even before rerunning stereo.
+
 .. figure:: ../images/aster_jitter_pointmap.png
    :name: aster_jitter_pointmap
 

docs/tools/orbit_plot.rst

@@ -73,10 +73,11 @@ Plot a single set of cameras along a given orbit::
       --orbit-label pinhole 
 
 We assume that the cameras are in the directory ``dataset1/``, and their names
-in that directory start with ``pinhole-fwd``. 
+in that directory contain the string ``pinhole-fwd``. 
 
-The slash (``/``) at the end of the directory name is important, as the two
-strings above will be concatenated to find the camera names.
+The slash (``/``) at the end of the directory name is important, on reading
+the tool will match the dataset name, followed by some characters, followed 
+by the orbit id. 
 
 The rest of a camera name can be any string ending in ``.tsai`` or ``.json``.
 Hence, only the cameras satisfying this convention will be read.
@@ -283,7 +284,11 @@ Command-line options
 
 --font-size <int (default: 14)>
     Font size for the plots.
-
+
+--output-file <string (default: "")>
+    Save the figure to this image file, instead of showing it on the screen.
+    A png extension is recommended.
+
 -h, --help
     Display this help message.
 

src/asp/Tools/orbit_plot.py

@@ -860,7 +860,7 @@ def plot_row(ax, row, orbits, hasList, datasets, orbit_labels, dataset_labels,
 
 parser.add_argument('--output-file', dest = 'out_file', type=str, default = '',
                     help='Save the figure to this image file, instead of showing it on ' +
-                    'the screen.')
+                    'the screen. A png extension is recommended.')
 
 (opt, args) = parser.parse_known_args(sys.argv)