Skip to main content

Scripting Example Using RunScript

Updated

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.

Export Raster Elevation Grid

Note: Before running this sample, configure these variables:

  • file_path: the file path to sample data

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

filepath = "Z:/GM-20069/using_script_commands_sample_data/Portland_Unclassified.laz"

# 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.

err_LoadLayerList, array_pointer, array_size_param = gm.LoadLayerList(
    filepath, gm.GM_LoadFlags_HideAllPrompts
)

# Get handle for the loaded layers
arr_ptr, arr_size = gm.GetLoadedLayerList()
layers_array = gm.GM_LayerHandle_array_frompointer(arr_ptr)
layers_list = gm.carray_to_list(layers_array, arr_size)

### START SAMPLE
# Setup grid parameters
gridsetup_string = "GENERATE_ELEV_GRID "
gridsetup_string += "FILENAME=" + str(filepath) + " "
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 += "SET_OPT=\"NONE,2\""

err_RunScript, elev_addr, num = gm.RunScript(
    gridsetup_string, gm.GM_LoadFlags_UseDefaultLoadOpts, 0
)

# From here, you can get the created layer handle and 
# perform operations with elevation_grid.

### END SAMPLE

arr_ptr, arr_size = gm.GetLoadedLayerList()
layers_array = gm.GM_LayerHandle_array_frompointer(arr_ptr)
err = gm.CloseLayer(layers_array[0])
err = gm.CloseLayer(layers_array[1])

assert (
    gm.GM_Error_None == err_LoadLayerList
), f"LoadLayerList: Expected {gm.GM_Error_None}, got {err_LoadLayerList}"
assert (
    gm.GM_Error_None == err_RunScript
), f"RunScript: Expected {gm.GM_Error_None}, got {err_RunScript}"

Export LAS/LAZ Files

Note: Before running this sample, configure these variables:

  • run_script_dir: the absolute path of the directory to be exported to

This script is an example of how to export lidar data as a LAS/LAZ file using the RunScript function. The idea is that you load lidar data, make modifications to it like adding/removing points, altering attributes, classifying it, etc. and then export the modified file into a specified directory. An important component of this sample is that FILENAME needs to be assigned the absolute file path to the file being created, otherwise it will not export properly. The exported file type is determined by its extension. For example, fileName.las will export a LAS file whereas fileName.laz will export a LAZ file. The extension for this sample is .laz, this is not seen though as it is included in ‘layer_name’ because a LAZ file was the previously loaded layer.

import os
import globalmapper as gm

filepath = "Z:/GM-20069/using_script_commands_sample_data/SM_Augusta_Classified.laz"
run_script_dir = os.path.join(os.path.dirname(os.path.dirname(__file__)), "../../misc/runscript_sample_output/")
os.makedirs(run_script_dir, exist_ok=True)

# This script is an example of how to export lidar data as a LAS/LAZ file using the RunScript function. The idea is that you
# load lidar data, make modifications to it like adding/removing points, altering attributes, classifying it, etc. and then 
# export the modified file into a specified directory. An important component of this sample is that FILENAME needs to be
# assigned the absolute file path to the file being created, otherwise it will not export properly. The exported file type
# is determined by its extension. For example, fileName.las will export a LAS file whereas fileName.laz will export a LAZ file.
# The extension for this sample is .laz, this is not seen though as it is included in 'layer_name' because a LAZ file was the
# layer loaded previously.

err_LoadLayerList, array_pointer, array_size_param = gm.LoadLayerList(
    filepath, gm.GM_LoadFlags_HideAllPrompts
)

# Get handle for the loaded layers
arr_ptr, arr_size = gm.GetLoadedLayerList()
layers_array = gm.GM_LayerHandle_array_frompointer(arr_ptr)
layers_list = gm.carray_to_list(layers_array, arr_size)

### START SAMPLE
# Exports the lidar data, reflecting new changes
# Get the name of the layer to be exported
layer_name = gm.GetLayerInfo(layers_list[0]).mDescription
# Use the RunScript func to export lidar data as a .laz file
export_string = "EXPORT_VECTOR "
export_string += "FILENAME=" + run_script_dir + "new_" + layer_name + " "
export_string += "EXPORT_LAYER=" + layer_name + " "
export_string += "TYPE=LIDAR_LAS "
export_string += "ELEV_UNITS=METERS "
export_string += "VERT_CS_CODE=NAVD88 "
err_RunScript, handle, size = gm.RunScript(
    export_string, gm.GM_LoadFlags_UseDefaultLoadOpts, 0
)

### END SAMPLE

assert (
    gm.GM_Error_None == err_LoadLayerList
), f"LoadLayerList: Expected {gm.GM_Error_None}, got {err_LoadLayerList}"
assert (
    gm.GM_Error_None == err_RunScript
), f"RunScript: Expected {gm.GM_Error_None}, got {err_RunScript}"

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

Related articles