Class: Grid

The Grid class encapsulates a floating point grid (with double precision). The class provides high-performance functions for element-wise computations, but also methods for Javascript access. You can load() grids from disk (and save() to disk), or from iLand by using methods such as Globals.grid, or one of its disturbance submodules (e.g., Barkbeetle.grid, Wind.grid). The extent and cell size depend on the respective functions, but usually cover the whole landscape. To view the content of the grid visually, use the registerUI() method.

Use apply() for updating a single grid, and combine() for calculating grid values based on combining multiple grid sources.

Javacsript based access to grid values is possible via value() and setValue() methods ( valueAt() and setValueAt() for access by coordinates).

Memory management

Methods such as Globals.grid return a copy of the data present in iLand, and calls to apply() or combine() alter the underlying data; you can use the copy() method create a duplicate grid (if the underlying data should not change). Memory of grids is freed automatically by the Javascript engine (garbage collection) when they are no longer referenced.

Coordinate system

Grids use the local coordiante system of iLand, i.e. the point (0,0) is the lower left corner of the project area. When grids are loaded from disk, the coordinates are transformed to that system (relative to the world.location.x and world.location.y settings in the iLand project file). For example, consider a iLand local system with an origin of (12650, 4500). Now, consider loading a grid with the origin (14000,5000) (i.e, xllcorner, yllcorner) and a cellsize of 100m. The iLand coordiantes (0/0) would then be invalid, and the lower left pixel of the grid can be accessed with, e.g., value(1420, 550).

Examples

// memory management
var g=Globals.grid('height');
g.apply('height*2'); // modify 'g'
var h=g.copy();
h.apply('x*2'); // modify copy of 'g'

Properties Overview

Name	Type	Description
`cellsize`	`integer` (read-only)	the cell size of the grid in meters.
`count`	`integer` (read-only)	the number of pixels of the grid.
`height`	`integer` (read-only)	the height (y-dimension) of the grid (number of pixels)
`isValid`	`boolean` (read-only)	is `true` if the grid contains data.
`minX`	`double` (read-only)	the minimum metric coordinate in X direction (left border of grid).
`minY`	`double` (read-only)	the minimum metric coordinate in Y direction (lower border of grid).
`name`	`string`	gets or sets the name of the grid (that are used for calculations)
`width`	`integer` (read-only)	the width (x-dimension) of the grid (number of pixels)

Methods Overview

Method	Return Type	Description
`aggregate(factor)`	`void`	Aggregates the grid by averaging over multiple cells. This changes the resolution of the underlying grid by a factor `factor` (e.g., aggregating a 10m grid with
`apply(expression)`	`void`	Apply a function on the values of the grid, thus modifiying the grid (see the copy() function).
`clear()`	`void`	Fill the grid with 0-values.
`combine(expression)`	`void`	Combine multiple grids, and set the value of the internal grid to the result of `expression` for each cell. The function expects
`copy()`	`grid`	Create a copy of the current grid and return a new grid object. The `name` of the copied grid is x. Memory management is automatic (garbage collection), i.e. you don’t have to worry about freeing the memory.
`create(width)`	`void`	Creates a numeric grid (floating point) with the dimensions `width` and `height` with the cell size `cellsize` and fills the grid with 0. The grid is
`info()`	`string`	Retrieve some key parameters of the grid as a string.
`load(file_name)`	`void`	Load from a file `file_name` (ESRI ASCII raster grid). The `name` property is set to the base file name (without path and extension).
`load(fileName)`	`boolean`	`load` loads a grid in ESRI ASCII format. The grid internally uses floating point precision. Furthermore, the grid is aligned to the iLand project area,
`paint(min_value)`	`void`	`paint` shows the content of the grid visually in iLand. Use `min_value` and `max_value` to provide a value range.
`registerUI(name)`	`void`	Registers the grid with the user interface of iLand (https://iland-model.org/iLand+viewer). The grid is added to the “Scripts” section of grids,
`resample(target_grid)`	`void`	Resamples the content of the current grid to the extent/cellsize given by the grid `target_grid`. If `target_grid` is larger than the current grid 0-values are inserted, otherwise
`save(file_name)`	`void`	Save to a file `file_name` as ESRI ASCII raster file or GeoTIFF. A TIF is created
`setOrigin(x)`	`void`	`setOrigin` updates the origin of the grid, effectively moving the grid to a new position relative to the origin of the project area.
`setValue(x)`	`void`	Set the value at position (`x`, `y`) to `value`. Note that using the value() and
`setValueAt(x)`	`void`	Set the value at the metric coordinates (`x`, `y`) to `value`. Note that using the value() and
`sum(expresion)`	`void`	Apply the expression `expression` on all pixels of the grid and return the sum of the values
`sumTrees(expresion)`	`void`	Evaluate the expression `expression` for all trees in the current treelist, and sum the
`value(x)`	`void`	Access individual cell values with an index in x- and y-direction (i.e., values between 0 and the width/height-1).
`valueAt(x)`	`void`	Access individual cell values of the grid at the given metric coordinates. If the grid is empty, or the the
`values()`	`void`	Get a Javascript array with that contains all the grid values as doubles.

Properties Details

`cellsize`

integer ReadOnly

the cell size of the grid in meters.

    See also: [count](grid.qmd#count), [height](grid.qmd#height), [width](grid.qmd#width)

`count`

integer ReadOnly

the number of pixels of the grid.

    See also: [cellsize](grid.qmd#cellsize), [height](grid.qmd#height), [width](grid.qmd#width)

`height`

integer ReadOnly

the height (y-dimension) of the grid (number of pixels)

    See also: [cellsize](grid.qmd#cellsize), [width](grid.qmd#width)

`isValid`

boolean ReadOnly

is true if the grid contains data.

`minX`

double ReadOnly

the minimum metric coordinate in X direction (left border of grid).

    See also: [minY](grid.qmd#miny), [height](grid.qmd#height), [width](grid.qmd#width)

`minY`

double ReadOnly

the minimum metric coordinate in Y direction (lower border of grid).

    See also: [minX](grid.qmd#minx), [height](grid.qmd#height), [width](grid.qmd#width)

`name`

string

gets or sets the name of the grid (that are used for calculations)

`width`

integer ReadOnly

the width (x-dimension) of the grid (number of pixels)

    See also: [cellsize](grid.qmd#cellsize), [height](grid.qmd#height)

Methods Details

`aggregate(factor)`

Returns: void

Aggregates the grid by averaging over multiple cells. This changes the resolution of the underlying grid by a factor factor (e.g., aggregating a 10m grid with

`factor`=4 results in a grid with 40m resolution). The value of the target cell is the average over source cells. Note: no special care is
taken for -1 values.

Parameters:

factor (int): multiplier for target cell size

`apply(expression)`

Returns: void

Apply a function on the values of the grid, thus modifiying the grid (see the copy() function).

The function is given as a string representing an [Expression](https://iland-model.org/Expression) and is evaluated for each cell of the grid.
In the expression, the current value of the grid cell can be accessed using the [name](grid.qmd#name).

See also: [copy()](grid.qmd#copy), [combine()](grid.qmd#combine)

Parameters:

expression (string): expression that is applied to each cell of the grid @Example var g = Globals.grid(‘height’); // name is ‘height’ g.apply(’x*x’); // error, invalid variable g.apply(‘min(height, 30’); // ok g.apply(‘if(height<=4, 0, height)’); // ok var h = g.copy(); h.apply(‘x^2’); // use copy() if the grid should not change (note: copies are named ‘x’)

Example:

var g = Globals.grid('height'); // name is 'height'
        g.apply('x*x'); // error, invalid variable
        g.apply('min(height, 30'); // ok
        g.apply('if(height<=4, 0, height)'); // ok
        var h = g.copy();
        h.apply('x^2'); // use copy() if the grid should not change (note: copies are named 'x')

`clear()`

Returns: void

Fill the grid with 0-values.

`combine(expression)`

Returns: void

Combine multiple grids, and set the value of the internal grid to the result of expression for each cell. The function expects

an object that includes named source grids. The `expression` is an [iLand Expression](https://iland-model.org/Expression),
and you can refer to the grids in `grid_objects` with the respective name of the grid. Note that the function
alters the data of the grid.


All grids must have the same dimensions, and the grid iteself can be accessed by adding the grid to `grid_objects`.


See also: [copy()](grid.qmd#copy), [apply()](grid.qmd#apply)

Parameters:

expression (string): expression that is applied to each cell of the grid @param {object} grid_objects object including the source grids; the individual grids are provided as name-value pairs and the provided names are the variable names in the expression (see example). @Example var g = Globals.grid(‘height’); // name of g is ‘height’ var j = Globals.grid(‘count’); var k = g.copy(); k.apply(‘if(height>30,1,0)’); // update ‘k’ by combining g,j, and k k.combine(‘heightcount filter’, { height: g, filter: k, count: j } ); // access grid ‘g’ as ‘height’, grid ‘k’ as ‘filter’, grid ‘j’ as count in the expression

Example:

var g = Globals.grid('height'); // name of g is 'height'
        var j = Globals.grid('count');
        var k = g.copy();
        k.apply('if(height>30,1,0)');
        // update 'k' by combining g,j, and k
        k.combine('height*count * filter', { height: g, filter: k, count: j } ); // access grid 'g' as 'height', grid 'k' as 'filter', grid 'j' as count in the expression

`copy()`

Returns: grid

Create a copy of the current grid and return a new grid object. The name of the copied grid is x. Memory management is automatic (garbage collection), i.e. you don’t have to worry about freeing the memory.

Return Value Description: a copy of the grid @Example var a = Globals.grid(‘height’); var ac = a.copy(); ac.name = ‘h2’; // change the name

Example:

var a = Globals.grid('height');
        var ac = a.copy();
        ac.name = 'h2'; // change the name

`create(width)`

Returns: void

Creates a numeric grid (floating point) with the dimensions width and height with the cell size cellsize and fills the grid with 0. The grid is

located at the origin of the project area (i.e., at coordiantes (0,0)). No clipping is applied.

Note that the grid object must already exist! Use `new Grid()` to create a new grid from scratch, or other functions
that return grids (e.g., [copy()](grid.qmd#copy), [grid()](globals.qmd#grid) ).

See also: [load()](grid.qmd#load), [setOrigin()](grid.qmd#setorigin)

Parameters:

width (int): the number of cells in x-direction @param {int} height the number of cells in y-direction @param {int} cellsize the cellsize (m) @return { boolean } true on success.

@Example var g = new Grid(); // create a grid g.create(10,20,5); // populate with an empty grid with 50x100m g.setValue(4,5,-1); // modify the grid g.setOrigin(1000, 1000); // move the grid (the lower left corner) to the given coordinates g.save(“test.txt”); // save as ESRI raster file

Example:

var g = new Grid(); // create a grid
        g.create(10,20,5); // populate with an empty grid with 50x100m
        g.setValue(4,5,-1); // modify the grid
        g.setOrigin(1000, 1000); // move the grid (the lower left corner) to the given coordinates
        g.save("test.txt"); // save as ESRI raster file

`info()`

Returns: string

Retrieve some key parameters of the grid as a string.

Return Value Description: the information string @Example var g = Globals.grid(‘height’); console.log(g.info()); //prints: grid-dimensions: 1820/1020 (cellsize: 10, N cells: 1856400), grid-name=‘height’

Example:

var g = Globals.grid('height');
        console.log(g.info());
        //prints:  grid-dimensions: 1820/1020 (cellsize: 10, N cells: 1856400), grid-name='height'

`load(file_name)`

Returns: void

Load from a file file_name (ESRI ASCII raster grid). The name property is set to the base file name (without path and extension).

See also: [save()](grid.qmd#save)

Parameters:

file_name (string): source file name (relative to project folder) @return { boolean } true on success.

`load(fileName)`

Returns: boolean

load loads a grid in ESRI ASCII format. The grid internally uses floating point precision. Furthermore, the grid is aligned to the iLand project area,

but not clipped and the `cellsize` is retained (contrary to the [MapGrid](map.qmd), which clips the grid to the project area and
resamples the content of the grid to a cellsize of 10m).

See also: [create()](grid.qmd#create), [setOrigin()](grid.qmd#setorigin)

Parameters:

fileName (string): the filename of the grid; paths are relatve to the root folder of the project. @return {boolean} returns true on success @Example var g = new Grid(); // create a grid g.load(‘gis/biggrid.asc’); // load the raster file

Return Value Description: returns true on success @Example var g = new Grid(); // create a grid g.load(‘gis/biggrid.asc’); // load the raster file

Example:

var g = new Grid(); // create a grid
        g.load('gis/biggrid.asc'); // load the raster file

`paint(min_value)`

Returns: void

paint shows the content of the grid visually in iLand. Use min_value and max_value to provide a value range.

Parameters:

min_value (double): minimum value (mapped to bottom of the color ramp) @param {double} max_value maximum value (mapped to top of the color ramp)

@Example var g = Globals.grid(‘height’); // get height grid from iLand g.paint(0,50);

Example:

var g = Globals.grid('height'); // get height grid from iLand
        g.paint(0,50);

`registerUI(name)`

Returns: void

Registers the grid with the user interface of iLand (https://iland-model.org/iLand+viewer). The grid is added to the “Scripts” section of grids,

and iLand renders the grid when clicking on it. Default value range is set to min/max values within the grid. Note that a Grid's `name` is the
relative file path when loaded from disk.

Parameters:

name (string): Name to use for the grid in the UI. When blank, the variable name is used.

@Example // create a new grid and load some data var g = new Grid(Globals.path(‘gis/extra_grid.asc’)); g.registerUI();

Example:

// create a new grid and load some data
    var g = new Grid(Globals.path('gis/extra_grid.asc'));
    g.registerUI();

`resample(target_grid)`

Returns: void

Resamples the content of the current grid to the extent/cellsize given by the grid target_grid. If target_grid is larger than the current grid 0-values are inserted, otherwise

the grid is cropped to `target_grid`.

Resampling is "brute-force", every cell of the new grid is set to the value that the current grid has at the new cell's center (i.e. no interpolation takes place).
Resampling alters the current grid.

Parameters:

target_grid (object): Grid with target extent and resolution

`save(file_name)`

Returns: void

Save to a file file_name as ESRI ASCII raster file or GeoTIFF. A TIF is created

when the file name ends with `.tif` or `.TIF`.


See also: [load()](grid.qmd#load)

Parameters:

file_name (string): destination file name (relative to project folder)

`setOrigin(x)`

Returns: void

setOrigin updates the origin of the grid, effectively moving the grid to a new position relative to the origin of the project area.

Note, that no additional checks are performed - use with care.


See also: [create()](grid.qmd#create), [load()](grid.qmd#load)

Parameters:

x (double): new value for the x-coordinate of the origin @param {double} y new value for the y-coordinate of the origin @Example var g = new Grid(); // create a grid g.create(10,20,5); // populate with an empty grid with 50x100m g.setValue(4,5,-1); // modify the grid g.setOrigin(1000, 1000); // move the grid (the lower left corner) to the given coordinates g.save(“test.txt”); // save as ESRI raster file

Example:

var g = new Grid(); // create a grid
        g.create(10,20,5); // populate with an empty grid with 50x100m
        g.setValue(4,5,-1); // modify the grid
        g.setOrigin(1000, 1000); // move the grid (the lower left corner) to the given coordinates
        g.save("test.txt"); // save as ESRI raster file

`setValue(x)`

Returns: void

Set the value at position (x, y) to value. Note that using the value() and

[setValue()](grid.qmd#setvalue) methods is much slower than using functions such as [apply()](grid.qmd#apply).



See also: [value()](grid.qmd#value)

Parameters:

x (integer): index in x direction (between 0 and grid.width-1) @param {integer} y index in y direction (between 0 and grid.height-1) @param {double} value value to set @Example // using javascript access functions can be 100x times slower: var g = Globals.grid(‘height’); var ela=Globals.msec; // for measuring time, see also the ‘msec’ doc
```
for (var i=0;i<g.width;++i) {
    for (var j=0;j<g.height;++j) {
        g.setValue(i,j, g.value(i,j)*2);
    }
}
console.log("javascript: " + (Globals.msec - ela) + "ms"); // 1650ms
ela = Globals.msec;
g.apply('height*2');
console.log("apply(): " + (Globals.msec - ela) + "ms"); // 17ms
```

Example:

// using javascript access functions can be 100x times slower:
        var g = Globals.grid('height');
        var ela=Globals.msec; // for measuring time, see also the 'msec' doc

        for (var i=0;i<g.width;++i) {
            for (var j=0;j<g.height;++j) {
                g.setValue(i,j, g.value(i,j)*2);
            }
        }
        console.log("javascript: " + (Globals.msec - ela) + "ms"); // 1650ms
        ela = Globals.msec;
        g.apply('height*2');
        console.log("apply(): " + (Globals.msec - ela) + "ms"); // 17ms

`setValueAt(x)`

Returns: void

Set the value at the metric coordinates (x, y) to value. Note that using the value() and

[setValue()](grid.qmd#setvalue) methods is much slower than using functions such as [apply()](grid.qmd#apply).

The coordinates are relative to the iLand project area and given in meters.


See also: [value()](grid.qmd#value)

Parameters:

x (double): meters in x direction (between 0 and ) @param {double} y meteres in y direction (between 0 and grid.height-1) @param {double} value value to set @Example // using javascript access functions can be 100x times slower: var g = Globals.grid(‘height’); var ela=Globals.msec; // for measuring time, see also the ‘msec’ doc
```
for (var i=0;i<g.width;++i) {
    for (var j=0;j<g.height;++j) {
        g.setValue(i,j, g.value(i,j)*2);
    }
}
console.log("javascript: " + (Globals.msec - ela) + "ms"); // 1650ms
ela = Globals.msec;
g.apply('height*2');
console.log("apply(): " + (Globals.msec - ela) + "ms"); // 17ms
```

Example:

// using javascript access functions can be 100x times slower:
        var g = Globals.grid('height');
        var ela=Globals.msec; // for measuring time, see also the 'msec' doc

        for (var i=0;i<g.width;++i) {
            for (var j=0;j<g.height;++j) {
                g.setValue(i,j, g.value(i,j)*2);
            }
        }
        console.log("javascript: " + (Globals.msec - ela) + "ms"); // 1650ms
        ela = Globals.msec;
        g.apply('height*2');
        console.log("apply(): " + (Globals.msec - ela) + "ms"); // 17ms

`sum(expresion)`

Returns: void

Apply the expression expression on all pixels of the grid and return the sum of the values

See also: [apply()](grid.qmd#apply)

Parameters:

expresion (string): expression to evaluate @return { double } sum of expression over all cells @Example var g = Globals.grid(‘height’); var mean_h = g.sum(‘height’) / g.count; g.apply(‘height/’ + mean_h); // scale the height grid

Example:

var g = Globals.grid('height');
        var mean_h = g.sum('height') / g.count;
        g.apply('height/' + mean_h); // scale the height grid

`sumTrees(expresion)`

Returns: void

Evaluate the expression expression for all trees in the current treelist, and sum the

result of `expression` to the cells of the grid. With other words, the result is a grid
with a sum over expression for all trees on a cell. The `filter` lets you sum over a subset of trees.

See also: [apply()](grid.qmd#apply)

Parameters:

expresion (string): expression to evaluate and sum for each grid cell @param {string} filter expression to filter a subset of trees (empty is no filter) @return { double } sum of expression over all cells @Example var g = Globals.grid(‘height’); // get a grid with the right size / resolution, here 10m g.sumTrees(‘basalArea’, ‘species=piab’); // g.save(Globals.path(‘temp/basal-area-spruce.asc’));

Example:

var g = Globals.grid('height'); // get a grid with the right size / resolution, here 10m
        g.sumTrees('basalArea', 'species=piab'); //
        g.save(Globals.path('temp/basal-area-spruce.asc'));

`value(x)`

Returns: void

Access individual cell values with an index in x- and y-direction (i.e., values between 0 and the width/height-1).

If the grid is empty, or the the given position is invalid, -1 is returned.

Note: For access with metric coordinates, use the valueAt() function!

See also: [setValue()](grid.qmd#setvalue)

Parameters:

x (integer): index in x direction (between 0 and grid.width-1) @param {integer} y index in y direction (between 0 and grid.height-1) @return { double } value of the grid at position (x, y)

`valueAt(x)`

Returns: void

Access individual cell values of the grid at the given metric coordinates. If the grid is empty, or the the

given position is invalid, -1 is returned. The coordiantes are relative to the origin of the iLand project area.

Note: For access with index coordinates, use the `value()` function!

See also: [setValue()](grid.qmd#setvalue)

Parameters:

x (double): coordinate (m) @param {double} y coordinate (m) @return { double } value of the grid at position (x, y)

`values()`

Returns: void

Get a Javascript array with that contains all the grid values as doubles.

See also: [value()](grid.qmd#value)

Example:

var g = Globals.grid('height');
        let hs = g.values(); // get a (large) array
        // loop over the array
        for (let i=0;i<hs.length;++i) {
            // do something with hs[i] ....
        }
        // use JS mapping/filter functions
        let bigs = hs.filter(h => h>50); // filter all grid values that are >50m
        print("number of tall pixels: " + bigs.length);