AutoRansac - Automatic RANSAC Algorithms
Comparison of RANSAC algorithms with automatic threshold estimation

Clement Riu clement.riu@enpc.fr
Pascal Monasse pascal.monasse@enpc.fr
Imagine/LIGM, Universite Paris Est/Ecole des Ponts ParisTech

# Reviewed files in IPOL:
src/demo/demo.cpp
src/libOrsa/lrtsac.{hpp,cpp}

# Future releases and updates:
https://github.com/ClementRiu/RANSAC-benchmark

# Description:
Implementation of RANSAC algorithms:
- RANSAC (the classic one)
- AC-RANSAC (a.k.a. ORSA) minimizing Number of False Alarms
- LRTSAC maximazing likelihood
They can solve the following computer vision estimation problems:
- Homography transform
- Fundamental matrix
- Essential matrix

# Licensing: See LICENSE.txt file

# Build
This project build relies on CMake ((https://cmake.org/).

## LINUX/MAC:
```
  $ cd .../AutoRansac
  $ mkdir Build
  $ cd Build
  $ cmake -D CMAKE_BUILD_TYPE:string=Release ../src
  $ make
```
If you target to use an IDE to compile the code:
```
  $ cmake -G "CodeBlocks - Unix Makefiles" ../src
```

## WINDOWS:
  Launch cmake-gui.exe

  Fill the blank path.
  "Where is the source code :" (where the general CMakeLists.txt is).
    => Scripts/src
  "Where to build the binaries:" (where build project and object files will be).
    => Scripts/build

  Press Configure. (Select your IDE. ie, Visual Studio 10 Win64)
  Press Generate.
  Go to the merged_script/build path.
  Launch the Visual Studio solution and compile in release mode.

# USAGE
Go to the build folder. The executable files are in the `demo`, and `experiments` subfolders.

## Demo

There is a single demo executable file for all models and all available algorithms.
The `-m` or `--model` parameter controls the model and the `-a` or `-algo` parameter controls the algorithm used. Available models are: `Homography/Fundamental/Essential`, available algorithms are: `Ransac/AC-Ransac/LRT`.

Usage:
```
./demo/demo [options] imgInA imgInB allInOutMatches.txt inlierOutMatches.txt [optImgOut]
- imgInA, imgInB: the two input image (JPG/PNG format)
- allInOutMatches.txt: output (input if -r) text file of format "x1 y1 x2 y2"
- inlierOutMatches.txt: output, but only with inliers.
        [optImgOut] (output images): inliers outliers [mosaic/epi [regA regB]]
- inliers, outliers: lines for inliers, lines for outliers and their error
- mosaic/epi: mosaic if Homography else epipolar lines
- regA, regB: registered images (Homography only)
        Options:
-c, --cut=ARG cut region of imagInA: wxh+x+y = rect [x,x+w] x [y,y+h] (0x0+0+0)
-r, --read Read file of matches allMatches.txt, do not use SIFT
-s, --sift=ARG SIFT distance ratio of descriptors (0.6)
-m, --model=ARG Model class: Homography/Fundamental/Essential (Homography)
-a, --algo=ARG Algorithm to use: Ransac/AC-Ransac/LRT (Ransac)
-i, --iterMax=ARG Number of iterations of the algorithm. (50000)
-p, --precision=ARG Max precision (in pixels) of registration (0=arbitrary) (3)
--cpIIT=ARG Confidence against type II error (Ransac/LRT) (0.99)
-n, --nModelMinRansac=ARG Min number of models before terminating ransac (1)
--cpI=ARG Confidence proba wrt type I error (LRT) (0.99)
--cpIIB=ARG Confidence proba wrt bailout (LRT) (0.95)
-k, --Kfile=ARG File for calibration matrices (Essential only)
-v, --verbose Print info during the run.
-t, --time-seed=ARG Use value instead of time for random seed. (1620308988)
```

Example of run: registration by homography of two images with LRTSAC, maximum allowable threshold 16 pixels. The algorithm puts a threshold at 2 pixels and finds 97% inliers.
```
./demo/demo ../../data/ramparts[12].jpg all.txt in.txt in.jpg out.jpg mosaic.jpg reg1.jpg reg2.jpg -a LRT -m Homography -v -p 16
Rerun with "-t 1620309519" to reproduce
sift:: 1st image: 629 keypoints
sift:: 2nd image: 695 keypoints
sift:: matches: 177
Remove 20/177 duplicate matches, keeping 157
Model: Homography, Algorithm: LRT
(init)  L=0.073914 inliers=0 precision=16 iter=-1/50000 Sigma={0.25...16}
  L=8.29127 inliers=154 precision=4 iter=0/27 Sigma={0.25...4}
  L=8.97558 inliers=154 precision=2.82843 iter=6/19 Sigma={0.25...2.82843}
  L=9.31486 inliers=150 precision=2 iter=7/16 Sigma={0.25...2}
  L=9.48396 inliers=152 precision=2 iter=10/15 Sigma={0.25...2}
Before refinement: RMSE/max error: 0.808628/1.56892
After  refinement: RMSE/max error: 0.63752/1.55203
Result=[ 1.09241 -0.109282 -162.474; 0.166758 1.04799 47.7185; 0.000210258 -3.15157e-05 1 ]
Inliers: 153/157=97%
Sigma: 2
Iterations: 15
Verif/model: 128.5
Runtime (s): 0.002387
-- Render Mosaic -- 
-- Render Mosaic - Image 1 -- 
-- Render Mosaic - Image 2 --
```

## Experiments

The `experiments` subfolder contain the files used to generate the data for icip paper [TODO] and ipol paper [TODO].
There is also a subfolder `data_analyse_python` containing the python files used to analyse the data and create the figures present in the papers.

See specific REAMDE.md files of each subfolder for how to reproduce the experiments.