The following can be used to create expressions. The can be simple scalar expression or map algebra expressions that manipulate entire spatial objects. Functions differ from commands in that they do not directly replicate LandSerf operations that would otherwise be accessed via the LandSerf menus. Instead, functions can be used to build complex expressions to manipulate the contents of variables in a script.
Arithmetic Operators | |
| These can be used in any expression that involves scalar quantities (simple numbers and variables) or spatial objects (raster and vector maps). | |
+, -, *, / | Addition, subtraction, multiplication and division operators. |
^ | Power operator (e.g. 5^2 is 25, 7^(1/3) is the cube root of 7). |
% | Modulus (remainder) operator (e.g. 15%6 is 3 since 15/6 is 2 with remainder 3). |
() | Brackets to control the order of evaluation. |
String Operators | |
| Applied to quantities representing text. | |
" | Identifies a string (e.g. title = "Elevation model";) |
& | String concatenation (e.g. title = "Elevation" & " model"; results in a single string Elevation model). |
compare(string1,string2) | Compares two strings alphabetically. If string1 comes alphabetically before string2, this function returns -1; if it comes alphabetically afterwards, returns 1; otherwise returns 0 if the strings are identical. |
quote(arg) | Creates a new string that wraps the given arg inside "quotes". The argument can be a number or a string, but the result is always a string. This can be useful when needing to create text with quotation marks. |
strlen(arg) | Returns the number of characters in string arg2. |
substring(string,arg1,arg2) | Creates a new string that is part or all of string. The substring starts from position arg1 where 0 is the first letter of the string, and continues until position just less than arg2. If arg2 is larger than the length of the string, the substring from arg1 to the end is returned. |
Mathematical Functions and Constants | |
| Applied to scalar numeric quantities. | |
abs(arg) | Calculates the absolute value of arg (strips it of any minus sign if it exists). |
acos(arg), asin(arg), atan(arg), atan2(arg1,arg2) | Inverse trigonometrical functions. Returns values in radians. Values outside the range of +-1 supplied to these functions will return a value of 0. |
cos(arg), sin(arg), tan(arg) | Trigonometrical functions. Expects arg to be an angle expressed in radians . Values of infinity (e.g. tan(pi()/2)) are returned as 0. |
e() | Provides Euler's number e (2.7182818). |
gauss() | Random value with Gaussian (normal) distribution with mean of 0 and standard deviation of 1. |
ln(arg) | Natural logarithm (to base e) of arg. If the value given to the function is <=0, the function will return a zero. |
null() | Provides the constant representing a null value. |
pi() | Provides the constant pi (3.14159). |
round(arg) | Rounds arg to the nearest whole number. |
rand() | Random value with 'rectangular' distribution between 0 and 1. |
sqrt(arg) | Square root of arg. If the value given to the function is negative, the function will return a 0. |
Statistical Functions | |
| Applied to a collection of scalar numeric quantities. | |
max(arg1,arg2,arg3...) | Returns the maximum of the given list of values. |
median(arg1,arg2,arg3...) | Returns the median value of the given list of values. If an even number of arguments specified, the mean of the two middle values returned. |
min(arg1,arg2,arg3...) | Returns the minimum of the given list of values. |
mode(arg1,arg2,arg3...) | Returns the mode of the given list of values. If more than one modal value is found, returns the right-most modal value in the parameter list. |
percentile(perc,arg2,arg3...) | Returns the value corresponding to the given percentile from the given list of values. The percentile (perc) should be a number between 0-100. If there is no value in the list corresponding to the precise percentile figure, the weighted mean of the two nearest ordered values is returned. |
rank(arg1,arg2,arg3...) | Returns the rank (position in ordered list) of the given value (arg1) in the given list of values. |
Colour Functions | |
| Used to maipulate images where each raster value is an integer representing a red, green, blue triplet. | |
blue(arg) | Returns the blue component of the colour integer represented by arg. This is scaled between 0-255. |
green(arg) | Returns the green component of the colour integer represented by arg. This is scaled between 0-255. |
red(arg) | Returns the red component of the colour integer represented by arg. This is scaled between 0-255. |
rgb(arg1,arg2,arg3) | Returns a single colour value composed of the red, green and blue colour components represented by arg1, arg2 and arg3 respectively. Each colour component should be a whole number between 0-255. |
Logical Operators and Functions | |
| Used to test boolean conditions that evaluate to true (non-zero) or false (zero). | |
and, or, not | Boolean AND, Boolean OR, Boolean NOT |
==, != | Equal to, not equal to |
>, <, >=, <= | Greater than, less than, greater than or equals, less than or equals |
ifelse(condition, value_if true, value_if_false) | Evaluates the expression condition. If the condition is true or evaluates to a non-zero value, returns value_if_true otherwise returns value_if_false. Returned values can be numbers, strings or spatial objects. |
Focal Operators | |
| The are applied to entire spatial objects. They cannot be applied to scalar quantities. | |
col | Extracts column coordinate from raster. Allows spatial coordinates to be used in map algebra calculations. |
easting | Extracts easting from a spatial object. Allows spatial coordinates to be used in map algebra calculations. |
northing | Extracts northing from a spatial object. Allows spatial coordinates to be used in map algebra calculations. |
row | Extracts row coordinate from raster. Allows spatial coordinates to be used in map algebra calculations. |
[row_offset,col_offset] | Extracts raster value with the given coordinate offset. Allows focal neighbourhoods to be processed |
_ (underscore) | When appended to a spatial object name inside a map algebra expression, forces it to treated as an entire spatial object rather than scalar value. This can be useful when passing spatial objects to commands inside a map algebra expression. |
Flow Control | |
| Used to control program flow of a script. | |
if (condition); {action} | Processes the code in action only if condition is true or evaluates to a non-zero value. |
while (condition); {action} | Repeatedly processes the code in action while condition is true or it evaluates to a non-zero value. |
return value | Leaves the the current user-defined function or script, optionally returning a value. If placed within a user-defined function, control is returned to the line of code that called the function. If placed elsewhere, the script will quit. |
Miscellaneous | |
| Other functions and reserved words. | |
clear variable | Clears the contents of the given variable. This can be used to free memory in scripts that contain variables holding very large spatial objects. |
function function_name(arg1,arg2,arg3...) | Declares a user-defined function that can be called from within a script. The function can take optional parameters which become local to the code enclosed in braces. |
help | If used as a parameter for any function or command, provides a brief message explaining how to use the function or command. |