Scripting Example Using RunScript¶
The RunScript function allows the SDK to run commands from the Global Mapper scripting language, which includes many of the features of the Global Mapper desktop application that are not otherwise available to the SDK. If there is something you know how to do in the Global Mapper app but cannot seem to find in the SDK, odds are it can be done with a script command. See below for the complete list of commands, or look here for a detailed reference: https://www.bluemarblegeo.com/knowledgebase/global-mapper/Scripting_Reference/Global_Mapper_Scripting_Language.htm
Scripts are written as normal text strings and can be stored either in .gms files or as string variables; RunScript will read both. A single script command will follow this general format:
EXAMPLE_COMMAND PARAM_A=x PARAM_B=y PARAM_C=z ...
The script line consists of the command followed by the parameters and their values. The names of the parameters depend on which script is being used; detailed information on which parameters are used by each command can be found in the documentation linked above. The order that the parameters are defined doesn’t matter, and not all parameters need to be defined. For example, the CALC_VOLUMES command takes the parameters FILENAME, OUTPUT_FILENAME, ADD_VOLUME_ATTRS, BASE_ELEVATION, BASE_ELEVATION_ABOVE_SEA_LEVEL, and VOLUME_UNIT, so this would be a valid script call:
CALC_VOLUMES VOLUME_UNIT=CUBIC_METERS FILENAME="myFile.tif" ADD_VOLUME_ATTRS=YES
This script would calculate the volume in meters between sea level and the raster surface of ‘myFile.tif’, and assign the result to a feature attribute of the layer. When using the RunScript function, that entire line would be the string that gets passed into the first parameter.
Here is a complete example of how a script can be used in a Python program to do something for which there is no function in the SDK; specifically, to create a raster elevation grid layer from only ground classified points. GENERATE_ELEV_GRID is a more complicated command than CALC_VOLUMES, so there are more parameters that need to be defined to use the command effectively. One of these is FILENAME, which is worth noting because it uses the filepath to the source image of a loaded layer rather than the layer handle.
import globalmapper as gm
err_code, lst_addr, lst_size = gm.LoadLayerList(filepath, gm.GM_LoadFlags_UseDefaultLoadOpts)
# setup grid parameters
gridsetup_string = "GENERATE_ELEV_GRID "
gridsetup_string += "FILENAME=" + str(filepath) + " " # use the file path, not the layer handle
gridsetup_string += "LAYER_DESC=ElevationGrid "
gridsetup_string += "SPATIAL_RES=1.0,1.0 "
gridsetup_string += "ELEV_UNITS=METERS "
gridsetup_string += "GRID_ALG=BIN_MAX "
gridsetup_string += "GRID_TYPE=ELEVATION "
gridsetup_string += "GRIDBINSIZE=2 "
gridsetup_string += "LIDAR_FILTER=\"NONE,2\""
err_code, elev_addr, num = gm.RunScript(gridsetup_string, gm.GM_LoadFlags_UseDefaultLoadOpts, 0)
layer_array = gm.GM_LayerHandle_array_frompointer(elev_addr)
elevation_grid = layer_array[0]
# do something with elevation_grid...
All Script Commands¶
ADD_MEASURE_ATTRS - Adds/Updates Measure Attributes to Features in a Layer
APPLY_FORMULA - Applies a Formula to Loaded Raster Layers to Create a New One
ASSIGN_TYPE - Deprecated, Use EDIT_VECTOR Instead
CALC_ATTR - Calculate a New Attribute Value Based on Existing Attribute(s) and a Second Value
CALC_ATTR_FORMULA - Calculate a New Attribute Value Based on a Formula Combining Existing Attributes
CALC_VOLUMES - Calculate the Volume of Areas Using Current Elevation Data
CALC_VOLUME_BETWEEN_SURFACES - Calculates the volume between two elevation grids
COMBINE_LINES - Combines Connected Line Features Into New Lines or Areas Based on Attribute Values
COMBINE_TERRAIN - Combines Two Loaded Terrain Layers to Generate a New Terrain Layer
COPY_ATTRS - Copies Attributes from One Type of Features to Another Spatially
COPY_LAYER_FILES - Copies the Base Files for Loaded Layers to a New Disk Location
CROP_AREAS_TO_LINES - Split or crop area features based on line features
DEFINE_LAYER_STYLE - Define a Layer Style for Later Use
DEFINE_PROJ - Define a Projection for Later Use
DEFINE_SDB_CONNECTION - Define an Spatial Database Connection
DEFINE_SHADER - Define an Elevation/Slope Shader for Later Use
DEFINE_SHAPE - Define a Shape (i.e. Polygon) for Later Use
DEFINE_TEXT_FILE - Define Embedded Text File with Features to Load with IMPORT_ASCII
DEFINE_VAR - Define a Variable for Later Use
DEFINE_VAR_TABLE - Define a Table of Variable Values for Lookup
DIR_LOOP_END - Ends a Loop of Commands Over Files in a Directory
DIR_LOOP_START - Start a Loop of Commands Over Files in a Directory
EDIT_MAP_CATALOG - Creates or Edits a Map Catalog
EDIT_VECTOR - Edit Loaded Vector Features that Match a Type/Name/Attribute Query
EMBED_SCRIPT - Runs Another Script File Within This Script
EXPORT_ANY - Automatically Use Proper Export Command Based on Target TYPE
EXPORT_CLOUD - Export data to cloud (Amazon s3)
EXPORT_ELEVATION - Export Elevation Data to a File
EXPORT_METADATA - Export Metadata for a Layer to a File
EXPORT_PACKAGE - Export Data to a Global Mapper Package File
EXPORT_PDF - Export Data to a PDF File
EXPORT_PDF3D - Export Data to a 3D PDF File
EXPORT_RASTER - Export Raster and Elevation Data to a File
EXPORT_VECTOR - Export Vector Data to a File
EXPORT_VECTOR_SPATIAL_DB
EXPORT_WEB - Export Vector Data to a File
FORCE_EXIT - Forces Global Mapper to Immediately Exit with a Return Code
GENERATE_CONTOURS - Generate Contours from Elevation Data
GENERATE_ELEV_GRID - Generates an Elevation Grid from Loaded 3D Vector Data
GENERATE_EQUAL_VAL_AREAS - Generates Area Features from Equal Values in Elevation/Terrain Layers
GENERATE_LAYER_BOUNDS - Generates a Layer with Bounding Area Features for each Loaded Layer
GENERATE_PATH_PROFILE - Generate a 3D Path Profile and Save it to a XYZ File
GENERATE_POINTS_FROM_ELEV_GRID - Generate points at elevation cell centers
GENERATE_REPORT - Generates a Report on the Loaded Vector Features
GENERATE_RIDGE_LINES - Generate Ridge Lines from Elevation Data
GENERATE_VIEWSHED - Generate Viewshed from Elevation Data
GENERATE_WATERSHED - Generate Watershed from Elevation Data
GLOBAL_MAPPER_SCRIPT - Script Header Line
IF/ELSE_IF/ELSE/END_IF - Conditional Execution Based on Variable Values (If/Then/Else)
IMPORT - Import Data From a File
IMPORT_ARCHIVE - Import Data From an Archive File (.zip, .tar.gz, etc.)
IMPORT_ASCII - Import Generic ASCII Data from a File
IMPORT_CLOUD - Import Cloud Dataset
IMPORT_DIR_TREE - Import All Data Files in a Directory Tree
IMPORT_OSM_TILE - Import Tiled (OSM/TMS/Google Maps/Bing Maps) Online Source
IMPORT_SPATIAL_DB - Import a Spatial Database
IMPORT_TERRASERVER - Deprecated, Terraserver-USA/MSRMAPS.COM Servers Down as of May 1, 2012
IMPORT_WMS - Import WMS Layer
JOIN_TABLE - Joins Attributes from a File to a loaded Vector Layer
LAYER_LOOP_END - Ends a Loop of Commands Over Loaded Layers
LAYER_LOOP_START - Start a Loop of Commands Over Loaded Layers
LIDAR_CLASSIFY - Automatically Classify Lidar Points
LIDAR_COMPARE - Compare point cloud to control points.
LIDAR_EXTRACT - Automatically Extract Building Outlines and Tree Points from Lidar
LOAD_PROJECTION - Loads a New Global Projection From a PRJ File
LOAD_STYLE_FILE - Loads a Style/Type File (.gm_style)
LOAD_TYPE_FILTER - Deprecated, Use SET_OPT Instead (Loads a Lidar Filter or Type Filter from a GMF (Global Mapper Filter) File)
LOG_MESSAGE - Logs a Status Message
MAP_LAYOUT - Define the Map Layout (Margins, Scale, etc.)
PAN_SHARPEN - Pan Sharpens a Color Layer with Pan Image (Creates New Layer)
PLAY_SOUND - Plays a Beep or a Specified Sound File
QUERY_LAYER_METADATA - Place Layer Metadta Value in a Variable
RESTORE_LAST_SAVED_VIEW - Restores Last Saved View
RUN_COMMAND - Runs a Command Line
SAVE_CURRENT_VIEW - Saves Current View
SAVE_PROJECTION - Saves the Current Global Projection to a PRJ File
SAVE_WORKSPACE - Saves Workspace (GMW) File with Loaded Layers
SET_BG_COLOR - Sets the Background Color
SET_LAYER_OPTIONS - Updates Display Options of Loaded Layer
SET_LOG_FILE - Sets the Name of the Log File
SET_OPT - Sets General Options (Like Position Display Format, Display Options, etc.)
SET_VERT_DISP_OPTS - Set Vertical Display Options
SET_VIEW - Sets the Display View
SHIFT_LAYER - Shifts the location of a layer by the specified distance.
SHOW_3D_VIEW - Displays the 3D View Window
SORT_LAYERS - Sorts the Loaded Layers Based on Some Criteria
SPLIT_LAYER - Splits a Layer Based on an Attribute
UNLOAD_ALL - Unloads All Currently Loaded Data
UNLOAD_LAYER - Unloads a Single Layer
VAR_LOOP_END - Ends a Loop of Commands Over a Range of Values
VAR_LOOP_START - Start a Loop of Commands Over a Range of Numeric Values
VIEW_LAYOUT - Define the Multi-View Layout