Feature/adaptive thresholding

readme.md

@@ -74,13 +74,25 @@ For more details about the parameters, please use `python run_matching_from_*.py
 For more details about the underlying method and the interpretation of the results, please have a look at [paper](http://www.ipb.uni-bonn.de/pdfs/vysotska16ral-icra.pdf).
 Here is a sketch of what roughly is happening for those who don't like to read much ![](doc/cost_matrix_view.png)
 
-## Parent project
+### Adaptive thresholding
 
-This repository is a continuation of my previous works [vpr_relocalization](https://github.com/PRBonn/vpr_relocalization) and [online_place_recognition](https://github.com/PRBonn/online_place_recognition).
+This algorithm requires user to provide a value for matching threshold, a value that defines starting with which similarity two images are no longer showing the same place. Selecting a correct value for this is not straightforward and depends on the degree of challenge two image sequences exhibit. For example, when matching summer sequence with respect to winter sequence one threshold value would be fitting, however, the same value may not be good when matching day and night sequences. Moreover, the environment can be gradually changing within one image sequence, for example, it becomes gradually darker when the sun goes down.
+
+Here we provide an option to dynamically adapt the initial threshold. The code will check the current similarity values and adapt the matching threshold accordingly.
+To use **adaptive thresholding** add `--adaptThreshold` parameter in the matching call, as shown here:
+
+```bash
+python run_matching_from_images.py \
+    --query_images <path_to_images> \
+    --reference_images <path_to_images> \
+    --dataset_name <dataset_name> \
+    --output_dir <path_to_folder>
+    --write_image_matches
+    --adaptThreshold
+```
 
-The plan is to gradually modernize and improve the code by preserving the essential capabilities of the system.
+For more details, please refer to the [paper](https://www.research-collection.ethz.ch/server/api/core/bitstreams/39b0396e-4743-4bf1-97c6-4cbcf97b0270/content).
 
-**Essential capabilities**:
+## Parent project
 
-1. Given two sequences of images compute the matching image pairs.
-2. Scripts to visualize the results.
+This repository is a continuation of my previous works [vpr_relocalization](https://github.com/PRBonn/vpr_relocalization) and [online_place_recognition](https://github.com/PRBonn/online_place_recognition).

src/apps/similarity_matrix_based_matching/online_localizer_lsh.cpp

@@ -90,9 +90,9 @@ int main(int argc, char *argv[]) {
       std::make_unique<loc::successor_manager::SuccessorManager>(
           database.get(), relocalizer.get(), parser.fanOut);
   loc::online_localizer::OnlineLocalizer localizer{
-      successorManager.get(), parser.expansionRate, parser.matchingThreshold};
+      successorManager.get(), parser.expansionRate, parser.matchingThreshold, parser.adaptThreshold};
   const loc::online_localizer::Matches imageMatches =
-      localizer.findMatchesTill(parser.querySize);
+      localizer.findMatchesTill(parser.querySize, parser.debugProto);
   loc::online_localizer::storeMatchesAsProto(imageMatches,
                                              parser.matchingResult);
 

src/apps/similarity_matrix_based_matching/similarity_matrix_no_hashing.cpp

@@ -1,7 +1,7 @@
 /* By O. Vysotska in 2023 */
 
-#include "database/similarity_matrix_database.h"
 #include "database/idatabase.h"
+#include "database/similarity_matrix_database.h"
 #include "online_localizer/online_localizer.h"
 #include "online_localizer/path_element.h"
 #include "relocalizers/default_relocalizer.h"
@@ -31,7 +31,8 @@ int main(int argc, char *argv[]) {
   parser.print();
 
   const auto database =
-      std::make_unique<loc::database::SimilarityMatrixDatabase>(parser.similarityMatrix);
+      std::make_unique<loc::database::SimilarityMatrixDatabase>(
+          parser.similarityMatrix);
 
   const auto relocalizer =
       std::make_unique<loc::relocalizers::DefaultRelocalizer>(
@@ -41,9 +42,10 @@ int main(int argc, char *argv[]) {
       std::make_unique<loc::successor_manager::SuccessorManager>(
           database.get(), relocalizer.get(), parser.fanOut);
   loc::online_localizer::OnlineLocalizer localizer{
-      successorManager.get(), parser.expansionRate, parser.matchingThreshold};
+      successorManager.get(), parser.expansionRate, parser.matchingThreshold,
+      parser.adaptThreshold};
   const loc::online_localizer::Matches imageMatches =
-      localizer.findMatchesTill(parser.querySize);
+      localizer.findMatchesTill(parser.querySize, parser.debugProto);
   loc::online_localizer::storeMatchesAsProto(imageMatches,
                                              parser.matchingResult);
 

src/localization/database/idatabase.h

@@ -24,14 +24,16 @@
 #ifndef SRC_DATABASE_IDATABASE_H_
 #define SRC_DATABASE_IDATABASE_H_
 
+#include <optional>
+
 namespace localization::database {
 
 /**
  * @brief      Interface class for a database.
  */
 class iDatabase {
 public:
-  virtual int refSize() = 0;
+  virtual int refSize() const = 0;
   /**
    * @brief      Gets the cost. This cost goes directly in the graph structure.
    * Smaller costs correspond to bigger similarities.
@@ -42,6 +44,8 @@ class iDatabase {
    * @return     The cost.
    */
   virtual double getCost(int quId, int refId) = 0;
+  virtual std::optional<double> getCostIfComputed(int quId,
+                                                  int refId) const = 0;
 
   iDatabase() = default;
   iDatabase(const iDatabase &) = delete;

src/localization/database/online_database.cpp

@@ -99,6 +99,24 @@ double OnlineDatabase::getCost(int quId, int refId) {
   return cost;
 }
 
+std::optional<double> OnlineDatabase::getCostIfComputed(int quId,
+                                                        int refId) const {
+  if (precomputedScores_) {
+    if (refId >= refSize()) {
+      return {};
+    }
+    return precomputedScores_->at(quId, refId);
+  }
+  auto rowIter = costs_.find(quId);
+  if (rowIter != costs_.end()) {
+    auto elementIter = rowIter->second.find(refId);
+    if (elementIter != rowIter->second.end()) {
+      return 1. / elementIter->second;
+    }
+  }
+  return {};
+}
+
 const features::iFeature &OnlineDatabase::getQueryFeature(int quId) {
   return addFeatureIfNeeded(*queryBuffer_, quFeaturesNames_, featureType_,
                             quId);

src/localization/database/online_database.h

@@ -26,8 +26,8 @@
 #ifndef SRC_DATABASE_ONLINE_DATABASE_H_
 #define SRC_DATABASE_ONLINE_DATABASE_H_
 
-#include "database/similarity_matrix.h"
 #include "database/idatabase.h"
+#include "database/similarity_matrix.h"
 #include "features/feature_buffer.h"
 #include "features/feature_factory.h"
 
@@ -48,8 +48,9 @@ class OnlineDatabase : public iDatabase {
                  const std::string &refFeaturesDir, features::FeatureType type,
                  int bufferSize, const std::string &similarityMatrixFile = "");
 
-  inline int refSize() override { return refFeaturesNames_.size(); }
+  inline int refSize() const override { return refFeaturesNames_.size(); }
   double getCost(int quId, int refId) override;
+  std::optional<double> getCostIfComputed(int quId, int refId) const override;
 
   double computeMatchingCost(int quId, int refId);
 

src/localization/database/similarity_matrix_database.cpp

@@ -38,4 +38,12 @@ double SimilarityMatrixDatabase::getCost(int quId, int refId) {
   return similarityMatrix_.getCost(quId, refId);
 }
 
+std::optional<double> SimilarityMatrixDatabase::getCostIfComputed(int quId,
+                                                            int refId) const {
+  if (refId >= refSize()) {
+    return {};
+  }
+  return similarityMatrix_.at(quId, refId);
+}
+
 } // namespace localization::database

src/localization/database/similarity_matrix_database.h

@@ -38,8 +38,9 @@ class SimilarityMatrixDatabase : public iDatabase {
 public:
   explicit SimilarityMatrixDatabase(const std::string &costMatrixFile);
 
-  int refSize() override { return similarityMatrix_.cols(); }
+  int refSize() const override { return similarityMatrix_.cols(); }
   double getCost(int quId, int refId) override;
+  std::optional<double> getCostIfComputed(int quId, int refId) const override;
 
 private:
   SimilarityMatrix similarityMatrix_;

src/localization/online_localizer/CMakeLists.txt

@@ -1,3 +1,5 @@
+add_subdirectory(math_tools)
+
 add_library(path_element path_element.cpp)
 target_link_libraries(path_element
 	cxx_flags
@@ -14,6 +16,8 @@ target_link_libraries(online_localizer
 	successor_manager
 	node
 	timer
+	gmm
+	statistical_test
 	protos
 	glog::glog
 )

src/localization/online_localizer/math_tools/CMakeLists.txt

@@ -0,0 +1,19 @@
+add_library(math_tools math_tools.cpp)
+target_link_libraries(math_tools
+    cxx_flags
+    glog::glog
+)
+
+add_library(gmm gmm.cpp)
+target_link_libraries(gmm
+    math_tools
+    cxx_flags
+    glog::glog
+)
+
+add_library(statistical_test statistical_test.cpp constants.h)
+target_link_libraries(statistical_test
+    math_tools
+    cxx_flags
+    glog::glog
+)