A handful of minor changes to push version 3.0.0 out

Author: oleg-alexandrov

INSTALLGUIDE.rst

@@ -203,15 +203,9 @@ environments, which you don't want.
 
 Install ASP with the command::
 
-    conda install stereo-pipeline==2.7.0
+    conda install stereo-pipeline==3.0.0
 
-This will install ASP 2.7.0 together with ISIS 4.1.0.
-
-Running instead::
-
-    conda install stereo-pipeline==isis5.0.1
-
-will install a development version of ASP together with ISIS 5.0.1.
+This will install ASP 3.0.0 together with ISIS 5.0.1.
 
 If using ISIS, the environmental variable ISISROOT should be set to
 point to this distribution, such as::
@@ -228,11 +222,11 @@ found as a set of .yaml files in the ``conda/`` subdirectory of the
 Stereo Pipeline GitHub repository. So, alternatively, the installation
 can happen as::
 
-    conda env create -f asp_2.7.0_linux_env.yaml
+    conda env create -f asp_3.0.0_linux_env.yaml
 
 or::
 
-    conda env create -f asp_2.7.0_osx_env.yaml
+    conda env create -f asp_3.0.0_osx_env.yaml
 
 depending on your platform. Then invoke, as earlier::
 
@@ -261,11 +255,11 @@ The environments having the ASP dependencies are in the ``conda``
 directory of the Stereo Pipeline repository, as above. After
 downloading those, one can run on Linux::
 
-    conda env create -f asp_deps_2.7.0_linux_env.yaml
+    conda env create -f asp_deps_3.0.0_linux_env.yaml
 
 or on the Mac::
 
-    conda env create -f asp_deps_2.7.0_osx_env.yaml
+    conda env create -f asp_deps_3.0.0_osx_env.yaml
 
 This will create an ``asp_deps`` environment. Activate it with::
 
@@ -304,7 +298,7 @@ Building VisionWorkbench and Stereo Pipeline on Linux::
     ~/miniconda3/envs/asp_deps/bin/git clone \
         git@github.com:visionworkbench/visionworkbench.git
     cd visionworkbench
-    git checkout 2.7.0 # check out the desired commit
+    git checkout 3.0.0 # check out the desired commit
     mkdir -p build
     cd build
     ~/miniconda3/envs/asp_deps/bin/cmake ..                                                 \
@@ -320,7 +314,7 @@ Building VisionWorkbench and Stereo Pipeline on Linux::
     ~/miniconda3/envs/asp_deps/bin/git clone \
     git@github.com:NeoGeographyToolkit/StereoPipeline.git
     cd StereoPipeline
-    git checkout 2.7.0 # check out the desired commit
+    git checkout 3.0.0 # check out the desired commit
     mkdir -p build
     cd build
     ~/miniconda3/envs/asp_deps/bin/cmake ..                                                 \
@@ -339,7 +333,7 @@ Building VisionWorkbench and ASP on OSX (just as above, but omitting the compile
     ~/miniconda3/envs/asp_deps/bin/git clone \
       git@github.com:visionworkbench/visionworkbench.git
     cd visionworkbench
-    git checkout 2.7.0 # check out the desired commit
+    git checkout 3.0.0 # check out the desired commit
     mkdir -p build
     cd build
     ~/miniconda3/envs/asp_deps/bin/cmake ..                                                 \
@@ -353,7 +347,7 @@ Building VisionWorkbench and ASP on OSX (just as above, but omitting the compile
     ~/miniconda3/envs/asp_deps/bin/git clone \
       git@github.com:NeoGeographyToolkit/StereoPipeline.git
     cd StereoPipeline
-    git checkout 2.7.0 # check out the desired commit
+    git checkout 3.0.0 # check out the desired commit
     mkdir -p build
     cd build
     ~/miniconda3/envs/asp_deps/bin/cmake ..                                                 \

NEWS.rst

@@ -1,12 +1,16 @@
-RELEASE 3.0.0, upcoming!
+RELEASE 3.0.0, July 27, 2021
+----------------------------
 
 New functionality:
   * Added new stereo algorithms: MGM (original author implementation),
-    OpenCV SGBM, LIBELAS, MSMW, MSMW2, and OpenCV BM.
+    OpenCV SGBM, LIBELAS, MSMW, MSMW2, and OpenCV BM to complement  
+    the existing ASP block matching, SGM, and MGM algorithms. See
+    https://stereopipeline.readthedocs.io/en/latest/next_steps.html
+    for usage. These will be further refined in subsequent releases.
   * Added the ability to perform piecewise local epipolar alignment
     for the input images, to be followed by a 1D disparity search (for
     non-mapprojected images), as suggested by the Satellite Stereo
-    Pipeline (S2P) approach.
+    Pipeline (S2P) approach. This is still somewhat experimental.
   * Added the ability for a user to plug into ASP any desired stereo
     program working on image clips to which epipolar alignment has
     been applied (as is customary in the computer vision community)
@@ -27,7 +31,8 @@ isis:
   * Ship a full Python 3.6 runtime, as expected by ISIS.
 
 csm:
-  * Upgraded to USGSCSM 1.5.2.
+  * Upgraded to USGSCSM 1.5.2 (ASP's own build of it has an additional
+    bugfix for LRO NAC not present in the conda-forge package).
   * Validated the CSM model for CTX, HiRISE, and LRO NAC cameras.
   * Added documentation for how to create CSM models from .cub
     cameras.

RELEASEGUIDE

@@ -108,19 +108,22 @@ The resulting release tarballs will go to BinaryBuilder/asp_tarballs.
 
 8.) Commit and tag the release in the VW and ASP repos. Example: 
 
-  git tag 2.7.0
+  git tag 3.0.0
 
 Push the tags to the remote server with: 
 
- git push origin 2.7.0 # commit to your branch
- git push god    2.7.0 # commit to main branch
+ git push origin 3.0.0 # commit to your branch
+ git push god    3.0.0 # commit to main branch
+
+(Here it is assumed that 'origin' points to your own fork and 'god'
+points to the parent repository.)
 
 If more commits were made and it is desired to apply this tag to a
 different commit, first remove the exiting tag with:
 
-  git tag -d 2.7.0
-  git push origin :refs/tags/2.7.0
-  git push god    :refs/tags/2.7.0
+  git tag -d 3.0.0
+  git push origin :refs/tags/3.0.0
+  git push god    :refs/tags/3.0.0
 
 9.) Upload the builds and the pdf documentation to GitHub, in the
 release area.
@@ -157,9 +160,9 @@ development, by updating the version number in:
 
 in both the VW and ASP repositories. 
 
-If you just released version 2.7.0, we expect that the next feature
-release will be 2.8.0, if a major release, or 2.7.1 if a minor
-release, so the version tag should be updated to 2.8.0-alpha in
+If you just released version 3.0.0, we expect that the next feature
+release will be 3.1.0, if a major release, or 3.0.1 if a minor
+release, so the version tag should be updated to 3.1.0-alpha in
 anticipation (see https://semver.org for guidance).
 
 13.) Reflect any changes in release policy by modifying this document.

docs/next_steps.rst

@@ -31,22 +31,43 @@ This invokes block-matching stereo with parabola subpixel mode, which
 can be fast but not of high quality. The best results are likely
 produced with::
 
-   parallel_stereo --alignment-method local_epipolar \
+   parallel_stereo --alignment-method affineepipolar \
      --stereo-algorithm asp_mgm --subpixel-mode 3    \
      <other options>
 
 which uses ASP's implementation of MGM (:numref:`asp_sgm`). 
 
-ASP also ships with a handful of third-party stereo algorithms, such
+ASP also implements local alignment, when the input images are split
+into tiles (with overlap) and locally aligned. This makes it possible
+to use third-party algorithms in addition to the ones ASP implements. 
+
+This mode is still in development, and best results with it, for the
+moment, are obtained with ASP's own MGM algorithm, if invoked as
+follows::
+
+   parallel_stereo --alignment-method local_epipolar \
+     --stereo-algorithm asp_mgm                      \
+     <other options>
+
+ASP also ships with the following third-party stereo algorithms:
 MGM (original author implementation), OpenCV SGBM, LIBELAS, MSMW,
 MSMW2, and OpenCV BM. For more details see :numref:`stereo_algos`.
 
-For example, the external MGM implementation can be called as follows::
+For example, the external MGM implementation can be called as::
 
    parallel_stereo --alignment-method local_epipolar \
      --stereo-algorithm mgm                          \
+     --corr-tile-size 512 --sgm-collar-size 256      \ 
      <other options>
+
+As before, this mode is still experimental. 
 
+Above we used tiles of size 512 pixels with an extra padding of 256
+pixels on each side, for a total size of 1024 pixels, to avoid using
+too much memory. The defaults in ``parallel_stereo`` are double these
+values, which work well with ASP's MGM which is more conservative with
+its use of memory but can be too much for this other implementation.
+
 It is suggested to not specify here ``--subpixel-mode``, in which case
 it will use MGM's own implementation. Using ``--subpixel-mode 3`` will
 refine that result using ASP's subpixel implementation. Using

docs/stereo_algorithms.rst

@@ -372,9 +372,10 @@ SGBM options
     Choose among several flavors of SGBM. Use ``sgbm`` for the
     less-memory intensive mode. Setting this mode to ``hh`` will run
     the full-scale two-pass dynamic programming algorithm. It will
-    consume O(image_width * image_height * num_disparities) bytes and
-    it tends to crash for a large input disparity range. Use ``3way``
-    for yet another flavor which OpenCV does not document.
+    consume O(image_width * image_height * num_disparities) bytes of
+    memory, and may run out of memory for a large input
+    disparity range. Use ``3way`` for yet another flavor which OpenCV
+    does not document.
 
 -block_size (default = 3):
     Block size to use to match blocks from left to right image. It
@@ -537,6 +538,11 @@ follows.
     options being used, as well as what the input and output files
     are.
 
+-debug_images (default = 0):
+    If non-zero, save the images to disk right before being passed
+    to libelas (the images are thus padded, aligned, and scaled
+    to have byte pixels).
+
 .. _msmw:
 
 Multi-Scale Multi-Window stereo matching

docs/stereodefault.rst

@@ -38,8 +38,8 @@ ip-per-image
 
 ip-detect-method
     What type of interest point detection algorithm to use for image
-    alignment. 0 = Custom OBAloG implementation (default) 1 = SIFT
-    implementation from OpenCV 2 = ORB implementation from OpenCV If
+    alignment. 0 = Custom OBAloG implementation (default), 1 = SIFT
+    implementation from OpenCV, 2 = ORB implementation from OpenCV. If
     the default method does not perform well, try out one of the other
     two methods.
 

src/CMakeLists.txt

@@ -21,8 +21,8 @@ project (StereoPipeline)
 
 # The line below is used by the docs/ so don't change it
 # without testing the result.  Versioning is based on https://semver.org
-set(PACKAGE_VERSION "2.7.0")
-#set(PACKAGE_VERSION "2.7.1-alpha")
+set(PACKAGE_VERSION "3.0.0")
+#set(PACKAGE_VERSION "3.0.1-alpha")
 set(PACKAGE_NAME "NASA Ames Stereo Pipeline")
 set(PACKAGE_STRING "${PACKAGE_NAME} ${PACKAGE_VERSION}")
 set(PACKAGE_BUGREPORT "scott.t.mcmichael@nasa.gov, oleg.alexandrov@nasa.gov")