From 9566f0f844743c664c8b490566a90a024221e959 Mon Sep 17 00:00:00 2001
From: ptresson <paul.tresson@ird.fr>
Date: Wed, 4 Sep 2024 18:52:16 +0200
Subject: [PATCH] update docs and readme
---
README.md | 4 ++++
docs/source/Installation.rst | 38 +++++++++++++++++++++++--------
docs/source/More.rst | 43 ++++++++++++++++++++++++++++++++----
3 files changed, 72 insertions(+), 13 deletions(-)
diff --git a/README.md b/README.md
index 3055bbb..890cd5f 100644
--- a/README.md
+++ b/README.md
@@ -38,6 +38,10 @@ At first usage, a pop up should appear if necessary dependencies are not detecte
You can find more detailled instructions in the documentation.
+For now, if you want to use a GPU you should install torch manualy following the instructions on https://pytorch.org/get-started/locally/
+
+Autommated GPU dependencies installation is in the works, you can try the `gpu-support` branch on this repo.
+
## Documentation
diff --git a/docs/source/Installation.rst b/docs/source/Installation.rst
index 3a13d17..85bbd1e 100644
--- a/docs/source/Installation.rst
+++ b/docs/source/Installation.rst
@@ -6,32 +6,52 @@ Installation Guide
Plug-in installation
---------------------
+As of now, the plugin is not yet published in official QGIS repos, so you have to clone or copy this code into the python plugin directory of QGIS and manualy install.
+
+this is where it probably is located :
+
+ ::
+
+ # Windows
+ %APPDATA%\QGIS\QGIS3\profiles\default\python\plugins
+
+ # Mac
+ ~/Library/Application\ Support/QGIS/QGIS3/profiles/default/python/plugins
+
+ # Linux
+ ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins
+
+
+Otherwise (for instance if you have several profiles), you can locate it by doing `Settings`>`User Profiles`>`Open active profile folder`.
+
+
Dependencies installation
--------------------------
-To work, the plugin requires QGIS >= 3.34 (LTR) and has been tested with python 3.11.
-
-The main dependencies are ``torchgeo``, ``timm``, ``geopandas``, ``scikit-learn`` and ``umap-learn``.
+To work, the plugin requires QGIS >= 3.34 (LTR) and has been tested with python 3.11. At first usage, a pop up should appear if necessary dependencies are not detected, that gives the option to install them automatically via `pip`.
+The main dependencies are ``torchgeo``, ``timm``, ``geopandas``, ``scikit-learn``. ``umap-learn`` can be used as well but as optional dependency.
The file ``requirement.txt`` in the plugin folder gives precise working versions of each dependencies.
-If the necessary dependencies are not installed, a pop-up should appear on the first usage to propose an automated installation of the dependencies.
-However, if this automated installation does not work, here are detailled instructions to install them.
+However, if the automated installation does not work, here are detailled instructions to install them.
Linux
^^^^^^
-If you want to control your python environment to avoid conflicts with other projects, you can work in a conda environment.
+If you want to control your python environment to avoid conflicts with other projects, you can work in a conda environment, where you can install QGIS.
+
+We will provide a minimum functionning conda environment.
::
conda env create -f environment.yml
-this creates a separate qgis installation within the environment.
+.. this creates a separate qgis installation within the environment.
-Alternatively, the main dependencies are installled via pip and available in the ``requirements_linux.txt`` file. Do keep in mind that there are possible conflict with geospatial dependencies (GDAL, PROJ etc).
+.. Alternatively, the main dependencies are installled via pip and available in the ``requirements_linux.txt`` file.
+Do keep in mind that there are possible conflict with geospatial dependencies (GDAL, PROJ etc).
Windows
@@ -44,7 +64,7 @@ Go to OSGeo4W Shell and install the following dependencies.
pip install torchgeo == 0.5.2
pip install geopandas == 0.14.4
pip install scikit-learn == 1.5.1
- pip install umap-learn == 0.5.6
+ # (optional) pip install umap-learn == 0.5.6
If you have any issue with windows, please provide your QGIS version, your python version an the dependencies currently installed in OSGeo4W.
You can do that by going to OSGeo4W Shell and run the following lines :
diff --git a/docs/source/More.rst b/docs/source/More.rst
index 37428c9..1a11eb2 100644
--- a/docs/source/More.rst
+++ b/docs/source/More.rst
@@ -2,26 +2,61 @@ More
================
-Commons Issue
+Common Issues
---------------
+
+UMAP crashes
+^^^^^^^^^^^^^^^
+
+Because of these issues, UMAP is disabled by default for now.
+
If you're using Windows, the use of UMAP may cause the plug-in to crash QGIS when using it.
If this issue happens we recommend to go in the reduction.py file of this plug in and comment the line :
+
::
+
import umap
Then save the change, reload the plug-in and try again.
-Citation
----------
+FAQ
+---------------
+
+How does it handle more than three band images with pretrained models ?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Our models are created using the `timm` librairy, which is widely used in deep learning research. [Here](https://timm.fast.ai/models#How-is-timm-able-to-use-pretrained-weights-and-handle-images-that-are-not-3-channel-RGB-images?) is the doc explaining how they handle non-RGB images when loading pre-trained models.
+
+How can I avoid tiling effects ?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can create an overlap by selecting a stride smaller than the sampling size of your raster. In the advanced options, you can change how the tiles will be merged afterwards.
+
+How can I obtain a better resolution ?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This plugin was developped with ViTs in mind as template models. These have spatialy explicit features and divide the image into patches of typially `16x16` or `14x14` pixels. By having a smaller sampling size, you will have better resolution but with less context for the model to work with.
+
+Which model should I use ?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We've selected some state of the art models that seem to work well on our usecases so far. If you are short in RAM, prefer using the ``ViT Tiny model``, that is almost ten times smaller than the others (but can provide a less nuanced map).
+
+
+.. Citation
+.. ---------
+
Future work
------------
+In the short term, we aim to extend the possible reduction and clustering algorithm available (for instance using HDBSCAN as a clustering algorithm).
+
Acknowledgements
-----------------
- This repo benefits from `Geo-SAM <https://github.com/coolzhao/Geo-SAM>`_ and `TorchGeo <https://github.com/microsoft/torchgeo>`_. Thanks for their wonderful work.
\ No newline at end of file
+ This repo benefits from `Geo-SAM <https://github.com/coolzhao/Geo-SAM>`_ and `TorchGeo <https://github.com/microsoft/torchgeo>`_. Thanks for their wonderful work.
--
GitLab