[backport] alternate asset and vrt string

CHANGES.md

@@ -1,5 +1,11 @@
 # unreleased
 
+# 6.8.0 (2024-10-23)
+
+* Enable **Alternate** asset's HREF for STAC by using `RIO_TILER_STAC_ALTERNATE_KEY` environment variable [Backported from `7.0`]
+
+* Adding support for GDAL VRT Connection string for STAC Assets [Backported from `7.0`]
+
 # 6.7.0 (2024-09-05)
 
 * raise `MissingCRS` or `InvalidGeographicBounds` errors when Xarray datasets have wrong geographic metadata

rio_tiler/io/stac.py

@@ -3,7 +3,7 @@
 import json
 import os
 import warnings
-from typing import Any, Dict, Iterator, Optional, Set, Type, Union
+from typing import Any, Dict, Iterator, Optional, Set, Tuple, Type, Union
 from urllib.parse import urlparse
 
 import attr
@@ -41,6 +41,8 @@
     "application/x-hdf",
 }
 
+STAC_ALTERNATE_KEY = os.environ.get("RIO_TILER_STAC_ALTERNATE_KEY", None)
+
 
 def aws_get_object(
     bucket: str,
@@ -275,16 +277,34 @@ def _minzoom(self):
     def _maxzoom(self):
         return self.tms.maxzoom
 
+    def _parse_vrt_asset(self, asset: str) -> Tuple[str, Optional[str]]:
+        if asset.startswith("vrt://") and asset not in self.assets:
+            parsed = urlparse(asset)
+            if not parsed.netloc:
+                raise InvalidAssetName(
+                    f"'{asset}' is not valid, couldn't find valid asset"
+                )
+
+            if parsed.netloc not in self.assets:
+                raise InvalidAssetName(
+                    f"'{parsed.netloc}' is not valid, should be one of {self.assets}"
+                )
+
+            return parsed.netloc, parsed.query
+
+        return asset, None
+
     def _get_asset_info(self, asset: str) -> AssetInfo:
-        """Validate asset names and return asset's url.
+        """Validate asset names and return asset's info.
 
         Args:
             asset (str): STAC asset name.
 
         Returns:
-            str: STAC asset href.
+            AssetInfo: STAC asset info.
 
         """
+        asset, vrt_options = self._parse_vrt_asset(asset)
         if asset not in self.assets:
             raise InvalidAssetName(
                 f"'{asset}' is not valid, should be one of {self.assets}"
@@ -295,13 +315,19 @@ def _get_asset_info(self, asset: str) -> AssetInfo:
 
         info = AssetInfo(
             url=asset_info.get_absolute_href() or asset_info.href,
-            metadata=extras,
+            metadata=extras if not vrt_options else None,
         )
 
+        if STAC_ALTERNATE_KEY and extras.get("alternate"):
+            if alternate := extras["alternate"].get(STAC_ALTERNATE_KEY):
+                info["url"] = alternate["href"]
+
+        # https://github.com/stac-extensions/file
         if head := extras.get("file:header_size"):
             info["env"] = {"GDAL_INGESTED_BYTES_AT_OPEN": head}
 
-        if bands := extras.get("raster:bands"):
+        # https://github.com/stac-extensions/raster
+        if (bands := extras.get("raster:bands")) and not vrt_options:
             stats = [
                 (b["statistics"]["minimum"], b["statistics"]["maximum"])
                 for b in bands
@@ -319,4 +345,7 @@ def _get_asset_info(self, asset: str) -> AssetInfo:
                     "Some statistics data in STAC are invalid, they will be ignored."
                 )
 
+        if vrt_options:
+            info["url"] = f"vrt://{info['url']}?{vrt_options}"
+
         return info

tests/fixtures/stac_alternate.json

@@ -0,0 +1,85 @@
+{
+  "stac_version": "0.9.0",
+  "stac_extensions": [
+    "https://stac-extensions.github.io/file/v2.1.0/schema.json",
+    "https://stac-extensions.github.io/alternate-assets/v1.2.0/schema.json"
+  ],
+  "type": "Feature",
+  "id": "JQT-123456789",
+  "bbox": [-81.3085227080129, 32.10817938759764, -78.81735409341113, 34.22870275071835],
+  "geometry": {
+    "type": "Polygon",
+    "coordinates": [
+        [
+            [
+                -81.3085227080129,
+                32.10817938759764
+            ],
+            [
+                -78.81735409341113,
+                32.10817938759764
+            ],
+            [
+                -78.81735409341113,
+                34.22870275071835
+            ],
+            [
+                -81.3085227080129,
+                34.22870275071835
+            ],
+            [
+                -81.3085227080129,
+                32.10817938759764
+            ]
+        ]
+    ]
+  },
+  "properties": {
+    "datetime": "2016-05-03T13:21:30.040Z",
+    "collection": "JQT"
+  },
+  "links": [
+    {
+      "rel": "self",
+      "href": "http://cool-sat.com/catalog/JQT/a-fake-item.json"
+    },
+    {
+      "rel": "collection",
+      "href": "http://cool-sat.com/catalog.json"
+    }
+  ],
+  "assets": {
+    "red": {
+      "href": "http://somewhere-over-the-rainbow.io/red.tif",
+      "title": "red",
+      "file:header_size": 16384,
+      "alternate:name": "HTTPS",
+      "alternate": {
+        "s3": {
+          "href": "s3://somewhere-over-the-rainbow.io/red.tif",
+          "alternate:name": "S3"
+        }
+      }
+    },
+    "green": {
+        "href": "http://somewhere-over-the-rainbow.io/green.tif",
+        "title": "green",
+        "file:header_size": 30000
+    },
+    "blue": {
+        "href": "http://somewhere-over-the-rainbow.io/blue.tif",
+        "title": "blue",
+        "file:header_size": 20000
+    },
+    "lowres": {
+        "href": "http://somewhere-over-the-rainbow.io/lowres.tif",
+        "title": "lowres"
+    },
+    "thumbnail": {
+      "href": "http://cool-sat.com/catalog/a-fake-item/thumbnail.png",
+      "title": "Thumbnail",
+      "type": "image/png",
+      "roles": [ "thumbnail" ]
+    }
+  }
+}