0
# rioxarray
1

2
A geospatial extension for xarray that enables powerful raster data manipulation and analysis through integration with rasterio. rioxarray provides coordinate reference system (CRS) transformations, reprojection operations, clipping and masking of raster data, and seamless integration with the scientific Python ecosystem.
3

4
## Package Information
5

6
- **Package Name**: rioxarray
7
- **Language**: Python
8
- **Installation**: `pip install rioxarray`
9

10
## Core Imports
11

12
```python
13
import rioxarray
14
```
15

16
The package automatically registers the `.rio` accessor when imported:
17

18
```python
19
import rioxarray  # Registers the .rio accessor
20
import xarray as xr
21

22
# Now .rio is available on all xarray objects
23
da = xr.open_dataarray('file.nc')
24
da.rio.crs  # Access rioxarray functionality
25
```
26

27
For merge functionality:
28

29
```python
30
from rioxarray.merge import merge_arrays, merge_datasets
31
```
32

33
## Basic Usage
34

35
```python
36
import rioxarray
37
import xarray as xr
38

39
# Open a raster file directly
40
da = rioxarray.open_rasterio('path/to/raster.tif')
41

42
# Or use with existing xarray objects
43
ds = xr.open_dataset('file.nc')
44
# Access geospatial functionality via .rio accessor
45
print(ds.rio.crs)
46

47
# Reproject to a new coordinate system
48
reprojected = da.rio.reproject('EPSG:4326')
49

50
# Clip to a bounding box
51
clipped = da.rio.clip_box(minx=-10, miny=40, maxx=10, maxy=60)
52

53
# Set coordinate reference system
54
da_with_crs = da.rio.set_crs('EPSG:3857')
55

56
# Save to raster format
57
da.rio.to_raster('output.tif')
58

59
# Merge multiple raster files
60
from rioxarray.merge import merge_arrays
61
da1 = rioxarray.open_rasterio('tile1.tif')
62
da2 = rioxarray.open_rasterio('tile2.tif')
63
merged = merge_arrays([da1, da2])
64
```
65

66
## Architecture
67

68
rioxarray extends xarray through the accessor pattern, providing geospatial capabilities without modifying xarray's core functionality:
69

70
- **Accessor Pattern**: All geospatial functionality available via `.rio` accessor on DataArrays and Datasets
71
- **Backend Integration**: rioxarray provides an xarray backend for seamless file opening
72
- **Type-Specific Functionality**: Different capabilities for DataArrays vs Datasets
73
- **Rasterio Integration**: Leverages rasterio for all geospatial operations and file I/O
74

75
## Capabilities
76

77
### File I/O Operations
78

79
Reading and writing geospatial raster data with comprehensive parameter support for chunking, caching, coordinate parsing, and format-specific options.
80

81
```python { .api }
82
def open_rasterio(
83
    filename: Union[str, os.PathLike, rasterio.io.DatasetReader, rasterio.vrt.WarpedVRT],
84
    *,
85
    parse_coordinates: Optional[bool] = None,
86
    chunks: Optional[Union[int, tuple, dict]] = None,
87
    cache: Optional[bool] = None,
88
    lock: Optional[Any] = None,
89
    masked: bool = False,
90
    mask_and_scale: bool = False,
91
    variable: Optional[Union[str, list[str], tuple[str, ...]]] = None,
92
    group: Optional[Union[str, list[str], tuple[str, ...]]] = None,
93
    default_name: Optional[str] = None,
94
    decode_times: bool = True,
95
    decode_timedelta: Optional[bool] = None,
96
    band_as_variable: bool = False,
97
    **open_kwargs
98
) -> Union[xarray.Dataset, xarray.DataArray, list[xarray.Dataset]]: ...
99
```
100

101
[I/O Operations](./io-operations.md)
102

103
### Coordinate Reference Systems
104

105
Comprehensive CRS management including setting, transforming, and reprojecting coordinate systems with support for various CRS formats and automatic UTM zone estimation.
106

107
```python { .api }
108
# Properties
109
@property
110
def crs: Optional[rasterio.crs.CRS]: ...
111

112
# Methods  
113
def set_crs(self, crs: Any, allow_override: bool = False, inplace: bool = False): ...
114
def estimate_utm_crs(self, datum_name: str = "WGS 84"): ...
115
def write_crs(self, crs: Any = None, grid_mapping_name: Optional[str] = None, inplace: bool = False): ...
116
```
117

118
[Coordinate Systems](./coordinate-systems.md)
119

120
### Spatial Operations
121

122
Clipping, reprojection, padding, and geometric operations on raster data with support for vector geometries, bounding boxes, and pixel-based operations.
123

124
```python { .api }
125
def reproject(
126
    self, dst_crs: Any, *, resolution: Optional[Union[float, tuple[float, float]]] = None,
127
    shape: Optional[tuple[int, int]] = None, transform: Optional[rasterio.Affine] = None,
128
    resampling: rasterio.enums.Resampling = rasterio.enums.Resampling.nearest, **kwargs
129
): ...
130

131
def clip(self, geometries: Any, crs: Optional[Any] = None, all_touched: bool = False, drop: bool = True, invert: bool = False, from_disk: bool = False): ...
132
def clip_box(self, minx: float, miny: float, maxx: float, maxy: float, crs: Optional[Any] = None, auto_expand: bool = False, auto_expand_limit: int = 3): ...
133
```
134

135
[Spatial Operations](./spatial-operations.md)
136

137
### Data Management
138

139
NoData value handling, attribute and encoding management, and data merging operations for combining multiple raster datasets.
140

141
```python { .api }
142
# NoData handling
143
@property  
144
def nodata: Any: ...
145
def set_nodata(self, nodata: Any, inplace: bool = False): ...
146

147
# Attribute management
148
def set_attrs(self, inplace: bool = False, **attrs): ...
149
def update_attrs(self, inplace: bool = False, **attrs): ...
150

151
# Merging
152
def merge_arrays(dataarrays: Sequence[xarray.DataArray], *, bounds: Optional[tuple] = None, res: Optional[tuple] = None, nodata: Optional[float] = None, precision: Optional[float] = None, method: Union[str, Callable, None] = None, crs: Optional[rasterio.crs.CRS] = None, parse_coordinates: bool = True) -> xarray.DataArray: ...
153

154
def merge_datasets(datasets: Sequence[xarray.Dataset], *, bounds: Optional[tuple] = None, res: Optional[tuple] = None, nodata: Optional[float] = None, precision: Optional[float] = None, method: Union[str, Callable, None] = None, crs: Optional[rasterio.crs.CRS] = None) -> xarray.Dataset: ...
155
```
156

157
[Data Management](./data-management.md)
158

159
### Configuration and Utilities
160

161
Global configuration options, version information, exception handling, and utility functions for CRS conversion and coordinate management.
162

163
```python { .api }
164
def set_options(**kwargs): ...
165
def show_versions(): ...
166

167
# Exception hierarchy
168
class RioXarrayError(Exception): ...
169
class NoDataInBounds(RioXarrayError): ...
170
class MissingSpatialDimensionError(RioXarrayError): ...
171
class MissingCRS(RioXarrayError): ...
172
```
173

174
[Configuration and Utilities](./config-utilities.md)
175

176
## Types
177

178
```python { .api }
179
# Union types for file inputs
180
FileInput = Union[str, os.PathLike, rasterio.io.DatasetReader, rasterio.vrt.WarpedVRT]
181

182
# CRS input types
183
CRSInput = Union[rasterio.crs.CRS, str, dict, int]
184

185
# Geometry input types  
186
GeometryInput = Union[dict, Any]  # GeoJSON-like dict or geometry objects
187

188
# Sequence types
189
Sequence = collections.abc.Sequence
190
Callable = collections.abc.Callable
191

192
# Resampling options from rasterio
193
Resampling = rasterio.enums.Resampling
194
```