Merge branch 'main' into dev

.readthedocs.yaml

@@ -9,7 +9,8 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.12"
+    python: "mambaforge-22.9"
+    # python: "3.12"
     # You can also specify other tool versions:
     # nodejs: "19"
     # rust: "1.64"
@@ -30,3 +31,5 @@ sphinx:
 # python:
 #    install:
 #    - requirements: docs/requirements.txt
+conda:
+  environment: docs/environment.yml

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
 

docs/environment.yml

+name: iamap
+channels:
+  - conda-forge
+
+dependencies:
+  - python
+  - myst-parser
+  - pip:
+    - pydata-sphinx-theme
+    - sphinx_favicon

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
@@ -41,10 +61,10 @@ 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
+       pip install torchgeo==0.5.2
+       pip install geopandas==0.14.4
+       pip install scikit-learn==1.5.1
+       # (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 :

docs/source/More.rst

@@ -51,6 +51,33 @@ 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
+.. ---------
+
+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
 .. ---------
 

docs/source/Tutorials.rst

@@ -58,33 +58,13 @@ Keep in mind that the more points you place the better the results will be.
 
 
 
-
-
-Using a new encoder
---------------------
-If you use Windows and you want to use a new encoder, you first need to create it in the OSGEO4W shell.
-For that, you can open OSGEO4W shell and run the following commands (assuming that "name" is the name of your encoder of choice) :
-::
-    python
-    import timm
-    #print(timm.__version__) if you want to see which timm version you are currently using
-    model = timm.create_model(name, pretrained=True)
-    print(model)  #to verify it was indeed created
-    exit()
-
-After those lines of code you should be able to use the new model by going into the "backbone choice" option in the encoder interface and typing
-the name of the model you want to use.
-
-As timm is a library regularly updated, be sure that the version you use is compatible with the model you want to use.
-
-
-
 Changing the parameters of the Random Forest
 -----------------------------------------------
 If you want to change the parameters of the random forest (such as the random state, number of trees, etc...), go to the random_forest.py file of this plugin.
 
 You can then go to the line 278 and 292 of this code which should look this :
 ::
+
     rf_classifier = RandomForestClassifier(n_estimators=100, min_samples_split=4, random_state=42)
 
 You can then change the parameters of the random forest freely. Please make sure to use the same parameters in both of those two lines of code

docs/source/conf.py

@@ -14,16 +14,28 @@ release = '0.5.9'
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
+import pydata_sphinx_theme
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    "myst_parser",
+    "sphinx_favicon",
+]
 
 templates_path = ['_templates']
 exclude_patterns = []
 
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
 
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-# html_theme = 'sphinx_rtd_theme'
+html_theme = 'pydata_sphinx_theme'
 html_static_path = ['_static']
+html_favicon = "./../../icons/encoder.svg"