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.

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_OPERATION or BEGIN_SPATIAL_OPERATION commands and run using the RUN_SPATIAL_OPERATION command.

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, MBR, and BUFFER. 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.

Features can also be filtered by geometry type or currently selected features by including the type (points, lines, areas) or the term selected in brackets after naming a feature collection. Ex: "layer 1"[lines, selected] will filter to only currently selected line features in layer 1.

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.

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.

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.

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.

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)

To specify the feature geometry for the results of an expression, a third parameter can be added specifying points, lines, or areas. For further information on valid input and result geometry combinations for each operation, see Spatial Operations.

operation-type ( feature-collection , feature-collection, results[geometry])

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 features by finding overlap 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 UNION(<feature-collection>, <feature-collection>).

• Union Single: Similar to the UNION operation the union single uses only one input layer and creates new features by finding overlap between the features in the layer. A union single expression takes the form UNION(<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>).

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 )

To specify the feature geometry for the results of an expression, a third parameter can be added specifying points, lines, or areas.

operation-type ( feature-collection , feature-collection, results[geometry])

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.

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), select features based on an attribute query, or current selection status. 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.

<feature collection> WHERE <attribute query>

Add a filter for geometry type in brackets after a feature collection name. Accepted values are point, lines, and areas. Multiple types can be listed separated by commas.

<feature collection>[geometry type]

Filter a feature collection based on the currently selected features by adding selected in brackets after the feature collection name.

<feature collection>[selected]

Layer Filters

Layer filters can be used to define a new layer or feature collection based on the valid, invalid, or currently selected features.

<filter> ( <feature collection >)

• Valid Geometry: The VALID filter creates a new feature collection of the valid features from the specified layer.
• Invalid Geometry: The INVALID filter creates a new feature collection containing the invalid features from the specified layer.
• Currently Selected: The SELECTION filter creates a new layer containing only the currently selected features. No layer can be specified with this operation. A geometry type filter can be added to this command ex: SELECTION[areas] to return only the selected areas in the new layer.

Units

The linear units to be used throughout the script can be specified with the DEFAULT UNITS command. This takes the form DEFAULT UNITS <unit>.

Valid unit values are: 

• Meters: m, meter, meters, metre, metres

• Kilometers: km, kilometer, kilometers, kilometre, kilometres

• International feet: ft, foot, feet

• US feet: usft, usfoot, usfeet

• Miles: mi, mile, miles

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.

• Buffer Feature(s): The BUFFER transform creates buffer features from the specified feature collection. This transform functions similarly to the Buffer Feature Creation. For this transform a linear unit can be specified, the defined default unit for the script will be used, or meters will be used as a default.

  BUFFER( <feature collection> , <distance>)

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.

To remove features from the current selection use the syntax SELECT DELETE <feature collection>.

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

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?”.