diff --git a/doc/source/programs/gdal_cli_from_python.rst b/doc/source/programs/gdal_cli_from_python.rst new file mode 100644 index 000000000000..93ad2fa49813 --- /dev/null +++ b/doc/source/programs/gdal_cli_from_python.rst @@ -0,0 +1,128 @@ +.. _gdal_cli_from_python: + +================================================================================ +How to use "gdal" CLI algorithms from Python +================================================================================ + +Raster commands +--------------- + +* Getting information on a raster dataset as JSON + +.. code-block:: python + + from osgeo import gdal + import json + + gdal.UseExceptions() + alg = gdal.GetGlobalAlgorithmRegistry()["raster"]["info"] + alg["input"] = "byte.tif" + alg.Run() + info = json.loads(alg["output-string"]) + print(info) + + +* Converting a georeferenced netCDF file to cloud-optimized GeoTIFF + +.. code-block:: python + + from osgeo import gdal + gdal.UseExceptions() + alg = gdal.GetGlobalAlgorithmRegistry()["raster"]["convert"] + alg["input"] = "in.nc" + alg["output"] = "out.tif" + alg["output-format"] = "COG" + alg["overwrite"] = True # if the output file may exist + alg.Run() + alg.Finalize() # ensure output dataset is closed + +or + +.. code-block:: python + + from osgeo import gdal + gdal.UseExceptions() + alg = gdal.GetGlobalAlgorithmRegistry()["raster"]["convert"] + alg.ParseRunAndFinalize(["--input=in.nc", "--output-format=COG", "--output=out.tif", "--overwrite"]) + + +* Reprojecting a GeoTIFF file to a Deflate compressed tiled GeoTIFF file + +.. code-block:: python + + from osgeo import gdal + gdal.UseExceptions() + alg = gdal.GetGlobalAlgorithmRegistry()["raster"]["reproject"] + alg["input"] = "in.tif" + alg["output"] = "out.tif" + alg["dst-crs"] = "EPSG:4326" + alg["creation-options"] = ["TILED=YES", "COMPRESS=DEFLATE"] + alg["overwrite"] = True # if the output file may exist + alg.Run() + alg.Finalize() # ensure output dataset is closed + +or + +.. code-block:: python + + from osgeo import gdal + gdal.UseExceptions() + alg = gdal.GetGlobalAlgorithmRegistry()["raster"]["reproject"] + alg.ParseRunAndFinalize(["--input=in.tif", "--output=out.tif", "--dst-crs=EPSG:4326", "--co=TILED=YES,COMPRESS=DEFLATE", "--overwrite"]) + + +* Reprojecting a (possibly in-memory) dataset to a in-memory dataset + +.. code-block:: python + + from osgeo import gdal + gdal.UseExceptions() + alg = gdal.GetGlobalAlgorithmRegistry()["raster"]["reproject"] + alg["input"] = input_ds + alg["output"] = "dummy_name" + alg["output-format"] = "MEM" + alg["dst-crs"] = "EPSG:4326" + alg.Run() + output_ds = alg["output"].GetDataset() + + + +Vector commands +--------------- + +* Getting information on a vector dataset as JSON + +.. code-block:: python + + from osgeo import gdal + import json + + gdal.UseExceptions() + alg = gdal.GetGlobalAlgorithmRegistry()["vector"]["info"] + alg["input"] = "poly.gpkg" + alg.Run() + info = json.loads(alg["output-string"]) + print(info) + + +* Converting a shapefile to a GeoPackage + +.. code-block:: python + + from osgeo import gdal + gdal.UseExceptions() + alg = gdal.GetGlobalAlgorithmRegistry()["vector"]["convert"] + alg["input"] = "in.shp" + alg["output"] = "out.gpkg" + alg["overwrite"] = True # if the output file may exist + alg.Run() + alg.Finalize() # ensure output dataset is closed + +or + +.. code-block:: python + + from osgeo import gdal + gdal.UseExceptions() + alg = gdal.GetGlobalAlgorithmRegistry()["vector"]["convert"] + alg.ParseRunAndFinalize(["--input=in.shp", "--output=out.gpkg", "--overwrite"]) diff --git a/doc/source/programs/index.rst b/doc/source/programs/index.rst index 95477fda0777..f98a1bccd476 100644 --- a/doc/source/programs/index.rst +++ b/doc/source/programs/index.rst @@ -26,6 +26,7 @@ single :program:`gdal` program that accepts commands and subcommands. :hidden: migration_guide_to_gdal_cli + gdal_cli_from_python gdal gdal_info gdal_convert @@ -50,6 +51,7 @@ single :program:`gdal` program that accepts commands and subcommands. .. only:: html - :ref:`migration_guide_to_gdal_cli`: Migration guide to "gdal" command line interface + - :ref:`gdal_cli_from_python`: How to use "gdal" CLI algorithms from Python - :ref:`gdal_program`: Main "gdal" entry point - :ref:`gdal_info_command`: Get information on a dataset - :ref:`gdal_convert_command`: Convert a dataset