0
# Rasterio
1

2
Rasterio provides fast and direct raster I/O for use with NumPy and SciPy. Built on top of GDAL, it offers efficient raster I/O operations, geospatial transformations, coordinate reference system management, and windowed reading/writing capabilities for handling large datasets.
3

4
## Package Information
5

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

10
## Core Imports
11

12
```python
13
import rasterio
14
from rasterio import open
15
```
16

17
For specific functionality:
18

19
```python
20
from rasterio.crs import CRS
21
from rasterio.warp import reproject
22
from rasterio.transform import from_bounds
23
from rasterio.windows import Window
24
```
25

26
## Basic Usage
27

28
```python
29
import rasterio
30
import numpy as np
31

32
# Open and read a raster file
33
with rasterio.open('example.tif') as dataset:
34
    # Read the full raster
35
    data = dataset.read()
36
    
37
    # Get dataset metadata
38
    print(f"Shape: {data.shape}")
39
    print(f"CRS: {dataset.crs}")
40
    print(f"Transform: {dataset.transform}")
41
    print(f"Bounds: {dataset.bounds}")
42
    
43
    # Read a specific band
44
    band1 = dataset.read(1)
45
    
46
    # Read a windowed subset
47
    from rasterio.windows import Window
48
    window = Window(0, 0, 512, 512)  # col_off, row_off, width, height
49
    subset = dataset.read(1, window=window)
50

51
# Create and write a new raster
52
profile = {
53
    'driver': 'GTiff',
54
    'dtype': 'float32',
55
    'nodata': -9999,
56
    'width': 100,
57
    'height': 100,
58
    'count': 1,
59
    'crs': 'EPSG:4326',
60
    'transform': rasterio.transform.from_bounds(-180, -90, 180, 90, 100, 100)
61
}
62

63
with rasterio.open('output.tif', 'w', **profile) as dst:
64
    # Create sample data
65
    data = np.random.rand(100, 100).astype('float32')
66
    dst.write(data, 1)
67
```
68

69
## Architecture
70

71
Rasterio is built around several key components:
72

73
- **Dataset Objects**: `DatasetReader` and `DatasetWriter` provide file I/O capabilities
74
- **Coordinate Systems**: `CRS` class handles coordinate reference system transformations
75
- **Windowing**: `Window` class enables efficient partial reading of large rasters
76
- **Transformations**: Affine transformations map pixel coordinates to geographic coordinates
77
- **Processing**: Warping, masking, merging, and feature extraction capabilities
78

79
## Capabilities
80

81
### Dataset I/O
82

83
Core functionality for opening, reading, and writing raster datasets. Supports numerous formats through GDAL including GeoTIFF, NetCDF, HDF5, and many others.
84

85
```python { .api }
86
def open(fp, mode='r', driver=None, **kwargs): ...
87
def copy(src_path, dst_path, **kwargs): ...
88
def band(ds, bidx): ...
89
def pad(array, transform, pad_width, mode=None, **kwargs): ...
90
```
91

92
[Dataset I/O](./dataset-io.md)
93

94
### Coordinate Reference Systems
95

96
Comprehensive coordinate reference system support including EPSG codes, PROJ4 strings, and WKT definitions. Handles CRS transformations and validation.
97

98
```python { .api }
99
class CRS:
100
    def __init__(self, initialdata=None, **kwargs): ...
101
    @classmethod
102
    def from_epsg(cls, code): ...
103
    @classmethod
104
    def from_proj4(cls, proj4): ...
105
    def to_epsg(self): ...
106
    def to_proj4(self): ...
107
```
108

109
[Coordinate Reference Systems](./crs.md)
110

111
### Geometric Transformations
112

113
Affine transformations for converting between pixel and geographic coordinates. Supports creating transforms from bounds, origins, and ground control points.
114

115
```python { .api }
116
def from_bounds(west, south, east, north, width, height): ...
117
def from_origin(west, north, xsize, ysize): ...
118
def xy(transform, rows, cols, **kwargs): ...
119
def rowcol(transform, xs, ys, **kwargs): ...
120
```
121

122
[Transformations](./transformations.md)
123

124
### Windowing Operations
125

126
Efficient reading and writing of rectangular subsets of raster data. Supports coordinate-based and index-based windowing with geometric operations.
127

128
```python { .api }
129
class Window:
130
    def __init__(self, col_off, row_off, width, height): ...
131

132
def from_bounds(left, bottom, right, top, transform, **kwargs): ...
133
def bounds(window, transform): ...
134
def union(*windows): ...
135
def intersection(*windows): ...
136
```
137

138
[Windowing](./windowing.md)
139

140
### Raster Processing
141

142
Advanced processing operations including reprojection, masking, merging, and resampling with support for various algorithms and coordinate systems.
143

144
```python { .api }
145
def reproject(source, destination, **kwargs): ...
146
def mask(dataset, shapes, **kwargs): ...
147
def merge(datasets, **kwargs): ...
148
```
149

150
[Raster Processing](./processing.md)
151

152
### Feature Operations
153

154
Conversion between raster and vector data including shape extraction, geometry rasterization, and spatial analysis operations.
155

156
```python { .api }
157
def shapes(image, **kwargs): ...
158
def rasterize(shapes, **kwargs): ...
159
def geometry_mask(geometries, **kwargs): ...
160
```
161

162
[Feature Operations](./features.md)
163

164
### Data Types and Enums
165

166
Comprehensive data type support with validation and conversion utilities. Includes enumerations for resampling algorithms and color interpretation.
167

168
```python { .api }
169
# Data types
170
uint8: numpy.dtype
171
int16: numpy.dtype
172
float32: numpy.dtype
173
float64: numpy.dtype
174

175
# Enumerations
176
class Resampling(Enum): ...
177
class ColorInterp(Enum): ...
178
```
179

180
[Data Types](./data-types.md)
181

182
### Command Line Interface
183

184
Complete command-line interface with 23+ subcommands for raster operations including format conversion, reprojection, masking, and analysis.
185

186
```bash
187
rio info input.tif
188
rio warp input.tif output.tif --dst-crs EPSG:3857
189
rio merge *.tif merged.tif
190
```
191

192
[Command Line Interface](./cli.md)
193

194
## Common Data Types
195

196
```python { .api }
197
# Core classes
198
class DatasetReader: ...
199
class DatasetWriter: ...
200
class CRS: ...
201
class Window: ...
202

203
# Transformation matrix
204
class Affine: ...
205

206
# Coordinate bounds
207
class BoundingBox:
208
    left: float
209
    bottom: float
210
    right: float
211
    top: float
212

213
# Profile dictionary structure
214
Profile = dict[str, Any]  # Contains driver, dtype, nodata, width, height, count, crs, transform
215
```
216

217
## Error Handling
218

219
Rasterio provides specific exception types for different error conditions:
220

221
```python { .api }
222
# Core exceptions
223
class RasterioError(Exception): ...
224
class RasterioIOError(RasterioError, OSError): ...
225
class RasterioDeprecationWarning(FutureWarning): ...
226

227
# Specific error types
228
class InvalidArrayError(RasterioError): ...
229
class WindowError(RasterioError): ...
230
class WindowEvaluationError(ValueError): ...
231
class CRSError(ValueError): ...
232
class TransformError(RasterioError): ...
233
class PathError(RasterioError): ...
234
class EnvError(RasterioError): ...
235
class DriverCapabilityError(RasterioError, ValueError): ...
236
class DriverRegistrationError(ValueError): ...
237
class UnsupportedOperation(RasterioError): ...
238
class DatasetAttributeError(RasterioError, NotImplementedError): ...
239
class ResamplingAlgorithmError(RasterioError): ...
240
class WarpOperationError(RasterioError): ...
241
class WarpOptionsError(RasterioError): ...
242
class WarpedVRTError(RasterioError): ...
243
class StatisticsError(RasterioError): ...
244
class MergeError(RasterioError): ...
245
class StackError(RasterioError): ...
246
class RPCError(ValueError): ...
247

248
# Warning types
249
class NodataShadowWarning(UserWarning): ...
250
class NotGeoreferencedWarning(UserWarning): ...
251
class TransformWarning(UserWarning): ...
252
class ShapeSkipWarning(UserWarning): ...
253
class BandOverviewError(UserWarning): ...
254
```