--------------------------------------------------------------------------------
	    TILDE: a Temporally Invariant Learned DEtector
	
This  software is  the  C++ and  MATLAB implementation  for  the TILDE  keypoint
detector presented in [1]. The software  provides both the C++ implementation of
TILDE  which  can  be used  easily  to  detect  keypoints,  and a  MATLAB  based
evaluation framework.

This  software is  strictly for  academic  purposes only.   For other  purposes,
please  contact  us.  When  using  this software,  please  cite  [1]  and  other
appropriate publications if necessary (see matlab/external/licenses for details).

[1] Y.  Verdie, K.   M.  Yi,  P.  Fua,  and V.   Lepetit.  "TILDE:  A Temporally
    Invariant Learned DEtector.", Computer Vision and Patern Recognition (CVPR),
    2015 IEEE Conference on.


Contact:

Yannick Verdie : yannick<dot>verdie<at>epfl<dot>ch
Kwang Moo Yi   : kwang<dot>yi<at>epfl<dot>ch


--------------------------------------------------------------------------------
      	  		<< The TILDE C++ Implementation >>

The C++  implementation of TILDE provides  an easy-to-use library with  a simple
demo program  to detect and  display the  keypoints. We provide  TILDE keypoints
learned with the Webcam dataset in [1].

----
NOTES:

 - Code compiles with clang (macOS) and gcc-4.9 (Linux)
 - The code will generate a static  library, a dynamic library (libTILDE) and an
   example code (demo).

----
REQUIREMENTS:

 - OpenCV 2.4.9 or higher
 - CMake 2.8 or higher

----
USAGE:

Build the  libraries and  the demo.  Standard procedure is  as follow  (from the
project root directory):

 >> cd c++
 >> mkdir build
 >> cd build
 >> cmake ..
 >> make

Then you can run the demo code from the build directory with:

 >> ./Demo/demo

----
IMPORTANT FUNCTIONS:

The main function is getTILDEKeyPoints (see demo.cpp)

std::vector<cv::KeyPoint> getTILDEKeyPoints(cv::Mat image,
			  		    std::string pathFilter,
					    bool useApprox,
					    bool sortKeypoints,
					    bool keepPositiveOnly,
					    cv::Mat *score)
					    
<<input parameters>>:

 - image: a openCV U8C3 Mat object representing the image to process
 - pathFilter: a std string object giving the name of the filter to apply
 - useApprox:  a boolean  indicating to  use TILDE  (false) or  the approximated
   version of TILDE (true).
 - sortKeypoints:  (true) we  sort the  keypoints by  decreasing order  of their
   scores
 - keepPositiveOnly: (true) only the keypoints with positive score are returned
 - score: a  pointer to an  openCV Mat  image, if the  pointer is not  null, the
   score map is retuned in addition to the keypoints
 
<<output parameters>>:

 - std::vector<KeyPoint>: a std vector of OpenCV KeyPoint object (see OpenCV doc
   for more details on how to use them)

----
DIRECTORY STRUCTURE:

<c++> : Main project directory
  |
  |------ <src> : Contains our main library code and a toy example (demo.cpp)
  |
  |------ <3rdParties> : Contains  the 3rd party codes  which our implementation
  |	  	         is dependent on.
  |			 
  |------ <filters> : Contains the filters  pre-learned with the Webcam dataset.
    	  	      When  a number  is added  in the  name of  the filter,  it
  	  	      denotes that the filter is  for use with the approximation
  	  	      flag  on (i.e.  it is  the approximated  TILDE). The  name
  	  	      indicates which dataset was used to learn this filter.
  
<data> : Contains  a test example testImage.png which is  read by demo.cpp. Also
         used by  the MATLAB  evaluation framework (detail  below) to  store the
         dataset for evaluation.

----
NOTE ON THE LICENSE OF 3RD PARTY SOFTWARE:

In  case of  3rd  party software  used  in  this project.  Please  refer to  the
corresponding copyright notifications on the top of each code.



--------------------------------------------------------------------------------
		      The MATLAB Evaluation Framework

The  MATLAB  evaluation   framework  provides  an  easy  way   to  evaluate  the
repeatability of different detectors. We provide the implementations we used for
SIFT, SURF, FAST-9,  LCF, EdgeFoci, MSER along with our  own TILDEP and TILDEP24
(see [1] for details).

----
NOTE:

Codes run  partially on Mac  OSX (some competitor  methods are not  available on
this platform) and  almost completelly on Linux (all the  competitor methods are
available  on   Linux  except   EdgeFoci.   We  provided   pre-computed  results
separately, available at project web page https://www.epfl.ch/labs/cvlab/research/descriptors-and-keypoints/research-tilde/)

In order  to avoid detecting  the same  keypoints multiple times,  This software
USES CACHING BY DEFAULT.  It will  save computed keypoints in sub-folders of the
dataset folders (detail on the dataset section below). In case you need to reset
the detected keypoints, be sure to erase the cache files.

We  have  enhanced  the  implementation  for easier  use  since  the  paper  was
submitted,  and   we  therefore   recommend  to  use   the  results   from  this
implementation when comparing.  There may be minor differences  with the results
reported in [1].


----
REQUIREMENTS:

 - MATLAB 2013b or higher (may run on older versions but not tested)
 - OpenCV 2.4.9 or higher
 - ImageMagick (for the command 'convert') available both on Mac and Linux
 - Pkg-config

 ** Make  sure the  binaries  provided  in <matlab/external/external_codes>  are
    compiled for your platform. We also  ship pre-compiled binaries for both Mac
    OSX and  Linux. If you want  to use this,  please run link.m to  have proper
    soft links pointing to the correct binary file

----
USAGE:

Try running  the following scripts with  MATLAB (they are located  in matlab/src
and should be run from this folder).

 - link.m: Automatic linking in case of using pre-compiled binaries.

 - demo.m: Here we provide a demo for using our TILDE detector on Matlab similar
   	   to the demo made in c++.
   
 - evaluate_OxfordEFDataset_2percents.m: Runs  the evaluation  of Oxford  and EF
   dataset with the new 2% criteria as reported in the paper [1]
   
 - evaluate_OxfordEFDataset_1000.m: Runs the evaluation of Oxford and EF dataset
   with 1000 keypoints and standard overlap measure as reported in the paper [1]
   
 - evaluate_WebcamDataset_2percents.m:  Runs the  evaluation of  the new  Webcam
   dataset with the new 2% criteria as reported in the paper [1]

----
THE DATASET:

The   dataset   is   available   for   download  at   the   project   web   page
http://cvlab.epfl.ch/research/tilde. Extract  the archive to the  data directory
to use the datasets.

 - Webcam Dataset includes the following folders:

   Chamonix, Courbevoie,Frankfurt, Mexico, Panorama, StLouis

 - Oxford and EF Dataset includes the following folders:

   bark, leuven, rushmore, wall, bikes, notredame, yosemite, boat, obama, trees,
   graf, paintedladies, ubc

For    example,    Chamonix   folder    should    be    located   at    <project
root>/data/Chamonix. Inside each dataset  folder, the following folder structure
should exist.

<Sequence Name>
	  |------ <test>
		    |------ <image_color>
		    |------ <image_gray>
		    |------ <homography>   (only for Oxford and EF)
		    |------ <features> 	   (automatically generated when running
		    |	   		    the benchmark software for caching)
		    |------ test_imgs.txt
		    |------ homography.txt (only for Oxford and EF)


 ** Using pre-computed EdgeFoci results: Simply download and extract the archive
    in the  data directory. It should  write the pre-computed files  (caches) in
    the corresponding <features> sub-folders of the datasets.

----
NOTE ON THE LICENSE OF 3RD PARTY SOFTWARE:

Implementations in the <matlab/external> directory are mostly adaptations of 3rd
party software into our evaluation framework.  For  the terms of use for the 3rd
party software, please refer to the license files in <matlab/external/licenses>


--------------------------------------------------------------------------------