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)

Example 1:

function initFromFile()
{
	var path = Globals.defaultDirectory("init"); // get project 'init' folder
	var init_file_content = Globals.loadTextFile(path + "iTest_script.csv");
	alert("Filecontent: " + init_file_content);
	Globals.addTreesOnMap(127, init_file_content);
}

Example 2:

function specialOutput()
{

}

Methods

access XML settings

object setting(string key)
get a value from the global xml-settings (returns undefined if not present).

void set(string key, string value)
set the value of the setting key with the value value.

accessing files and directories

string defaultDirectory(string category)
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: property currentDir.

string path(string filename)
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"

string loadTextFile(string fileName)
returns the content of the text file fileName.
See also: Object CSVFile for tabular data.

saveTextFile(string fileName, string content)
save the string content to a text file with the path fileName.

bool fileExists(string fileName)
returns true if the given file (fileName) exists.

programmatically adding tree initialization

int addSingleTrees(int resourceIndex, string content)
add single trees on a specific resource unit with the 0-based index resourceIndex. The tree list is in the string contest and follows the single-tree syntax described in initialize+trees.
Returns the number of added trees.

int addTrees(int resourceIndex, string content)
add trees distribution on a specific resource unit with the 0-based index resourceIndex. The tree list is in the string contest and follows the distribution-tree syntax described in initialize+trees.
Returns the number of added trees.

int addTreesOnMap(int mapID, string content)
add trees distribution on a specific stand described by the mapID. The stand is defined in the global stand grid. The tree list is in the string contest and follows the distribution-tree syntax described in initialize+trees.
Returns the number of added trees.

int addSaplingsOnMap(Map map, mapID, species, count_pixels, height)
The function adds count_pixels saplings with a height of of height meters of the specified species on the polygon mapID of the map map. The number of saplings count_pixels is the number of 2m x 2m pixels which should be filled per Hectare and is scaled to larger or smaller stands accordingly. Saplings are added only on empty pixels (i.e. without regeneration). Tree locations are selected randomly without considering environmental factors (light). Species is a valid species name.

// add 100 saps with 0.8m height
Globals.addSaplingsOnMap(mgmt_map,1, 'Psme', 100, 0.8);

access to iLand outputs

bool startOutput(string table_name)
starts the output 'table_name'. Use the table name provided in Outputs for table_name.
Return true on success or throws an exception if table_name is not found.
Starting debug outputs is possible - the table_name has to have the format debug_XXX, with XXX one of the following:

Debug output name

treeNPP

treePartition

treeGrowth

waterCycle

dailyResponse

establishment

carbonCycle

Example:

// start the debug output 'carbonCycle'
Globals.startOutput('debug_carbonCycle');
// stop the output 'dynamicstand'
Globals.stopOutput('dynamicstand');

bool stopOutput(string table_name)
stops the output 'table_name'. Use the table name provided in Outputs for table_name.
Stop a debug output by specifying a special name (described above).
Return true on success or throws an exception if table_name is not found.

loading and saving vegetation snapshots

The Globals object provides two function to load and store a snapshot of the model content to a SQLite database. Currently, the trees, the soil pools and the snag pools are stored/restored.

bool saveModelSnapshot(string file_name)
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.

bool loadModelSnapshot(string file_name)
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.

miscellaneous functions

void repaint()
force a repaint of the GUI main visualization area.

bool screenshot(string file_name)
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.
An Example (call this function from the management main function manage()):

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

gridToFile(grid, file_name)
Creates a ESRI style grid file from a iLand grid. Specify the target file name with file_name and the type of the source grid with the string grid.
Allowed grids are: 'height' and 'lif', being the 10m dominant heights and the 2m LIF pixels.
Example:

Globals.gridToFile('height', 'c:/temp/heightgrid.txt');

bool seedMapToFile(string species, string file_name)
Tells iLand to create a seed map 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()' must be called every year.

// 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

setViewport(x,y,scale)
Sets the current viewing rectangle of the iLand program programmatically. After the call, the screen centers on the (world coordinates) x and y. The scale is defined as pixels per meter, e.g. 1 value of 0.5 would mean that each screen pixel are two meters in the real world.

include(source_file_name)
Loads (includes) a Javascript source code file and "runs" it in the current context. Default search path is the root directory of the project.

Globals.include('scripts/my_script.js'); // load a file from the scripts directory

Properties

year
The property year holds the current simulation year.
The property is read-only.

resourceUnitCount
resourceUnitCount is the number of resource units in the system.
The property is read-only.

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

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

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

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