From 1d47e59826dce784989b6ad6ac87a3b65023dd9d Mon Sep 17 00:00:00 2001 From: Patryk Szczodrowski Date: Wed, 28 Oct 2026 01:46:42 +0100 Subject: [PATCH 1/2] DOC: add writing files section to getting started (#584) Add a "Writing Files" section to the getting started page covering GeoTIFF, Cloud Optimized GeoTIFF (driver="COG"), and writing to cloud storage via GDAL /vsis3/ paths or fsspec file objects, plus a short example of reading from cloud storage. Co-Authored-By: Claude Opus 5.5 --- docs/getting_started/getting_started.rst | 75 ++++++++++++++++++++++++ docs/history.rst | 2 + 2 files changed, 77 insertions(+) diff --git a/docs/getting_started/getting_started.rst b/docs/getting_started/getting_started.rst index 01d62cb0..daaaf478 100644 --- a/docs/getting_started/getting_started.rst +++ b/docs/getting_started/getting_started.rst @@ -73,6 +73,81 @@ Why use :func:`rioxarray.open_rasterio` instead of `xarray.open_rasterio`? 7. `xarray.open_rasterio` is deprecated (since v0.20.0) +Cloud storage +~~~~~~~~~~~~~~ + +Paths are passed through to rasterio/GDAL, so you can also read files directly +from HTTP(S) URLs and cloud storage (e.g. ``s3://``). See :ref:`gdal_env` for +configuring GDAL when working with cloud-stored data. + +.. code-block:: python + + import xarray + + xds = xarray.open_dataset("s3://bucket/my.tif", engine="rasterio") + + +Writing Files +------------- + +GeoTIFF +~~~~~~~~ + +Use ``rio.to_raster`` on an ``xarray.DataArray`` or ``xarray.Dataset`` to write a raster. +The driver is detected from the ``.tif``/``.tiff`` extension. Additional keyword arguments +are passed to rasterio as GDAL creation options. + +.. code-block:: python + + import rioxarray + + xds = rioxarray.open_rasterio("my.tif") + xds.rio.to_raster("out.tif") + xds.rio.to_raster("out_lzw.tif", compress="LZW") + +Cloud Optimized GeoTIFF (COG) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To write a COG, use GDAL's ``COG`` driver: + +.. code-block:: python + + xds.rio.to_raster("out_cog.tif", driver="COG") + +For more examples, including writing large rasters with ``windowed=True`` or with dask, +see :doc:`../examples/convert_to_raster`, :doc:`../examples/COG`, +and :doc:`../examples/dask_read_write`. + +Cloud storage +~~~~~~~~~~~~~~ + +To write directly to cloud storage, use a +`GDAL virtual file system `__ +path such as ``/vsis3/`` (``/vsigs/`` and ``/vsiaz/`` work similarly). +These file systems only support sequential writes, so set +``CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE`` to have GDAL write to a local temporary file +and upload it when the file is closed: + +.. code-block:: python + + import rasterio + + with rasterio.Env(CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE="YES"): + xds.rio.to_raster("/vsis3/bucket/out.tif", driver="COG") + +Alternatively, ``rio.to_raster`` accepts a file-like object, such as an ``io.BytesIO`` +buffer or a file opened with `fsspec `__ +(writing to ``s3://`` with fsspec requires `s3fs `__). +The ``driver`` must be set explicitly because it cannot be detected from a file extension. + +.. code-block:: python + + import fsspec + + with fsspec.open("s3://bucket/out.tif", "wb") as fobj: + xds.rio.to_raster(fobj, driver="COG") + + Introductory Information -------------------------- diff --git a/docs/history.rst b/docs/history.rst index c07fc71b..af19f2f0 100644 --- a/docs/history.rst +++ b/docs/history.rst @@ -10,6 +10,8 @@ Latest coordinates, which also fixes the output size of ``rio.reproject`` with ``src_geoloc_array`` (issue #848) +- DOC: Add writing files section to getting started (issue #584) + 0.23.0 ------ - ENH: Add write support for Zarr spatial and proj conventions From 9bfaea5e8eb07fe38df3d27b51b8923f18545d88 Mon Sep 17 00:00:00 2001 From: Deelay1403 Date: Sat, 31 Oct 2026 19:28:56 +0000 Subject: [PATCH 2/2] DOC: move file IO content to a separate page (#584) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Cu867eV1RAU4h7rAnN5mwf --- docs/getting_started/file_io.rst | 84 ++++++++++++++++++++++++ docs/getting_started/getting_started.rst | 76 +-------------------- docs/history.rst | 2 +- 3 files changed, 88 insertions(+), 74 deletions(-) create mode 100644 docs/getting_started/file_io.rst diff --git a/docs/getting_started/file_io.rst b/docs/getting_started/file_io.rst new file mode 100644 index 00000000..6ca96dbd --- /dev/null +++ b/docs/getting_started/file_io.rst @@ -0,0 +1,84 @@ +.. _file_io: + +File I/O +======== + +This page covers reading and writing raster files with rioxarray. For the basics of +opening files, see :ref:`getting_started`. + +Reading Files +------------- + +Cloud storage +~~~~~~~~~~~~~~ + +Paths are passed through to rasterio/GDAL, so you can also read files directly +from HTTP(S) URLs and cloud storage (e.g. ``s3://``). See :ref:`gdal_env` for +configuring GDAL when working with cloud-stored data. + +.. code-block:: python + + import xarray + + xds = xarray.open_dataset("s3://bucket/my.tif", engine="rasterio") + + +Writing Files +------------- + +GeoTIFF +~~~~~~~~ + +Use ``rio.to_raster`` on an ``xarray.DataArray`` or ``xarray.Dataset`` to write a raster. +The driver is detected from the ``.tif``/``.tiff`` extension. Additional keyword arguments +are passed to rasterio as GDAL creation options. + +.. code-block:: python + + import rioxarray + + xds = rioxarray.open_rasterio("my.tif") + xds.rio.to_raster("out.tif") + xds.rio.to_raster("out_lzw.tif", compress="LZW") + +Cloud Optimized GeoTIFF (COG) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To write a COG, use GDAL's ``COG`` driver: + +.. code-block:: python + + xds.rio.to_raster("out_cog.tif", driver="COG") + +For more examples, including writing large rasters with ``windowed=True`` or with dask, +see :doc:`../examples/convert_to_raster`, :doc:`../examples/COG`, +and :doc:`../examples/dask_read_write`. + +Cloud storage +~~~~~~~~~~~~~~ + +To write directly to cloud storage, use a +`GDAL virtual file system `__ +path such as ``/vsis3/`` (``/vsigs/`` and ``/vsiaz/`` work similarly). +These file systems only support sequential writes, so set +``CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE`` to have GDAL write to a local temporary file +and upload it when the file is closed: + +.. code-block:: python + + import rasterio + + with rasterio.Env(CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE="YES"): + xds.rio.to_raster("/vsis3/bucket/out.tif", driver="COG") + +Alternatively, ``rio.to_raster`` accepts a file-like object, such as an ``io.BytesIO`` +buffer or a file opened with `fsspec `__ +(writing to ``s3://`` with fsspec requires `s3fs `__). +The ``driver`` must be set explicitly because it cannot be detected from a file extension. + +.. code-block:: python + + import fsspec + + with fsspec.open("s3://bucket/out.tif", "wb") as fobj: + xds.rio.to_raster(fobj, driver="COG") diff --git a/docs/getting_started/getting_started.rst b/docs/getting_started/getting_started.rst index daaaf478..f234372d 100644 --- a/docs/getting_started/getting_started.rst +++ b/docs/getting_started/getting_started.rst @@ -73,79 +73,8 @@ Why use :func:`rioxarray.open_rasterio` instead of `xarray.open_rasterio`? 7. `xarray.open_rasterio` is deprecated (since v0.20.0) -Cloud storage -~~~~~~~~~~~~~~ - -Paths are passed through to rasterio/GDAL, so you can also read files directly -from HTTP(S) URLs and cloud storage (e.g. ``s3://``). See :ref:`gdal_env` for -configuring GDAL when working with cloud-stored data. - -.. code-block:: python - - import xarray - - xds = xarray.open_dataset("s3://bucket/my.tif", engine="rasterio") - - -Writing Files -------------- - -GeoTIFF -~~~~~~~~ - -Use ``rio.to_raster`` on an ``xarray.DataArray`` or ``xarray.Dataset`` to write a raster. -The driver is detected from the ``.tif``/``.tiff`` extension. Additional keyword arguments -are passed to rasterio as GDAL creation options. - -.. code-block:: python - - import rioxarray - - xds = rioxarray.open_rasterio("my.tif") - xds.rio.to_raster("out.tif") - xds.rio.to_raster("out_lzw.tif", compress="LZW") - -Cloud Optimized GeoTIFF (COG) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To write a COG, use GDAL's ``COG`` driver: - -.. code-block:: python - - xds.rio.to_raster("out_cog.tif", driver="COG") - -For more examples, including writing large rasters with ``windowed=True`` or with dask, -see :doc:`../examples/convert_to_raster`, :doc:`../examples/COG`, -and :doc:`../examples/dask_read_write`. - -Cloud storage -~~~~~~~~~~~~~~ - -To write directly to cloud storage, use a -`GDAL virtual file system `__ -path such as ``/vsis3/`` (``/vsigs/`` and ``/vsiaz/`` work similarly). -These file systems only support sequential writes, so set -``CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE`` to have GDAL write to a local temporary file -and upload it when the file is closed: - -.. code-block:: python - - import rasterio - - with rasterio.Env(CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE="YES"): - xds.rio.to_raster("/vsis3/bucket/out.tif", driver="COG") - -Alternatively, ``rio.to_raster`` accepts a file-like object, such as an ``io.BytesIO`` -buffer or a file opened with `fsspec `__ -(writing to ``s3://`` with fsspec requires `s3fs `__). -The ``driver`` must be set explicitly because it cannot be detected from a file extension. - -.. code-block:: python - - import fsspec - - with fsspec.open("s3://bucket/out.tif", "wb") as fobj: - xds.rio.to_raster(fobj, driver="COG") +See :ref:`file_io` for reading from cloud storage and for writing files +(GeoTIFF, Cloud Optimized GeoTIFF, and cloud storage). Introductory Information @@ -155,6 +84,7 @@ Introductory Information :maxdepth: 1 switching_from_rasterio + file_io crs_management.ipynb nodata_management.ipynb manage_information_loss.ipynb diff --git a/docs/history.rst b/docs/history.rst index af19f2f0..7509a949 100644 --- a/docs/history.rst +++ b/docs/history.rst @@ -10,7 +10,7 @@ Latest coordinates, which also fixes the output size of ``rio.reproject`` with ``src_geoloc_array`` (issue #848) -- DOC: Add writing files section to getting started (issue #584) +- DOC: Add file I/O page with writing files section (issue #584) 0.23.0 ------