Operations

Operations are the generic building blocks for larger applications. Most operations use some computation to combine and translate one or more arguments into one or more results. For example, the convolve() operation combines an array of floating point values with a kernel of floating point weights and computes a result array with floating point values.

array = convolve(array, kernel)

Operations can be called using syntax that depends on the programming language used. Function call syntax is always supported and some combinations of a programming language and an operation support operator syntax as well.

# Function syntax
result1, result2 = some_function(argument1, argument2)

# Operator syntax
result = argument1 some_binary_operator argument2

Operations can be combined to define large computations, like simulation models.

In LUE, operations asynchronously compute results, using a collection of interdependent asynchronous tasks. Tasks execute as soon as all (asynchronously computed!) arguments are ready to be used and hardware is available to them. As operations only create tasks and don’t wait for them to finish executing, they typically return much sooner than their tasks finish executing. This is a good thing. That way, tasks created by multiple operations are available for the scheduler to select for execution, keeping all hardware busy doing useful work.

Note

• Not all available operations are documented already. In Python the help function can be used to obtain more information (e.g.: help(lue.framework.uniform)).

• Except when explicitly stated, all operations require the input arguments to be “compatible”. In the case of rasters, this implies that each raster must cover the same area, have the same resolution, and have the same coordinate reference system. LUE won’t implicitly convert arguments to become compatible. Operations exist that help with such conversion, like resample().

• The signatures of the operations are written in a language-agnostic manner. How to use each operation from a specific language might slightly differ. Check the usage examples for inspiration.

• The most relevant part of each usage example is the call of the operation. Some of the code surrounding such calls is atypical code developed specifically to make it easy to write usage examples. This code, from the lue_document_c C library, lue_document_cxxC++ library and thelue.document` Python subpackage, should not be used in real-world LUE code.

• The C++ and Python APIs are more mature than the C API.

• C does not support overloading functions easily. In case of overloaded functions, the C API provides only one of these functions. These overloads are the once used in the example code of the relevant reference pages.

Local operations

Local operations (AKA point operations) compute values for each cell in the result array, given one or more corresponding cells in one or more argument arrays.

Local operations differ with respect to how they compute a result value for a cell, given one or more argument values.

An example of a local operation is the add() operation, which assigns the sum of argument cell values to the corresponding result cell.

See Local operations for an overview of all local operations.

Focal operations

Focal operations (AKA filter operations, neighbourhood operations, window operations) compute values for each cell in the result array, given values within a kernel centered on each corresponding (focal) cell in the argument array. Kernels have a shape and contain weights with which to multiply each corresponding cell in the argument array.

Focal operations differ with respect to how they compute a result value given argument values.

An example of a focal operation is the focal_maximum() operation, which assigns to each focal result element the maximum value in the values found in the neighbourhood around the corresponding focal argument cell. See Focal operations for an overview of all focal operations.

Zonal operations

Zonal operations (AKA area operations) compute values for each cell in the result array, given corresponding (zonal) cells in an argument array. Each cell in the argument array belongs to a class, each of which defines a zone. Result values are computed per zone, so cells in the result array located within the same zone receive the same value.

Zonal operations differ with respect to how they compute a result given the argument values per zone.

An example of a zonal operation is the zonal_sum() operation, which assigns to each zonal result element the sum of the values found in the zone of the corresponding zonal argument cell. See Zonal operations for an overview of all zonal operations.

Global operations

Global operations (AKA map operations) compute a single result value, given all cell values in the input argument array.

Global operations differ with respect to how they compute a result given all values.

An example of a global operation is the minimum() operation, which returns the minimum value of all element values in the argument.

See Global operations for an overview of all global operations.

Routing operations

In general, routing operations compute result element values, given argument element values, while taking a topological network into account. Only argument values from elements that are somehow connected are taken into account when computing a result element value. Networks can be defined in multiple ways. A common approach is to use a flow direction field represented by an array, in which each cell contains a code representing a direction to which it drains.

Other operations involving networks, for example, those creating a network as a result instead of using one as an argument, are also grouped as routing operations.

Routing operations differ with respect to how they compute a result given the argument values reachable using a network, or how this network is represented.

An example of routing operation is the d8_flow_direction() operation, which returns a so-called D8 flow direction field, given an elevation model as argument. Routing operations can, for example, be used to simulate the flow of surface water through a landscape.

See Routing operations for an overview of all routing operations.

I/O operations

Operations related to reading and writing data.

See I/O operations for an overview of all I/O operations.

Conversion operations

Operations related to interacting with other software packages.

See Conversion operations for an overview of all conversion operations.

Miscellaneous operations

Operations that do not fall in the above categories.

See Miscellaneous operations for an overview of all miscellaneous operations.