Grid Class
iLand\grid_doc.js:1
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:method, Wind/grid:method). The extent and
cell size depend on the respective functions, but usually cover the whole landscape.
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'
Item Index
Methods
Methods
apply
-
expression
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 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.
Parameters:
-
expression
Stringexpression 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')
clear
()
Fill the grid with 0-values.
combine
-
expression
-
grid_objects
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,
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
.
Parameters:
-
expression
Stringexpression that is applied to each cell of the grid
-
grid_objects
Objectobject 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('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
()
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.
Returns:
a copy of the grid
Example:
var a = Globals.grid('height');
var ac = a.copy();
ac.name = 'h2'; // change the name
create
-
width
-
height
-
cellsize
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 newGrid to create a new grid from scratch, or other functions that return grids (e.g., copy, grid ).
Parameters:
-
width
Intthe number of cells in x-direction
-
height
Intthe number of cells in y-direction
-
cellsize
Intthe cellsize (m)
Returns:
true on success.
Example:
var g = Factory.newGrid(); // 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
()
String
Retrieve some key parameters of the grid as a string.
Returns:
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'
load
-
file_name
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
Parameters:
-
file_name
Stringsource file name (relative to project folder)
Returns:
true on success.
load
-
fileName
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, which clips the grid to the project area and
resamples the content of the grid to a cellsize of 10m).
Parameters:
-
fileName
Stringthe filename of the grid; paths are relatve to the root folder of the project.
Returns:
returns true on success
Example:
var g = Factory.newGrid(); // create a grid
g.load('gis/biggrid.asc'); // load the raster file
resample
-
target_grid
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
ObjectGrid with target extent and resolution
save
-
file_name
Save to a file file_name
as ESRI ASCII raster file.
See also: load
Parameters:
-
file_name
Stringdestination file name (relative to project folder)
setOrigin
-
x
-
y
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.
Parameters:
-
x
Doublenew value for the x-coordinate of the origin
-
y
Doublenew value for the y-coordinate of the origin
Example:
var g = Factory.newGrid(); // 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
-
y
-
value
Set the value at position (x
, y
) to value
. Note that using the value and
setValue methods is much slower than using functions such as apply.
See also: value
Parameters:
-
x
Integerindex in x direction (between 0 and grid.width-1)
-
y
Integerindex in y direction (between 0 and grid.height-1)
-
value
Doublevalue 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
setValueAt
-
x
-
y
-
value
Set the value at the coordinates (x
, y
) to value
. Note that using the value and
setValue methods is much slower than using functions such as apply.
The coordinates are relative to the iLand project area.
See also: value
Parameters:
-
x
Doubleindex in x direction (between 0 and grid.width-1)
-
y
Doubleindex in y direction (between 0 and grid.height-1)
-
value
Doublevalue 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
sum
-
expresion
Apply the expression expression
on all pixels of the grid and return the sum of the values
See also: apply
Parameters:
-
expresion
Stringexpression to evaluate
Returns:
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
value
-
x
-
y
Access individual cell values of the grid at the given position. If the grid is empty, or the the given position is invalid, -1 is returned.
See also: setValue
Parameters:
-
x
Integerindex in x direction (between 0 and grid.width-1)
-
y
Integerindex in y direction (between 0 and grid.height-1)
Returns:
value of the grid at position (x
, y
)
valueAt
-
x
-
y
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.
See also: setValue
Parameters:
-
x
Doublecoordinate (m)
-
y
Doublecoordinate (m)
Returns:
value of the grid at position (x
, y
)
Properties
isValid
Boolean
is true
if the grid contains data.
name
String
gets or sets the name of the grid (that are used for calculations)