Command Line Interface
======================
Rasterio's new command line interface is a program named "rio".
.. code-block:: console
$ rio
Usage: rio [OPTIONS] COMMAND [ARGS]...
Rasterio command line interface.
Options:
-v, --verbose Increase verbosity.
-q, --quiet Decrease verbosity.
--version Show the version and exit.
--help Show this message and exit.
Commands:
bounds Write bounding boxes to stdout as GeoJSON.
env Print information about the rio environment.
info Print information about a data file.
insp Open a data file and start an interpreter.
merge Merge a stack of raster datasets.
rasterize Rasterize features.
sample Sample a dataset.
shapes Write the shapes of features.
stack Stack a number of bands into a multiband dataset.
It is developed using `Click `__.
bounds
------
New in 0.10.
The bounds command writes the bounding boxes of raster datasets to GeoJSON for
use with, e.g., `geojsonio-cli `__.
.. code-block:: console
$ rio bounds tests/data/RGB.byte.tif --indent 2
{
"features": [
{
"geometry": {
"coordinates": [
[
[
-78.898133,
23.564991
],
[
-76.599438,
23.564991
],
[
-76.599438,
25.550874
],
[
-78.898133,
25.550874
],
[
-78.898133,
23.564991
]
]
],
"type": "Polygon"
},
"properties": {
"id": "0",
"title": "tests/data/RGB.byte.tif"
},
"type": "Feature"
}
],
"type": "FeatureCollection"
}
Shoot the GeoJSON into a Leaflet map using geojsonio-cli by typing
``rio bounds tests/data/RGB.byte.tif | geojsonio``.
info
----
Rio's info command prints structured information about a dataset.
.. code-block:: console
$ rio info tests/data/RGB.byte.tif --indent 2
{
"count": 3,
"crs": "EPSG:32618",
"dtype": "uint8",
"driver": "GTiff",
"bounds": [
101985.0,
2611485.0,
339315.0,
2826915.0
],
"lnglat": [
-77.75790625255473,
24.561583285327067
],
"height": 718,
"width": 791,
"shape": [
718,
791
],
"res": [
300.0379266750948,
300.041782729805
],
"nodata": 0.0
}
More information, such as band statistics, can be had using the `--verbose`
option.
.. code-block:: console
$ rio info tests/data/RGB.byte.tif --indent 2
{
"count": 3,
"crs": "EPSG:32618",
"stats": [
{
"max": 255.0,
"mean": 44.434478650699106,
"min": 1.0
},
{
"max": 255.0,
"mean": 66.02203484105824,
"min": 1.0
},
{
"max": 255.0,
"mean": 71.39316199120559,
"min": 1.0
}
],
"dtype": "uint8",
"driver": "GTiff",
"bounds": [
101985.0,
2611485.0,
339315.0,
2826915.0
],
"lnglat": [
-77.75790625255473,
24.561583285327067
],
"height": 718,
"width": 791,
"shape": [
718,
791
],
"res": [
300.0379266750948,
300.041782729805
],
"nodata": 0.0
}
insp
----
The insp command opens a dataset and an interpreter.
.. code-block:: console
$ rio insp tests/data/RGB.byte.tif
Rasterio 0.18 Interactive Inspector (Python 2.7.9)
Type "src.meta", "src.read_band(1)", or "help(src)" for more information.
>>> print src.name
tests/data/RGB.byte.tif
>>> print src.bounds
BoundingBox(left=101985.0, bottom=2611485.0, right=339315.0, top=2826915.0)
merge
-----
The merge command can be used to flatten a stack of identically structured
datasets.
.. code-block:: console
$ rio merge rasterio/tests/data/R*.tif merged.tif
rasterize
---------
New in 0.18.
The rasterize command rasterizes GeoJSON features into a new or existing
raster.
.. code-block:: console
$ rio rasterize test.tif --res 0.0167 < input.geojson
The resulting file will have an upper left coordinate determined by the bounds
of the GeoJSON (in EPSG:4326, which is the default), with a
pixel size of approximately 30 arc seconds. Pixels whose center is within the
polygon or that are selected by brezenhams line algorithm will be burned in
with a default value of 1.
It is possible to rasterize into an existing raster and use an alternative
default value:
.. code-block:: console
$ rio rasterize existing.tif --default_value 10 < input.geojson
It is also possible to rasterize using a template raster, which will be used
to determine the transform, dimensions, and coordinate reference system of the
output raster:
.. code-block:: console
$ rio rasterize test.tif --like tests/data/shade.tif < input.geojson
GeoJSON features may be provided using stdin or specified directly as first
argument, and dimensions may be provided in place of pixel resolution:
.. code-block:: console
$ rio rasterize input.geojson test.tif --dimensions 1024 1024
Other options are available, see:
.. code-block:: console
$ rio rasterize --help
sample
------
New in 0.18.
The sample command reads ``x, y`` positions from stdin and writes the dataset
values at that position to stdout.
.. code-block:: console
$ cat << EOF | rio sample tests/data/RGB.byte.tif
> [220649.99999832606, 2719199.999999095]
> EOF
[18, 25, 14]
The output of the transform command (see below) makes good input for sample.
shapes
------
New in 0.11.
The shapes command extracts and writes features of a specified dataset band out
as GeoJSON.
.. code-block:: console
$ rio shapes tests/data/shade.tif --bidx 1 --precision 6 > shade.geojson
The resulting file, uploaded to Mapbox, looks like this: `sgillies.j1ho338j `__.
Using the ``--mask`` option you can write out the shapes of a dataset's valid
data region.
.. code-block:: console
$ rio shapes --mask --precision 6 tests/data/RGB.byte.tif | geojsonio
See http://bl.ocks.org/anonymous/raw/ef244954b719dba97926/.
stack
-----
New in 0.15.
The rio-stack command stack a number of bands from one or more input files into
a multiband dataset. Input datasets must be of a kind: same data type,
dimensions, etc. The output is cloned from the first input. By default,
rio-stack will take all bands from each input and write them in same order to
the output. Optionally, bands for each input may be specified using a simple
syntax:
- ``--bidx N`` takes the Nth band from the input (first band is 1).
- ``--bidx M,N,O`` takes bands M, N, and O.
- ``--bidx M..O`` takes bands M-O, inclusive.
- ``--bidx ..N`` takes all bands up to and including N.
- ``--bidx N..`` takes all bands from N to the end.
Examples using the Rasterio testing dataset that produce a copy of it.
.. code-block:: console
$ rio stack RGB.byte.tif stacked.tif
$ rio stack RGB.byte.tif --bidx 1,2,3 stacked.tif
$ rio stack RGB.byte.tif --bidx 1..3 stacked.tif
$ rio stack RGB.byte.tif --bidx ..2 RGB.byte.tif --bidx 3.. stacked.tif
transform
---------
New in 0.10.
The transform command reads a JSON array of coordinates, interleaved, and
writes another array of transformed coordinates to stdout.
To transform a longitude, latitude point (EPSG:4326 is the default) to
another coordinate system with 2 decimal places of output precision, do the
following.
.. code-block:: console
$ echo "[-78.0, 23.0]" | rio transform - --dst_crs EPSG:32618 --precision 2
[192457.13, 2546667.68]
To transform a longitude, latitude bounding box to the coordinate system of
a raster dataset, do the following.
.. code-block:: console
$ echo "[-78.0, 23.0, -76.0, 25.0]" | rio transform - --dst_crs tests/data/RGB.byte.tif --precision 2
[192457.13, 2546667.68, 399086.97, 2765319.94]
Suggestions for other commands are welcome!