From a05db8be269f4b9b273e67bca4da69bb3d05d37f Mon Sep 17 00:00:00 2001
From: Max Jones <14077947+maxrjones@users.noreply.github.com>
Date: Wed, 28 Jan 2026 17:54:00 -0500
Subject: [PATCH 1/2] Add user-guide example with rasterio

---
 docs/user-guide/opening-data-with-rasterio.md | 61 +++++++++++++++++++
 mkdocs.yml                                    |  1 +
 pyproject.toml                                |  5 ++
 3 files changed, 67 insertions(+)
 create mode 100644 docs/user-guide/opening-data-with-rasterio.md

diff --git a/docs/user-guide/opening-data-with-rasterio.md b/docs/user-guide/opening-data-with-rasterio.md
new file mode 100644
index 0000000..c8da8f6
--- /dev/null
+++ b/docs/user-guide/opening-data-with-rasterio.md
@@ -0,0 +1,61 @@
+# Opening Data with Rasterio
+
+This guide shows how to use `obspec-utils` readers to open cloud-hosted raster data with [rasterio](https://rasterio.readthedocs.io/).
+
+## Opening a Cloud-Hosted GeoTIFF
+
+Use [`EagerStoreReader`][obspec_utils.readers.EagerStoreReader] to provide a file-like interface that rasterio can read:
+
+```python exec="on" source="above" session="rasterio" result="code"
+import rasterio
+from obstore.store import S3Store
+from obspec_utils.readers import EagerStoreReader
+
+# Access public Arctic DEM data (no credentials needed)
+store = S3Store(
+    bucket="pgc-opendata-dems",
+    aws_region="us-west-2",
+    skip_signature=True,
+)
+
+path = "arcticdem/mosaics/v4.1/2m_dem_tiles.vrt"
+
+with EagerStoreReader(store, path) as reader:
+    with rasterio.open(reader) as src:
+        print(f"CRS: {src.crs}")
+        print(f"Bounds: {src.bounds}")
+        print(f"Shape: {src.width} x {src.height}")
+```
+
+## Using with Xarray and rioxarray
+
+For analysis workflows, combine with [rioxarray](https://corteva.github.io/rioxarray/) to load raster data as xarray datasets:
+
+```python exec="on" source="above" session="rasterio" result="code"
+import xarray as xr
+from obstore.store import S3Store
+from obspec_utils.readers import EagerStoreReader
+
+store = S3Store(
+    bucket="pgc-opendata-dems",
+    aws_region="us-west-2",
+    skip_signature=True,
+)
+
+path = "arcticdem/mosaics/v4.1/2m_dem_tiles.vrt"
+
+with EagerStoreReader(store, path) as reader:
+    ds = xr.open_dataset(reader, engine="rasterio")
+    print(ds)
+```
+
+## Choosing a Reader
+
+For raster data, the choice of reader depends on your access pattern:
+
+| Reader | Best for |
+|--------|----------|
+| [`EagerStoreReader`][obspec_utils.readers.EagerStoreReader] | Small files or when you need the entire file (metadata parsing, VRT files) |
+| [`BlockStoreReader`][obspec_utils.readers.BlockStoreReader] | Large files with sparse access patterns (reading specific tiles/windows) |
+
+For most rasterio use cases, [`EagerStoreReader`][obspec_utils.readers.EagerStoreReader] works well since rasterio typically needs to read file headers and metadata which requires random access across the file.
diff --git a/mkdocs.yml b/mkdocs.yml
index b46f595..4eb8dbe 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -16,6 +16,7 @@ nav:
   - "index.md"
   - "User Guide":
     - "Opening Data with Xarray": "user-guide/opening-data-with-xarray.md"
+    - "Opening Data with Rasterio": "user-guide/opening-data-with-rasterio.md"
     - "Finding Files on the Cloud": "user-guide/finding-files.md"
     - "Minimizing Data Transfer via Caching": "user-guide/caching-remote-data.md"
     - "Debugging Slow Data Access": "user-guide/debugging-data-access.md"
diff --git a/pyproject.toml b/pyproject.toml
index 45763f7..be99e07 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -60,6 +60,11 @@ xarray = [
   "h5py",
   "cftime",
   "scipy",
+  "rasterio",
+  "rioxarray",
+]
+dask = [
+  "dask",
 ]
 fsspec = [
   "s3fs",

From aaa208b3908f6faa84e4c3f3cb025e1836db13a3 Mon Sep 17 00:00:00 2001
From: Max Jones <14077947+maxrjones@users.noreply.github.com>
Date: Wed, 28 Jan 2026 17:56:29 -0500
Subject: [PATCH 2/2] Add to changelog

---
 docs/changelog.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/changelog.md b/docs/changelog.md
index a133c06..7752606 100644
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -15,6 +15,7 @@ This release includes the addition of globbing functionality, a rename of Parall
 - Add user guide section on globbing by @maxrjones in https://github.com/virtual-zarr/obspec-utils/pull/51
 - Add user guide section on debugging slow access by @maxrjones in https://github.com/virtual-zarr/obspec-utils/pull/53
 - Add user guide section on caching by @maxrjones in https://github.com/virtual-zarr/obspec-utils/pull/54
+- Add user guide section on rasterio by @maxrjones in https://github.com/virtual-zarr/obspec-utils/pull/56
 
 ### Bug Fixes