Add STACIT driver examples

Author: geographika

doc/source/drivers/raster/examples/stacit.py

@@ -0,0 +1,25 @@
+from osgeo import gdal
+
+gdal.UseExceptions()
+
+stac_url = "https://planetarycomputer.microsoft.com/api/stac/v1/search"
+bbox = "-100,40,-99,41"
+datetime = "2019-01-01T00:00:00Z%2F.."
+collections = "naip"
+url = f"{stac_url}?collections={collections}&bbox={bbox}&datetime={datetime}"
+
+ds = gdal.OpenEx(
+    url, allowed_drivers=["STACIT"]
+)  # force the STACIT driver or it opens as GeoJSON
+
+print(gdal.Info(ds, format="json"))
+
+# subdatasets
+
+subdatasets = ds.GetSubDatasets()
+# get the first subdataset properties
+sds_properties = subdatasets[0]
+subdataset_url = sds_properties[0]  # a tuple of URL and description
+subdataset = gdal.OpenEx(subdataset_url, allowed_drivers=["STACIT"])
+
+print(gdal.Info(subdataset, format="json"))

doc/source/drivers/raster/stacit.rst

@@ -10,13 +10,17 @@ STACIT - Spatio-Temporal Asset Catalog Items
 
 .. built_in_by_default::
 
-This driver supports opening STAC API ItemCollections, with the input usually being a `STAC API search query <https://github.com/radiantearth/stac-api-spec/tree/main/item-search>`_ or the results saved as a JSON file. Items in the response must include projection information following the `Projection Extension Specification <https://github.com/stac-extensions/projection/>`_.
+This driver supports opening STAC API ItemCollections, with the input usually being a `STAC API search query <https://github.com/radiantearth/stac-api-spec/tree/main/item-search>`_
+or the results saved as a JSON file. Items in the response must include projection information following the
+`Projection Extension Specification <https://github.com/stac-extensions/projection/>`_.
 It builds a virtual mosaic from the items.
 
 A STACIT dataset which has no subdatasets is actually a :ref:`raster.vrt` dataset.
 Thus, translating it into VRT will result in a VRT file that directly references the items.
 
-Note that `STAC API ItemCollections <https://github.com/radiantearth/stac-api-spec/blob/main/fragments/itemcollection/README.md>`_ are not the same as  `STAC Collections <https://github.com/radiantearth/stac-spec/tree/master/collection-spec>`_. STAC API ItemCollections are GeoJSON FeatureCollections enhanced with STAC entities.
+Note that `STAC API ItemCollections <https://github.com/radiantearth/stac-api-spec/blob/main/fragments/itemcollection/README.md>`_
+are not the same as  `STAC Collections <https://github.com/radiantearth/stac-spec/tree/master/collection-spec>`_.
+STAC API ItemCollections are GeoJSON FeatureCollections enhanced with STAC entities.
 
 Open syntax
 -----------
@@ -108,17 +112,47 @@ Examples
 List the subdatasets associated to a `STAC search <https://github.com/radiantearth/stac-api-spec/tree/master/item-search>`_
 on a given collection, bbox and starting from a datetime:
 
-::
+.. tabs::
+
+   .. code-tab:: bash
 
     gdalinfo "STACIT:\"https://planetarycomputer.microsoft.com/api/stac/v1/search?collections=naip&bbox=-100,40,-99,41&datetime=2019-01-01T00:00:00Z%2F..\""
+    # from GDAL 3.11+
+    gdal raster info "STACIT:\"https://planetarycomputer.microsoft.com/api/stac/v1/search?collections=naip&bbox=-100,40,-99,41&datetime=2019-01-01T00:00:00Z%2F..\""
+
+
+   .. code-tab:: ps1
+
+    gdalinfo 'STACIT:\"https://planetarycomputer.microsoft.com/api/stac/v1/search?collections=naip&bbox=-100,40,-99,41&datetime=2019-01-01T00:00:00Z%2F..\"'
+    # from GDAL 3.11+
+    gdal raster info 'STACIT:\"https://planetarycomputer.microsoft.com/api/stac/v1/search?collections=naip&bbox=-100,40,-99,41&datetime=2019-01-01T00:00:00Z%2F..\"'
+
+   .. tab:: Python
 
+      .. literalinclude :: examples/stacit.py
+         :language: python
+         :end-before: # subdatasets
 
 Open a subdataset returned by the above request:
 
-::
+.. tabs::
+
+   .. code-tab:: bash
 
     gdalinfo "STACIT:\"https://planetarycomputer.microsoft.com/api/stac/v1/search?collections=naip&bbox=-100,40,-99,41&datetime=2019-01-01T00:00:00Z%2F..\":asset=image"
+    gdal raster info "STACIT:\"https://planetarycomputer.microsoft.com/api/stac/v1/search?collections=naip&bbox=-100,40,-99,41&datetime=2019-01-01T00:00:00Z%2F..\":asset=image"
+
+   .. code-tab:: ps1
+
+    gdalinfo 'STACIT:\"https://planetarycomputer.microsoft.com/api/stac/v1/search?collections=naip&bbox=-100,40,-99,41&datetime=2019-01-01T00:00:00Z%2F..\":asset=image'
+    # from GDAL 3.11+
+    gdal raster info 'STACIT:\"https://planetarycomputer.microsoft.com/api/stac/v1/search?collections=naip&bbox=-100,40,-99,41&datetime=2019-01-01T00:00:00Z%2F..\":asset=image'
+
+   .. tab:: Python
 
+      .. literalinclude :: examples/stacit.py
+         :language: python
+         :start-after: # subdatasets
 
 See Also
 --------