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 000000000000..6fddac128624 Binary files /dev/null and b/doc/source/api/python/data/byte.tif differ 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..8f1e52c5bced --- /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 dedicate 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. + +```{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