Defined in: iLand\globals_doc.js:20

Module: iLand

The Globals object exposes a series of auxiliary functions to the scripting context. An instance of "Globals" is always available in the global context, so no explicit creation is necessary. The provided function cover inter alia:

handling of directories and simple text files
access to XML settings
access and control over Outputs
miscellaneous functions (e.g., for making screeshots)

Global functions

In addition to the functions provided by the Globals object, there are a number of (truly) global helper functions available. They are:

print(x): prints x (see Globals.print() and console.log())
include(source_file): loads a Javascript code file source_file and runs the code. Can be useful to load "libraries". (See Globals.include()).
alert(message): shows a message box with the text message and stops until user clicks Ok. (See Globals.alert())
printObj(obj): helper function to pretty print an object to the console.

Handling of exceptions

Some functions throughout the iLand API "throw errors". Unhandled, a message box shows the error and iLand stops running. You can, however, also handle these errors programmatically, i.e. "catch" them and continue with the execution of the model. Here is an example:

// not handled: this throws an error that the setting key is not valid.
let x = Globals.setting("mr.james.bond");

// handled using a try/catch block
try {
let x = Globals.setting("mr.james.bond");
} catch (error) {
    console.log(error);
}

Item Index

Methods

Properties

Methods

`addSaplings`

(

standId
x
y
width
height
species
treeheight
age

)

Integer

Defined in iLand\globals_doc.js:446

add sapling on a metric rectangle given with width and height at x/y. if a standId is provided (-1 or 0: no stand), x/y is relative to the lower left edge of the stand rectangle. If no stand is provided, x/y are absolute (relative to the project area). returns the number of successfully added sapling cells

Parameters:

standId Integer

id of the stand (0 or -1 for no stand provided)
x Double

id x-coordinate of the rectangle
y Double

id y-coordinate of the rectangle
width Double

width (m) of the rectangle
height Double

height (m) of the rectangle
species String

species code of the species to plant saplings
treeheight Double

height (m) of saplings
age Integer

age of the saplings that are planted

Returns:

Integer:

the number of saplings trees

Example:

// this function creates gaps of fixed sizes on a fixed location relative to a position given by dx/dy
                    function createPattern4x4(id, dx, dy) {
                        var beech = true;
                        // (1) remove saplings...
                        Globals.removeSaplings(-1,dx-20,dy-20,40,40);
                        // (2) ... and trees
                        trees.loadAll();
                        trees.simulate = false;
                        console.log('createPattern4x4: stand ' + id + ', N=' + trees.count);
                        trees.filter("mod(x,100)>29 and mod(x,100)<71 and mod(y,100)>29 and mod(y,100)<71");
                        console.log('createPattern4x4: stand ' + id + ', Nafter=' + trees.count);
                        trees.kill();
                        // (3) plant saplings into the created gaps; actually, create alternating 10x10m cells with Silver fir and beech.
                        for (var ix=0;ix<4;++ix) {
                            for (var iy=0;iy<4;++iy) {
                                Globals.addSaplings(-1, dx-20 + 10*ix, dy-20 + 10*iy, 8,8, (beech?"abal":"fasy"), 0.25, 4);
                                beech = !beech; // flip between beech and silver fir
                                //console.log('createPattern4x4: ' + id + ', x: ' + dx +  ', y: ' + dy );
                            }
                        }
                    }

`addSaplingsOnMap`

(

map
mapId
species
px_per_hectare
treeheight
age

)

Integer

Defined in iLand\globals_doc.js:488

add sapling on a stand defined by a (spatial) map if a standId is provided (-1 or 0: no stand), x/y is relative to the lower left edge of the stand rectangle. If no stand is provided, x/y are absolute (relative to the project area). returns the number of successfully added sapling cells

Parameters:

map Map

Map object
mapId Integer

identifier for the stand / polygon on the given map for which to add saplings
species String

species code of the species to plant saplings
px_per_hectare Double

proportion to plant saplings from the 2x2m cells within the given stand (0..1)
treeheight Double

height (m) of saplings
age Integer

age of the saplings that are planted

Returns:

Integer:

the number of saplings trees

`addSingleTrees`

(

resourceIndex
content

)

Integer

Defined in iLand\globals_doc.js:412

Add single trees on a specific resource unit with the 0-based index resourceIndex. The tree list is in the string content and follows the single-tree syntax described in the wiki.

Parameters:

resourceIndex Integer

0-based resource unit index
content String

line (or lines) of an init-file to initialize

Returns:

Integer:

the number of added trees.

`addTrees`

(

resourceIndex
content

)

Integer

Defined in iLand\globals_doc.js:423

Add trees distribution on a specific resource unit with the 0-based index resourceIndex. The tree list is in the string content and follows the distribution-tree syntax described in the wiki.

Parameters:

resourceIndex Integer

0-based resource unit index
content String

line (or lines) of an init-file to initialize

Returns:

Integer:

the number of added trees.

`addTreesOnMap`

(

standID
content

)

Integer

Defined in iLand\globals_doc.js:432

Add trees distribution on a specific stand described by the standID. The stand is defined in the global stand grid. The tree list is in the string content and follows the distribution-tree syntax described in the wiki.

Parameters:

standID Integer

ID of the stand in the stand grid
content String

line (or lines) of an init-file to initialize

Returns:

Integer:

the number of added trees.

`alert`

(

message

)

Defined in iLand\globals_doc.js:86

shows a message box to the user (only available with iLand GUI) and halts execution until the user clicks OK.

Note: The global function alert() is a short-cut to Globals.alert().

Parameters:

message String

message to show as a string

`debugOutputFilter`

(

RUs

)

Defined in iLand\globals_doc.js:274

can be used to limit the amount of debug output that is generated on resource unit level. If the function is called with a list of resource unit indices, then only RUs within the list produce debug output. Output is deactivated for all other resource units (a call with an empty list effectively disables the output).

Effective for debug outputs on resource unit level and partiucularly useful for outputs with daily resolution (e.g., daiyle water cycle, daily species response).

Parameters:

RUs Array

array of resource unit indices

Example:

// limit output to a sample of the resource units
                    Globals.debugOutputFilter([106,235,414,543]);

`defaultDirectory`

(

category

)

String

Defined in iLand\globals_doc.js:152

Get directory with of the given category category. See filenames and paths for available categories. Using this defaultDirectory() avoids absolute file paths in scripts.

Parameters:

category String

folder category

Returns:

String:

The requested file path (without a trailing slash)

`fileExists`

(

file_name

)

Boolean

Defined in iLand\globals_doc.js:375

Check if the file file_name already exists.

Parameters:

file_name String

file to check

Returns:

Boolean:

true if the file already exists

`grid`

(

type

)

Grid

Defined in iLand\globals_doc.js:565

extract a grid of type type from iLand. The extracted grid is a floating point grid (double precision) and a copy of the current state in iLand (memory is freed automatically during Javascript garbage collection).

The grid has a cell size of 10m or 100m (depending on the type) and covers the full extent of the model.

The available grid types with 10m resolution are:

height: dominant tree height (m)
count: number of living trees (>4m height) on each pixel
standgrid the internal standgrid of iLand (see https://iland-model.org/landscape+setup#Setting_up_the_stand_grid)
valid: pixels inside the project area get a value of 1, pixels non within the project area 0 (see wiki page)
forestoutside: 1 if a pixel is out of project area and is considered to be forested (see wiki page)

The available grid types with 100m resolution are:

smallsaplingcover: the fraction of the area which is covered by small saplings (<=1.3m) OR grass cover (0..1). (Note: RUs with non-stockable area have always a value <1).
saplingcover: the fraction of the area which is covered by saplings (with a height >1.3m) (0..1). (Note: RUs with non-stockable area have always a value <1).
swc: mean annual water content (mm) over the full year
swc_gs: mean annual water content (mm) during the growing season (fixed month April - September)
swc_pot: field water capacity (mm) of the resource unit (potential water content)

Parameters:

type String

select the type of grid to return

Returns:

Grid:

a Javascript object encapsulating the Grid

`gridToFile`

(

grid_type
file_name
height_level

)

Boolean

Defined in iLand\globals_doc.js:526

Creates a ESRI style grid file from an iLand grid. Specify the target file name with file_name and the type of the source grid with the string grid_type.

The avaialable grid_types are:

lif: the basic LIF grid of iLand (2m resolution)
height: the height grid (10m resolution) of iLand (top tree heights)
lifc: a height-corrected LIF with 10m resolution. Calculated as mean LIF value over 10m, and height corre

Parameters:

grid_type String

select the type of grid to export
file_name String

target file path (relative to the home directory)
height_level Numeric

gives the reference height level for the height-corrected LIF lifc (see also the competition for light wiki page)

Returns:

Boolean:

true on success.

Example:

Globals.gridToFile('height', 'temp/heightgrid.txt'); // store in project_folder/temp

`include`

(

name

)

Defined in iLand\globals_doc.js:95

Includes / runs a Javascript file. The file is loaded and evaluated in the current Javascript context. include is useful for loading additional code (e.g., library style scripts), or several management programs in ABE, or several agents in BITE.

Note: The global function include() is a short-cut to Globals.include().

Parameters:

name String

of the Javascript file to include (path relative to the project root)

Example:

// File 1
                    include('scripts/file2.js');
                    print(a); // prints "defined in file2"
                    
                    // file2.js:
                    var a = "defined in file2";
                    // some other stuff

`loadModelSnapshot`

(

file_name

)

Boolean

Defined in iLand\globals_doc.js:314

loads a snapshot database (created with a previous call to saveModelSnapshot). The model must be already created (i.e. resource units, ...); exisiting trees are removed and replaced by the trees from the database.

Parameters:

file_name String

filename of the input database.

Returns:

Boolean:

true on succes.

`loadTextFile`

(

file_name

)

String

Defined in iLand\globals_doc.js:359

Load the content of a text file into a string. Throws an error if the file does not exist.

Parameters:

file_name String

filename to load

Returns:

String:

the content of the file or an empty text if file does not exist/is empty.

`path`

(

filename

)

String

Defined in iLand\globals_doc.js:164

Use path() to construct a path relative to the project directory. Useful for avoiding absolute file paths in Javascript.

Example (Project-file: "c:\iland\test\test.xml"): Globals.path('temp/filexy.txt') -> "c:\iland\test\temp.filexy.txt"

See also: defaultDirectory, currentDirectory

Parameters:

filename String

filename that should be extended

Returns:

String:

fully qualified file path

`print`

(

message

)

Defined in iLand\globals_doc.js:76

print the contents of the message to the log. In iLand GUI the message is also printed to the screen even if a logfile is specified. In addition to the iLand print() function also the built-in Javascript object console can be used (e.g. console.log(); see https://developer.mozilla.org/de/docs/Web/API/Console).

Note: The global function print() is a short-cut to Globals.print().

Parameters:

message String

message to print as a string

`random`

(

from
to

)

Double

Defined in iLand\globals_doc.js:190

Return a random number between from and to. This function uses the iLand internal random number generation process and respects a global random seed. With other words: Using the Javascript Math.random() does not guarantee the same sequence of numbers, even when a global random seed is set (and multithreading is disabled)

Parameters:

from Double

lower bound (inclusive), default=0
to Double

upper bound (inclusive), default=1

Returns:

Double:

the random number

`reloadABE`

()

Defined in iLand\globals_doc.js:116

Completely reloads the ABE (agent based management engine) sub module. This includes loading of the (static) stand description file, and the javascript source code of ABE.

`repaint`

()

Defined in iLand\globals_doc.js:520

force a repaint of the GUI main visualization area.

`resourceUnitGrid`

(

expression

)

Grid

Defined in iLand\globals_doc.js:605

Return a grid (resolution of resource units) with the result of an expression (Expression) evaluated in the context of the resource unit (see the wiki for a list of available variables).

Parameters:

expression String

Expression to evaluate for each resource unit

Returns:

Grid:

a Javascript Grid

`saveDebugOutputs`

(

do_clear

)

Defined in iLand\globals_doc.js:291

forces writing of debug outputs from the internal buffer of iLand to disk.

Parameters:

do_clear Boolean

if true, debug output buffer is cleared

`saveModelSnapshot`

(

file_name

)

Boolean

Defined in iLand\globals_doc.js:303

creates a snapshot from the current state of the model. file_name is the path to the target database, which is created if the database file does not exist (paths relative to the home directory). The wiki provides details about snapshots.

Parameters:

file_name String

filename of the output database.

Returns:

Boolean:

true on succes.

`saveTextFile`

(

file_name
content

)

Boolean

Defined in iLand\globals_doc.js:367

Save the content of a string content to a file.

Parameters:

file_name String

filename to save to
content String

content that should be written

Returns:

Boolean:

true on success.

`screenshot`

(

file_name

)

Boolean

Defined in iLand\globals_doc.js:505

make a screenshot from the central viewing widget (as if pressing Ctrl+P in the iLand viewer) and stores the image to the provided file file_name. The image type depends on the extension provided with file_name. Default path is the home directory.

Parameters:

file_name String

file name that

Returns:

Boolean:

true on success.

Example:

// make a screenshot every 5 years
                    function screenshot() {
                       if (Globals.year % 5 == 0)
                          Globals.screenshot( Globals.defaultDirectory('temp') + 'image_' + Globals.year + '.png' );
                    }

`seedMapToFile`

(

species
file_name

)

Boolean

Defined in iLand\globals_doc.js:546

Creates a ESRI style grid file from the seed map for a given species. The functions causes the creation of a raster file for 'species' the next time seed dispersal is calculated. species is the species-id (e.g., 'piab', 'fasy'), and file_name the destination location of the grid file ESRI ASCII raster. The saved seed map contains the seed distribution on 20m resolution. Seed maps are only saved once, i.e. if a time series of seed maps is needed, seedMapToFile() need to be called periodically.

Parameters:

species String

species code to export (e.g., 'piab')
file_name String

target file path (relative to the home directory)

Returns:

Boolean:

true on success.

Example:

// save maps for scots pine and beech
                    Globals.seedMapToFile('pisy', 'temp/map_pisy.asc');
                    Globals.seedMapToFile('fasy', 'temp/map_fasy.asc');
                    // now run the model, at least for one year
                    // files are created during model execution

`set`

(

key
value

)

Boolean

Defined in iLand\globals_doc.js:139

Set a setting in the project file with the key key to a value of value. The key is the full path to the requested node using a '.'-notation.

Parameters:

key String

fully qualified key within the project file
value Object

new value of the setting key.

Returns:

Boolean:

true on success.

`setting`

(

key

)

Defined in iLand\globals_doc.js:122

Read a value from the project file. The key is the full path to the requested node using a '.'-notation.

Parameters:

key String

fully qualified key within the project file

Returns:

The value of the setting, or undefined if the setting is not present

Example:

// global 'onInit' function is called during startup
                    var width = Globals.setting('model.world.width'); // the horizontal extent of the project area
                    var filename = Globals.setting('user.targetdir') + "my_file.txt"; // a user-defined key in the project file

`setUIshortcuts`

(

shortcuts

)

Defined in iLand\globals_doc.js:626

This is a helper function that allows to add shortcut links to the 'Scripting' panel in the iLand Viewer user interface. shortcuts is a object with name/value pairs, where the value is the string displayed in iLand, and name the Javascript function call (as a string).

Parameters:

shortcuts Object

Javascript object that defines named Javascript calls

Example:

Globals.setUIshortcuts({ 'kyrill()': 'run the kyrill storm',
                                     'emma_paula()': 'run the emma/paula storms' }) ;

`speciesShareGrid`

(

species

)

Grid

Defined in iLand\globals_doc.js:595

Return a grid with the basal area of the given species (resource unit resolution, i.e. 100m).

Parameters:

species String

species code (e.g., 'piab') of the species

Returns:

Grid:

a Javascript Grid

`startOutput`

(

table_name

)

Boolean

Defined in iLand\globals_doc.js:242

starts the output table_name. The table name for each output can be found on the output wiki page. Starting debug outputs is also possible - the table_name has to have the format debug_XXX, with XXX one of the following:

treeNPP
treePartition
treeGrowth
waterCycle
dailyResponse
establishment
carbonCycle
performance

Parameters:

table_name String

Output that should be started

Returns:

Boolean:

true on succes, an error message is printed in case of failure.

Example:

Globals.startOutput("debug_performance");

`stopOutput`

(

table_name

)

Boolean

Defined in iLand\globals_doc.js:263

stops the output table_name. The table name for each output can be found on the output wiki page. Starting (debug outputs) is also possible - see startOutput.

Parameters:

table_name String

Output that should be stopped

Returns:

Boolean:

true on succes, an error message is printed in case of failure.

`systemCmd`

(

command

)

String

Defined in iLand\globals_doc.js:382

Execute a system command (e.g., for copying files). Commands are operating system dependent; For windows, cmd.exe /C executes a command without a separate command window (see example below). Output of the executed command is redirected to the iLand log (stdout, stderr), the stdout output is returned as a string.

Parameters:

command String

command to execute

Returns:

String:

the output of the command (std-out)

Example:

// helper function for windows: fix slashes and add 'cmd.exe /C'
                    function winnify(s) {
                         // replace forward with backward slashes
                         s = s.replace(/\//g, '\\');
                         s = "cmd.exe /C " + s;
                         return s;
                    }
                    
                    // onYearEnd: is called automtically from iLand at the end of a year
                    function onYearEnd()
                    {
                        v = Globals.setting('user.v'); // 'version' is a user defined variable in the project file
                        // create a folder for the simulation using 'v' at the end of the first simulation year
                        if (Globals.year==1)
                            Globals.systemCmd(winnify('mkdir ' + Globals.path('output/v' + v)));
                    }

`wait`

(

milliseconds

)

Defined in iLand\globals_doc.js:616

Pause model execution for milliseconds ms. This can be useful to slow down animations.

Parameters:

milliseconds Integer

time to wait in milliseconds

Properties

`currentDir`

String

Defined in iLand\globals_doc.js:177

gets or sets the current directory of iLand. Relative paths are resolved relative to the currentDir.

Example (Project-file: "c:\iland\test\test.xml"): Globals.path('temp/filexy.txt') -> "c:\iland\test\temp.filexy.txt"

Example:

Globals.currentDir="c:/temp";
                    Globals.loadTextFile("i_am_in_temp.txt"); // accesses c:/temp

`msec`

Integer

Defined in iLand\globals_doc.js:217

The milliseconds since the start of the day.

Example:

// simple timer functions:
                    var _elapsed=-1;
                    function start_timer() { _elapsed = Globals.msec; }
                    function elapsed(thingi)
                    {
                        var elapsed=Globals.msec - _elapsed;
                        _elapsed = Globals.msec;
                        console.log("Time: " + thingi + ": " + elapsed + "ms");
                    }
                    
                    // use timers:
                    start_timer();
                    // do some lengthy operation x
                    elapsed("x"); // prints time elapsed since start_timer()
                    // some other lenghty operation y
                    elapsed("y"); // print duration of 'y' in ms

`resourceUnitCount`

Integer

Defined in iLand\globals_doc.js:68

The number of resource units in the current simulation.

Default: 1

`viewOptions`

Object

Defined in iLand\globals_doc.js:326

viewOptions allow some control over the visualization of the landscape in the iLand GUI. The viewOptions is an object with the following elements:

minValue and maxValue: the value range of the visualization; if not present, the value range of the ruler is automatically scaled
type: defines the type of visualization, and is one of the following:
- lif: the 'Light Influence Field' (2m)
- dom: the dominant height (10m)
- regeneratation: saplings/regeneration (2m)
- seed: seed availability (20m)
- trees: individual trees
- ru: resource units (1ha)
clip: boolean ; if true, grids are clipped to the height grid (i.e. white for out-of-project-areas) (not supported for all visualizations)
transparent: boolean; if true, trees are drawn semi-transparent
species
- boolean value in single tree mode: if true, draw trees using species colors (true)
- a species short name (e.g. 'piab'): select this species, e.g. for seed availability per species, or species shares
grid: draw one of the dynamic grids layers from active sub modules (check the possible names either in iLand or in the wiki)
expression: provides a expression that can be evaluated for trees or for resource unit (depending on the type)
filter: expression that is used to filter trees (useful for showing only a subset of trees)

This option is not available in the iLand console version.

Example:

  Globals.viewOptions = { type: 'trees', species: true };
                      var vo = Globals.viewOptions;
                      vo.filter = 'dbh<10';
                      Globals.viewOptions = vo;
                      Globals.repaint();

`worldX`

Integer

Defined in iLand\globals_doc.js:202

extent of the world (without buffer) in meters (x-direction).

`worldY`

Integer

Defined in iLand\globals_doc.js:210

extent of the world (without buffer) in meters (y-direction).

`year`

Integer

Defined in iLand\globals_doc.js:61

The current year of the simulation.

The iLand Javascript API

APIs

Globals Class

Global functions

Handling of exceptions

Item Index

Methods

Properties

Methods

addSaplings

Parameters:

Returns:

Example:

addSaplingsOnMap

Parameters:

Returns:

addSingleTrees

Parameters:

Returns:

addTrees

Parameters:

Returns:

addTreesOnMap

Parameters:

Returns:

alert

Parameters:

debugOutputFilter

Parameters:

Example:

defaultDirectory

Parameters:

Returns:

fileExists

Parameters:

Returns:

grid

Parameters:

Returns:

gridToFile

Parameters:

Returns:

Example:

include

Parameters:

Example:

loadModelSnapshot

Parameters:

Returns:

loadTextFile

Parameters:

Returns:

path

Parameters:

Returns:

print

Parameters:

random

Parameters:

Returns:

reloadABE

repaint

resourceUnitGrid

Parameters:

Returns:

saveDebugOutputs

Parameters:

saveModelSnapshot

Parameters:

Returns:

saveTextFile

Parameters:

Returns:

screenshot

Parameters:

Returns:

Example:

seedMapToFile

Parameters:

Returns:

`addSaplings`

`addSaplingsOnMap`

`addSingleTrees`

`addTrees`

`addTreesOnMap`

`alert`

`debugOutputFilter`

`defaultDirectory`

`fileExists`

`grid`

`gridToFile`

`include`

`loadModelSnapshot`

`loadTextFile`

`path`

`print`

`random`

`reloadABE`

`repaint`

`resourceUnitGrid`

`saveDebugOutputs`

`saveModelSnapshot`

`saveTextFile`

`screenshot`

`seedMapToFile`

`set`

`setting`

`setUIshortcuts`

`speciesShareGrid`

`startOutput`

`stopOutput`

`systemCmd`

`wait`

`currentDir`

`msec`

`resourceUnitCount`

`viewOptions`

`worldX`

`worldY`

`year`