updated docs

Former-commit-id: 22128de

README.md

@@ -101,7 +101,7 @@ python -m deep_image_matching --dir assets/example_cyprus --config superpoint+li
 
 For all the usage instructions, refer to the documenation at [https://3dom-fbk.github.io/deep-image-matching/](https://3dom-fbk.github.io/deep-image-matching/getting_started) or check the example notebooks.
 
-To run the GUI by using the following command:
+To run the GUI, you can use the following command:
 
 ```bash
 python main.py --gui

docs/getting_started.md

@@ -14,7 +14,7 @@ The minimal required option are:
 Other optional parameters are:
 
 - `--strategy` `-m`: the strategy to use for matching the images. See [Matching strategies](#matching-strategies) section (default: `matching_lowres`)
-- `--quality` `-Q`  : the quality of the images to be matched. It can be `low`, `medium` or `high` See [Quality](#quality) section (default: `high`).
+- `--quality` `-Q`: the quality of the images to be matched. It can be `lowest`, `low`, `medium`, `high` or `highest`. See [Quality](#quality) section (default: `high`).
 - `tiling` `-t`: if passed, the images are tiled in 4 parts and each part is matched separately. This is useful for high-resolution images if you do not want to resize them. See [Tiling](#tiling) section (default: `None`).
 - `--images` `-i`: if the folder containing the image is not located in the project directory, you can manually specify the path to the folder containing the images If nothing is passed, deep_image_matching will look for a folder named "image" inside the project directory (default: `None`).
 - `--outs` `-o`: if you want the outputs to be save to a specific folder, different than the one set with '--dir', the path to the folder where the matches will be saved. If nothing is passed, the output will e saved in a folder 'results' inside the project direcoty (default: `None`)
@@ -31,7 +31,7 @@ Finally, there are some 'strategy-dependent' options (i.e., options that are use
 - `--pairs` `-p`: if `strategy` is set to `custom_pairs`, set the path to the text file containing the pairs of images to be matched. (default: `None`).
 
 
-## GUI
+## Graphical User Interface (GUI)
 
 **Note that the GUI is still under development and it may have some bugs**
 
@@ -42,9 +42,9 @@ python ./main.py --gui
 ```
 
 In the GUI, you can define the same parameters that are available in the CLI.
-The GUI loads the available configurations from `config.py` `config.py` file located in `/src/deep_image_matching`.
+The GUI loads the available configurations from [`config.py`](https://github.com/3DOM-FBK/deep-image-matching/blob/master/src/deep_image_matching/config.py) located in `/src/deep_image_matching`.
 
-## From a Jupyter notebook
+## From a Jupyter notebooks
 
 If you want to use Deep_Image_Matching from a Jupyter notebook, you can check the examples in the [`notebooks`](https://github.com/3DOM-FBK/deep-image-matching/tree/master/notebooks) folder.
 
@@ -92,13 +92,13 @@ More information can be obtained looking to the code in [`config.py`](https://gi
 The matching strategy defines how the pairs of images to be matches are selected. Available matching strategies are:
 
 - `matching_lowres`: the images are first matched at low resolution (resizing images with the longest edge to 1000 px) and candidates are selected based on the number of matches (the minimum number of matches is 20). Once the candidate pairs are selected, the images are matched at the desired resolution, specified by the `Quality` parameter in the configuration. This is the default option and the recommended strategy, especially for large datasets.
-- `bruteforce`: all the possible pairs of images are matched. This is is usefult in case of very challenging datasets, where some image pairs may be rejected by the previous strategies, but it can take significantly more time for large datasets. 
+- `bruteforce`: all the possible pairs of images are matched. This is is useful in case of very challenging datasets, where some image pairs may be rejected by the previous strategies, but it can take significantly more time for large datasets. 
 - `sequential`: the images are matched sequentially, i.e., the first image is matched with the second, the second with the third, and so on. The number of images to be matched sequentially is defined by the `--overlap` option in the CLI. This strategy is useful for datasets where the images are taken sequentially, e.g., from a drone or a car.
 - `retrieval`: the images are first matched based with a global descriptor to select the pairs. The global descriptor to be used is defined by the `--retrieval` option in the CLI. Available global descriptors are: "netvlad", "openibl", "cosplace", "dir".
 - `custom_pairs`: the pairs of images to be matched are defined in a text file. The path to the text file is defined by the `--pairs` option in the CLI. The text file must contain one pair of images per line, separated by a space. The images must be identified by their full name (i.e., the name of the image file with the extension). 
 For example:
 
-```bash
+```text
     image_1.jpg image_2.jpg
     image_3.jpg image_4.jpg
 ```
@@ -110,19 +110,19 @@ The `Quality` parameter define the resolution at which the images are matched. T
 - `high`: the images are matched at the original resolution (default)
 - `highest`: the images are upsampled by a factor of 2 by using a bicubic interpolation.
 - `medium`: the images are downsampled by a factor of 2 by using the OpenCV pixel-area approach ([cv2.INTER_AREA](https://docs.opencv.org/4.x/da/d54/group__imgproc__transform.html#gga5bb5a1fea74ea38e1a5445ca803ff121acf959dca2480cc694ca016b81b442ceb)).
-- `low`: the images are downsampled by a factor of 4.
-- `lowest`: the images are downsampled by a factor of 8.
+- `low`: the images are downsampled by a factor of 4 by using the OpenCV pixel-area approach.
+- `lowest`: the images are downsampled by a factor of 8 by using the OpenCV pixel-area approach.
 
 ### Tiling
 
-If images have a high resolution (e.g., larger than 2000 px) and you do not want to downsample them (e.g., to avoid loosing accuracy in feature detection), it may be useful to carry out the matching by dividing the images into regular tiles.
+If images have a high resolution (e.g., larger than 3000 px, but this limit depends on the memory of your GPU) and you do not want to downsample them (e.g., to avoid loosing accuracy in feature detection), it may be useful to carry out the matching by dividing the images into regular tiles.
 This can be done by specifying the tiling approach with the `--tiling` option in the CLI. 
 If you want to run the matching by tile, you can choose different approaches for selecting the tiles to be matched. Available options are:
 
 - `None`: no tiling is applied (default)
-- `preselection`: images are divided into a regular grid of size 2400x2400 px and the features are extracted from each tile separately on all the images. For the matching, each image pair is first matched at a low resolution to select which are the tiles that most likely see the same scene and therefore are good candidates to be matched. Then, the selected candidate tiles are matched at full resolution. This is the recommended option for most of the cases as it allows for a significantly reduction in processing time compared to the `exhaustive` approach.
-- `grid`: the images are divided into a regular grid of size 2400x2400 px for feature extraction. The matching is carried out by matching the tiles in the same position in the grid (e.g., the tile in the top-left corner of the first image is matched with the tile in the top-left corner of the second image). This method is recommended only if the images are taken from the same point of view and the camera is not rotated.
-- `exhaustive`: the images are divided into a regular grid of size 2400x2400 px to extract the features. The matching is carried out by matching all the possible combinations of tiles (brute-force). This method can be very slow for large images or in combination with the `highest` quality option and, in some cases, it may lead to error in the geometric verification if too many wrong matches are detected.
+- `preselection`: images are divided into a regular grid of size 2400x2000 px and the features are extracted from each tile separately on all the images. For the matching, each image pair is first matched at a low resolution to select which are the tiles that most likely see the same scene and therefore are good candidates to be matched. Then, the selected candidate tiles are matched at full resolution. This is the recommended option for most of the cases as it allows for a significantly reduction in processing time compared to the `exhaustive` approach.
+- `grid`: the images are divided into a regular grid of size 2400x2000 px for feature extraction. The matching is carried out by matching the tiles in the same position in the grid (e.g., the tile in the top-left corner of the first image is matched with the tile in the top-left corner of the second image). This method is recommended only if the images are taken from the same point of view and the camera is not rotated.
+- `exhaustive`: the images are divided into a regular grid of size 2400x2000 px to extract the features. The matching is carried out by matching all the possible combinations of tiles (brute-force). This method can be very slow for large images or in combination with the `highest` quality option and, in some cases, it may lead to error in the geometric verification if too many wrong matches are detected.
 
 To control the tile size and the tile overlap, refer to the [Advanced configuration](#advanced-configuration) section.
 
@@ -154,7 +154,12 @@ general:
   tile_overlap: 20
 ```
 
-The `extractor` section contains the parameters that control the feature extractor with each approach. The `extractor` section **must contain the name** of the local feature extractor that will be used for the matching and other additional parameters. The name must be the same as the one used in the `--config` option in the CLI.
+The `extractor` and `matcher` sections contain the parameters that control the local feature extractor and the matcher selected by the '--config' option from the CLI (or from GUI). 
+Both the sections **must contain the name** of the local feature extractor or the matcher that will be used for the matching (the name must be the same as the one used in the `--config` option in the CLI).
+In addition, you can specify any other parameters for controlling the extractor and the matcher. 
+The default values of all the configuration parameters are defined in the [`config.py`](https://github.com/3DOM-FBK/deep-image-matching/blob/master/src/deep_image_matching/config.py) file located in `/src/deep_image_matching` directory. 
+Please, note that different extractors or matchers may have different parameters, so you need to check carefully 
+
 
 ```yaml
 extractor:
@@ -166,7 +171,6 @@ matcher:
   filter_threshold: 0.1
 ```
 
-The default values of all the configuration parameters are defined in the[ `config.py`](https://github.com/3DOM-FBK/deep-image-matching/blob/master/src/deep_image_matching/config.py) file located in `/src/deep_image_matching` directory.
 
 <details>
 

docs/installation.md

@@ -30,9 +30,9 @@ Install pycolmap:
 pip install pycolmap
 ```
 
-As [pycolmap](https://github.com/colmap/pycolmap) was released on PyPi only for Linux and macOS (up to version 0.4.0), it is not installed by default with deep-image-matching. 
-Therefore, it is not included in the dependencies of deep-image-matching.
-From version 0.5.0, pycolmap can be installed on Windows too, so we are considering to add it as a dependency of deep-image-matching.
+Up to version 0.4.0, [pycolmap](https://github.com/colmap/pycolmap) was released on PyPi only for Linux and macOS.
+Therefore, it was not included in the dependencies of deep-image-matching, so you need to install it manually.
+From [version 0.5.0](https://github.com/colmap/pycolmap/releases/tag/v0.5.0), pycolmap can be installed on Windows too, so we are considering to add it as a dependency of deep-image-matching.
 
 
 ## Notes and troubleshooting
@@ -41,7 +41,6 @@ From version 0.5.0, pycolmap can be installed on Windows too, so we are consider
 
 If you run into any troubles installing Pytorch (and its related packages, such as Kornia), please check the official website ([https://pytorch.org/get-started/locally/](https://pytorch.org/get-started/locally/)) and follow the instructions for your system and CUDA architecture. Then, try to install again deep-image-matching.
 
-
 ### Pydegensac
 Deep-image-matching relies on [pydegensac](https://github.com/ducha-aiki/pydegensac) for the geometric verification of matches, which is only available for `Python <=3.9` on Windows. If you are using Windows, please, install `Python 3.9`, on Linux, you can also use `Python 3.10`.
 

mkdocs.yml

@@ -1,10 +1,10 @@
 site_name: Deep Image Matching
-repo_url: https://3DOM-FBK.github.io/deep-image-matching
+site_url: https://3dom-fbk.github.io/deep-image-matching/
+repo_url: https://github.com/3DOM-FBK/deep-image-matching
 site_author: 3DOM
 
 theme:
   name: readthedocs
-  highlightjs: true
   # palette:
   #   primary: indigo
   # font:
@@ -28,7 +28,6 @@ nav:
   - Home: index.md
   - Installation: installation.md
   - Getting started: getting_started.md
-  # - Advanced usage: advanced_usage.md
   - API Reference:
       - Configuration: config.md
       - Extractors: extractors.md