From 6c250664ae23331395811a8256df4456850304d4 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Tue, 12 Nov 2024 17:53:42 +0100 Subject: [PATCH] Doc: Python: add executable examples using myst-nb --- doc/requirements.txt | 1 + doc/source/api/python/data/byte.tif | Bin 0 -> 736 bytes doc/source/api/python/index.rst | 1 + doc/source/api/python/python_examples.myst | 94 +++++++++++++++++++++ doc/source/conf.py | 8 ++ 5 files changed, 104 insertions(+) create mode 100644 doc/source/api/python/data/byte.tif create mode 100644 doc/source/api/python/python_examples.myst diff --git a/doc/requirements.txt b/doc/requirements.txt index 34b6230cfd8d..8e566338af66 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -11,3 +11,4 @@ recommonmark sphinx-markdown-tables sphinxcontrib-spelling sphinxcontrib-jquery +myst_nb diff --git a/doc/source/api/python/data/byte.tif b/doc/source/api/python/data/byte.tif new file mode 100644 index 0000000000000000000000000000000000000000..6fddac1286241fd62383c20965a11c38f021d7bc GIT binary patch literal 736 zcmZuuJ&P1U5bfDr4}(P!ygQK#7K}8JGcmmblM`s4NH1($H)vMP%CnxvPmnJ1v6Ein6#x_x;;c%h zs8JDc6d4y&@I+WRn<|=Buvsz-idI5QL^Nxs#%x8`wdO1tePV^8<$}*^b~mUC=rN=! z7{PLA8RSW+C-^ZLEUFqI7n9w|2_p?2P*mI@R(R!%f>)$;a~u|><;qwwt!9b}@wzgk z$hmrsdlS@+90ovxH})3tE$rehVT`QHMIj>?P823vm34LR#9ERTIVj+9N)HEctB+yW zi*+zufB(5KcFopx8BfXBeP41ZrMGzTSVDX~rDmG&W718WW`rkOd=>fW76)%OJrrVa} zmuq>n!T;iA<$vht*X`rT|NQo3h=H5o23Jy=Z7}Q(xykHowHt(ae7}4>8{*wN%i~86 X9xm=LUOYctynpxh)#C7Q`62xUqeR@! literal 0 HcmV?d00001 diff --git a/doc/source/api/python/index.rst b/doc/source/api/python/index.rst index 37a976b20fc2..b7e93f6a05ef 100644 --- a/doc/source/api/python/index.rst +++ b/doc/source/api/python/index.rst @@ -10,6 +10,7 @@ Python API :maxdepth: 2 python_bindings + python_examples osgeo raster_api vector_api diff --git a/doc/source/api/python/python_examples.myst b/doc/source/api/python/python_examples.myst new file mode 100644 index 000000000000..79f294d88620 --- /dev/null +++ b/doc/source/api/python/python_examples.myst @@ -0,0 +1,94 @@ +--- +jupytext: + formats: md:myst + text_representation: + extension: .md + format_name: myst +kernelspec: + display_name: Python 3 + language: python + name: python3 +--- + +# Examples + +## Getting information on a raster dataset using dedicated methods + +The following snippet uses individual API methods to retrieve characters of +a GDAL raster dataset and its bands. + +```{code-cell} + +from osgeo import gdal +import json + +gdal.UseExceptions() + +with gdal.Open("data/byte.tif") as ds: + print(f"Width: {ds.RasterXSize}") + print(f"Height: {ds.RasterYSize}") + print(f"Number of bands: {ds.RasterCount}") + print(f"Metadata: {ds.GetMetadata()}") + srs = ds.GetSpatialRef() + if srs: + srs_as_projjson = json.loads(srs.ExportToPROJJSON()) + print("SRS:") + name = srs_as_projjson["name"] + print(f" Name: {name}") + if "id" in srs_as_projjson: + id = srs_as_projjson["id"] + authority = id["authority"] + code = id["code"] + print(f" Id: {authority}:{code}") + geotransform = ds.GetGeoTransform() + if geotransform[2] == 0 and geotransform[4] == 0: + print(f"Upper-left corner georeferenced position: X={geotransform[0]}, Y={geotransform[1]}") + print(f"Horizontal resolution: {geotransform[1]}") + print(f"Vertical resolution: {geotransform[5]} (if negative, indicates a north-up image)") + else: + print(f"Geotransformation matrix: {geotransform}") + for idx, band in enumerate(ds): + print(f"Band {idx+1}:") + print(f" Data type: {gdal.GetDataTypeName(band.DataType)}") + block_width, block_height = band.GetBlockSize() + print(f" Block width: {block_width}") + print(f" Block height: {block_height}") + print(f" Metadata: {band.GetMetadata()}") +``` + +## Getting information on a raster dataset using gdal.Info() + +The following snippet uses the {py:func}`osgeo.gdal.Info()` method to retrieve characters of +a GDAL raster dataset and its bands, as a JSON document. + +```{code-cell} +:tags: [hide-output] + +from osgeo import gdal +import pprint + +gdal.UseExceptions() + +with gdal.Open("data/byte.tif") as ds: + info = gdal.Info(ds, format='json') + del info["stac"] # to avoid cluttering below output + pprint.pprint(info, indent=2, width=100) +``` + +## Reading a whole raster as a numpy array + +The following snippet uses the {py:func}`osgeo.gdal.Dataset.ReadAsArray()` +method to retrieve the pixel values of all the bands of a dataset as a +[numpy array](https://numpy.org/doc/stable/reference/generated/numpy.array.html). + +```{code-cell} +:tags: [hide-output] + +from osgeo import gdal + +gdal.UseExceptions() + +with gdal.Open("data/byte.tif") as ds: + array = ds.ReadAsArray() + print(array) +``` diff --git a/doc/source/conf.py b/doc/source/conf.py index 4b3bcaf485d1..381b932e471a 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -72,6 +72,7 @@ "sphinx.ext.napoleon", "sphinxcontrib.jquery", "sphinxcontrib.spelling", + "myst_nb", ] # Add any paths that contain templates here, relative to this directory. @@ -84,6 +85,7 @@ "substitutions.rst", "programs/options/*.rst", "api/python/modules.rst", + "gdal_rtd/README.md", ] # Prevents double hyphen (--) to be replaced by Unicode long dash character @@ -112,6 +114,12 @@ .. |offline-download| replace:: {offline_download_text} """ +source_suffix = { + ".rst": "restructuredtext", + ".ipynb": "myst-nb", + ".myst": "myst-nb", +} + # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for