rio-stac-io 0.3.4__tar.gz

rio_stac_io-0.3.4/.gitignore

@@ -0,0 +1,151 @@
+# local testing data/results
+*.vrt
+scripts/*.tif
+scripts/*.laz
+scripts/*.tif.aux.xml
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# cba
+.zedstate
+
+# channel/package builds
+channel/
+package/
+
+# lbatch ephemeral
+jobs.json
+nohup.out
+results.json
+
+# pixi environments
+.pixi
+*.egg-info

rio_stac_io-0.3.4/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

rio_stac_io-0.3.4/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: rio-stac-io
+Version: 0.3.4
+Author-email: Thomas Maschler <thomas.maschler@planet.com>
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: pystac-client>=0.9.0
+Requires-Dist: pystac>=1.11.0
+Requires-Dist: rasterio>=1.4.3
+Provides-Extra: gti
+Requires-Dist: stac-geoparquet>=0.7.0; extra == 'gti'

rio_stac_io-0.3.4/pyproject.toml

@@ -0,0 +1,238 @@
+[project]
+authors = [{ name = "Thomas Maschler", email = "thomas.maschler@planet.com" }]
+name = "rio-stac-io"
+requires-python = ">= 3.10"
+version = "v0.3.4"
+dependencies = [
+    "rasterio>=1.4.3",
+    "pystac>=1.11.0",
+    "pystac-client>=0.9.0",
+
+]
+
+[project.optional-dependencies]
+gti = ["stac-geoparquet>=0.7.0",]
+
+
+[tool.pixi.workspace]
+channels = ["conda-forge"]
+platforms = ["osx-arm64", "linux-64"]
+
+[tool.pixi.pypi-options]
+no-binary = ["rasterio"]
+
+[tool.pixi.pypi-dependencies]
+rio_stac_io = { path = ".", editable = true }
+
+[tool.pixi.environments]
+default = { features = ["gti"], solve-group = "default" }
+dev = { features = ["gti", "dev", "lint", "gdal-311"], solve-group = "gdal-311" }
+dev-gdal38 = { features = ["gti", "dev", "lint", "gdal-38"], solve-group = "gdal-38" }
+dev-gdal39 = { features = ["gti", "dev", "lint", "gdal-39"], solve-group = "gdal-39" }
+dev-gdal310 = { features = ["gti", "dev", "lint", "gdal-310"], solve-group = "gdal-310" }
+dev-gdal311 = { features = ["gti", "dev", "lint", "gdal-311"], solve-group = "gdal-311" }
+lint = { features = ["lint"], solve-group = "lint", no-default-feature = true }
+docs = { features = ["docs"], solve-group = "docs", no-default-feature = true  }
+build = { features = ["build"], solve-group = "build",  no-default-feature = true  }
+
+######## Pixi/ GDAL 3.8
+
+[tool.pixi.feature.gdal-38.dependencies]
+libgdal = "==3.8.5"
+libgdal-arrow-parquet = "*"
+proj = ">=9"
+libexpat = "*"
+
+######## Pixi/ GDAL 3.9
+
+[tool.pixi.feature.gdal-39.dependencies]
+libgdal = "==3.9.3"
+libgdal-arrow-parquet = "*"
+proj = ">=9"
+libexpat = "*"
+
+######## Pixi/ GDAL 3.10
+
+[tool.pixi.feature.gdal-310.dependencies]
+libgdal = "==3.10.3"
+libgdal-arrow-parquet = "*"
+proj = ">=9"
+libexpat = "*"
+
+######## Pixi/ GDAL 3.11
+
+[tool.pixi.feature.gdal-311.dependencies]
+libgdal = "==3.11.4"
+libgdal-arrow-parquet = "*"
+proj = ">=9"
+libexpat = "*"
+
+######## Pixi/ DEV
+
+[tool.pixi.feature.dev.pypi-dependencies]
+pytest = ">=7.4.0"
+pytest-cov = ">=4.1.0"
+pytest-recording = ">=0.13.0"
+rasterio = { version = "*", extras = ["s3"] }
+rio-stac = ">=0.10.1"
+morecantile = ">6.1.0"
+
+
+[tool.pixi.feature.dev.tasks]
+test = "pytest --record-mode=once"
+test-ci = "pytest --record-mode=none"
+
+######## Pixi Lint
+
+[tool.pixi.feature.lint.dependencies]
+python = ">=3.10,<=3.12"
+
+[tool.pixi.feature.lint.pypi-dependencies]
+ruff = ">=0.1.12"
+mypy = ">=1.5.1"
+pre-commit = ">=2.19.0"
+types-python-dateutil = ">=2.9.0.20240315"
+types-pytz = ">=2024.1.0.20240203"
+types-requests = ">=2.26.0.20240315"
+
+
+[tool.pixi.feature.lint.tasks]
+_setup = "pre-commit install"
+lint = { cmd = "pre-commit run --all-files", depends-on = ["_setup"] }
+
+######## Pixi/ DOCS
+
+[tool.pixi.feature.docs.dependencies]
+python = ">=3.10"
+
+[tool.pixi.feature.docs.pypi-dependencies]
+mkdocs = ">=1.5.3"
+mkdocs-jupyter = ">=0.24.6"
+mkdocs-material = ">=9.5.3"
+mkdocstrings-python = ">=1.7.5"
+livereload = ">=2.6.3"
+
+[tool.pixi.feature.docs.tasks]
+localdocs = "mkdocs serve"
+deploy = "mkdocs gh-deploy"
+
+######## Pixi/ Hatch Build
+
+[build-system]
+build-backend = "hatchling.build"
+requires = ["hatchling"]
+
+[tool.hatch.build.targets.sdist]
+include = ["rio_stac_io"]
+
+[tool.hatch.build.targets.wheel]
+only-include = ["rio_stac_io"]
+
+[tool.pixi.feature.build.dependencies]
+python = ">=3.10"
+
+[tool.pixi.feature.build.pypi-dependencies]
+hatch = "*"
+twine = "*"
+
+[tool.pixi.feature.build.tasks]
+build = "pixi project version set $(git describe --tags) && hatch build"
+deploy = { cmd = "twine upload -r planet dist/*", depends-on = ["build"] }
+
+# PYTEST
+
+[tool.pytest.ini_options]
+addopts = "--cov=rio_stac_io --no-cov-on-fail --cov-report=term-missing:skip-covered --record-mode=rewrite"
+
+[tool.mypy]
+ignore_missing_imports = true
+warn_unused_configs = true
+disallow_incomplete_defs = true
+disallow_untyped_defs = true
+warn_return_any = true
+exclude = "tests/*"
+
+[tool.ruff]
+exclude = [
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".git-rewrite",
+    ".hg",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "venv",
+]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["F", "E", "W", "I001"]
+ignore = []
+fixable = [
+    "A",
+    "B",
+    "C",
+    "D",
+    "E",
+    "F",
+    "G",
+    "I",
+    "N",
+    "Q",
+    "S",
+    "T",
+    "W",
+    "ANN",
+    "ARG",
+    "BLE",
+    "COM",
+    "DJ",
+    "DTZ",
+    "EM",
+    "ERA",
+    "EXE",
+    "FBT",
+    "ICN",
+    "INP",
+    "ISC",
+    "NPY",
+    "PD",
+    "PGH",
+    "PIE",
+    "PL",
+    "PT",
+    "PTH",
+    "PYI",
+    "RET",
+    "RSE",
+    "RUF",
+    "SIM",
+    "SLF",
+    "TCH",
+    "TID",
+    "TRY",
+    "UP",
+    "YTT",
+]
+unfixable = []
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.format]
+quote-style = "double"

rio_stac_io-0.3.4/rio_stac_io/__init__.py

@@ -0,0 +1,6 @@
+from .io import open  # noqa E402
+from importlib import metadata
+
+__version__ = metadata.version(__package__)
+
+del metadata

rio_stac_io-0.3.4/rio_stac_io/drivers/gti.py

@@ -0,0 +1,92 @@
+from contextlib import ExitStack
+from typing import Any, Iterable
+
+import rasterio as rio
+from pystac import Item, ItemCollection
+from pystac_client import ItemSearch
+from rasterio import DatasetReader
+from rasterio.env import Env, local
+
+from rio_stac_io.utils import require_gdal_version, vsi_href
+
+
+class GTIDatasetReader(DatasetReader):
+    links: list[str | None]
+
+    @require_gdal_version("3.10.0")
+    def __init__(
+        self,
+        item_collection: ItemCollection | ItemSearch,
+        asset_key: str,
+        **profile: Any,
+    ) -> None:
+        try:
+            from geopandas import GeoDataFrame
+            from stac_geoparquet.arrow import parse_stac_items_to_arrow
+            from stac_geoparquet.arrow._constants import DEFAULT_PARQUET_SCHEMA_VERSION
+        except ImportError as e:
+            raise ImportError(
+                "Missing extra modules. Please install package with as rio-stac-io[gti]"
+            ) from e
+
+        with rio.Env() as env:
+            if not env.drivers().get("Parquet"):
+                raise SystemError(
+                    "Cannot open Stac Query using GTI driver. "
+                    "Make sure your GDAL library is build with GeoParquet support."
+                )
+
+        def rewrite_href(assets: dict[str, Any]) -> dict[str, Any]:
+            assets[asset_key]["href"] = vsi_href(assets[asset_key]["href"])
+            return assets
+
+        stack = ExitStack()
+
+        if isinstance(item_collection, ItemSearch):
+            _items: Iterable[Item] = item_collection.items()
+        else:
+            _items = item_collection.items
+
+        try:
+            # Write ItemCollection to a temporary in-memory Parquet file
+            # This will create a /vsimem/ path that can be used by the GTI driver
+            tmp_path = stack.enter_context(rio.MemoryFile(ext=".parquet"))
+            arrow = parse_stac_items_to_arrow(_items)
+            gdf = GeoDataFrame.from_arrow(arrow)
+            gdf["assets"] = gdf["assets"].apply(rewrite_href)
+
+            gdf.to_parquet(tmp_path, schema_version=DEFAULT_PARQUET_SCHEMA_VERSION)
+            tmp_path.seek(0)
+
+            href = f"GTI:{tmp_path.name}"
+            profile.pop("driver", None)
+            profile["LOCATION_FIELD"] = f"assets.{asset_key}.href"
+
+            self._files: list[str] = (
+                gdf["assets"].apply(lambda x: x[asset_key]["href"]).to_list()
+            )
+            self.links = [item.get_self_href() for item in _items]
+
+            if not local._env:
+                stack.enter_context(Env.from_defaults())
+
+            super().__init__(href, **profile)
+
+            self._env = stack
+
+        except TypeError as e:
+            stack.close()
+            if "got pyarrow.lib.NullArray" in str(e):
+                raise ValueError(
+                    "Cannot open dataset. Got empty ItemCollection."
+                ) from e
+
+            else:
+                raise
+        except Exception:
+            stack.close()
+            raise
+
+    @property
+    def files(self) -> list[str]:
+        return self._files

rio_stac_io-0.3.4/rio_stac_io/drivers/stacit.py

@@ -0,0 +1,137 @@
+import json
+import warnings
+from contextlib import ExitStack
+from typing import Any, Iterable, Literal
+
+import rasterio as rio
+from packaging.version import parse
+from pystac import Item, ItemCollection
+from pystac_client import ItemSearch
+from rasterio import DatasetReader
+from rasterio.env import Env, GDALVersion, local
+from rasterio.errors import RasterioIOError
+
+from rio_stac_io.utils import infer_projection_metadata, vsi_href
+
+
+def rewrite_item(
+    item: Item,
+    asset_key: str,
+    merge_collections: bool,
+    gdal_version: str,
+    infer_projection: bool,
+) -> Item:
+    item.assets[asset_key].href = vsi_href(item.assets[asset_key].href)
+
+    if merge_collections:
+        # STACIT keeps item from different collections in separate subdatasets
+        # We can bypass this by removing the collection reference
+        item.collection_id = None
+
+    if infer_projection:
+        # Infer projection metadata if missing
+        # This will call the file header of each asset to extract the projection info
+        item = infer_projection_metadata(item, asset_key)
+
+    # STACIT driver only starts supporting STAC v1.1.0 starting in GDAL v3.10.2
+    # For lower versions, we need to substitute the `proj:code` property
+    # with the now deprecated `proj:epsg`` property
+    if parse(gdal_version) < parse("3.10.2"):
+        if "proj:code" in item.properties:
+            item.properties["proj:epsg"] = int(
+                item.properties["proj:code"].replace("EPSG:", "")
+            )
+
+        if "proj:code" in item.assets[asset_key].extra_fields:
+            item.assets[asset_key].extra_fields["proj:epsg"] = int(
+                item.assets[asset_key].extra_fields["proj:code"].replace("EPSG:", "")
+            )
+
+    return item
+
+
+class STACITDatasetReader(DatasetReader):
+    links: list[str | None]
+
+    def __init__(
+        self,
+        item_collection: ItemCollection | ItemSearch,
+        asset_key: str,
+        merge_collections: bool,
+        overlap_strategy: Literal["REMOVE_IF_NO_NODATA​", "​USE_ALL", "​USE_MOST_RECENT"]
+        | None = None,
+        infer_projection: bool = False,
+        **profile: Any,
+    ) -> None:
+        stack = ExitStack()
+
+        gdal_version = rio.__gdal_version__
+
+        if isinstance(item_collection, ItemSearch):
+            _items: Iterable[Item] = item_collection.items()
+        else:
+            _items = item_collection.items
+
+        item_collection = ItemCollection(
+            items=[
+                rewrite_item(
+                    item,
+                    asset_key,
+                    merge_collections=merge_collections,
+                    gdal_version=gdal_version,
+                    infer_projection=infer_projection,
+                )
+                for item in _items
+            ]
+        )
+
+        if not item_collection.items:
+            raise ValueError("Cannot open dataset. Got empty ItemCollection.")
+
+        try:
+            # Write ItemCollection to a temporary in-memory file
+            # this will create a /vsimem/ path that can be used by the STACIT driver
+            tmp_path = stack.enter_context(rio.MemoryFile(ext=".json"))
+            tmp_path.write(json.dumps(item_collection.to_dict()).encode("utf-8"))
+            tmp_path.seek(0)
+
+            href = f'STACIT:"{tmp_path.name}":asset={asset_key}'
+
+            if GDALVersion.runtime() < GDALVersion.parse("3.9.1") and (
+                overlap_strategy == "USE_ALL"
+            ):
+                warnings.warn(
+                    "USE_ALL overlap strategy is only supported "
+                    "starting at GDAL Version 3.9.1. "
+                    "Using USE_MOST_RECENT instead."
+                )
+                overlap_strategy = "USE_MOST_RECENT"
+
+            profile["overlap_strategy"] = overlap_strategy
+
+            if not local._env:
+                stack.enter_context(Env.from_defaults())
+            super().__init__(href, **profile)
+
+            self.links = [
+                item.get_self_href()
+                for item in item_collection.items
+                if item.assets[asset_key].href in self.files
+            ]
+            self._env = stack
+
+        except RasterioIOError as e:
+            stack.close()
+            if str(e) == "No compatible asset found" and not infer_projection:
+                raise RasterioIOError(
+                    "No compatible asset found. "
+                    "This is likely due to missing projection information "
+                    "in the STAC Item or Asset. "
+                    "Consider setting the `infer_projection` parameter to `True` "
+                    "to infer missing projection information."
+                ) from e
+            else:
+                raise
+        except Exception:
+            stack.close()
+            raise

rio_stac_io-0.3.4/rio_stac_io/drivers/stacta.py

@@ -0,0 +1,89 @@
+import os
+import warnings
+from contextlib import ExitStack
+from tempfile import TemporaryDirectory
+from typing import Any
+
+import rasterio as rio
+from pystac import Item
+from rasterio.env import Env, local
+
+from rio_stac_io.utils import require_gdal_version
+
+
+class STACTADatasetReader(rio.DatasetReader):
+    links: list[str | None]
+
+    @require_gdal_version("3.8.2")
+    def __init__(
+        self,
+        item: Item,
+        asset_key: str,
+        zoom_level: int | None = None,
+        skip_missing_metatile: bool | None = None,
+        **profile: Any,
+    ) -> None:
+        stack = ExitStack()
+
+        if skip_missing_metatile is None:
+            skip = os.environ.get("GDAL_STACTA_SKIP_MISSING_METATILE")
+            match skip:
+                case "NO", "no":
+                    skip_missing_metatile = False
+                case _:
+                    skip_missing_metatile = True
+
+        profile["skip_missing_metatile"] = skip_missing_metatile
+
+        if skip_missing_metatile and not any(
+            [ext for ext in item.stac_extensions if "raster" in ext]
+        ):
+            warnings.warn(
+                "SKIP_MISSING_METATILE is set to True "
+                "but STAC raster extension is not used. "
+                "This will likely cause an error.",
+                UserWarning,
+            )
+
+        if zoom_level is not None:
+            for key, matrix_set in item.properties["tiles:tile_matrix_sets"].items():
+                try:
+                    matrices = matrix_set["tileMatrices"]
+                    id = "id"
+                except KeyError:
+                    matrices = matrix_set["tileMatrix"]
+                    id = "identifier"
+
+                matrix_set["tileMatrices"] = [
+                    matrix for matrix in matrices if int(matrix[id]) <= zoom_level
+                ]
+
+                max_zoom = max(
+                    [int(matrix[id]) for matrix in matrix_set["tileMatrices"]]
+                )
+
+                if not matrix_set["tileMatrices"] or max_zoom < zoom_level:
+                    raise ValueError(
+                        "Requested zoom level is not present in tile matrix set."
+                    )
+
+                item.properties["tiles:tile_matrix_sets"][key] = matrix_set
+
+        try:
+            tmp_dir = stack.enter_context(TemporaryDirectory())
+            tmp_path = f"{tmp_dir}/stacta.json"
+
+            item.save_object(dest_href=tmp_path)
+
+            href = f'STACTA:"{tmp_path}":{asset_key}'
+
+            self.links = [item.get_self_href()]
+
+            if not local._env:
+                stack.enter_context(Env.from_defaults())
+            super().__init__(href, **profile)
+            self._env = stack
+
+        except Exception:
+            stack.close()
+            raise

rio_stac_io-0.3.4/rio_stac_io/io.py

@@ -0,0 +1,332 @@
+from typing import Annotated, Any, Literal, overload
+
+import pystac
+import pystac_client
+import rasterio as rio
+from pystac import Item, ItemCollection
+from pystac_client import ItemSearch
+
+from rio_stac_io.drivers.gti import GTIDatasetReader
+from rio_stac_io.drivers.stacit import STACITDatasetReader
+from rio_stac_io.drivers.stacta import STACTADatasetReader
+
+
+@overload
+def open(
+    items: Annotated[
+        pystac.ItemCollection | pystac_client.ItemSearch,
+        "STAC Items must implement the Projection STAC extension",
+    ],
+    mode: Literal["r"] = "r",
+    *,
+    asset_key: str,
+    use_gti: Literal[False] = False,
+    merge_collections: bool = False,
+    infer_projection: bool = False,
+    max_items: int = 1000,
+    collection: str | None = None,
+    crs: str | None = None,
+    resolution: Literal["AVERAGE", "HIGHEST", "​LOWEST"] = "AVERAGE",
+    overlap_strategy: Literal[
+        "REMOVE_IF_NO_NODATA", "USE_ALL", "USE_MOST_RECENT"
+    ] = "REMOVE_IF_NO_NODATA",
+) -> STACITDatasetReader:
+    """
+    STACIT
+
+    The [GDAL StacIT driver](https://gdal.org/en/stable/drivers/raster/stacit.html)
+    accepts pystac ItemCollections or ItemSearch as input and
+    will return a rasterio Dataset, similar to a VRT.
+    This driver is used by default when using a ItemCollection or ItemSearch as input.
+
+    STAC Items must use the [STAC Projection extension](https://github.com/stac-extensions/projection),
+    providing metadata about CRS used, projected bounds and Affine transformation.
+    Items without this metadata will be ignored.
+
+    By default, STACIT will split items from different STAC collections
+    or with different projections into subdatasets.
+    You can force the driver to return a single dataset
+    by either filtering by CRS or Collections or telling it
+    to merge all collections setting `merge_collections=True`.
+
+    If you need to merge items using different projection
+    consider using the GTI driver instead.
+
+    While the StacIT driver only fully supports STAC v1.1.0
+    Items starting with GDAL 3.10.2, `rio-stac-io` will assure
+    backwards compatibility also for earlier GDAL versions.
+
+    Parameters
+    ----------
+    items : pystac.ItemCollection or pystac_client.ItemSearch
+        Input STAC Items. Items must implement the Projection STAC extension.
+    mode : Literal["r"], default "r"
+        Read-only mode.
+    asset_key : str
+        Asset to open.
+    use_gti : Literal[False], default False
+        Must be set to False to use the STACIT driver.
+    merge_collections : bool, default False
+        Combine items from multiple collections into a single dataset.
+    infer_projection : bool, default False
+        Infer projection metadata if missing.
+        This will call the file header of each asset to extract the projection metadata.
+    max_items : int, default 1000
+        Maximum number of items fetched. 0 means unlimited.
+    collection : str or None, optional
+        Name of collection to filter items.
+    crs : str or None, optional
+        Name of CRS to filter items.
+    resolution : Literal["AVERAGE", "HIGHEST", "LOWEST"], default "AVERAGE"
+        Strategy to use to determine dataset resolution.
+    overlap_strategy : Literal["REMOVE_IF_NO_NODATA", "USE_ALL", "USE_MOST_RECENT"],
+        default "REMOVE_IF_NO_NODATA"
+        Strategy to use when the ItemCollections contains overlapping items.
+
+    Returns
+    -------
+    rio.DatasetReader
+        A rasterio DatasetReader object.
+    """  # noqa: E501
+    ...
+
+
+@overload
+def open(
+    items: Annotated[
+        pystac.ItemCollection | pystac_client.ItemSearch,
+        "STAC Items must implement the Projection STAC extension",
+    ],
+    mode: Literal["r"] = "r",
+    *,
+    asset_key: str,
+    use_gti: Literal[True] = True,
+    sort_field: str | None = None,
+    sort_field_asc: bool = True,
+    filter: str | None = None,
+    resx: float | None = None,
+    resy: float | None = None,
+    srs: str | None = None,
+    minx: float | None = None,
+    miny: float | None = None,
+    maxx: float | None = None,
+    maxy: float | None = None,
+) -> GTIDatasetReader:
+    """
+    GTI
+
+    Similar to STACIT, the [GDAL GTI driver](https://gdal.org/en/stable/drivers/raster/gti.html)
+    accepts pystac ItemCollections or ItemSearch as input and will return a rasterio Dataset,
+    similar to a VRT.
+
+    The GTI driver requires GDAL version 3.10 or later
+    and GDAL must be built with (geo)parquet support.
+    In addition, rio-stac-io needs to be installed together with the `gti` extras.
+
+    Because of the extra dependencies, this driver is not the default and users
+    must opt into it by setting `use_gti=True`.
+
+    Unlike STACIT, GTI will always combine input items into a single rasterio Dataset.
+    Items in different projections will be reprojected into the projection of the first item.
+    The user can also set a different output projection by setting the `srs` argument.
+
+    Parameters
+    ----------
+    items : pystac.ItemCollection or pystac_client.ItemSearch
+        Input STAC Items. Items must implement the Projection STAC extension.
+    mode : Literal["r"], default "r"
+        Read-only mode.
+    asset_key : str
+        Asset to open.
+    use_gti : Literal[True], default True
+        Must be set to True in order to use this driver.
+    sort_field : str or None, optional
+        Name of a field to use to control the order in which tiles are composited,
+        when they overlap (z-order).
+        That field may be of type String, Integer, Integer64, Date or DateTime.
+        By default, the higher the value in that field,
+        the last the corresponding tile will be rendered in the virtual mosaic (unless
+        SORT_FIELD_ASC=NO is set).
+    sort_field_asc : bool, default True
+        Whether the values in SORT_FIELD should be sorted in ascending or descending order.
+    filter : str or None, optional
+        Value of a SQL WHERE clause, used to select a subset of the features of the index.
+    resx : float or None, optional
+        Resolution along X axis in SRS units / pixel.
+    resy : float or None, optional
+        Resolution along Y axis in SRS units / pixel.
+    srs : str or None, optional
+        Override/sets the Spatial Reference System.
+    minx : float or None, optional
+        Minimum X value for the virtual mosaic extent.
+    miny : float or None, optional
+        Minimum Y value for the virtual mosaic extent.
+    maxx : float or None, optional
+        Maximum X value for the virtual mosaic extent.
+    maxy : float or None, optional
+        Maximum Y value for the virtual mosaic extent.
+
+    Returns
+    -------
+    rio.DatasetReader
+        A rasterio DatasetReader object.
+    """  # noqa: E501
+    ...
+
+
+@overload
+def open(  # type: ignore[overload-cannot-match]  # passes on macos but not linux ¯\_(ツ)_/¯
+    items: Annotated[pystac.Item, "regular STAC Item"],
+    mode: Literal["r"] = "r",
+    *,
+    asset_key: str,
+) -> rio.DatasetReader:
+    """
+    STAC Item
+
+    A regular STAC Item can be opened directly with rasterio.
+
+    Parameters
+    ----------
+    items : pystac.Item
+        Input STAC Item. Must implement the Tiled Asset STAC extension.
+    mode : Literal["r"], default "r"
+        Read-only mode.
+    asset_key : str
+        Asset to open.
+
+    Returns
+    -------
+    rio.DatasetReader
+        A rasterio DatasetReader object.
+    """
+    ...
+
+
+@overload
+def open(  # type: ignore[overload-cannot-match]  # passes on macos but not linux ¯\_(ツ)_/¯
+    items: Annotated[pystac.Item, "uses tiled-assets STAC extension"],
+    mode: Literal["r"] = "r",
+    *,
+    asset_key: str,
+    zoom_level: int | None = None,
+    whole_metatile: bool = True,
+    skip_missing_metatile: bool = True,
+) -> STACTADatasetReader:
+    """
+    STACTA
+
+    The [GDAL StacTA driver](https://gdal.org/en/stable/drivers/raster/stacta.html)
+    accepts a single STAC item that implements the
+    [tiled-assets STAC extension](https://github.com/stac-extensions/tiled-assets/tree/main).
+    The driver is designed to open gridded data that are stored following the TMS specifications
+    (i.e., Z/X/Y file path). All data will be loaded lazily.
+
+    When using GDAL versions prior to v3.8.x, the driver expects all tiles of the Tile matrix to be present.
+    Later versions will try to use the [STAC Raster extension](https://github.com/stac-extensions/raster/tree/main)
+    metadata (if present) to infer datatype and no data value.
+    When using sparse tiles you must set `skip_missing_metatile=True`.
+
+    Parameters
+    ----------
+    items : pystac.Item
+        Input STAC Item. Must implement the Tiled Asset STAC extension.
+    mode : Literal["r"], default "r"
+        Read-only mode.
+    asset_key : str
+        Asset to open.
+    zoom_level : int or None, optional
+        Specific zoom level to open. Will default to the max zoom level specified in the tile matrix set.
+    whole_metatile : bool, default True
+        If set to True, metatiles will be entirely downloaded (into memory).
+        Otherwise, by default, if metatiles are bigger than a threshold,
+        they will be accessed in a piece-wise way.
+    skip_missing_metatile : bool, default True
+        If set to True, metatiles that are missing will be skipped without error,
+        and the corresponding area in the dataset will be filled with the nodata value or zero if there is no nodata value.
+        This setting will require the implementation of the STAC Raster Extension.
+        This setting can also be set with the GDAL_STACTA_SKIP_MISSING_METATILE configuration option.
+
+    Returns
+    -------
+    rio.DatasetReader
+        A rasterio DatasetReader object.
+    """  # noqa: E501
+    ...
+
+
+def open(
+    items: Item | ItemCollection | ItemSearch,
+    mode: Literal["r"] = "r",
+    *,
+    asset_key: str,
+    use_gti: bool = False,
+    merge_collections: bool = False,
+    infer_projection: bool = False,
+    zoom_level: int | None = None,
+    **kwargs: Any,
+) -> rio.DatasetReader:
+    """rio-stac-io accepts any pystac Item, ItemCollection or ItemSearch
+    and returns a rasterio DatasetReader.
+    Input items will be merged into a single layer,
+    similar to a VRT and served as a single rasterio Dataset.
+    If you need to read time series,
+    consider using [ODC STAC](https://github.com/opendatacube/odc-stac)
+    that will return an multi-dimensional XArray object instead.
+
+    ```python
+
+    from pystac_client import Client
+
+    import rio_stac_io as stacio
+
+    client = Client.open(...)
+    search = client.search(...)
+
+    with stacio.open(search, asset_key="data") as src:
+        data = src.read()
+
+    ```
+
+    # Drivers
+
+    rio-stac-io will determine which driver to use based on your input data.
+    By default, it will use the STACIT driver for all
+    ItemCollection and ItemSearch inputs.
+    If you set `use_gti=True`, it will use the GTI driver instead.
+    When provided with a single Item as input, it will use the
+    STACTA driver if the item uses the tiled-asset STAC extension
+    and rasterio when using a regular item.
+
+    See overloaded function signatures for details.
+
+    """
+
+    if mode != "r":
+        raise ValueError(
+            f"This is a read-only dataset. Mode `{mode}` is not supported."
+        )
+
+    if isinstance(items, Item):
+        if any([ext for ext in items.stac_extensions if "tiled-assets" in ext]):
+            return STACTADatasetReader(
+                items, asset_key, zoom_level=zoom_level, **kwargs
+            )
+        else:
+            return rio.open(items.assets[asset_key].href)
+
+    elif isinstance(items, (ItemCollection, ItemSearch)):
+        if use_gti:
+            return GTIDatasetReader(items, asset_key, **kwargs)
+
+        else:
+            return STACITDatasetReader(
+                items,
+                asset_key,
+                merge_collections=merge_collections,
+                infer_projection=infer_projection,
+                **kwargs,
+            )
+
+    else:
+        return rio.open(items, **kwargs)

rio_stac_io-0.3.4/rio_stac_io/utils.py

@@ -0,0 +1,77 @@
+from functools import wraps
+from typing import Any, Callable
+
+import rasterio as rio
+from packaging.version import parse
+from pystac import Item
+from pystac.extensions.projection import AssetProjectionExtension
+from rasterio import __gdal_version__
+from rasterio.errors import GDALVersionError
+
+
+def require_gdal_version(gdal_version: str) -> Callable:
+    def decorator(function: Callable) -> Callable:
+        @wraps(function)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            runtime = parse(__gdal_version__)
+            required = parse(gdal_version)
+
+            if not runtime >= required:
+                raise GDALVersionError(
+                    f"Selected Driver requires GDAL Version {gdal_version} or higher."
+                )
+
+            return function(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def vsi_href(href: str) -> str:
+    if href.startswith("http"):
+        href = f"/vsicurl/{href}"
+    elif href.startswith("s3://"):
+        href = href.replace("s3://", "/vsis3/")
+    elif href.startswith("gs://"):
+        href = href.replace("gs://", "/vsigs/")
+    return href
+
+
+def has_projection_metadata(properties: dict[str, Any]) -> bool:
+    """Check if all required projection metadata is present
+    GDAL requires the following fields:
+    1. proj:code or proj:wkt2 or proj:projjson (one of them filled with non-null values)
+    2. Any of the following:
+        proj:transform and proj:shape
+        proj:transform and proj:bbox
+        proj:bbox and proj:shape
+    """
+    crs_info = ["proj:code", "proj:wkt2", "proj:projjson", "proj:epsg"]
+    proj_info = [
+        ("proj:transform", "proj:shape"),
+        ("proj:transform", "proj:bbox"),
+        ("proj:bbox", "proj:shape"),
+    ]
+    if not any(key in properties for key in crs_info) and not any(
+        all(key in properties for key in pair) for pair in proj_info
+    ):
+        return False
+    return True
+
+
+def infer_projection_metadata(item: Item, asset_key: str) -> Item:
+    """Infer projection metadata in the asset's extra_fields if missing"""
+
+    if not has_projection_metadata(
+        item.assets[asset_key].extra_fields
+    ) and not has_projection_metadata(item.properties):
+        with rio.open(item.assets[asset_key].href) as src:
+            asset = AssetProjectionExtension.ext(
+                item.assets[asset_key], add_if_missing=True
+            )
+            asset.bbox = list(src.bounds)
+            asset.transform = list(src.transform)
+            asset.shape = [src.height, src.width]
+            asset.code = src.crs.to_string()
+    return item