Spatial Operations Scripting

Spatial Operations Scripting is a dialog that allows the user to create and execute spatial scripts, which can perform a number of advanced queries, overlay operations and additional functions on vector layers. Spatial script commands may also be used within a Global Mapper script to perform many functions previously only available by manually using the digitizer tools.

Spatial Operations Scripting exposes Global Mapper spatial analysis functionality using a simple text-based script language. In the Spatial Operations Scripting dialog, users can perform a number of advanced queries, overlay operations and additional functions on vector layers.

While editing a spatial script, the dialog constantly checks the script syntax, and gives the location and reason for the first syntax error it encounters, if there are any. The Run button is enabled only if there are no syntax errors in the script. After creating a Spatial Operations script in this dialog box, click Run to execute the entire script. To run only a portion of the created script, select a section of the script and hold the Control key when you click Run to execute only part of the script that is selected in the edit box.

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

Spatial scripts can be created and run in the Scripting tab of the Spatial Operations dialog, but can also be defined and run in a Global Mapper script using the DEFINE_SPATIAL_OPERATION or BEGIN_SPATIAL_OPERATION commands.

Concepts

Feature Collections: Layers and Feature Sets

Spatial Operations scripts generally manipulate collections of geometric features, or just "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 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 execution ends, any feature sets created in the script and their contents are removed, unless they have been saved as layers.

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. In general, 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 in another collection.

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 identify existing features from a feature collection as they relate to features in another collection. Once identified, predicate results may be used to create new layers or for modifying the current Global Mapper feature selection. The types of spatial predicates currently available are INTERSECTS, OVERLAPS, TOUCHES, CONTAINS, EQUALS, WITHIN, DISJOINT, and RELATE. 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. Transforms may be applied to individual geometries or to groups of geometries in a collection. The types of feature transforms currently available are HULL, MBR, CIRCLE, CENTROID, CIRCLE, BUFFER, CONVEX HULL, CONCAVE HULL, and DISSOLVE. 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 commands. 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 set" (or just "set"). 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 term "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.

Loading and Unloading Layers

• Load : the Load function will load a layer or layers from the named file.

  LAYER LOAD <filename>

• Unload : The Unload function will unload a layer from the workspace.

  LAYER UNLOAD <layer name>

 

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.

• Relate: the RELATE predicate returns the set of features from one layer using a DE-9IM formatting string to designate relations between the Inner, Outer and Boundary portions of pairs of geometries.

 

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 feature collection containing only the currently selected features. No layer can be specified with this filter. A feature type filter can be modify this filter; for example:  use SELECTION[areas, lines] to return only the selected areas and lines in the new layer.

• Filter by MBR (Minimum Bounding Rectangle): An MBR filter can be used to select or filter geometries that intersect a given MBR. The general syntax for specifying MBRs is:

MBR( left, top, right, bottom )

where 'left', ;'right', 'top', and 'bottom' are all coordinates in the global projection. Note that MBRs must be normalized, i.e., left </= right, and bottom </= top. Filter by MBR also works with attribute queries.

 

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>, grouping:<grouping>)

Spatial transforms are executed on groups of features within a layer. The following grouping options are available:

• None will consider each feature as its own group, executing the spatial transform for each feature in the selected layer. This is the default if no grouping is specified in the transform. To specify no grouping, use the grouping:none parameter.
• Partition allows the grouping of features using matching attributes. One or more layer attribute names may be specified. Each group is composed of features whose attributes match. The spatial transform will be executed for each group of features identified. To use partitioning by attribute, use grouping:partition (<attribute list>), where an attribute is quote-delimited, and multiple attributes are separated by a comma (','). For example: grouping: partition( "Attribute1", "Attribute2")
• All will consider all the features in the layer as a single group. To specify this, use the grouping:all parameter.

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, “buffer” is the same as “buffer” and “BUFFER”.

• Minimum Bounding Rectangle : The MBR (for Minimum Bounding Rectangle) transform creates a minimum bounding rectangle for each feature in its collection. MBR ( <feature collection>, grouping:<grouping>)
• Center: The CENTER transform generates the center point of the MBR of each of the geometry groups. CENTER ( <feature collection>, grouping:<grouping>)
• Centroid: The CENTROID transform generates the geometric center point of each of the geometry groups. CENTROID ( <feature collection>, grouping:<grouping>)
• Circle: The CIRCLE transform generates a circle area of the given radius around the center point of each of the geometry groups. As a special case, a radius of zero generates a minimum enclosing circle around the group; the center will generally not be at the center of the geometry's MBR. Specify the radius using radius:value as an additional parameter in the transform. 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. CIRCLE( <feature collection> , distance:<distance>, grouping:<grouping>)
• 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:<distance>, grouping:<grouping>)
• Convex Hulls : The CONVEXHULL transform creates a convex hull from each area feature in its collection. CONVEXHULL ( <feature collection>, grouping:<grouping>)
• Concave Hulls: The CONCAVEHULL transform generates a concave hull around each the geometry groups. A smoothing parameter determines how precisely to follow the edge of features to contain them. A rough concave hull will typically include more vertices and may contain more concave sections. A smooth hull value will simplify the boundary to generate a less complex bounding feature. Any smoothing value zero or above is valid. CONCAVEHULL( <feature collection> , smoothing:<hull smoothing>, grouping:<grouping>)
• Dissolve: The DISSOLVE transform creates a new layer by combining overlapping geometries and converting them into multi-geometries. The Dissolve transform can only be executed on area features, and grouping:none is not allowed. DISSOLVE ( <feature collection>, grouping:<grouping>)

 

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, removed from the current selection using the REMOVE specifier, or the selection may be cleared using the CLEAR specifier. Note that when selecting features, the Global Mapper digitizer is automatically enabled.

To select all of 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 reverse the current selection, use the syntax SELECT INVERT.

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

To select features that intersect a circle, as defined by its XY center and a radius in units, use the below syntax. Center coordinates are assumed to be in global coordinates. Radius units, if not specified, are also assumed to be in global units.

'select' [ 'add' | 'delete' ] <layer> 'circle' 'center' <number> ',' <number> 'radius' <number> <units>

In addition to using feature collections to specify features to consider for selection, you may also specify an MBR to select features with MBR( left, top, right, bottom ). This works in much the same way as a sweep select operation using the mouse in Global Mapper. In this case, a minimum bounding rectangle denoting the selection rectangle must be specified, in the current global units.

 

Attribute Management

Spatial operations can be used to add, remove, or edit attributes for a feature collection. Operators ADD, DELETE, and RENAME are used to manage and change attributes.

To add a new attribute to a feature set use attribute ADD with the syntax <feature collection> attribute ADD <attribute-name = attribute-formula> To create a formula see the Formula Calculator 

To delete an attribute use attribute DELETE with the syntax <feature collection> attribute DELETE <attribute-name>

To rename an attribute use attribute RENAME with the syntax <feature collection> attribute RENAME <attribute-name> <new-attribute-name>

 

Auto-styling generated features

By default generated features inherit the style settings of the parent layers. In spatial scripting, use AUTOSTYLE to set a specific or default random color to generated layers. Autostyle is off by default, and is currently limited to area features.

To enable auto-styling, use AUTOSTYLE ON

To disable auto-styling use, AUTOSTYLE OFF

To set auto-style parameters, any of the ‘fillcolor’, ‘linecolor’, or ‘linewidth’ specifiers may be used:

autostyle [fillcolor <color>]

autostyle [linecolor <color>]

autostyle [linewidth <number>]

autostyle [fillcolor <color>] [linecolor <color>] [linewidth <number>]

Color specifiers designate RGBA (Red, Green, Blue, Alpha) color components using number in the range 0-255 to specify individual R, G, B, or A values. If desired, a random component value may be generated at script run time by specifying -1 or ‘random’. Examples.

autostyle fillcolor( 114, 155, 1111, 255 ) // solid light green

autostyle fillcolor( 61, 56, 209, 127 ) // dark blue, half transparent

autostyle fillcolor( -1, -1, -1, 255 ) // random color, solid

autostyle fillcolor( random, random, random, 127 ) // random color, transparent

autostyle fillcolor( 255, 255, random, 127 ) // pure yellow with random blue component, transparent

Currently, autostyling is off by default for spatial scripts. The default line width is 1. The defaults for fill color and line color are set to ( random, random, random, 255 ), that is, random RGB, solid. If fewer than four components are specified, then whatever is specified is taken as R, then G, then B, with any missing components set as random. Hence, fillcolor( 127, 43 ) is the same as fillcolor( 127, 43, -1, -1 )

 

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