La nouvelle CLI GDAL 3.11#

Date de publication initiale : 23 mars 2026

"Oh non, pas gdal_translate ! C'était mon préféré !" Un photogramètre anonyme en détresse

Depuis sa version 3.11 (et son intégration à QGIS 3.44), la CLI (Command Line Interface / Interface en Ligne de Commande) de GDAL a été entièrement revue. On va ici présenter cette nouvelle interface et brosser un aperçu de ce qu'on peut réaliser avec GDAL dans un court article. Nota bene : COURT on a dit.

GDAL qu'est ce que c'est ?#

GDAL est une librairie de programmes open source en C/C++ permettant de réaliser des convertion de fichier vecteur/rasteur, et des traitements raster. Cette librairie se cache derrière à peu près tous les logiciels contenant "SIG" dans leur description. Quand vous demandez à QGIS d'enregistrer votre fichier geopackage en flatgeobuf ou en geoparquet pour les amateur.trices de formats modernes mais étranges (perso je ne travaille plus qu'en DuckLake Spatial pour embêter mes collègues), en réalité QGIS demande à GDAL de réaliser l'opération.

Les anciens noms des programmes dédiés au vecteur font référence à ogr, une ancienne librairie depuis absorbée par GDAL.

On ne le répétera jamais assez mais sans GDAL, presque rien n'existerait dans le monde de la géomatique, qu'elle soit libre ou propriétaire. A tout ces égards, cette librairie fait partie de la sainte trinité gdal/geos/proj.

Maîtriser GDAL, c'est être capable de remplacer des interfaces graphiques logiciels coûtant des dizaines de milliers d'euros.

Cependant, historiquement les programmes GDAL étaient ... comment dire ... peut normés entre eux, par exemple gdal_translate (le programme servant aux conversions raster) demandait ses fichiers d'entrée / sortie dans cet ordre : in -> out alors qu'ogr2ogr (le programme servant aux conversions vecteur) lui demandait : out -> in. De plus les plus gros programmes, ceux qui "faisaient tout" on été supprimés et remplacés par des équivalents plus spécifiques. Pas de panique, les anciennes commandes restent disponibles pour garder vos scripts existants en vie.

Principes de la nouvelle CLI#

• Les gros programmes sont divisés en plusieurs (au revoir gdal_translate qui convertissait mais faisait aussi tout pareil que gdalwarp, bonjour gdal raster convert et gdal raster reproject)
• Les positions des fichiers d'entrées et de sorties sont cohérentes entre les programmes et les noms des options sont normés !
• On fait appel aux nouvelles commandes GDAL git style.

flowchart
 A(["gdal"])
 A --> B(["Vector/Raster"])
 B --> C(["Programme"])
 C --> D(["Options"])
 D --> E(["In / Out"])

Vous pourrez retrouver l'intégralité des programmes disponibles et leurs options ici

Exemple :

gdal raster convert --overwrite in.jp2 out.tif

Commande pour convertir un fichier in.jp2 au format geotiff en autorisant l'écrasement d'un potentiel fichier out.tif déjà existant.

Pour du vecteur on peut aussi importer un shape (beurk) dans une base PostGIS :

gdal vector convert --append in.shp PG:"dbname='my_db' user='me' password='admin123' schemas='my_schema'"

Une différence par rapport à l'ancienne CLI est l'obligation de l'utilisation de l'option append, même pour créer une table non existante.

On peut même copier le contenu d'un flux WFS vers un geopackage :

gdal vector convert --overwrite --output-layer=arrondissement_municipal WFS:"https://data.geopf.fr/wfs/ows?SERVICE=WFS&REQUEST=GetFeature&VERSION=2.0.0&TYPENAMES=BDTOPO_V3:arrondissement_municipal" bdtopo.gpkg

On pourrait imaginer combiner les commandes précédentes pour importer le contenu d'un flux WFS vers une base PostgreSQL, mais pour ça on préfèrera utiliser le Foreign Data Wrapper OGR car Saint Paul Ramsey veille sur nous. (rejoignez moi dans mon culte esothérique secret vénérant la sainte trinité gdal/geos/proj, représentée par Saint Paul Ramsey, Saint Even Rouault et la Sainte papesse Anita Graser. Venez, on est pas méchant, ça vous coute juste une licence ESRI pour l'adhésion mais on pourra en discuter après la première réunion).

Si certain.nes d'entre vous ont envie de faire comme le bouton "calculer un indice radiométrique" d'un quelconque logiciel de télédétection, on peut appliquer des formules avec gdal raster calc. On assigne les bandes/rasters à des lettres qu'on appellera ensuite dans la formule. Laissez bien sur toutes les options par défaut :

gdal raster calc -i "A=ir.tif" -i "B=r.tif" --calc "(A-B)/(A+B)" -o out.tif

On peut s'en servir pour créer des Cloud Optimized Geotiff. Voir cet article de geotribu par Nicolas Rochard pour les options qui sont utilisées par la région Hauts de France.

gdal raster convert --ouput-format=COG -co COMPRESS=ZSTD -co BIGTIFF=IF_NEEDED in.tif out.tif

Avec les --co qui servent à passer les options spécifiques au driver de sortie. On retrouvera ces différents drivers ici pour le raster, et ici pour le vecteur.

Ou bien simplement pour demander des informations sur une couche :

gdal raster info ma_couche.tif

Voir même créer des ombrages :

gdal raster hillshade --zfactor=2 in.tif out.tif

Les pipelines#

Une autre nouveauté fait partie de cette mise à jour : les pipelines vecteurs ou raster. Ils permettent d'appeler un programme nommé pipeline qui va enchainer les traitements de plusieurs programmes GDAL avant d'écrire le fichier de sortie.

flowchart
 A(["gdal"])
 A --> B(["vector / raster"])
 B --> C(["pipeline"])
 C --> D(["read"])
 D --> E(["programme 1"])
 E --> F(["programme 2"])
 F --> G(["write"])

Exemple simple n'appliquant qu'une reprojection :

gdal vector pipeline --progress ! read in.gpkg ! reproject --dst-crs=EPSG:2154 ! write out.gpkg --overwrite

On peut aussi écrire le pipeline au format gdalg.json et son driver dédié. Attention, ne pas confondre gdalg etgdalf qui invoquera un magicien bourru et surtout ces cochoncettés de Hobbits qui vous viderons le frigo. Ce format rappelera le pipeline à chaque appel sur le fichier !

gdal vector pipeline --progress ! read in.gpkg ! reproject --dst-crs=EPSG:2154 ! write in_epsg_2154.gdalg.json --overwrite

Qu'on lira ensuite avec :

gdal vector info in_epsg_2154.gdalg.json

(L'exemple ci-dessus est issu de la documentation officielle de GDAL)

On peut ainsi imaginer un pipeline qui reprojetera une couche, avant de la filtrer sur la valeur d'un de ses attributs :

gdal vector pipeline ! read in.gpkg ! reproject --dst-crs=EPSG:2154 ! filter --where "mon_champ = 'valeur'" ! write out.gdalg.json

Cette manière de faire est certes plus verbeuse qu'un classique :

ogr2ogr --t_srs=EPSG:2154 --sql "WHERE mon_champ='valeur'" --option_3 --option_4 --option_n -lco option1_diver=YES -lco option2_diver=NO out.gpkg in.shp

Mais bien plus claire, et surtout réemployable puisque le fichier gdalg.json n'est que la description d'une succession de traitements sur la couche source, et peut être appelé comme n'importe quelle autre entrée par n'importe quel programme de GDAL .

L'Interface Système Virtuelle (VSI)#

C'est ici le moment magique où votre schéma interne de pensée va être modifié. Désormais quand vous vous poserez la question "comment je fais pour insert random bidule ?", vous vous direz alors "en fait je vais le faire avec gdal, ça sera plus simple". On peut ainsi donc dire que GDAL est vecteur (ah ah ah !) de manipulations mémétiques. C'est qu'on en apprend des trucs dans les vieux bouquins de jdr. Sur ce, l'interface système virtuelle de GDAL (VSI : Virtual System Interface).

GDAL possède une mécanique (le VSI) qui lui permet de lire des fichiers à travers un autre média (fichier zip, serveur http...).

Pour l'invoquer, on utilisera vsi à la place de vector/raster pour on ajoute le préfixe /vsi*quelque_chose*/ devant notre fichier.

Exemple :

gdal vsi info /vsizip/my_file.zip/my_layer_in.shp

Lire un fichier contenu dans un zip et le convertir (on peut s'en servir juste pour dézipper) :

gdal vsi copy /vsizip/my_file.zip/my_layer_in.gpkg my_layer_out.gpkg

Convertir un fichier stocké sur un serveur http :

gdal vsi copy /vsicurl/https://www.ign.fr/bd_topo/my_layer_in.gpkg my_layer_out.gpkg

Et on peut combiner pour convertir un fichier zip stocké sur un serveur web ! (attention à chainer les vsi avec //) :

gdal vsi copy /vsizip//vsicurl/https://www.ign.fr/bd_topo/my_file.zip/my_layer_in.shp my_layer_out.gpkg

GDAL possède même des pilotes S3 ou AWS pour son système VSI !

Enfin, on peut aussi profiter de GDAL pour générer des SOzip (Seek-Optimized Zips), grace au programme sozip. Des zips faits pour qu'on cherche vite à l'intérieur. C'est bizarre, ça parait être le penchant de "lire une donnée dans un zip sans avoir à le dézipper" vu juste haut dessus ;).

gdal vsi sozip create my.gpkg my.gpkg.zip

l'API Python#

Enfin, toute cette modernisation impacte évidemment les API, et celle qui nous interesse ici, l'API Python.

On rappelle que de façon curieuse, l'API Python de GDAL s'installe et s'importe comme ceci :

pip install gdal

from osgeo import gdal

gdal.Run(...)

Chaque programme GDAL est implémenté sous forme d'instances de la classe osgeo.gdal.Algorithm, qu'on appelle en utilisant la méthode osgeo.gdal.Run() ou plutôt gdal.Run() si on a importé GDAL comme dans l'exemple ci-dessus.

Ensuite, c'est simple, ils s'appellent comme ceci :

gdal.Run("vector"/"raster"/"vsi", "programme", option(s), input="in.tif", output="out.tif)

Exemple pour importer un fichier csv dans une base PostgreSQL (plutôt que d'utiliser COPY de postgres, plus fastidieux):

gdal.Run("vector", "convert", append=True, format="PostgreSQL", lco="LAUNDER=NO", input=my_file.csv, output="PG:dbname='insee' schemas='wip' user='me' password='admin123'")

Le driver PostgreSQL possède une option LAUNDER activée par défaut qui va normaliser votre import (mettre les noms de champs en minuscule ...), que je désire désactiver ici.

Exemple pour dézipper un fichier car c'est pénible en Python sinon (ça necessite genre, au moins 3 lignes !), et où le nom du fichier et du zip sont contenus dans une variable file :

gdal.Run("vsi", "copy", source=f"/vsizip/{file}_csv.zip/{file}.CSV", destination=f"{file}.csv")

(notez qu'avec le programme copy, entrée et sortie se nomment source et destination)

Sur ce, g la dahl de lentilles, alors bon appétit ! (au fond de moi j'ai honte, mais ça fait du bien).

Auteur·ice#

Thomas SZCZUREK-GAYANT#

Géomaticien, on a installé un jour QGIS sur mon ordinateur alors que je ne l'avais pas ouvert depuis 2008 et j'ai compris que ma vision de l'open source était dépassée de plus de 10 ans. On peut me retrouver maintenant errant dans les rues en hurlant "passez sous Linux" aux inconnus. Sinon j'aime bien l'astronomie et les chats.

Licence #

Ce contenu est sous licence Creative Commons International 4.0 BY-NC-SA, avec attribution et partage dans les mêmes conditions, sauf dans le cadre d'une utilisation commerciale.
Les médias d'illustration sont potentiellement soumis à d'autres conditions d'utilisation.

Partager sur :

Commentaires