1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
|
Using rio-calc
==============
Simple raster data processing on the command line is possible using Rasterio's
rio-calc command. It uses the `snuggs <https://github.com/mapbox/snuggs>`__
Numpy S-expression engine. The `snuggs README
<https://github.com/mapbox/snuggs/blob/master/README.rst>`__ explains how
expressions are written and evaluated in general. This document explains
Rasterio-specific details of rio-calc and offers some examples.
Expressions
-----------
Rio-calc expressions look like
.. code-block:: console
(func|operator arg [*args])
where ``func`` may be the name of any function in the module ``numpy`` or
one of the rio-calc builtins: ``read``, ``fillnodata``, or ``sieve``; and
``operator`` may be any of the standard Python arithmetic or logical operators.
The arguments may themselves be expressions.
Copying a file
--------------
Here's a trivial example of copying a dataset. The expression ``(read 1)``
evaluates to all bands of the first input dataset, an array with shape
``(3, 718, 791)`` in this case.
Note: rio-calc's indexes start at ``1``.
.. code-block:: console
$ rio calc "(read 1)" tests/data/RGB.byte.tif out.tif
Reversing the band order of a file
----------------------------------
The expression ``(read i j)`` evaluates to the j-th band of the i-th input
dataset. The ``asarray`` function collects bands read in reverse order into
an array with shape ``(3, 718, 791)`` for output.
.. code-block:: console
$ rio calc "(asarray (read 1 3) (read 1 2) (read 1 1))" tests/data/RGB.byte.tif out.tif
Stacking bands of multiple files
--------------------------------
Bands can be read from multiple input files. This example is another (slower)
way to copy a file.
.. code-block:: console
$ rio calc "(asarray (read 1 1) (read 2 2) (read 3 3))" \
> tests/data/RGB.byte.tif tests/data/RGB.byte.tif tests/data/RGB.byte.tif \
> out.tif
Named datasets
--------------
Datasets can be referenced in expressions by name and single bands picked out
using the ``take`` function.
.. code-block:: console
$ rio calc "(asarray (take a 3) (take a 2) (take a 1))" \
> --name "a=tests/data/RGB.byte.tif" out.tif
The third example, re-done using names, is:
.. code-block:: console
$ rio calc "(asarray (take a 1) (take b 2) (take b 3))" \
> --name "a=tests/data/RGB.byte.tif" --name "b=tests/data/RGB.byte.tif" \
> --name "c=tests/data/RGB.byte.tif" out.tif
Read and take
-------------
The functions ``read`` and ``take`` overlap a bit in the previous examples but
are rather different. The former involves I/O and the latter does not. You may
also ``take`` from any array, as in this example.
.. code-block:: console
$ rio calc "(take (read 1) 1)" tests/data/RGB.byte.tif out.tif
Arithmetic operations
---------------------
Arithmetic operations can be performed as with Numpy. Here is an example of
scaling all three bands of a dataset by the same factors.
.. code-block:: console
$ rio calc "(+ 2 (* 0.95 (read 1)))" tests/data/RGB.byte.tif out.tif
Here is a more complicated example of scaling bands by different factors.
.. code-block:: console
$ rio calc "(asarray (+ 2 (* 0.95 (read 1 1))) (+ 3 (* 0.9 (read 1 2))) (+ 4 (* 0.85 (read 1 3))))" tests/data/RGB.byte.tif out.tif
Logical operations
------------------
Logical operations can be used in conjunction with arithmetic operations. In
this example, the output values are 255 wherever the input values are greater
than or equal to 40.
.. code-block:: console
$ rio calc "(* (>= (read 1) 40) 255)" tests/data/RGB.byte.tif out.tif
|
