Documentation

Doc badging

README.md

@@ -6,7 +6,8 @@
 <a href="https://pytorchlightning.ai/"><img alt="Lightning" src="https://img.shields.io/badge/-Lightning-792ee5?logo=pytorchlightning&logoColor=white"></a>
 <a href="https://hydra.cc/"><img alt="Config: Hydra" src="https://img.shields.io/badge/Config-Hydra-89b8cd"></a>
 
-[![Documentation Build](https://github.com/IGNF/lidar-prod-quality-control/actions/workflows/gh-pages.yml/badge.svg)](https://github.com/IGNF/lidar-prod-quality-control/actions/workflows/gh-pages.yml)
+[![Documentation Build](https://github.com/IGNF/lidar-prod-quality-control/actions/workflows/gh-pages.yaml/badge.svg?event=push)](https://github.com/IGNF/lidar-prod-quality-control/actions/workflows/gh-pages.yaml)
+[![CI/CD](https://github.com/IGNF/lidar-prod-quality-control/actions/workflows/cicd.yaml/badge.svg?event=push)](https://github.com/IGNF/lidar-prod-quality-control/actions/workflows/cicd.yaml)
 
 </div>
 <br><br>
@@ -31,6 +32,6 @@ Our strategy is to fuse together different sources of informations (rules-based
 
 Right now, the class `building` is the only one that is addressed. The extension to other classes is dependent on the training of multiclass AI model, which requires high quality training datasets that are currently being produced.
 
-> Please refer to the documentation for [installation and usage](https://ignf.github.io/lidar-prod-quality-control/tutorials/install_and_use.html).
+> Please refer to the documentation for [installation and usage](https://ignf.github.io/lidar-prod-quality-control/tutorials/install.html).
     
 > Please refer to the documentation to understand the [production process](https://ignf.github.io/lidar-prod-quality-control/background/production_process.html).

docs/source/guides/development.md

@@ -4,7 +4,7 @@
 
 Package version follows semantic versionning conventions and is defined in `setup.py`. 
 
-Releases are generated when new high-level functionnality are implemented (e.g. a new step in the production process), with a documentation role. Production-ready code is fast-forwarded in the `prod` branch when needed.
+Releases are generated when new high-level functionnality are implemented (e.g. a new step in the production process), with a documentation role. Production-ready code is fast-forwarded in the `prod` branch when needed to match the `main` branch.
 
 ## Tests
 
@@ -17,14 +17,16 @@ python -m pytest
 
 One test depends on a large, non-versionned file (665MB), which is accessible from the self-hosted action runner, but not publicly available at the moment. The absence of the file makes the test xfail so that it is not required for local development.
 
-# Continuous Integration (CI)
+## Continuous Integration (CI)
 
-New features are developped in ad-hoc branches, and merged in the `dev` branch, where they may be accumulated until stability. 
-CI tests are run for pull request to merge on either `dev` or `main` branches, and only for branches that are flagged as "ready for review" in github.
+New features are developped in ad-hoc branches (e.g. `refactor-database-query`), and merged in the `dev` branch. When ready, `dev` can be merged in `main`.
 
-# Continuous Delivery (CD)
+CI tests are run for pull request to merge on either `dev` or `main` branches, and on pushes to `dev`, `main`, and `prod`. The CI workflow builds a docker image, runs linting, and tests the code.
 
+## Continuous Delivery (CD)
 
+When the event is a push and not a merge request, this means that there was either a direct push to `dev`|`main`|`prod` or that a merge request was accepted. In this case, if the CI workflow passes, the docker image is tagged with the branch name, resulting in e.g. a `lidar_prod_im:prod` image that is up to date with the branch content. See [../tutorials/use.md] for how to leverage such image to run the app.
+
+Additionnaly, pushes on the `main` branch build this library documentation, which is hosted on Github pages.
 
-Additionally, in the CICD workflow, the app is run on two point clouds (a subset and the large, non-versionned file mentionned in [Tests](#Tests)). Outputs are saved to the self-hosted action runner, and can be inspected to get a qualitative sense of the performance.
 

docs/source/guides/thresholds_optimization.md

@@ -15,7 +15,7 @@ A large validation dataset might help having a better sense of the app performan
 
 ### Finding optimal thresholds
 
-> Refer to the [installation tutorial](../tutorials/install_and_use.md) to set up your python environment.
+> Refer to the [installation tutorial](../tutorials/install.md) to set up your python environment.
 
 Your corrected data must live in a single `input_las_dir` directory as a set of LAS files. 
 Prepared and updated files will be saved in subfolder of a `results_output_dir` directory (`./prepared` and `./updated/`, respectively).

docs/source/index.rst

@@ -18,7 +18,8 @@ Lidar-Prod > Documentation
    :maxdepth: 1
    :caption: Getting Started
 
-   tutorials/install_and_use
+   tutorials/install
+   tutorials/use
 
 .. toctree::
    :maxdepth: 1

docs/source/tutorials/install.md

@@ -0,0 +1,45 @@
+# Installation
+
+## Set up a virtual environment
+
+We use [Anaconda](https://anaconda.org/)] to manage and isolate dependencies. 
+The provided environment setup script also installs [Mamba](https://mamba.readthedocs.io/en/latest/index.html),
+which gets on top of conda for faster environment installs.
+
+```yaml
+# clone project
+git clone https://github.com/IGNF/lidar-prod-quality-control
+cd lidar-prod-quality-control
+
+# install conda
+# see https://www.anaconda.com/products/individual
+
+# you need to install postgis to request a public database
+sudo apt-get install postgis
+
+# create conda environment
+source bash/setup_environment/setup_env.sh
+
+# activate the virtual env
+conda activate lidar_prod
+```
+
+## Install the app as a python module
+
+To run the application from anywhere, you can install as a module in a your virtual environment.
+
+```bash
+# activate your env
+conda activate lidar_prod
+
+# install the package from github directly, using production branch
+pip install --upgrade https://github.com/IGNF/lidar-prod-quality-control/tarball/prod
+
+```
+
+During development, install in editable mode directly from source with
+ ```bash
+ pip install --editable .
+ ```
+
+Then, refert to the [usage page](./use.md).

docs/source/tutorials/use.md

@@ -0,0 +1,43 @@
+# Using the app
+
+## Run within a docker container
+
+Up to date docker images (named `lidar_prod_im`) are created via Github integration actions (see [Developer's guide](../guides/development.md)). 
+
+To run the app, use
+
+```bash
+docker run \
+-v {local_src_las_dir}:/inputs/ \
+-v {local_output_dir}:/outputs/
+lidar_prod_im \
+python lidar_prod/run.py \
+paths.src_las=/inputs/{src_las_basename}.las
+paths.output_dir=/outputs/
+# + other options...
+
+```
+
+A docker image encapsulating the virtual environment and application sources can also be built using the provided Dockerfile. This Dockerfile is not standalone and should be part of the repository (whose content is copied into the image), on the github reference you want to build from.
+
+## Run as a python module
+To run the module as a module, you will need a source cloud point in LAS format with an additional channel containing predicted building probabilities (`ai_building_proba`) and another one containing predictions entropy (`entropy`). The names of thes channel can be specified via hydra config `config.data_format.las_dimensions`.
+
+To run using default configurations of the installed module, use
+```bash
+python -m lidar_prod.run paths.src_las=</path/to/file.las>
+```
+
+You can specify a different yaml config file with the flags `--config-path` and `--config-name`. You can also override specific parameters. By default, results are saved to a `./outputs/` folder, but this can be overriden with `paths.output_dir` parameter. Refer to [hydra documentation](https://hydra.cc/docs/next/tutorials/basic/your_first_app/config_file/) for the overriding syntax.
+
+To print default configuration run `python -m lidar_prod.run -h`. For pretty colors, run `python -m lidar_prod.run print_config=true`.
+
+## Run from source directly
+
+For developments and debugging, you can run the package directly from python sources instead:
+
+```bash
+# activate an env matching ./bash/setup_env.sh requirements.
+conda activate lidar_prod
+python lidar_prod/run.py paths.src_las=[/path/to/file.las]
+```

lidar_prod/tasks/building_validation_optimization.py

@@ -375,21 +375,24 @@ def _load_clusters(self):
             log.info(f"Loading pickled groups from {self.paths.group_info_pickle_path}")
         return clusters
 
-    def evaluate_decisions(self, mts_gt, ia_decision):
-        """Evaluate confirmation and refutation decisions.
+    def evaluate_decisions(self, mts_gt, ia_decision) -> Dict[str, Any]:
+        r"""Evaluate confirmation and refutation decisions.
 
         Get dict of metrics to evaluate how good module decisions were in reference to ground truths.
+
         Targets: U=Unsure, N=No (not a building), Y=Yes (building)
+
         Predictions : U=Unsure, C=Confirmation, R=Refutation
-        Confusion Matrix :
-                predictions
-                [Uu Ur Uc]
-        target  [Nu Nr Nc]
-                [Yu Yr Yc]
 
-        Maximization criteria:
-        Proportion of each decision among total of candidate groups.
-        We want to maximize it.
+        Confusion Matrix (horizontal: target, vertical: predictions)
+
+        [Uu Ur Uc]
+
+        [Nu Nr Nc]
+
+        [Yu Yr Yc]
+
+        Automation: Proportion of each decision among total of candidate groups.
 
         Accuracies:
         Confirmation/Refutation Accuracy.
@@ -398,9 +401,18 @@ def evaluate_decisions(self, mts_gt, ia_decision):
         Quality
         Precision and Recall, assuming perfect posterior decision for unsure predictions.
         Only candidate shapes with known ground truths are considered (ambiguous labels are ignored).
+
         Precision : (Yu + Yc) / (Yu + Yc + Nc)
+
         Recall : (Yu + Yc) / (Yu + Yn + Yc)
 
+        Args:
+            mts_gt (np.array): ground truth of rules-based classification (0, 1, 2)
+            ia_decision (np.array): AI application decision (0, 1, 2)
+
+        Returns:
+            dict: dictionnary of metrics.
+
         """
         metrics_dict = dict()