General Overview
Global Mapper script files allow the user to create custom batch processes that make use of the functionality built in to Global Mapper. From a script, one can import data in any of the numerous formats supported by the software, reproject that data if desired or perform analysis on it, and export it to a new file. Scripts can be run from within the application interface using the File> Run Script... option. They can also be automatically run in the background by double clicking the *.gms file or called from the command line on a machine with Global Mapper installed.
Syntax
Global Mapper script files consist of a series of command lines. Each command line begins with a command. A series of parameter/value pairs should follow the command. These pairs should be written as parameter=value. No spaces should exist before or after the equal sign.
Individual parameter/value pairs should be separated by spaces. If a pair requires spaces internal to the value, quotes may be used around the entire value. For example, for a filename with spaces, the pair could look like FILENAME="c:\\my documents\\test.tif". The string designation can be nested by combining single and double quote marks (" and '). For example when specifying a variable inside a formula, like the formula in Normalize a Loaded Terrain Layer sample script.
Parameters and values are case-independent, but by convention, and in this guide, they are written in all uppercase. Commands are uppercase.
Command lines typically consist of one line each. To extend a command to another line, use the backslash character (\) at the end of the line. There are a few exceptions to this, including the DEFINE_PROJ and DEFINE_SHAPE commands and the looping functionality provided by the DIR_LOOP_START and DIR_LOOP_END commands.
Boolean Values
The values listed through-out this guide are YES to enable the option and NO to disable it, but there are a number of accepted values to specify the state:
- YES can be represented by "YES", "Y", "TRUE", "T" , "1" , or no value (see below).
- NO can be represented by "NO", "N", "FALSE", "F", or "0".
Parameters that expect a value of YES or NO to enable or disable functionality can (starting with v13.1) be enabled with just the parameter name. So rather than saying FLAG_PARAM_NAME=YES, you can just say FLAG_PARAM_NAME to get the same behavior as specifying yes.
Wildcards and variables
Some parameters accept values including wildcard characters.
- * (an asterisk) represents a wildcard of any length.
- ? (a question mark) represents a single character wildcard.
Parameters can also except variables as values or parts of values. Variables are delimited by %VARIABLE%. Some variables are built-in but they can also be defined within the script. Custom variables must be defined before they are used in a command (the script is run from top to bottom sequentially). Typically variables are defined at the top of the script for ease of use. If a variable is defined with the same name as a previously defined variable, it is replaced with the new value for the rest of the script.
See DEFINE_VAR for more information.
Predefined and Built-in Variables
The DIR_LOOP_START and LAYER_LOOP_START and DEFINE_VAR commands all contain built-in variables.
%DIR% |
|
%FNAME_W_DIR% |
|
%FNAME% |
|
%FNAME_WO_EXT% |
|
%PARENT_DIR% |
|
%PARENT_DIRN% |
|
%RECURSE_FOLDER% |
|
%LAYER_DIR% |
|
%LAYER_FNAME_W_DIR% |
|
%LAYER_FNAME% |
|
%LAYER_FNAME_WO_EXT% |
|
%LAYER_PARENT_DIR% |
|
%LAYER_DESC% |
|
%TIMESTAMP% |
|
%TIMESTAMP_MS% |
|
%DATE% |
|
%TIME% |
|
%TIME_SINCE_START% |
|
%TIME_SINCE_LAST_LOG% |
|
%SCRIPT_FILENAME% |
|
%SCRIPT_FOLDER% |
|
%GM_MAJOR_VER% |
|
%GM_FULL_VER_W_DATE% |
|
%GM_FULL_VER_NO_DATE% |
|
%left% |
|
%right% |
|
%top% |
|
%bottom% |
|
%left% |
|
%right% |
|
%top% |
|
%bottom% |
|
%left% |
|
%right% |
|
%top% |
|
%bottom% |
|
%left% |
|
%right% |
|
%top% |
|
%bottom% |
|
%left% |
|
%right% |
|
%top% |
|
%bottom% |
|
%left% |
|
%right% |
|
%top% |
|
%bottom% |
|
%SPLIT_ATTR% |
|
%left% |
|
%right% |
|
%top% |
|
%bottom% |
|
%TILE_DIR% |
|
%TILE_FNAME_W_DIR% |
|
%TILE_FNAME% |
|
%TILE_FNAME_WO_EXT% |
|
Comments
Any lines that begin with the forward slash character (/) are considered comments and are ignored by the script processing engine. This means that you can use C or C++ style comments like // or /* at the start of your line.
Note: For user-created syntax highlight for common text editors and shared example scripts from users see the Global Mapper User Forum