Spatial Operations Scripting

Spatial Operations Scripting is a dialog that can perform a number of advanced queries, overlay operations and additional functions on vector layers containing area features.

This powerful tool can also be used within a global mapper script to perform many functions previously only available by manually using the digitizer tools.

To open this tool press the Spatial Operations button from the Digitizer(Advanced) toolbar and switch to the scripting tab, or choose Spatial Operations Query Builder... from the Analysis menu.

Overview

Global Mapper spatial scripting exposes Global Mapper spatial analysis functionality using a simple text-based script language. Users can manipulate and create Global Mapper layers and features using common spatial analysis operations, predicates, feature filtering, and feature transforms.

Spatial scripts can be created and run in the Scripting tab of the Spatial Operations dialog (Analysis / Spatial Operations). Spatial scripts can be defined in a Global Mapper script using the DEFINE_SPATIAL_OPERATIONS command and run using the RUN_SPATIAL_OPERATION command.

Note: Some of the tools used in the scripting language are exposed using other parts of Global Mapper. For example, spatial operations and predicates are also exposed in the Operations tab of the Spatial Operations dialog, feature filtering is also exposed in the Vector Query Search dialog.

Technical note: The spatial tools and concepts used in spatial scripting generally follow the OGC Simple Feature Access specification. See https://portal.ogc.org/files/?artifact_id=25355.

Important note: the current implementation of spatial scripting only supports Global Mapper area features.

Concepts

Feature Collections: Layers and Feature Sets

Spatial Operations scripts generally manipulate collections of geometric features, or feature collections. One type of feature collection is the Global Mapper layer, which are shown in the Control Center. Another is a feature set(or just set), which is a named collection of features, or references to features in a layer. Feature sets can be named, or just exist as an unnamed collection in a feature collection expression or just collection expression). Collection expressions are like arithmetic formulas, except that the operands are feature collections, and the operators are spatial analysis operations and predicates, feature transforms, and feature filtering.

One important difference between layers and feature sets are that layers persist in the Control Center, and feature sets only persist while the script is running. When the script ends, any feature sets created in the script and their contents are removed.

It is important to note that while layers contain their own features, feature sets can contain either their own features or references to existing features in a different collection. Certain spatial tools always create new features (spatial operations, spatial transforms), and other tools create feature references by default (spatial predicates, filters). When creating a new layer, new features are always created regardless of the tool used to produce them. On the other hand, when creating a new set using a spatial operation or transform, the set will be populated by new features; on the other hand, when using spatial predicates or filters, the set will contain references to existing features.

Spatial Operations

Spatial operations create new features based on the spatial relations between the features in one or two feature collections. The types of spatial operations currently available are INTERSECTION, UNION, DIFFERENCE, and SYMMETRICDIFFERENCE.

Spatial Predicates

Spatial predicates select existing features from a feature collection as they relate to features in another set. The types of spatial predicates currently available are INTERSECTS, OVERLAPS, TOUCHES, CONTAINS, EQUALS, WITHIN, and DISJOINT. A simple example: Create a feature set of areas in the “Townships” layer that intersect with any of the areas in the “Endangered Species Habitats” layer.

Transforms

Feature transforms create new features by transforming feature geometries in some way. The types of feature transforms currently available are HULL and MBR. A simple example: Create a new feature set comprised of the convex hulls of the area features in the “Townships” layer.

Filtering

Feature filtering reduces the number of features used in other spatial operations tools. In the scripting language, feature filtering is done using the same queries used by the Search Vector Data and Attribute Calculator dialogs. These queries are introduced using a WHERE term. A simple example: Filter the features in the “Townships” layer that have a “population” attribute with values less than 10000.

Syntax

Spatial Operations scripts consist of a series of command. There are several specific command types in the scripting language: some begin with a specific command name (for example, the SELECT command), and some do not (for example, assignment commands). The command names are keywords in the scripting language. In addition, the names of the Spatial Operations tools used in the scripting language, for example, INTERSECTION, CONTAINS, HULL, are also keywords. These keywords are reserved, meaning that they cannot be used as the names of feature sets. Keywords are case-independent, but by convention, in this guide, they are written in uppercase in this guide.

In general, an end-of-line character is treated as a space character (except for single-line comments; see below), so that it’s possible to string commands together all on the same line, but this can make the script harder to read and comprehend.

For example:

MySet = “Townships” WHERE population > @average(population) SELECT Myset

is equivalent to

MySet = “Townships” WHERE population > @average(population)

SELECT Myset

In Global Mapper, layers are named collections of geographic entities like points, lines, and polygons. Using the spatial operations scripting language, users can operate on Global Mapper layers using spatial analysis tools. In addition, the scripting language also supports another type of feature collection called feature sets, or just sets. Feature sets, like layers, are also named collections of Global Mapper features, except that feature sets do not appear in the Global Mapper Control Center.

In the scripting language, layer names are denoted using their Control Center names in quotes, e.g., “Maine Townships – 1984”. You may use either single or double quotes, so ‘Maine Townships – 1984’ is also valid, but the beginning quote type and the ending quote type must match. That is, “Maine Townships – 1984’ is not valid. Layer names are case independent.

By contrast, feature set names are just identifiers, that is, a letter followed by some number of letters or numbers. For example, MySet and MaineTownships84 are both valid set names, while 123MySet or My-Set are not. As with layer names, set names are case-independent.

In the script language descriptions, the terms feature collection (or just collection) is used to refer to either a Global Mapper Layer or a scripting language feature set, as in many cases, either a layer or set can be used in the same context.

When describing spatial analysis tools used in scripting, the tools use one or more feature collections. The first collection is generally referred to as the input or first collection, and the second, if present, is usually referred to as the overlay or second collection.

Spatial analysis tools generally use ‘function notation’, borrowed from programming languages. So, for example, the syntax for the INTERSECTION operation is:

<feature collection> = INTERSECTION( <input collection>, <overlay collection> )

The syntax for the CONTAINS predicate is:

<feature collection> = CONTAINS( <input collection>, <overlay collection> )

The syntax for the HULL transform is:

<feature collection> = HULL( <input collection> )

Using function notation, operations, predicates, and transforms can be nested with filtering added as well.

For example:

LAYER “MyLayer” = INTERSECTION( Set1 where ID = 43, CONTAINS( HULL(“Townships”), “Lakes” ) )

Comments may be added to spatial operations scripts. There are two types:

  • Use /* to begin a block comment and */ to end it. Everything in between will be ignored. Note that these cannot be nested. When /* is encountered, everything between that and the next */ is skipped. If the a */ comment end marker is not found after an initial /*, then the script is not valid, and will not run. Conversely, if a */ comment end marker is found with no initial /*, then the script is not valid, and will not run.
  • Use // to start a comment that will last until the end of the current text line.

Examples:

/* This is

a multi-line

comment */

// This is a single line comment

LAYER “NewLayer“ = HULL( “OldLayer” ) // comment can appear here

Spatial Scripting Reference

Creating Feature Collections

In the script language, feature collections are created and updated using feature collection assignment statements, or just assignment statements. These take two general forms, based on the target collection (either a layer or a feature set):

New layers and sets can be created using assignment statements that resemble algebraic expressions. They take the general form:

<feature collection> = <collection expression>

Here, the <feature collection> is either a layer name (for example, LAYER “NewLayer”) or the name of a feature set (for example, NewSet)

LAYER <layer name> = <feature collection expression>

<set name> =<feature collection expression>

where <layer name> is the name of a layer that will reside in the Control Center, <set name> is the user-chosen name of a feature set, and <feature collection expression> is an expression that involves some combination of other feature collections, spatial operations, predicates, transforms, or filters. Collection expressions will be discussed below.

Note that when creating a new layer, the layer name used must not already exist in the Control Center; this command can be used to create new layers only. By contrast, a set name that has been used before can be used again; the command will cause the original contents to be replaced by the new collection.

Example: Feature Collections

// Create a new layer of the townships that contain at least one entire lake

// The features in “NewLayer” are copies of features from the “Townships” layer

LAYER “NewLayer” = CONTAINS( “Townships”, “Lakes” )

// Create a new set that references the township features in the “TownShips”

// layer that contain at least one entire lake

NewSet = CONTAINS( “Townships”, “Lakes” )

// Create a new set that that contains new features that are the convex

// hulls of some townships in “Townships” layer

NewSet = HULL( “Townships” where County = “Sagadahoc” )

// Create a feature set from the “Townships” layer features

// that have an ‘area’ attribute that is less than 200

SmallTownships = “Townships” where area < 200

// Create a new layer from features in the SmallTownships set

// that intersects features in the “Lakes” layer

layer “NewLayer” = intersects( SmallTownships, “Lakes” )

Expressions

There are several types of tools that can be used in spatial analysis scripts: spatial operations, spatial predicates, feature transforms, and feature filtering.

Spatial Operations

Spatial operations are used to create new features based on the spatial relationships between features from two feature collections. The new features are stored in a separate collection. Typically, each operation uses two collections: the “input” collection and the “overlay” collection. Typically, new features retain the attributes from their original feature in the input collection but may also take on attributes from their constituent feature in the overlay collection. When attribute name conflicts occur, the name from the input collection is used, and the name from the overlay collection is modified by adding a decimal digit to guarantee uniqueness. Spatial operations currently use two feature collection operands, and use a function-like syntax:

operation-type ( feature-collection , feature-collection )

The following spatial operations available in the Global Mapper spatial analysis scripting language. The script language keyword for each operation is specified in CAPITAL LETTERS; note that in the script language, the names of operations are case-independent; that is, “Difference” is the same as “difference” and “DIFFERENCE”.

  • Intersection : The INTERSECTION operation creates a new feature for each feature of the input collection that spatially intersects with features in the overlay collection. New features retain the attributes of both features that were used to create the intersection. An intersection expression takes the form INTERSECTION(<feature-collection>, <feature-collection>).

  • Union : The UNION operation creates new feature by finding areas of overlapping areas between the input and overlay collections. For each overlapping area, a new feature is created, retaining the attributes of both of its source features. For each non-overlapping area, a new feature is created, retaining its original attributes from either the input or the overlay collections. A union expression takes the form IUNION(<feature-collection>, <feature-collection>).

  • Difference : The DIFFERENCE operation creates a new feature for features of the input collection that do not overlap features in the overlay collection. Input collection features that do overlap features in the overlay collection have overlapping areas clipped away. New features retain the attributes of their original feature from the input collection.An difference expression takes the form DIFFERENCE(<feature-collection>, <feature-collection>).

  • Symmetric Difference : The SYMMETRICDIFFERENCE operation creates new features for features from both the input and overlay collections, with areas of overlap removed. New features retain the attributes of both features that were used to create the intersection. An symmetric difference expression takes the form SYMMETRICDIFFERENCE(<feature-collection>, <feature-collection>).

Example: Spatial Operations

Here, the layer “NewLayer” consists of new features made from overlapping areas between each area feature in the “Townships” layer and “Endangered Species Habitats” layer.

LAYER “NewLayer” = INTERSECTION( “Townships”, “Endangered Species Habitats” )

An additional example which includes a commented out description:

// Create a new layer of intersecting areas of towns and wetland areas

LAYER “Wetland Areas” = INTERSECTION( “Townships”, “Wetlands” )

Spatial Predicates

Spatial predicates are used to determine which features in a feature collection bear a certain spatial relationship with features in another collection. By default, the collection of features returned by a predicate operation are references to existing features.

For example, if a user had a collection of areas representing townships in a state or county, it might be useful to determine which townships border on a body of water, also represented by an area feature in a different collection. The user could use the Intersect predicate to determine those townships. Spatial predicates currently use two feature collection operands, and use a function-like syntax:

predicate-type ( feature-collection , feature-collection )

The following spatial predicates are currently available in the Global Mapper spatial analysis scripting language. The script language keyword for each operation is specified in CAPITAL LETTERS; note that in the script language, the names of operations are case-independent; that is, “Intersects” is the same as “intersects” and “INTERSECTS”:

  • Intersects : The INTERSECTS predicate returns the features in one collection that intersect any feature in another collection.

  • Overlaps : The OVERLAPS predicate returns the features in one collection that overlap any feature in another collection.

  • Touches : The TOUCHES predicate returns the features in one collection that touch any feature in another collection.

  • Contains : The CONTAINS predicate returns the features in one collection that wholly contain any feature in another collection.

  • Equals : The EQUALS predicate returns the features in one collection that equal any feature in another collection.

  • Within : The WITHIN predicate returns the features in one collection that are wholly contained by any feature in another collection.

  • Disjoint : The DISJOINT predicate returns the features in one collection that do not intersect equal any feature in another collection.

Example: Spatial Predicates

In the above example, it is important to understand that the features contained in MySet are references to features that exist in the “Townships” layer, and not separate new features.

MySet = INTERSECTS( “Townships”, “Endangered Species Habitats” )

A second example below including descriptive comment:

// Create a new layer from the towns that intersect wetland areas

LAYER “Wetland Towns” = INTERSECTS( “Townships”, “Wetlands” )

Filters

Filters are used to make subsets of feature collections. Filters can be used to select features of specific geometry types (points, lines, or areas), or select features based on an attribute query. By default, the features in a subset are references to existing features. Attribute query filters use the same queries used in Search Vector Data. Attribute query filters are initiated using a WHERE clause after the collection expression.

Example: Feature Filtering

Output a new temporary set called MySet, containing townships with a population over 10,000.

MySet = “Townships” WHERE population > 10000

The below example creates a new layer called Small Towns.

// Create a new layer from the towns whose “population” attribute is less than 1000

LAYER “Small Towns” = “Townships” WHERE population < 1000

Transforms

Transforms are used to create new geometries by transforming the original geometries in some way. Using a transform on a collection of geometries creates new, separate geometries in a different collection. Transforms work on a single feature collection, and use a function-like syntax:

<transform type> ( <feature collection> )

The following spatial transforms are currently available in the Global Mapper spatial analysis scripting language. The script language keyword for each operation is specified in CAPITAL LETTERS; note that in the script language, the names of operations are case-independent; that is, “Intersects” is the same as “intersects” and “INTERSECTS”:

  • Convex Hulls : The HULL transform creates a convex hull from each area feature in its collection.

  • Minimum Bounding Rectangle : The MBR (for Minimum Bounding Rectangle) transform creates a minimum bounding rectangle for each feature in its collection.

Example: Transforms

A simple convex hull calculation on a layer "Townships":

MySet = HULL( “Townships” )

An advanced example of a convex hull calculation that first performs an attribute query on the layer:

// Create a new layer from convex hulls of the areas in the “Townships” layer

LAYER “Town Hulls” = HULL (“Townships” WHERE population < 1000)

Selecting Features

The script language allows the user to manage feature selection in layers using the SELECT command. Features may be added to the current selection using the ADD specifier, or the selection may be cleared using the CLEAR specifier.

To select the features in a layer, use the syntax SELECT <feature collection>.

To add features to the current selection, use the syntax SELECT ADD <feature collection>.

To clear the current selection, use the syntax SELECT CLEAR.

Note that when selecting features, the Global Mapper digitizer is automatically enabled.

Example: Selection

// Create a new feature set named ‘selected’ based on the currently selected

// features in the layer “MeTwp24.shp” that have attribute ‘area’ value

// less than the aggregate average of all ‘area’ attributes

selected = "MeTwp24.shp" WHERE IsSelected() and area < @Average(area)

// Create a new selection from the members of the set ‘selected’

SELECT selected

// Add features from layer "MeTwp24.shp" that have attribute ‘county’ value

// equal to ‘Hancock’ and ‘area’ attribute value less than 1000

SELECT ADD "MeTwp24.shp" WHERE county = "Hancock" and area < 10000

// Create a new layer named “New Selected” from the features in the set ‘selected’

LAYER "NewSelected" = selected

Error Handling

When performing spatial operations on Global Mapper features, the features are checked for validity, for example, polygon closure, orientation, self-intersection, and so on. The scripting language allows the user to choose what happens when validation errors occur. The possible behaviors are to skip the current geometry, to use it anyway (possibly leading to incorrect results) or to halt the script altogether. In addition, the script implementation may be able to repair certain types of geometry problems, and the user can choose to let the implementation try to do the repairs. The command that controls these behaviors is the ONERROR command.

To tell the script engine to skip invalid geometries, use ONERROR GEOMETRY SKIP.

To tell the script engine to ignore geometry errors and use invalid geometries anyways, use ONERROR GEOMETRY IGNORE.

To tell the script engine to halt the current script when an invalid geometry is detected, use ONERROR GEOMETRY HALT.

To tell the script engine to attempt to repair invalid geometries before acting on the main command, append the REPAIR parameter to the command. For example: ONERROR GEOMETRY SKIP REPAIR.

The default setting for scripts is to skip invalid geometries, and not attempt to repair them first. That is, it is as if the script begins with ONERROR GEOMETRY SKIP.

Script Control and Messages

The PAUSE command is used to pause script operation and show a message to the user. The user will be prompted to either halt or continue the script operation. To specify the message for the user, append a quote-delimited string to the command. For example: PAUSE ‘Intersection calculated’.

The default message, if not specified, is “Execution paused, continue?”.