mirror of
https://github.com/rasterio/rasterio.git
synced 2025-12-08 17:36:12 +00:00
120 lines
3.5 KiB
ReStructuredText
120 lines
3.5 KiB
ReStructuredText
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 arithemtic 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
|
|
|