pySLAM v2 master update

very concise list of updates:
- fixed many bugs
- huge refactoring
- added keyframe management with covisibility graph
- added multi-threading
- added support for many modern local features

Author: luigifreda

.gitignore

@@ -14,3 +14,9 @@ matches.txt
 map.png
 .vscode 
 videos/webcam
+
+kf_info.log 
+local_mapping.log 
+tum_association_matches.txt 
+
+thirdparty/protoc 

.gitmodules

@@ -4,3 +4,27 @@
 [submodule "thirdparty/tfeat"]
 	path = thirdparty/tfeat
 	url = https://github.com/vbalnt/tfeat.git
+[submodule "thirdparty/hardnet"]
+	path = thirdparty/hardnet
+	url = https://github.com/DagnyT/hardnet
+[submodule "thirdparty/SOSNet"]
+	path = thirdparty/SOSNet
+	url = https://github.com/yuruntian/SOSNet.git
+[submodule "thirdparty/logpolar"]
+	path = thirdparty/logpolar
+	url = https://github.com/cvlab-epfl/log-polar-descriptors.git
+[submodule "thirdparty/d2net"]
+	path = thirdparty/d2net
+	url = https://github.com/mihaidusmanu/d2-net.git
+[submodule "thirdparty/tensorflow_models"]
+	path = thirdparty/tensorflow_models
+	url = https://github.com/tensorflow/models
+[submodule "thirdparty/lfnet"]
+	path = thirdparty/lfnet
+	url = https://github.com/vcg-uvic/lf-net-release.git
+[submodule "thirdparty/r2d2"]
+	path = thirdparty/r2d2
+	url = https://github.com/naver/r2d2.git
+[submodule "thirdparty/keynet"]
+	path = thirdparty/keynet
+	url = https://github.com/axelBarroso/Key.Net.git

CONDA.md

@@ -1,14 +1,80 @@
-# Test under Anaconda 
+# Install under Anaconda or Miniconda
+
+I've successfully tested `pyslam` under [Anaconda](https://docs.anaconda.com/anaconda/install/linux/) (version *2019.10*, build *py37_0*) and [Miniconda](https://docs.conda.io/en/latest/miniconda.html#linux-installers) (SHA256 hash *957d2f0f0701c3d1335e3b39f235d197837ad69a944fa6f5d8ad2c686b69df3b*).   
+Please, follow the instructions below.
+
+## Create a `pyslam` conda environment 
+
+In order to create a custom `pyslam` conda environment, run the following command: 
+```
+$ . pyenv-conda-create.sh 
+```
+
+## Activate the created `pyslam` conda environment 
+
+Run the following command: 
+```
+$ . pyenv-conda-activate.sh 
+```
+or 
+```
+$ conda activate pyslam 
+```
+
+# Deactivate `pyslam` conda environment 
+
+To deactivate the `pyslam` environment, use
+```
+$ conda deactivate
+```
+
+--- 
+# General Notes About Conda
+
+Below, you can find some useful details. The scripts mentioned above make the work for you. 
+
+## Install packages/env from file 
+
+You can generate a `requirements.txt` file by running: 
+```
+$ conda list -e > requirements-conda.txt
+```
+You can create and environment from such a file by runnning: 
+```
+$ conda create --name <env> --file requirements-conda.txt
+```
+
+**N.B.**: the file `requirements.txt` generated by conda cannot be used with pip3 (and viceversa)! 
+
+Another approach is to use `.yml` files. In order to create a file `requirements-conda.yml` run:   
+```
+$ conda env export > requirements-conda.yml
+```
+You can create an environment from it by running: 
+```
+$ conda env create -f requirements.yml
+```
+
+## Deleting an environment 
+
+To delete an environment, in your terminal window or an Anaconda Prompt, run:
+`$ conda remove --name myenv --all`
+
+You may instead use 
+`$ conda env remove --name myenv`
+To verify that the environment was removed, in your terminal window or an Anaconda Prompt, run:
+`$ conda info --envs` 
+The environments list that displays should not show the removed environment.
 
-I've successfully tested `main_vo.py` under Anaconda (version 2019.10). Please, follow the instructions below.
 
 In order to create a new conda environment `opencvenv`, activate it  and install OpenCV in it, run the following commands:  
 ```
-$ conda create -yn opencvenv python=3.6
+$ conda create -yn opencvenv python=3.6.9
 $ conda activate opencvenv
 $ conda install -c menpo opencv3
 ```
 This should install OpenCV 3.4.1 and everything you need to run SIFT and SURF. 
+
 In order to install pytorch and torchvision: 
 ```
 $ conda install pytorch torchvision cudatoolkit=10.1 -c pytorch
@@ -33,9 +99,3 @@ To re-activate the conda `opencvenv` environment, use
 ```
 $ conda activate opencvenv
 ```
-
-## TODO
-Test the following script under Anaconda 
-``` 
-$ ./install_thirdparty.sh 
-```

PYTHON-VIRTUAL-ENVS.md

@@ -0,0 +1,110 @@
+# pySLAM2 Virtual Environment 
+
+## Create a `pyslam` python virtual environment 
+
+In order to create a custom `pyslam` python virtual environment, get in the root of this repository and run the following command: 
+```
+$ . pyenv-create.sh 
+```
+**N.B.**: do not forget the dot!
+
+This will create and activate a python virtual environment `pyslam` where to safely run pyslam scripts. 
+
+## Activate the created `pyslam` environment 
+
+Run the following command: 
+```
+$ . pyenv-activate.sh 
+```
+Now, you can launch pySLAM scripts. 
+
+## Deactivate `pyslam` environment 
+
+Run the command: 
+```
+$ deactivate 
+```
+
+
+--- 
+# General Notes About Python Virtual Environments 
+
+Below, you can find some useful details. The scripts mentioned above make the work for you. 
+
+## Install virtualenv package 
+
+```
+sudo apt install python3-venv
+```
+
+## Where to create a new virtual environment 
+
+You can create a new directory where to deploy the new environment with name `venv-name`
+```
+$ mkdir -p ~/.python/venvs/<venv-name> 
+$ cd ~/.python/venvs/<venv-name>
+```
+Create a new virtual environment inside the directory:
+```
+$ python3 -m venv <venv-name>
+```
+
+## Activate the environment 
+
+In order to use this environment’s packages/resources in isolation, you need to “activate” it. To do this, just run the following:
+
+```
+$ source ~/.python/venvs/<venv-name>/bin/activate
+```
+This will return in your shell a prefixed prompt with the name of your environment
+```
+(env) $
+```
+This is the indicator that env is currently active, which means the python executable will only use this environment’s packages and settings.
+
+
+## Deactivate the environment 
+
+Run the following command 
+```
+(env) $ deactivate
+```
+This will removed the prefixed prompt. 
+
+## Install packages from requirements.txt 
+
+You can generate a `requirements.txt` file by running: 
+```
+$ pip3 freeze > requirements-pip3.txt 
+``` 
+You can install from such a file by runnning: 
+```
+$ pip3 install -r requirements-pip3.txt
+```
+
+**N.B.**: the file `requirements.txt` generated by pip3 cannot be used with conda (and viceversa)! 
+
+## Check if you are in an activated virtual environment 
+
+From shell check the shell prefix, as explained above 
+
+From a script, you can use the following code:
+```
+function get_after_last_slash(){
+    ret=$(echo $1 | sed 's:.*/::')
+    echo $ret 
+}
+function get_virtualenv_name(){
+    cmd_out=$(printenv | grep VIRTUAL_ENV)
+    virtual_env_name=$(get_after_last_slash $cmd_out)
+    echo $virtual_env_name
+}
+```
+the function `get_virtualenv_name` returns the name of the path of the activated virtual environment. 
+If no virtual environment has been activated then the output will be empty.  
+
+
+
+## Links 
+
+* https://realpython.com/python-virtual-environments-a-primer/  (first and clear reference)