Rasterrechner
-------------

.. note::
   Der Rasterrechner steht ab PlexMap 6 zur Verfügung.

Der Rasterrechner (grid.calc) ermöglicht es, Berechnungen auf ein oder mehreren Rastern anhand einer Berechnungsvorschrift durchzuführen.
Im Folgenden werden die Grundfunktionen und der Syntax erläutert und anschließend Beispiele für die Anwendungen gegeben.

.. figure:: grid_calc_switchboard.png
    :width: 40%
    :align: center

    Die Switchboard-Funktion des Rasterrechners

Die Dimensionen der Eingangsraster müssen für die Berechnung übereinstimmen. Die Metadaten vom ersten Eingangsraster werden übernommen.
Eingangsdaten werden wiederholt, wenn unterschiedlich viele Raster an den Eingängen anliegen.

Mit dem optionalen Parameter ``type`` kann der Datentyp des Ergebnisrasters festgelegt werden.
Wenn ``type`` nicht angeben ist, wird der Datentyp des Rasters am ersten Eingang übernommen.
Mögliche Werte für ``type`` sind: ``ubyte``, ``uint8``, ``uint16``, ``int16``, ``uint32``, ``int32``, ``float32``, ``float64``.


Syntax
======

Die mit dem Parameter ``expression`` angegebene Berechnungsvorschrift wird als S-expression formuliert,
dabei können mathematische Funktionen und logische Operatoren verwendet werden.

::

    expression = "(" (operator | function) *argument ")"
    argument = expression | number

Mit der Funktion ``read`` können Raster oder einzelne Bänder eingelesen werden.
Die Eingänge sind beginnend mit 0 nummeriert, das Band kann optional angegeben werden und startet bei Index 1.
Neben grundlegenden mathematischen (``*``, ``+``, ``-``, ``/``) und logischen (``&``, ``|``, ``<``, ``<=``, ``==``, ``!=``, ``>=``, ``>``) Operatoren
stehen viele Funktionen aus dem Python-Package ``numpy`` zur Verfügung.
Mit der Funktion ``asarray`` können Bänder zu einem Raster zusammengefasst werden.


Beispiele
=========


Gelände überhöhen
.................

Durch Multiplikation können beispielsweise Höhenunterschiede hervorgehoben werden::

    (* (read 0) 1.5)


Einheitenkonvertierung
......................

Mit einer Division lassen sich Werte in Meter in Angaben in Fuß umrechnen::

    (/ (read 0) 0.3048)


Zusammengesetzte Ausgabe
........................

Mit der Funktion ``asarray`` können Bänder in einem Raster neu arrangiert werden. Zum Beispiel lassen sich Bänder eines Rasters vertauschen::

    (asarray (read 0 2) (read 0 1))

Das Ergebnisraster kann ebenso aus Bändern unterschiedlicher Eingangsraster zusammengestellt werden::

    (asarray (read 0 1) (read 0 2) (read 0 3) (read 1 4))


nDOM-Berechnung
...............

Das normalisierte digitale Oberflächenmodell (nDOM) beschreibt die relative Höhe von Objekten und ergibt sich aus der
Differenz aus dem digitalen Geländemodell (DGM) und dem digitalen Oberflächenmodell (DOM).
Die Berechnungsvorschrift für den Rasterrechner sieht wie folgt aus::

    (- (read 0) (read 1))


Filtern und Maskieren
.....................

Sollen beispielsweise Höhen von mindestens 12 m übernommen werden und niedrigere Objekte gefiltert werden, lässt sich das mit diesem Ausdruck realisieren::

    (* (>= (read 0) 5) (read 0))

Mit ``where`` kann man zusätzlich den Wert angeben, der verwendet werden soll, wenn die Bedingung nicht zutrifft.
So lässt sich zum Beispiel eine Maske (das dritte Argument ist der Leerwert) erzeugen::

    (where (>= (read 0) 12) 1 -9999)

.. figure:: ndom_example.png
    :width: 60%
    :align: center

    Die Abbildung zeigt ein normalisiertes digitales Oberflächenmodell, auf das die vorhergehende Berechnungsvorschrift angewendet wird.

.. figure:: filter_example.png
    :width: 60%
    :align: center

    Durch die Anwendung der Berechnungsvorschrift wird der Wert 1 für alle Felder gesetzt, auf die die Bedingung zutrifft, andernfalls der Leerwert.


Durchschnitt
............

Der Durchschnittswert einzelner Zellen über mehrere Bänder lässt sich mittels Addition und Division berechnen::

    (/ (+ (read 0 1) (read 0 2) (read 0 3)) 3)

Zu beachten ist, dass im Gegensatz dazu die Funktion ``mean`` aus ``numpy`` den Mittelwert über alle Felder eines Rasters berechnet.


Minimum und Maximum
...................

Um jeweils den kleinsten Wert aus zwei Rastern auszuwählen, bietet sich die Verwendung der Funktion ``minimum`` an::

    (minimum (read 0) (read 1))

Analog dazu kann mit ``maximum`` das Maximum ermittelt werden.
Die Funktionen ``min`` und ``max`` geben das globale Minimum bzw. Maximum für ein Raster zurück.