Show:
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)

Methods

addSingleTrees

(
  • resourceIndex
  • content
)
Integer

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

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

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.

defaultDirectory

(
  • category
)
String

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

See also: currentDir

Parameters:

  • category String

    folder category

Returns:

String:

The requested file path (without a trailing slash)

fileExists

(
  • file_name
)
Boolean

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

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
  • 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)

See also: gridToFile

Parameters:

  • type String

    select the type of grid to return

Returns:

Grid:

a Javascript object encapsulating the Grid

gridToFile

(
  • grid_type
  • file_name
)
Boolean

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. See grid for the avaialble grids (e.g., 'height' and 'lif)..

See also: grid

Parameters:

  • grid_type String

    select the type of grid to export

  • file_name String

    target file path (relative to the home directory)

Returns:

Boolean:

true on success.

Example:

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

loadModelSnapshot

(
  • file_name
)
Boolean

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.

See also: saveModelSnapshot

Parameters:

  • file_name String

    filename of the input database.

Returns:

Boolean:

true on succes.

loadTextFile

(
  • file_name
)
String

Load the content of a text file into a string.

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

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

reloadABE

()

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

()

force a repaint of the GUI main visualization area.

resourceUnitGrid

(
  • expression
)
Grid

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

saveModelSnapshot

(
  • file_name
)
Boolean

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.

See also: loadModelSnapshot

Parameters:

  • file_name String

    filename of the output database.

Returns:

Boolean:

true on succes.

saveTextFile

(
  • file_name
  • content
)
Boolean

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

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

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

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.

See also: setting

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
)

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

See also: set

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
)

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

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

See also: grid

Parameters:

  • species String

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

Returns:

Grid:

a Javascript Grid

startOutput

(
  • table_name
)
Boolean

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

See also: stopOutput

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

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.

See also: 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
)

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).

Parameters:

  • command String

    command to execute

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
)

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

See also: repaint

Parameters:

  • milliseconds Integer

    time to wait in milliseconds

Properties

currentDir

String

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"

See also: path

Example:

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

msec

Integer

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

The number of resource units in the current simulation.

Default: 1

viewOptions

Object

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

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

See also: worldY

worldY

Integer

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

See also: worldX

year

Integer

The current year of the simulation.