Scripting Language Reference

Contents

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, and export it to a new file.

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

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.

Batch Mode Operation

You can run a Global Mapper script file automatically be passing it on the command line to the Global Mapper .exe file. The script file will be run with no user interface displayed and Global Mapper will immediately exit when the script file completes processing. This allows you to easily run Global Mapper scripts from another application or from a DOS batch file. Note that your script files need to have an extension of .gms for this to work.

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.

ADD_MEASURE_ATTRS

The ADD_MEASURE_ATTRS command allows you to add/update feature measure attributes to all of the line and area features in a loaded vector layer.

The following parameters are supported by the command:

ASSIGN_TYPE

The ASSIGN_TYPE command allows you to assign feature types (classifications) based on one or more attribute or label values. You can choose to update area, line, and or point features with a single operation. You can also supply multiple COMPARE_STR parameters to apply multiple criteria, all of which must be true, in order to assign a type.

The following parameters are supported by the command:

For an example of how to use the ASSIGN_TYPE command, see the sample at the bottom of this document.

COMBINE_TERRAIN

The COMBINE_TERRAIN command generates a new terrain (gridded elevation) layer by combining two loaded terrain layers through some operation, like addition, subtraction (difference), average, min/max, etc. The new terrain layer can then be operated on just like any other terrain layer.

The following parameters are used by the COMBINE_TERRAIN command:

DEFINE_PROJ

The DEFINE_PROJ command allows a projection (including datum) to be associated with a name. The projection name can then be used in later IMPORT, IMPORT_ARCHIVE, IMPORT_ASCII, and LOAD_PROJECTION commands to specify a projection as needed.

The DEFINE_PROJ command consists of a single command line followed by a series of lines describing the projection in the format of an ESRI PRJ file. The easiest way to determine the text for a projection is to setup a projection on the Projection tab of the Tools->Configuration and then use the Save to File button to create a new .prj file. Then just open the .prj file up in Notepad and copy the contents to the lines following the DEFINE_PROJ command line.

The DEFINE_PROJ command is terminated with a single line containing only the text END_DEFINE_PROJ.

For a sample of the DEFINE_PROJ command in use, load some data and then save a Global Mapper workspace file from the File->Save Workspace menu command. Open the resulting .gmw file in an editor and you can see how the DEFINE_PROJ command is used to define a view projection and the set it.

The following parameters are required by the DEFINE_PROJ command.

DEFINE_SHAPE

The DEFINE_SHAPE command allows a multi-point shape (like a polygon) to be associated with a name. The projection name can then be used in later commands for things like cropping and feathering to polygonal boundaries.

The DEFINE_SHAPE command consists of a single command line followed by a series of lines describing the series of XY coordinate pairs that define the shape. Each line should have a single coordinate value with the X and Y coordinates separated by a comma.

The DEFINE_SHAPE command is terminated with a single line containing only the text END_DEFINE_SHAPE.

The following parameters are required by the DEFINE_SHAPE command.

Here is an example of a DEFINE_SHAPE command used to define a feather polygon with a name of 'FEATHER_POLY'

DEFINE_SHAPE SHAPE_NAME="FEATHER_POLY"
	377493.234,4323974.016
	375343.359,4318676.109
	381101.953,4314414.750
	387014.109,4317178.875
	386975.719,4322400.000
	381869.766,4324588.266
	377493.234,4323974.016
END_DEFINE_SHAPE

DIR_LOOP_END

The DIR_LOOP_END command ends a loop of commands over all of the folders within a directory. See the DIR_LOOP_START command for details.

DIR_LOOP_START

The DIR_LOOP_START command begins a loop of commands over all of the folders within a directory (and optionally its subdirectories) that match one or more filename masks. This is a powerful feature allowing you to do things like easily batch convert a collection of files or perform any other supported operation over a collection of files. You end a loop over the files in a folder using the DIR_LOOP_END command. Note that it is also possible to nest loops.

For any commands found within a DIR_LOOP_START...DIR_LOOP end pair defining a loop, the following special character sequences can be used anywhere (examples of what the values will be based on a current filename of 'C:\data\my_file.dem' are listed):

For a sample of the DIR_LOOP_START command in use, see the example at the bottom of this reference.

The following parameters are used by the DIR_LOOP_START command.

EMBED_SCRIPT

The EMBED_SCRIPT command allows you to call another script from within a script. This can be useful in many situations. For example, if you have a common set of data files that you want to load for each script operation, you could simply create a script that loaded those files, then embed that script within your other scripts.

The following parameters are supported by the command:

EXPORT_ELEVATION

The EXPORT_ELEVATION command exports all currently loaded elevation data to a file. The following parameters are supported by the command.

EXPORT_METADATA

The EXPORT_METADATA command exports the metadata for a specified load layer. The following parameters are supported by the command.

EXPORT_PACKAGE

The EXPORT_PACKAGE command exports all currently loaded raster, vector, and elevation data to a Global Mapper Package (GMP) file. The following parameters are supported by the command.

EXPORT_RASTER

The EXPORT_RASTER command exports all currently loaded raster, vector, and elevation data to a file. The following parameters are supported by the command.

EXPORT_VECTOR

The EXPORT_VECTOR command exports all currently loaded vector data to a file. The following parameters are supported by the command.

GENERATE_CONTOURS

The GENERATE_CONTOURS command allows for the generation of contour lines (isolines of equal elevation) from any or all currently loaded elevation data. The following parameters are supported by the command.

GENERATE_ELEV_GRID

The GENERATE_ELEV_GRID command allows for the generation of a gridded elevation layer using loaded 3D vector data. The following parameters are supported by the command.

GENERATE_LAYER_BOUNDS

The GENERATE_LAYER_BOUNDS command create a new layer with a single bounding box area created from the bounding box of each loaded layer.

GENERATE_PATH_PROFILE

The GENERATE_PATH_PROFILE command allows for the saving of a 3D path profile to an ASCII XYZ file. This command uses loaded elevation data to generate a list of the 3D coordinates between two given points in the given elevation units. The following parameters are supported by the command.

GLOBAL_MAPPER_SCRIPT

The GLOBAL_MAPPER_SCRIPT must be the first command in the file. The only parameter supported is the VERSION parameter. Typically, the entire command line will look like: 

GLOBAL_MAPPER_SCRIPT VERSION=1.00

You can use the following parameters with this command:

GENERATE_REPORT

The GENERATE_REPORT command allows you to generate a CSV text report file on the data in one or more loaded layers broken down by a particular attribute value, feature name, or type, or just a single line report about all features. The report will include the count of area, line, and point features matching the specified criteria as well as the total combined length of the line features and combined covered area of the area features.

The following parameters are supported by the command:

IMPORT

The IMPORT command imports a data file for later use. The following parameters are supported by the command.

  • ALLOW_SELECTION - set to NO to disable selection of features from this layer using either the Feature Info or Digitizer Tools.

    IMPORT_ARCHIVE

    The IMPORT_ARCHIVE command imports a data file from a .tar.gz archive for later use. The only time you should ever need to use the IMPORT_ARCHIVE command is when you only want to load some of the data inside a .tar.gz archive. For the typical case of just loading everything in an archive, use the IMPORT command with AUTO as the value for the TYPE parameter. The following parameters are supported by the command.

    IMPORT_ASCII

    The IMPORT_ASCII command imports data from a generic ASCII text file for later use. The following parameters are supported by the command.

    SAMPLE: 

    IMPORT_ASCII FILENAME="C:\data\ASCII Files\usvi_landmark.asc" TYPE=POINT_AND_LINE COORD_DELIM=AUTO COORD_ORDER=X_FIRST COORD_PREFIX="XY,"INC_COORD_LINE_ATTRS=NO

    IMPORT_DIR_TREE

    The IMPORT_DIR_TREE command imports all of the data files in a given directory tree that match a list of filename masks. The following parameters are supported by the command. In addition, all of the display option parameters for the IMPORT command are also supported for this command.

    SAMPLE: 

    IMPORT_DIR_TREE DIRECTORY="C:\TEMP\EXPORT TEST" FILENAME_MASKS="*.OPT *.GMP"

    IMPORT_TERRASERVER

    The IMPORT_TERRASERVER command imports a chunk of TerraServer data, such as satellite imagery or topographic maps. The following parameters are supported by the command:

    LOAD_PROJECTION

    The LOAD_PROJECTION command imports a projection from a PRJ file and makes it the current global projection. This projection will be used for all exports after this command until another LOAD_PROJECTION command is encountered to change the global projection. The following parameters are supported by the command:

    LOAD_STYLE_FILE

    The LOAD_STYLE_FILE command load a Global Mapper Style (.gm_style) file containing style definitions for a list of types. You can optionally choose to have any types specified in the style file that aren't present in the running instance of Global Mapper to be added, providing a script way to add new custom types. The following parameters are supported by the command:

    LOAD_TYPE_FILTER

    The LOAD_TYPE_FILTER command load a type filter from a Global Mapper Filter (GMF) file. You can create new GMF files from the type filter dialogs accessible from the Vector Display tab of the Configuration dialog. The following parameters are supported by the command:

    PLAY_SOUND

    The PLAY_SOUND command plays either the information sound for the system or a specified sound file. This can be useful if you want audible confirmation when a script completes. The following parameters are supported by the command.

    RESTORE_LAST_SAVED_VIEW

    The RESTORE_LAST_SAVED_VIEW command restores the last view saved with the SAVE_CURRENT_VIEW command (or the last view saved with the View->Save Current View menu command in the Global Mapper user interface). This command does not take any parameters.

    SAVE_CURRENT_VIEW

    The SAVE_CURRENT_VIEW command saves the current view window for later restoration using the RESTORE_LAST_SAVED_VIEW command. This command does not take any parameters.

    SAVE_PROJECTION

    The SAVE_PROJECTION command saves the current global projection to a PRJ file. The following parameters are supported by the command.

    SET_BG_COLOR

    The SET_BG_COLOR command sets the color to use for any background pixels when rendering layers. The following parameters are supported by the command.

    SET_LOG_FILE

    The SET_LOG_FILE command sets the name of the file to log status, warning, and error messages to. If the log file specified already exists, the messages will be appended to the end of it. The following parameters are supported by the command.

    SET_VERT_DISP_OPTS

    The SET_VERT_DISP_OPTS command allows you to modify the options used when rendering elevation layers, such as the shader to use, if any, as well as the lighting and water setup. The following parameters are supported by this command:

    SHOW_3D_VIEW

    The SHOW_3D_VIEW command displays the 3D view window with the loaded data.

    The following parameters are supported by the command:

    UNLOAD_ALL

    The UNLOAD_ALL command unloads all currently loaded data. This command takes no parameters.

    The following parameters are supported by the command:

    UNLOAD_LAYER

    The UNLOAD_LAYER command allows you to unload all previous loaded layers with a given filename. This is useful if you don't want to unload all previously loaded layers just to get rid of a few of them.

    The following parameters are supported by the command:

    Crop, Merge, and Reproject 4 USGS DRGs into new GeoTIFF and JPEG files
    GLOBAL_MAPPER_SCRIPT VERSION=1.00
UNLOAD_ALL

// Import the four 24K DRGs that we want to merge. We use the CLIP_COLLAR option
// to indicate that we want the collar to be automatically removed from the
// DRGs when they are imported.
IMPORT FILENAME="C:\DATA\DRG\KANSAS CITY\O39094B2.TIF"                      \
    TYPE=AUTO ANTI_ALIAS=NO AUTO_CONTRAST=NO CLIP_COLLAR=AUTO TEXTURE_MAP=NO
IMPORT FILENAME="C:\DATA\DRG\KANSAS CITY\O39094A1.TIF"                      \
    TYPE=AUTO ANTI_ALIAS=NO AUTO_CONTRAST=NO CLIP_COLLAR=AUTO TEXTURE_MAP=NO
IMPORT FILENAME="C:\DATA\DRG\KANSAS CITY\O39094A2.TIF"                      \
    TYPE=AUTO ANTI_ALIAS=NO AUTO_CONTRAST=NO CLIP_COLLAR=AUTO TEXTURE_MAP=NO
IMPORT FILENAME="C:\DATA\DRG\KANSAS CITY\O39094B1.TIF"                      \
    TYPE=AUTO ANTI_ALIAS=NO AUTO_CONTRAST=NO CLIP_COLLAR=AUTO TEXTURE_MAP=NO

// Load a projection file to set the global projection to geographic (lat/lon)
// arc degrees with a datum of NAD83.
LOAD_PROJECTION FILENAME="C:\DATA\PRJ Files\geo_degrees_nad83.prj"

// Use the EXPORT_RASTER command to generate a new 8-bit per pixel GeoTIFF file
EXPORT_RASTER FILENAME="C:\DATA\EXPORTED DATA\merged_drg_8bpp.tif"          \
    TYPE=GEOTIFF PALETTE=OPTIMIZED

// Now, use the EXPORT_RASTER command to generate a grayscale GeoTIFF file. Lets
// also create a world file for this one
EXPORT_RASTER FILENAME="C:\DATA\EXPORTED DATA\merged_drg_gray.tif"          \
    TYPE=GEOTIFF PALETTE=GRAYSCALE GEN_WORLD_FILE=YES

// Create a JPEG file using the EXPORT_RASTER command. Also create a world file
// and a projection file to make it easier to load in other places.
EXPORT_RASTER FILENAME="C:\DATA\EXPORTED DATA\merged_drg.jpg"				\
    TYPE=JPEG GEN_WORLD_FILE=YES GEN_PRJ_FILE=YES

    Generate Contours from all USGS DEMs in a Folder and Export them to DXF and Shape files 
    GLOBAL_MAPPER_SCRIPT VERSION=1.00
UNLOAD_ALL

// Loop over all DEM files in a folder and convert them
DIR_LOOP_START DIRECTORY="C:\DATA\SDTS_DEM\24K\" FILENAME_MASKS="*.DEM.STDS.TAR.GZ" RECURSE_DIR=NO

	// Import an archived SDTS DEM file. Global Mapper will automatically 
	// determine that this is an archived SDTS DEM file and load it
	// correctly.
	IMPORT FILENAME="%FNAME_W_DIR%" ANTI_ALIAS=YES 

	// Generate 50 ft contours from the loaded DEM data.
	GENERATE_CONTOURS INTERVAL=50 ELEV_UNITS=FEET

	// Export the contours to a new DXF file. The created file will have
	// 3D polyline features for the contours.
	EXPORT_VECTOR FILENAME="%DIR%%FNAME_WO_EXT%_CONTOURS.DXF" TYPE=DXF GEN_PRJ_FILE=YES

	// Export the contours to a 3D shape file.
	EXPORT_VECTOR FILENAME="%DIR%%FNAME_WO_EXT%_CONTOURS.SHP" TYPE=SHAPEFILE  \
		SHAPE_TYPE=LINES GEN_3D_LINES=YES GEN_PRJ_FILE=YES
		
	// Unload the loaded data
	UNLOAD_ALL

// End the loop
DIR_LOOP_END

    Reclassify Features Based on an Attribute and Display Label 
    GLOBAL_MAPPER_SCRIPT VERSION=1.00

// Import the file to modify
IMPORT FILENAME="C:\Temp\export test\tiger_wyandotte_sample.gmp"
	 
// Assign the type "railroad" to all features with a CFCC attribute with a value of A41
// and a display label with '74' in it somewhere.
ASSIGN_TYPE LINE_TYPE="RAILROAD" COMPARE_STR="CFCC=A41" COMPARE_STR="<Feature Name>=*74*"