Rev 1221 |
Blame |
Compare with Previous |
Last modification |
View Log
| RSS feed
// documentation for the FMTreeList API
/**
The TreeList class (**`trees`** variable) represents a list of trees that can be manipulated (e.g., harvested) with functions of the class.
When javascript code is executed in the context of an Activity, a variable 'trees' is available in the global context. This instance
of a TreeList is linked automatically to the forest stand that is currently managed.
## Overview
### initializing the list
The main function for loading (i.e. making available for manipulation) trees of a forest stand is `load()`. `load()` can be used to load either
all trees, or a subset of trees (based on filter criteria).
### manipulating the content of the list
The trees in a list (loaded by `load()`) may be manipulated using functions such as `filter()` or `sort()`. There are functions helping to get aggregate values
(`mean()`, `sum()`), or to get the value of a given `percentile()`.
### manipulationg trees
Trees present in the tree list may be harvested or simply cut down. Main functions are `kill()`, `harvest()`. If `simulate` is true, harvested/killed trees
are only marked for removal. At a later point in time, all marked trees can be removed using `removeMarkedTrees()`.
### extra features
something here...
## Examples
// 'trees' variable is always available.
// this loads *all* trees of the current forest stand (i.e. trees>4m)
trees.load();
trees.simulate = true; // enable simulation mode (this is the default)
// keep only spruce trees with a dbh>20cm in the list:
trees.filter("species = piab and dbh>20");
// now harvest all trees (since simulate=true, the trees are only marked for harvesting)
trees.harvest();
...
// later: remove all trees from the system that are marked for removal (harvest/kill)
trees.removeMarkedTrees();
@class TreeList
***/
/**
The `load()` method is the main means to get all the trees of a forest stand into the list.
Per default, all trees (i.e. trees>4m height) that are located on the forest stand are loaded. If `filter` is provided, only a subset
of the trees are loaded. `filter` can either be a probability (between 0..1) for selecting individual trees, or an Expression using tree
variables.
trees.load(0.2); // load (randomly selected) 20% of all trees
trees.load("rnd(0,1)<0.2)"); // the same as above, but using an Expression
// load a subset of trees (for which the given Expression evalulates to true):
trees.load("species=piab and dbh>20");
@method load
@param {String} filter optional filter criterion (see above).
@return {Integer} the number of trees loaded.
**/
/**
When `simulate` is true, harvest operations are not actually executed, but affected trees are marked as either for harvest or killing. Calling `removeMarkedTrees()` then
executes the harvest operation.
Note: tree variables `markharvest`, `markcut`, `markcrop` are available for use in `filter()` or for visualization in iLand.
@propery simulate
@type Boolean
@default true
*/
/**
the ID of the currently active stand (or -1).
@propery stand
@type Integer
@readonly
*/
/**
the number of trees that are currently loaded in the list.
@propery count
@type Integer
@readonly
*/
/**
Load all trees (living trees, >4m height) of the current `stand` into the internal list.
@method loadAll
@return {Integer} the number of loaded harvested.
**/
/**
Check all trees of the stand and either kill or harvest those trees that are marked for that operation.
See also: {{#crossLink "TreeList/simulate:property"}}{{/crossLink}}, {{#crossLink "TreeList/harvest:method"}}{{/crossLink}}
@method removeMarkedTrees
@return {Integer} the number of trees that have been removed.
**/
/**
Kill (i.e., cut down and do not remove from the forest) the trees in the list, filtered with `filter`.
See also: {{#crossLink "TreeList/simulate:property"}}{{/crossLink}}
@method kill
@param {String} filter A valid filter Expression.
@return {Integer} the number of trees that have been removed.
@Example
trees.loadAll();
trees.kill('dbh<10'); // kill all trees with a dbh<10cm
**/
/**
Remove the `fraction` of all trees [0..1] for which `filter` evalulates to `true`. Return number of removed trees.
When trees are harvested, the biomass is removed from the system (compare kill/cut).
When `harvest()` is called without parameters, then all trees that are currently in the list are removed (see also `load()`).
See also: {{#crossLink "TreeList/simulate:property"}}{{/crossLink}}, {{#crossLink "TreeList/kill:method"}}{{/crossLink}}
@method harvest
@param {string} filter A valid filter Expression.
@param {double} fraction The fraction [0..1] of trees that should be harvested. Default value is 1.
@return {Integer} the number of trees that have been removed.
@Example
trees.loadAll();
trees.harvest('species=piab', 0.2); // remove 20% (selected randomly) from all spruce
trees.harvest('dbh>30'); // harvest all trees with dbh>30cm
**/