Feature/documentation new users

HOWTO.md

@@ -0,0 +1,147 @@
+## Exemple de cas d'utilisations des fichiers exécutables du projet ROK4
+
+### PYR2PYR : un exemple de ligne de commande à lancer :
+
+Cet exemple s'appuie sur l'image docker rok4/dataset en lançant la commande suivante depuis le dépôt comme suit :
+```sh
+docker run -p 9000:9000 -p 9001:9001 rok4/dataset:minio
+```
+
+et une interface graphique de gestion est disponible à l'URL http://localhost:9001/buckets (accès : rok4 / rok4S3storage) :
+
+```sh
+pyr2pyr --role check --conf path_to_file/PM.json
+pyr2pyr --role master --conf path_to_file/PM.json
+
+# Les lignes de commandes suivantes contenant l'option split peuvent être lancées en parallèle
+
+pyr2pyr --role agent --conf path_to_file/PM.json --split 1
+pyr2pyr --role agent --conf path_to_file/PM.json --split 2
+pyr2pyr --role agent --conf path_to_file/PM.json --split 3
+
+pyr2pyr --role finisher --conf path_to_file/PM.json
+```
+
+### JOINCACHE : Exemple de fichier de configuration :
+
+*   Exemple de fichier de configuration valide `exemple_valid_json.json`:
+  ```json
+{
+    "logger": {
+        "level": "INFO"
+    },
+    "datasources": [
+        {
+            "top": "0",
+            "bottom": "1",
+            "source": {
+                "type": "PYRAMIDS",
+                "descriptors": [
+		    "path_to_file/ALTI.json"]
+            }
+        }
+    ],
+    "pyramid": {
+        "name": "joincache",
+        "root": "pyramids"
+    },
+    "process": {
+        "directory": "s3://bucket_temp/joincache",
+        "parallelization": 1,
+        "mask": true
+    }
+}
+```
+
+*   Résultat obtenu :
+  ```sh
+   joincache --role check --conf  exemple_valid_json.json 
+    Valid configuration !
+  ```
+
+### MAKELAYER : un exemple de ligne de commande à lancer :
+
+Cet exemple s'appuie sur l'image docker rok4/dataset en lançant la commande suivante depuis le dépôt comme suit :
+```sh
+docker run -p 9000:9000 -p 9001:9001 rok4/dataset:minio
+```
+
+et une interface graphique de gestion est disponible à l'URL http://localhost:9001/buckets (accès : rok4 / rok4S3storage) :
+
+```sh
+make-layer --pyramids s3://pyramids/ALTI.json  --name ALTI_data --styles normal --title ALTI --resampling bicubic --directory .
+```
+
+Voici le fichier de résultats au format JSON `ALTI_data.json` obtenu :
+```json 
+{   "title": "ALTI_data", 
+    "abstract": "bicubic", 
+    "keywords": ["RASTER", "my_data"], 
+    "wmts": {"authorized": true}, 
+    "tms": {"authorized": true}, 
+    "bbox": {"south": 14.221788628396906, 
+    "west": -61.435546874999375,
+    "north": 14.944784875087676, 
+    "east": -60.64453124999938}, 
+    "pyramids": [{"bottom_level": "13", "top_level": "0", "path": "s3://pyramids/ALTI.json"}],
+    "wms": {
+            "authorized": true, 
+            "crs": ["CRS:84", "IGNF:WGS84G", "EPSG:3857", "EPSG:4258", "EPSG:4326"]
+            }, 
+    "styles": ["normal", "normal"], 
+    "resampling": "nn"
+}
+```
+
+### PYROLYSE : un exemple de ligne de commande à lancer :
+
+Cet exemple s'appuie sur l'image docker rok4/dataset en lançant la commande suivante depuis le dépôt comme suit :
+```sh
+docker run -p 9000:9000 -p 9001:9001 rok4/dataset:minio
+```
+
+et une interface graphique de gestion est disponible à l'URL http://localhost:9001/buckets (accès : rok4 / rok4S3storage) :
+
+```sh
+pyrolyse --pyramid s3://pyramids/ALTI.json --output resultats.json --tiles --progress --deciles --ratio 1
+```
+
+Le résultat donne le fichier de résultats `resultats.json` suivant : 
+```json
+{"global": {"slab_count": 17, "slab_sizes": [77819.0, 77844.6, 77860.6, 77975.8, 78644.6, 82379.0, 119482.99999999999, 335572.59999999986, 825531.0000000003, 2665611.0, 3715851.0], "link_count": 0, "tile_
+sizes": [283.0, 283.0, 283.0, 283.0, 283.0, 283.0, 283.0, 283.0, 283.0, 287.0, 310.0]}, "levels": {"13": {"slab_count": 4, "slab_sizes": [77819.0, 199047.80000000002, 320276.60000000003, 441505.3999999999
+7, 863780.6000000003, 1436579.0, 2009377.3999999997, 2523703.7999999993, 2921086.2, 3318468.6, 3715851.0], "link_count": 0, "tile_sizes": [283.0, 283.0, 283.0, 283.0, 283.0, 283.0, 283.0, 283.0, 283.0, 28
+3.0, 283.0]}, "12": {"slab_count": 1, "slab_sizes": [3077163], "link_count": 0, "tile_sizes": [283]}, "11": {"slab_count": 1, "slab_sizes": [911435], "link_count": 0, "tile_sizes": [283]}, "10": {"slab_co
+unt": 1, "slab_sizes": [298987], "link_count": 0, "tile_sizes": [283]}, "9": {"slab_count": 1, "slab_sizes": [136827], "link_count": 0, "tile_sizes": [283]}, "8": {"slab_count": 1, "slab_sizes": [93467], 
+"link_count": 0, "tile_sizes": [283]}, "7": {"slab_count": 1, "slab_sizes": [82379], "link_count": 0, "tile_sizes": [283]}, "6": {"slab_count": 1, "slab_sizes": [79211], "link_count": 0, "tile_sizes": [28
+3]}, "5": {"slab_count": 1, "slab_sizes": [78267], "link_count": 0, "tile_sizes": [283]}, "4": {"slab_count": 1, "slab_sizes": [77995], "link_count": 0, "tile_sizes": [283]}, "3": {"slab_count": 1, "slab_
+sizes": [77899], "link_count": 0, "tile_sizes": [283]}, "2": {"slab_count": 1, "slab_sizes": [77851], "link_count": 0, "tile_sizes": [283]}, "1": {"slab_count": 1, "slab_sizes": [77851], "link_count": 0, 
+"tile_sizes": [310]}, "0": {"slab_count": 1, "slab_sizes": [77835], "link_count": 0, "tile_sizes": [293]}}, "perfs": [0.002020657000684878, 0.0021233711999229855, 0.0021787890007544776, 0.0023693994000495
+875, 0.0024838273999193915, 0.0027725769996322924, 0.002991372598626185, 0.0032549347990425298, 0.004386014799820259, 0.005820798000422655, 0.006239024000024074]}
+```
+
+### TMSIZER : un exemple de lignes de commande avec différents filtres :
+
+#### TMSIZER : un exemple de lignes de commande avec un filtre de 59 requêtes pour générer l'image :
+
+Dans l'exemple ci-après, on a 59 requêtes pris en compte pour générer l'image, en fonction des filtres choisis et de la zone couverte par la carte de chaleur:
+```sh
+tmsizer -i requests.txt --tms PM -io levels=0,15 -io layer=LAYER.NAME2 -if GETTILE_PARAMS -of HEATMAP -oo bbox=65000,6100000,665000,6500000 -oo dimensions=600x400 -o heatmap.tif
+HeatmapProcessor : 59 hits on image with dimensions (600, 400) and bbox (65000.0, 6100000.0, 665000.0, 6500000.0) (resolutions (1000.0, 1000.0))
+```
+
+#### TMSIZER : un exemple de lignes de commande avec un filtre de 81 requêtes pour générer l'image :
+
+Dans l'exemple ci-après, on a 81 requêtes pris en compte pour générer l'image, en fonction des filtres choisis et de la zone couverte par la carte de chaleur:
+```sh
+tmsizer -i requests.txt --tms PM -io levels=15,12 -io layer=LAYER.NAME2 -if GETTILE_PARAMS -of HEATMAP -oo bbox=65000,6100000,665000,6500000 -oo dimensions=600x400 -o heatmap.tif
+HeatmapProcessor : 81 hits on image with dimensions (600, 400) and bbox (65000.0, 6100000.0, 665000.0, 6500000.0) (resolutions (1000.0, 1000.0))
+```
+
+#### TMSIZER : un exemple de lignes de commande avec un filtre de 110 requêtes pour générer l'image :
+
+Dans l'exemple ci-après, on a 110 requêtes pris en compte pour générer l'image, en fonction des filtres choisis et de la zone couverte par la carte de chaleur:
+```sh
+tmsizer -i requests.txt --tms PM -io levels=15,14 -io layer=LAYER.NAME1,LAYER.NAME2,LAYER.NAME3 -if GETTILE_PARAMS -of HEATMAP -oo bbox=65000,6100000,665000,6500000 -oo dimensions=600x400 -o heatmap.tif
+HeatmapProcessor : 110 hits on image with dimensions (600, 400) and bbox (65000.0, 6100000.0, 665000.0, 6500000.0) (resolutions (1000.0, 1000.0))
+```

README.md

@@ -21,6 +21,8 @@ L'environnement d'exécution doit avoir accès aux librairies système. Dans le
 
 ### PYR2PYR
 
+Installer la commande `jsonschema2md` en tapant `pip install jsonschema2md`
+
 PYR2PYR est un outil de copie d'une pyramide d'un stockage à un autre. Il est possible de filtrer les dalles transférée en précisant une taille limite sous laquelle les données ne sont pas recopiées. La copie des dalles est parallélisable. Si des signatures MD5 sont présente dans le fichier liste, elles sont contrôlées après recopie.
 
 Un exemple de configuration est affichable avec la commande `pyr2pyr --role example` et l'appel `pyr2pyr --role check --conf conf.json` permet de valider un fichier de configuration. Le fichier de configuration peut être un objet, auquel cas le chemin doit être préfixé par le type de stockage (exemple : `s3://bucket/configuration.json`)
@@ -34,7 +36,7 @@ Une copie complète d'une pyramide implique l'utilisation de l'outil avec les 3
     * Appel : `pyr2pyr --role master --conf conf.json`
 2. Rôle `agent` :
     * Actions : lecture de la TODO list depuis le dossier de traitement et recopie des dalles
-    * Appel (un appel par TODO list) : `pyr2pyr --role agent --conf conf.json --split X`
+    * Appel (un appel par TODO list) : `pyr2pyr --role agent --conf conf.json --split X` où X : est un entier naturel.
 3. Rôle `finisher` :
     * Actions : lecture des TODO lists pour écrire le fichier liste final et écriture du descripteur de la pyramide en sortie.
     * Appel : `pyr2pyr --role finisher --conf conf.json`
@@ -62,6 +64,10 @@ Possibilités de contenu du fichier JSON (généré à partir du schéma JSON av
     - **`parallelization`** *(integer)*: Parallelization level, number of todo lists and agents working at the same time. Minimum: `1`. Default: `1`.
     - **`follow_links`** *(boolean)*: Do we follow links (data slabs in others pyramids than the 'from' one). Default: `False`.
     - **`slab_limit`** *(integer)*: Minimum slab size (if under, we do not copy). Minimum: `0`. Default: `0`.
+
+* Exemple d'utilisation de pyr2pyr :
+
+![ROK4 PYR2PYR](https://github.com/rok4/pytools/blob/feature/documentation_new_users/HOWTO.md#pyr2pyr--un-exemple-de-ligne-de-commande-%C3%A0-lancer-)
 
 ### JOINCACHE
 
@@ -83,6 +89,8 @@ Un calcul complet d'une pyramide implique l'utilisation de l'outil avec les 3 mo
     * Actions : lecture des TODO lists pour écrire le fichier liste final et écriture du descripteur de la pyramide en sortie.
     * Appel : `joincache --role finisher --conf conf.json`
 
+![ROK4 PYTOOLS FICHIER DE CONFIGURATION](https://github.com/rok4/pytools/blob/feature/documentation_new_users/HOWTO.md#joincache--exemple-de-fichier-de-configuration-)
+
 #### Configuration
 
 Possibilités de contenu du fichier JSON (généré à partir du schéma JSON avec `jsonschema2md src/rok4_tools/joincache_utils/schema.json /dev/stdout`)
@@ -126,6 +134,8 @@ Utilisation : `make-layer [-h] [--version] --pyramids storage://path/to/pyr.json
 * `--resampling {nn,linear,bicubic,lanczos_2,lanczos_3,lanczos_4}` : type d'interpolation pour le réechantillonnage
 * `--directory s3://layers_bucket` : dossier, fichier ou objet, dans lequel écrire le descripteur de pyramide. Affiche dans la sortie standard si non fourni
 
+![ROK4 MAKELAYER](https://github.com/rok4/pytools/blob/feature/documentation_new_users/HOWTO.md#makelayer--un-exemple-de-ligne-de-commande-%C3%A0-lancer-)
+
 ### PYROLYSE
 
 PYROLYSE est un outil d'analyse d'une pyramide, permettant d'avoir le nombre et la taille des dalles et tuiles, au global et par niveau. Les tailles des dalles et des tuiles ne sont pas toutes récupérées : un ratio permet de définir le nombre de mesures (un ratio de 100 entraînera la récupération de la taille d'une dalle sur 100 et d'une de ses tuile). Ce ratio s'applique par niveau (pour ne pas avoir que des données sur le meilleur niveau, celui qui contient le plus de dalles). Lorsque les statistiques sur les tuiles sont activées, on mesure le temps de lecture du header.
@@ -144,6 +154,8 @@ Utilisation : `pyrolyse [-h] [--version] --pyramid storage://path/to/pyr.json [-
 * `--centiles` : avoir les centiles plutôt que toutes les valeurs de taille et de temps d'accès
 * `--ratio N` : ratio à appliquer sur la mesure de taille (un parmi <ratio>, 100 par défaut). Toutes les dalles sont comptées
 
+![ROK4 PYROLYSE](https://github.com/rok4/pytools/blob/feature/documentation_new_users/HOWTO.md#pyrolyse--un-exemple-de-ligne-de-commande-%C3%A0-lancer-)
+
 ### TMSIZER
 
 TMSIZER est un outil permettant de convertir des informations selon différents formats en accord avec un Tile Matrix Set en particulier. Les données en entrée peuvent être lues depuis un fichier, un objet ou l'entrée standard. Les données en sortie peuvent être écrites dans un fichier, un objet ou la sortie standard.
@@ -182,6 +194,12 @@ Exemple (GETTILE_PARAMS -> HEATMAP) avec une aire prédéfinie et une correspond
 
 `tmsizer -i logs.txt --tms PM -if GETTILE_PARAMS -of HEATMAP -oo area=FXX -oo level=15 -o heatmap.tif`
 
+Le nombre de requêtes pris en compte pour générer l'image, en fonction des filtres et de la zone couverte par la carte de chaleur :
+
+```HeatmapProcessor : 81 hits on image with dimensions (600, 400) and bbox (65000.0, 6100000.0, 665000.0, 6500000.0) (resolutions (1000.0, 1000.0))```
+
+![ROK4 PYTOOLS TMSIZER FILE GETTILES](https://github.com/rok4/pytools/blob/feature/documentation_new_users/HOWTO.md#tmsizer--un-exemple-de-lignes-de-commande-avec-diff%C3%A9rents-filtres-)
+
 ## Compiler la suite d'outils
 
 ```sh

pyproject.toml

@@ -39,7 +39,8 @@ dependencies = [
 
 [project.optional-dependencies]
 doc = [
-  "pdoc3 >= 0.10.0"
+  "pdoc3 >= 0.10.0",
+  "pydeps"
 ]
 
 dev = [