Option --num-matches-from-disparity will save match files reflecting …

…original unprojected images

NEWS.rst

@@ -26,6 +26,9 @@ misc:
  * The option ``--flann-method`` in ``bundle_adjust`` and ``stereo`` defaults to
    using the slower but deterministic ``kmeans`` method for a smaller set of
    interest points, and to ``kdtree`` otherwise (:numref:`stereodefault-pprc`).
+ * When creating dense interest point matches from disparity and mapprojected
+   images, the match file reflects the name of the original unprojected images
+   (:numref:`dense_ip`).
 
 RELEASE 3.4.0, June 19, 2024
 ----------------------------

docs/bundle_adjustment.rst

@@ -1115,13 +1115,24 @@ or::
   
     --num-matches-from-disparity 10000
 
+in order to create such a match file.
+
 Only the second approach is supported with mapprojected images. See
 :numref:`triangulation_options` for more details. 
 
-The produced interest points *must be renamed to the standard convention* and
-reflect the names of the raw images, not the mapprojected ones
-(:numref:`ba_match_files`), then passed to ``bundle_adjust`` via the
-``--match-files-prefix`` option.
+The produced match file name is named along the lines of::
+
+   run/run-disp-left__right.match
+
+where ``left.tif`` and ``right.tif`` are the input images. If these images are
+mapprojected, the latest ASP (post version 3.4.0) will instead adjust the match
+file name to reflect the original, unprojected image names, as the matches are
+between those images. 
+
+In either case, the produced match files *must use the standard naming
+convention* for the original image names (:numref:`ba_match_files`). The match
+files must be passed to ``bundle_adjust`` via the ``--match-files-prefix``
+option. In this example, the prefix would be ``run/run-disp``.
 
 Invoke ``bundle_adjust`` with an option along the lines of
 ``--max-pairwise-matches 20000`` (or larger) to ensure that on reading the

docs/stereodefault.rst

@@ -796,19 +796,22 @@ save-double-precision-point-cloud (default = false)
     precision at twice the storage).
 
 num-matches-from-disp-triplets (*integer*) (default = 0)
-    Create a match file with this many points uniformly sampled from the stereo
-    disparity, while making sure that if there are more than two images, a
-    set of ground features are represented by matches in at least three of
-    them. The matches are between original images (that is, before any
-    alignment or map-projection). The file name is ``<output
-    prefix>-disp-<left image>__<right image>.match``. This can
-    be very slow for images 50,000 or more on the side. Use then
-    ``num-matches-from-disparity``.  To not continue
-    with triangulation, use ``--compute-point-cloud-center-only``.
-    See :numref:`floatingintrinsics` for an application.
+    Create a match file with roughly this many points uniformly sampled from the
+    stereo disparity, while making sure that if there are more than two images,
+    a set of ground features are represented by matches in at least three of
+    them. The matches are between original images (that is, before any alignment
+    or map-projection). The file name is ``<output prefix>-disp-<left
+    image>__<right image>.match``. In latest ASP (post version 3.4.0), if these
+    images are mapprojected, the mach file is adjusted to reflect the names of
+    the original unprojected images. Creating this match file can be very slow
+    for images 50,000 or more on the side. Use then
+    ``num-matches-from-disparity``.  To not continue with triangulation, use
+    ``--compute-point-cloud-center-only``. Such match files can be used in
+    bundle adjustment when refining the lens distortion
+    (:numref:`heights_from_dem`).
 
 num-matches-from-disparity (*integer*) (default = 0)
-    Create a match file with this many points uniformly sampled from
+    Create a match file with roughly this many points uniformly sampled from
     the stereo disparity. The matches are between original images
     (that is, before any alignment or map-projection). See also
     ``num-matches-from-disp-triplets``.

src/asp/Core/StereoSettings.cc

@@ -423,7 +423,11 @@ namespace asp {
       ("unalign-disparity",                 po::bool_switch(&global.unalign_disparity)->default_value(false)->implicit_value(true),
        "Take the computed disparity, and compute the disparity between unaligned images.")
       ("num-matches-from-disparity", po::value(&global.num_matches_from_disparity)->default_value(0), "Create a match file with this many points uniformly sampled from the stereo disparity. The matches are between original images (that is, before any alignment or map-projection). See also num-matches-from-disp-triplets.")
-      ("num-matches-from-disp-triplets", po::value(&global.num_matches_from_disp_triplets)->default_value(0), "Create a match file with this many points uniformly sampled from the stereo disparity, while making sure that if there are more than two images, a set of ground features are represented by matches in at least three of them. The matches are between original images (that is, before any alignment or map-projection). The file name is <output prefix>-disp-<left image>__<right image>.match.")
+      ("num-matches-from-disp-triplets", po::value(&global.num_matches_from_disp_triplets)->default_value(0), 
+       "Create a match file with this many points uniformly sampled from the stereo "
+       "disparity, while making sure that if there are more than two images, a set of ground "
+       "features are represented by matches in at least three of them. See the documentation "
+       "for more info.")
       ("point-cloud-rounding-error",
        po::value(&global.point_cloud_rounding_error)->default_value(0.0),
        "How much to round the output point cloud values, in meters (more rounding means less precision but potentially smaller size on disk). The inverse of a power of 2 is suggested. Default: 1/2^10 for Earth and proportionally less for smaller bodies, unless error propagation happens, when it is set by default to 1e-8 meters, to avoid introducing step artifacts in these errors.")

src/asp/Sessions/StereoSession.cc

@@ -77,10 +77,6 @@ namespace asp {
                         m_left_map_proj_model, m_right_map_proj_model);
   }
 
-  // TODO(oalexan1): The logic below must be a function, to be applied to left and
-  // to right data, and also to be used in bundle_adjust to find the right camera
-  // when undoing mapprojection.
-
   // Read keywords that describe how the images were map-projected.
   void read_mapproj_headers(std::string const& map_file,
                             std::string const& input_cam_file,

src/asp/Tools/stereo.cc

@@ -557,6 +557,16 @@ void handle_arguments(int argc, char *argv[], ASPGlobalOptions& opt,
               << usage << general_options);
   }
 
+  // For time being the crop wins are not taken into account when
+  // matches are produced from disparity, and the results are wrong.
+  // Therefore, disable this.
+  if ((crop_left || crop_right) && 
+      (stereo_settings().num_matches_from_disparity > 0 ||
+       stereo_settings().num_matches_from_disp_triplets > 0))
+    vw_throw(ArgumentErr() << "Cannot use --num-matches-from-disparity or "
+              << "--num-matches-from-disp-triplets with --left-image-crop-win or "
+              << "--right-image-crop-win.\n");
+
   // Ensure good order
   BBox2 & b = stereo_settings().lon_lat_limit; // alias
   if (b != BBox2(0,0,0,0)) {

src/asp/Tools/stereo_tri.cc

@@ -570,9 +570,28 @@ void disp_or_matches_work(std::string const& output_prefix,
     unalign_disparity(is_map_projected, disparity_maps[0], left_trans, right_trans,  
                       opt, unaligned_disp_file);
   }
-
+
+  // If the images are mapprojected and we know the original image names,
+  // use those for the match file. That because the matches are between
+  // the original images, not the map-projected ones.
+  std::string img_file_key = "INPUT_IMAGE_FILE"; 
+  std::string left_image = opt.in_file1, right_image = opt.in_file2;
+  {
+    std::string img_file;  
+    boost::shared_ptr<vw::DiskImageResource> rsrc(new vw::DiskImageResourceGDAL(opt.in_file1));
+    vw::cartography::read_header_string(*rsrc.get(), img_file_key, img_file);
+    if (!img_file.empty()) 
+      left_image = img_file;
+  }
+  {
+    std::string img_file;
+    boost::shared_ptr<vw::DiskImageResource> rsrc(new vw::DiskImageResourceGDAL(opt.in_file2));
+    vw::cartography::read_header_string(*rsrc.get(), img_file_key, img_file);
+    if (!img_file.empty())
+      right_image = img_file; 
+  }
   std::string match_file = ip::match_filename(output_prefix + "-disp",
-                                              opt.in_file1, opt.in_file2);
+                                              left_image, right_image);
 
   // Pull matches from disparity.
   if (stereo_settings().num_matches_from_disparity > 0 &&