The iLand Javascript API The iLand Javascript API

  • API Docs for Version: 1.0

    • APIs

    Show:

    Globals Class

    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)

    Methods

    addSingleTrees

    (
    • resourceIndex
    • content
    )
    Integer

    Defined in iLand\globals_doc.js:342

    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:353

    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:362

    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:57

    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

    defaultDirectory

    (
    • category
    )
    String

    Defined in iLand\globals_doc.js:123

    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

    Defined in iLand\globals_doc.js:306

    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:429

    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

    Defined in iLand\globals_doc.js:395

    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

    include

    (
    • name
    )

    Defined in iLand\globals_doc.js:66

    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:245

    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

    Defined in iLand\globals_doc.js:290

    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

    Defined in iLand\globals_doc.js:135

    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:47

    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

    reloadABE

    ()

    Defined in iLand\globals_doc.js:87

    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:389

    force a repaint of the GUI main visualization area.

    resourceUnitGrid

    (
    • expression
    )
    Grid

    Defined in iLand\globals_doc.js:468

    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

    Defined in iLand\globals_doc.js:234

    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

    Defined in iLand\globals_doc.js:298

    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:374

    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:410

    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:110

    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
    )

    Defined in iLand\globals_doc.js:93

    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
    )

    Defined in iLand\globals_doc.js:489

    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:458

    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

    Defined in iLand\globals_doc.js:201

    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

    Defined in iLand\globals_doc.js:222

    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
    )

    Defined in iLand\globals_doc.js:313

    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
    )

    Defined in iLand\globals_doc.js:479

    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

    Defined in iLand\globals_doc.js:148

    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

    Defined in iLand\globals_doc.js:176

    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:39

    The number of resource units in the current simulation.

    Default: 1

    viewOptions

    Object

    Defined in iLand\globals_doc.js:257

    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:161

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

    See also: worldY

    worldY

    Integer

    Defined in iLand\globals_doc.js:169

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

    See also: worldX

    year

    Integer

    Defined in iLand\globals_doc.js:32

    The current year of the simulation.