0
# Data Types
1

2
Comprehensive data type support with validation and conversion utilities. Rasterio provides standardized data types for raster operations and includes enumerations for algorithms and metadata.
3

4
## Capabilities
5

6
### Supported Data Types
7

8
Rasterio supports a comprehensive set of numeric data types compatible with NumPy and GDAL:
9

10
```python { .api }
11
# Boolean type
12
bool_: numpy.dtype     # Boolean values (True/False)
13

14
# Unsigned integer types  
15
ubyte: numpy.dtype     # Unsigned 8-bit integer (0-255)
16
uint8: numpy.dtype     # Unsigned 8-bit integer (0-255) 
17
uint16: numpy.dtype    # Unsigned 16-bit integer (0-65535)
18
uint32: numpy.dtype    # Unsigned 32-bit integer (0-4294967295)
19
uint64: numpy.dtype    # Unsigned 64-bit integer
20

21
# Signed integer types
22
int8: numpy.dtype      # Signed 8-bit integer (-128 to 127)
23
int16: numpy.dtype     # Signed 16-bit integer (-32768 to 32767)
24
int32: numpy.dtype     # Signed 32-bit integer (-2147483648 to 2147483647)
25
int64: numpy.dtype     # Signed 64-bit integer
26

27
# Floating point types
28
float32: numpy.dtype   # 32-bit floating point (single precision)
29
float64: numpy.dtype   # 64-bit floating point (double precision)
30

31
# Complex number types
32
complex_: numpy.dtype   # Complex number type
33
complex64: numpy.dtype  # 64-bit complex (32-bit real + 32-bit imaginary)
34
complex128: numpy.dtype # 128-bit complex (64-bit real + 64-bit imaginary)
35
```
36

37
Usage examples:
38

39
```python
40
import rasterio.dtypes
41
import numpy as np
42

43
# Access rasterio data types
44
print(rasterio.dtypes.uint8)    # <class 'numpy.uint8'>
45
print(rasterio.dtypes.float32)  # <class 'numpy.float32'>
46

47
# Create arrays with specific types
48
data_uint8 = np.array([0, 127, 255], dtype=rasterio.dtypes.uint8)
49
data_float32 = np.array([0.0, 127.5, 255.9], dtype=rasterio.dtypes.float32)
50

51
# Use in dataset creation
52
profile = {
53
    'driver': 'GTiff',
54
    'dtype': rasterio.dtypes.uint16,  # Use rasterio data type
55
    'width': 100,
56
    'height': 100,
57
    'count': 1,
58
    'crs': 'EPSG:4326'
59
}
60
```
61

62
### Data Type Validation
63

64
Functions for validating and working with data types in raster operations:
65

66
```python { .api }
67
def check_dtype(dt):
68
    """
69
    Validate data type compatibility with GDAL.
70
    
71
    Parameters:
72
    - dt (numpy.dtype or str): Data type to check
73
    
74
    Returns:
75
    bool: True if compatible with GDAL
76
    """
77

78
def get_minimum_dtype(values, have_nodata=False):
79
    """
80
    Determine minimum required data type for values.
81
    
82
    Parameters:
83
    - values (array-like): Input values to analyze
84
    - have_nodata (bool): Whether nodata value needs to be represented
85
    
86
    Returns:
87
    numpy.dtype: Minimum data type that can represent all values
88
    """
89

90
def validate_dtype(dataset, dtype):
91
    """
92
    Validate data type for dataset operations.
93
    
94
    Parameters:
95
    - dataset (DatasetReader): Input dataset
96
    - dtype (numpy.dtype): Target data type
97
    
98
    Returns:
99
    bool: True if conversion is valid
100
    
101
    Raises:
102
    ValueError: If dtype is incompatible
103
    """
104
```
105

106
Usage examples:
107

108
```python
109
from rasterio.dtypes import check_dtype, get_minimum_dtype, validate_dtype
110
import numpy as np
111

112
# Check data type compatibility
113
print(check_dtype('uint8'))     # True
114
print(check_dtype('float32'))   # True  
115
print(check_dtype('object'))    # False (not supported by GDAL)
116

117
# Determine minimum data type needed
118
values = [0, 127, 255]
119
min_dtype = get_minimum_dtype(values)
120
print(min_dtype)  # uint8
121

122
# With negative values
123
values_signed = [-100, 0, 127]
124
min_dtype_signed = get_minimum_dtype(values_signed)
125
print(min_dtype_signed)  # int16
126

127
# With nodata consideration
128
values_with_nodata = [0, 127, 254]  # Need to reserve 255 for nodata
129
min_dtype_nodata = get_minimum_dtype(values_with_nodata, have_nodata=True)
130
print(min_dtype_nodata)  # uint8 (255 available for nodata)
131

132
# Validate conversion
133
with rasterio.open('input.tif') as dataset:
134
    # Check if we can convert to different data type
135
    can_convert_uint8 = validate_dtype(dataset, 'uint8')
136
    can_convert_float32 = validate_dtype(dataset, 'float32')
137
```
138

139
### Resampling Algorithms
140

141
Enumeration of resampling algorithms available for raster operations:
142

143
```python { .api }
144
class Resampling(Enum):
145
    """Resampling algorithms for raster operations."""
146
    
147
    nearest = 'nearest'           # Nearest neighbor interpolation
148
    bilinear = 'bilinear'         # Bilinear interpolation  
149
    cubic = 'cubic'               # Cubic convolution
150
    cubic_spline = 'cubic_spline' # Cubic spline interpolation
151
    lanczos = 'lanczos'           # Lanczos windowed sinc interpolation
152
    average = 'average'           # Average of contributing pixels
153
    mode = 'mode'                 # Most common value (mode)
154
    gauss = 'gauss'               # Gaussian kernel
155
    max = 'max'                   # Maximum value
156
    min = 'min'                   # Minimum value
157
    med = 'med'                   # Median value
158
    q1 = 'q1'                     # First quartile (25th percentile)
159
    q3 = 'q3'                     # Third quartile (75th percentile)
160
    sum = 'sum'                   # Sum of values
161
    rms = 'rms'                   # Root mean square
162
```
163

164
### Color Interpretation
165

166
Enumeration for color interpretation of raster bands:
167

168
```python { .api }
169
class ColorInterp(Enum):
170
    """Color interpretation for raster bands."""
171
    
172
    undefined = 'undefined'       # Undefined interpretation
173
    gray = 'gray'                 # Grayscale
174
    palette = 'palette'           # Palette/colormapped  
175
    red = 'red'                   # Red band of RGB
176
    green = 'green'               # Green band of RGB
177
    blue = 'blue'                 # Blue band of RGB
178
    alpha = 'alpha'               # Alpha/transparency band
179
    hue = 'hue'                   # Hue band of HSV
180
    saturation = 'saturation'     # Saturation band of HSV
181
    lightness = 'lightness'       # Lightness band of HSL
182
    cyan = 'cyan'                 # Cyan band of CMYK
183
    magenta = 'magenta'           # Magenta band of CMYK
184
    yellow = 'yellow'             # Yellow band of CMYK
185
    black = 'black'               # Black band of CMYK
186
```
187

188
### Mask Flags
189

190
Enumeration for mask flag values indicating pixel validity:
191

192
```python { .api }
193
class MaskFlags(Enum):
194
    """Mask flag values for pixel validity."""
195
    
196
    all_valid = 'all_valid'       # All pixels valid
197
    per_dataset = 'per_dataset'   # Per-dataset mask
198
    alpha = 'alpha'               # Alpha band mask
199
    nodata = 'nodata'             # NoData mask
200
```
201

202
### Photometric Interpretation
203

204
Enumeration for photometric interpretation of imagery:
205

206
```python { .api }
207
class PhotometricInterp(Enum):
208
    """Photometric interpretation values."""
209
    
210
    miniswhite = 'miniswhite'     # Minimum value is white
211
    minisblack = 'minisblack'     # Minimum value is black  
212
    rgb = 'rgb'                   # RGB color model
213
    palette = 'palette'           # Palette color model
214
    mask = 'mask'                 # Transparency mask
215
    separated = 'separated'       # Color separations (CMYK)
216
    ycbcr = 'ycbcr'              # YCbCr color model
217
    cielab = 'cielab'            # CIE L*a*b* color model
218
    icclab = 'icclab'            # ICC L*a*b* color model
219
    itulab = 'itulab'            # ITU L*a*b* color model
220
```
221

222
Usage examples for enumerations:
223

224
```python
225
from rasterio.enums import Resampling, ColorInterp, MaskFlags, PhotometricInterp
226

227
# Use resampling in operations
228
with rasterio.open('input.tif') as src:
229
    # Read with resampling
230
    data = src.read(
231
        out_shape=(src.count, 500, 500),  # Resample to 500x500
232
        resampling=Resampling.cubic       # High-quality interpolation
233
    )
234

235
# Set color interpretation when writing  
236
profile = {
237
    'driver': 'GTiff',
238
    'dtype': 'uint8',
239
    'width': 100, 'height': 100, 'count': 3,
240
    'photometric': PhotometricInterp.rgb.value
241
}
242

243
with rasterio.open('rgb_image.tif', 'w', **profile) as dst:
244
    # Set individual band color interpretation
245
    dst.colorinterp = [ColorInterp.red, ColorInterp.green, ColorInterp.blue]
246
    
247
    # Write RGB data
248
    dst.write(red_band, 1)
249
    dst.write(green_band, 2)  
250
    dst.write(blue_band, 3)
251

252
# Check mask flags
253
with rasterio.open('dataset.tif') as src:
254
    mask_flags = src.mask_flag_enums
255
    has_nodata = MaskFlags.nodata in mask_flags
256
    has_alpha = MaskFlags.alpha in mask_flags
257
```
258

259
### Data Type Conversion Examples
260

261
Common patterns for working with different data types:
262

263
```python
264
# Convert between data types safely
265
def safe_convert(data, target_dtype, nodata_in=None, nodata_out=None):
266
    """Safely convert array to target data type."""
267
    
268
    # Get data type info
269
    target_info = np.iinfo(target_dtype) if np.issubdtype(target_dtype, np.integer) else np.finfo(target_dtype)
270
    
271
    # Handle nodata values
272
    if nodata_in is not None:
273
        valid_mask = data != nodata_in
274
        data = data[valid_mask]
275
    
276
    # Clip to target range
277
    if hasattr(target_info, 'min') and hasattr(target_info, 'max'):
278
        data_clipped = np.clip(data, target_info.min, target_info.max)
279
    else:
280
        data_clipped = data
281
    
282
    # Convert
283
    converted = data_clipped.astype(target_dtype)
284
    
285
    # Restore nodata
286
    if nodata_in is not None and nodata_out is not None:
287
        result = np.full_like(converted, nodata_out, dtype=target_dtype)
288
        result[valid_mask] = converted
289
        return result
290
    
291
    return converted
292

293
# Scale data to different ranges
294
def scale_to_uint8(data, min_val=None, max_val=None):
295
    """Scale data to 0-255 range for uint8."""
296
    
297
    if min_val is None:
298
        min_val = data.min()
299
    if max_val is None:
300
        max_val = data.max()
301
    
302
    # Scale to 0-1
303
    scaled = (data - min_val) / (max_val - min_val)
304
    
305
    # Scale to 0-255 and convert
306
    return (scaled * 255).astype(np.uint8)
307

308
# Example usage
309
with rasterio.open('float_data.tif') as src:
310
    float_data = src.read(1)
311
    
312
    # Convert to uint8 for visualization
313
    uint8_data = scale_to_uint8(float_data)
314
    
315
    # Save as uint8
316
    profile = src.profile.copy()
317
    profile['dtype'] = 'uint8'
318
    
319
    with rasterio.open('uint8_output.tif', 'w', **profile) as dst:
320
        dst.write(uint8_data, 1)
321
```