Prétraitement automatique pour Geo-Deep-Learning

Le pipeline de prétraitement comporte trois principales étapes:

Rechercher des paires d'images multispectrale (mul) et panchromatique (pan) ainsi que des images déjà pansharp (psh);
Faire l'affinage panchromatique des paires mul/pan;
Fusionner les tuiles appartenant à la même scène en une seule image.
Faire la conversion en 8bit.
Créer 1 tif/bande.

Description des besoins

Identifier automatiquement plusieurs dizaines de paires d'images multispectrale et panchromatique liées par différents motifs relatifs;
- Identifier des images avec différentes extensions (i.e. pas juste .tif);
Effectuer l'affinage panchromatique automatique sur ces images
Idenfier des images déjà pansharp;

Exigences techniques (requirements)

Python >= 3.6 avec librairies suivantes:

tqdm
rasterio
rio-cogeo
orfeo toolbox (from CLI or Python with otbApplication*)

* Il n'est pas possible présentement d'installer otbApplication sur Python > 3.5. L'utilisation d'orfeo via la ligne de commande a donc été privilégiée. Il faut s'assurer que les variables d'environnement pour orfeo sont bien configurées. Voir le guide d'installation orfeo.

Compatibilité inter-plateformes

Il existe trois enjeux pour la compatibilité entre Linux et Windows.

1. Longueur des chemins vers les fichiers (enjeu majeur)

Les modules pathlib et os ne "trouvent" pas les fichiers dont le chemin absolu a plus de 260 caractères. Ainsi, il est problématique de lire ou écrire un fichier sur un système Linux qui a plus de 260 caractères. Il s'agit d'un enjeu majeur pour lequel aucune solution n'a été trouvée. Lorsque l'utilisateur a les droits admin de sa machine, il peut toutefois lever cet obstacle. Voir: https://www.howtogeek.com/266621/how-to-make-windows-10-accept-file-paths-over-260-characters/. Les scripts de prétraitement émettront un avertissement lorsque la longueur du chemin dépasse la limite, si Python est exécuté sur Windows.

2. Impossible de lancer cmd.exe (via subprocess) lorsque le répertoire de travail est de type UNC (enjeu mineur)

Sur Windows, il n'est pas possible de lancer OTB toolbox via la ligne de commande lorsque le répertoire de travail est de type UNC. Pour plus de détails, voir script otb_apps.py, ligne 86. Il n'est donc pas possible d'utiliser OTB via la ligne de commande lorsqu'on travaille sur des fichiers issus de CITS, sauf si on s'y réfère, par exemple, via W:\travail, plutôt que \\DFSCITSH.nrn.nrcan.gc.ca\Cits\Travail.

3. Sensibilité à la casse pour les chemins sur Linux (enjeu mineur)

Par exemple, lorsque le script preoprocess_glob recherche des images avec une extension .tif ou .TIF sur Linux, il est nécessaire de chercher ces deux cas spécifiquement, ce qui n'est pas le cas pour Windows. Un exemple pour la ligne correspondante du fichier de config:

Sur Linux (ex.: cavum): extensions: ["tif", "ntf", "TIF", "NTF"]

Sur Windows: extensions: ["tif", "ntf"]

Une solution potentielle pour éviter que l'utilisateur porte la responsabilité de cette particularité: le recours à des regular expressions plutôt que glob.

Fonctionnement des scripts

La ligne suivante permet d'exécuter le script à partir de la ligne de commandes:

python preprocess_pipeline.py path/to/config.yaml

Ce script utilise le fichier de paramètres config.yaml (voir section ci-dessous). Puis, preprocess_glob.py est appelé pour la recherche mul/pan (voir section «Étape 1: ...»), puis effectue le pansharp (voir section «.Étape 2: ...») et le cog (voir section «Étape 3: ...»).

config.yaml

Il possède 2 sections principales:

glob : paramètres pour l'étape 1 (recherche)
pansharp: paramètres pour les étapes 2 et 3 (pansharp/cog)

# Preprocessing configuration file ------------------------------------------------

glob:
  base_dir: \\dfscitsh\cits\Travail\bdgrid2\EXTRACTION\Deep_learning\GDL_EAU_2019_20\AMA3\image # Directory containing all images  
  mul_pan_glob: # See below
    1: ["**/*_MUL/*-M*_P00?", "../*_PAN"]
    2: ["**/*_MSI*", "."]
  mul_pan_str: # See below
    1: ["-M", "-P"]
    2: ["_MSI", "_PAN"]
  psh_glob: ["**/*_PSH/*_P00?"] # See below
  extensions: ["tif", "ntf"] # list of all possible extensions the raster files may have. Case-sensitive on Linux.
  out_csv: 'logs/glob_metadata.csv' # Output csv for glob process

pansharp:
  input_csv: logs/glob_metadata.csv # csv from glob process, if glob was done as separate step (ex.: by executing preprocess_glob.py directly).
  method: otb-bayes # otb-lmvm, otb-bayes, simple_brovey, brovey, simple_mean, esri, hsv
  copy_to_8bit: True # create a uint8 copy if pansharp is uint16.
  trim: 0 # Quantiles to cut from histogram low/high values.
  cog: False # Create and validate COG from pansharp.
  cog_delete_source: False  # if True, deletes source image after coggifying process is done
  overwrite: False # if True, overwrites existing output file
  dry_run: False
  log_csv: # "pansharp_log.csv" # Output csv for pansharp process

Détails

Paramètre mul_pan_glob:

List de motifs qui permettent, premièrement, de trouver des images multispectrales et, deuxièmement, de trouver leurs équivalents panchromatiques. Ce paramètre contient des listes de deux éléments: (1) motif glob pour trouver l'image multispectrale (sans l'extension); (2) motif vers le répertoire qui contient l'image panchromatique (et non vers l'image directement) à partir de l'image multispectrale.

Exemple: ["**/*_MUL/*-M*_P00?", "../*_PAN"]

"**/*_MUL/*-M*_P00?" recherche les images multispectrales dont le nom contient le motif *-M*_P00?, en autant qu'elles soient dans un dossier qui répond au motif *_MUL/. Le **/ au début du motif signifie que la recherche aura lieu dans le dossier actuel et tous les sous-dossiers récursivement. Pour plus d'information sur les motifs glob, voir la documentation.

Le "../*_PAN" signifie quant à lui que glob, après avoir trouvé une multispectrale remontera un dossier (../) à partir du dossier de la multispectrale, puis cherchera dans un répertoire répondant au motif *_PAN l'équivalent panchromatique. Pour plus de détails sur la recherche de la panchromatique, voir le script preprocess_glob.py, ligne 84.

Ce motif permettrait donc de trouver une paire d'images organisée de la manière suivante:

├── base_dir
    └── QC_14_052615225040_01
        └── 052615225040_01
            └── 052615225040_01_P001_MUL
	            └── 11OCT09161417-M2AS-052615225040_01_P001.TIF
	        └── 052615225040_01_P001_PAN
		        └── 11OCT09161417-P2AS-052615225040_01_P001.TIF```

Paramètre mul_pan_str:

Liste de listes de deux éléments contenant des tronçons de texte qui identifient spécifiquement les images multispectrale et panchromatique dans le nom de ces fichiers. Ce paramètre optionnel a deux fonctiones:

Permet de trouver avec plus de certitude l'image panchromatique
Permet de donner un nom pertinent à l'image pansharp résultat du prétraitement. Le tronçon en question est remplacé par -PSH-(nom de la méthode utilisée) dans le fichier de sortie. Pour plus de détails, voir script preprocess_glob.py, ligne 131.

Exemple: [['-M', '-P'],["_MSI", "_PAN"]]

Paramètre psh_glob:

Ce paramètre permet de trouver des images déjà pansharp dans le répertoire base_dir correspondant au motif spécifié. Exemple: ["**/*_PSH/*_P00?"]

Étape 1. Recherche de paires mul/pan

Tel que mentionné ci-haut, cette étape permet d'identifier des paires mul/pan. C'est aussi à cette étape qu'est déterminé le nom et répertoire des fichiers de sortie. Pour plus de détails, voir script preprocess_glob.py.

Étape 2: Pansharp

Après la recherche de paires mul/pan (ou de pansharp déjà créés), le pipeline crée un objet du type PansharpRaster. Puis, selon le paramètre spécifié, cette étape fait appel au script otb_apps ou pansharp_numpy qui contient toutes les fonctions nécessaires pour l'affinage panchromatique.

Étape 3: Cog

Méthode utilisée

Création des COGs: cog_translate par rio_cogeo

Validation des COGs cog_validate par rio_cogeo

Copie 8bit

Cette étape de prétraitement est effectuée seulement si copy_to_8bit: True. La compression radiométrique est effectuée grâce à l'application DynamicConvert d'Orfeo Toolbox.

valhassan / preprocess-gdl