0
# Command Line Interface
1

2
Command-line tools for processing GeoJSON data with rasterstats functionality. These tools integrate with the rasterio plugin system and provide convenient access to zonal statistics and point queries from the shell.
3

4
## Capabilities
5

6
### CLI Commands
7

8
rasterstats provides two command-line interfaces through rasterio plugins.
9

10
```python { .api }
11
@click.command(context_settings=SETTINGS)
12
@cligj.features_in_arg
13
@click.version_option(version=version, message="%(version)s")
14
@click.option("--raster", "-r", required=True)
15
@click.option("--all-touched/--no-all-touched", default=False)
16
@click.option("--band", type=int, default=1)
17
@click.option("--categorical/--no-categorical", default=False)
18
@click.option("--indent", type=int, default=None)
19
@click.option("--info/--no-info", default=False)
20
@click.option("--nodata", type=int, default=None)
21
@click.option("--prefix", type=str, default="_")
22
@click.option("--stats", type=str, default=None)
23
@click.option("--sequence/--no-sequence", type=bool, default=False)
24
@cligj.use_rs_opt
25
def zonalstats(features, raster, all_touched, band, categorical, indent, 
26
               info, nodata, prefix, stats, sequence, use_rs):
27
    """
28
    Generate summary statistics of geospatial raster datasets based on vector features.
29
    
30
    Reads GeoJSON Features and outputs GeoJSON with additional statistical properties.
31
    The raster is specified by the required -r/--raster argument.
32
    
33
    Parameters:
34
    - features: Input GeoJSON features (from stdin or file)
35
    - raster: Path to raster file (-r/--raster, required)
36
    - all_touched: Include all touched pixels vs center-point only
37
    - band: Raster band number (default: 1)
38
    - categorical: Enable categorical analysis mode
39
    - indent: JSON indentation for output formatting
40
    - info: Enable info-level logging
41
    - nodata: Override raster nodata value
42
    - prefix: Prefix for statistic property names (default: "_")
43
    - stats: Space-delimited statistics to calculate or "all"
44
    - sequence: Output as GeoJSON sequence vs FeatureCollection
45
    - use_rs: Use record separator for sequence output
46
    """
47

48
@click.command(context_settings=SETTINGS)
49
@cligj.features_in_arg
50
@click.version_option(version=version, message="%(version)s")
51
@click.option("--raster", "-r", required=True)
52
@click.option("--band", type=int, default=1)
53
@click.option("--nodata", type=int, default=None)
54
@click.option("--indent", type=int, default=None)
55
@click.option("--interpolate", type=str, default="bilinear")
56
@click.option("--property-name", type=str, default="value")
57
@click.option("--sequence/--no-sequence", type=bool, default=False)
58
@cligj.use_rs_opt
59
def pointquery(features, raster, band, indent, nodata, interpolate,
60
               property_name, sequence, use_rs):
61
    """
62
    Query raster values at points of input GeoJSON Features.
63
    
64
    Adds raster values to feature properties and outputs as GeoJSON.
65
    For Points, uses point geometry. For other types, queries all vertices.
66
    
67
    Parameters:
68
    - features: Input GeoJSON features (from stdin or file)
69
    - raster: Path to raster file (-r/--raster, required)
70
    - band: Raster band number (default: 1)
71
    - indent: JSON indentation for output formatting
72
    - nodata: Override raster nodata value
73
    - interpolate: Interpolation method - "bilinear" or "nearest" (default: "bilinear")
74
    - property_name: Property name for query results (default: "value")
75
    - sequence: Output as GeoJSON sequence vs FeatureCollection
76
    - use_rs: Use record separator for sequence output
77
    """
78
```
79

80
### CLI Configuration
81

82
Global settings and version information for command-line tools.
83

84
```python { .api }
85
SETTINGS = {"help_option_names": ["-h", "--help"]}  # Click command settings
86
version: str  # Version string from rasterstats.__version__
87
```
88

89
## Usage Examples
90

91
### Zonal Statistics CLI
92

93
```bash
94
# Basic zonal stats from shapefile to GeoJSON
95
fio cat watersheds.shp | rio zonalstats -r elevation.tif > watershed_elevation.geojson
96

97
# Calculate specific statistics
98
fio cat polygons.shp | rio zonalstats -r temperature.tif --stats "mean max min std" > temp_stats.geojson
99

100
# All available statistics
101
fio cat zones.shp | rio zonalstats -r data.tif --stats "all" > comprehensive_stats.geojson
102

103
# Categorical analysis with prefix
104
fio cat counties.shp | rio zonalstats -r landcover.tif --categorical --prefix "lc_" > landcover_stats.geojson
105

106
# All-touched rasterization
107
fio cat thin_polygons.shp | rio zonalstats -r raster.tif --all-touched > touched_stats.geojson
108

109
# Specific band and nodata override
110
fio cat areas.shp | rio zonalstats -r multiband.tif --band 3 --nodata -999 > band3_stats.geojson
111
```
112

113
### Point Query CLI
114

115
```bash
116
# Basic point queries
117
fio cat points.shp | rio pointquery -r elevation.tif > points_with_elevation.geojson
118

119
# Nearest neighbor interpolation
120
fio cat sample_points.shp | rio pointquery -r categorical_raster.tif --interpolate nearest > point_categories.geojson
121

122
# Custom property name
123
fio cat weather_stations.shp | rio pointquery -r temperature.tif --property-name "temp_c" > stations_temp.geojson
124

125
# Query specific band
126
fio cat locations.shp | rio pointquery -r landsat.tif --band 4 --property-name "nir" > nir_values.geojson
127

128
# Line profile (queries all vertices)
129
fio cat transect_line.shp | rio pointquery -r elevation.tif --property-name "elevation" > elevation_profile.geojson
130
```
131

132
### Output Formatting Options
133

134
```bash
135
# Formatted JSON output
136
fio cat polygons.shp | rio zonalstats -r data.tif --indent 2 > formatted_output.geojson
137

138
# Sequence output (one feature per line)
139
fio cat large_dataset.shp | rio zonalstats -r raster.tif --sequence > streaming_output.geojson
140

141
# Record separator for streaming
142
fio cat huge_dataset.shp | rio zonalstats -r raster.tif --sequence --use-rs | head -n 100
143
```
144

145
### Integration with Other Tools
146

147
```bash
148
# Chain with other rasterio/fiona commands
149
fio cat input.shp | \
150
  rio zonalstats -r dem.tif --stats "mean" --prefix "elev_" | \
151
  rio pointquery -r temperature.tif --property-name "temp" | \
152
  fio collect > combined_analysis.geojson
153

154
# Filter results with jq
155
fio cat watersheds.shp | \
156
  rio zonalstats -r precipitation.tif --stats "sum" --prefix "precip_" | \
157
  jq '.features[] | select(.properties.precip_sum > 1000)' > high_precip_watersheds.geojson
158

159
# Convert to other formats
160
fio cat regions.shp | \
161
  rio zonalstats -r population.tif --stats "sum count" --prefix "pop_" | \
162
  fio load | \
163
  fio dump --format CSV > population_by_region.csv
164
```
165

166
### Debugging and Logging
167

168
```bash
169
# Enable info logging
170
fio cat polygons.shp | rio zonalstats -r raster.tif --info > stats_with_logging.geojson
171

172
# Check version
173
rio zonalstats --version
174
rio pointquery --version
175

176
# Help information
177
rio zonalstats --help
178
rio pointquery --help
179
```
180

181
### Working with stdin/stdout
182

183
```bash
184
# Direct GeoJSON input
185
echo '{"type":"Point","coordinates":[100,200]}' | \
186
  rio pointquery -r elevation.tif
187

188
# Process from URL
189
curl -s "https://example.com/data.geojson" | \
190
  rio zonalstats -r remote_raster.tif
191

192
# Pipe through multiple processing steps
193
fio cat raw_data.shp | \
194
  rio zonalstats -r raster1.tif --prefix "r1_" | \
195
  rio zonalstats -r raster2.tif --prefix "r2_" | \
196
  fio dump --format Shapefile output_with_stats.shp
197
```
198

199
### Large Dataset Processing
200

201
```bash
202
# Stream processing of large datasets
203
fio cat large_polygons.shp | \
204
  rio zonalstats -r high_res_raster.tif --sequence | \
205
  while IFS= read -r feature; do
206
    # Process each feature individually
207
    echo "$feature" | jq '.properties.mean' >> means.txt
208
  done
209

210
# Parallel processing (GNU parallel)
211
fio cat huge_dataset.shp | \
212
  parallel --pipe --block 10M \
213
    "rio zonalstats -r raster.tif --sequence" > \
214
  parallel_results.geojson
215
```
216

217
## Installation and Setup
218

219
The CLI tools are automatically available after installing rasterstats:
220

221
```bash
222
# Install rasterstats
223
pip install rasterstats
224

225
# Verify rasterio plugins are registered
226
rio --help
227
# Should show 'zonalstats' and 'pointquery' in the commands list
228

229
# Check plugin versions
230
rio zonalstats --version
231
rio pointquery --version
232
```
233

234
## Entry Points
235

236
The CLI commands are registered as rasterio plugins through setuptools entry points:
237

238
```python { .api }
239
# From pyproject.toml
240
entry_points = {
241
    "rasterio.rio_plugins": {
242
        "zonalstats": "rasterstats.cli:zonalstats",
243
        "pointquery": "rasterstats.cli:pointquery"
244
    }
245
}
246
```
247

248
## Error Handling
249

250
Common CLI error scenarios and troubleshooting:
251

252
```bash
253
# Missing raster file
254
fio cat points.shp | rio pointquery -r nonexistent.tif
255
# Error: Unable to open raster file
256

257
# Invalid statistics
258
fio cat polygons.shp | rio zonalstats -r raster.tif --stats "invalid_stat"
259
# Error: Stat 'invalid_stat' not valid
260

261
# Coordinate system mismatch (warning, but processed)
262
fio cat utm_polygons.shp | rio zonalstats -r geographic_raster.tif
263
# Warning: Coordinate systems may not match
264

265
# Invalid interpolation method
266
fio cat points.shp | rio pointquery -r raster.tif --interpolate "invalid"
267
# Error: interpolate must be nearest or bilinear
268
```