DEFINE_SPATIAL_OPERATION and BEGIN_SPATIAL_OPERATION

The DEFINE_SPATIAL_OPERATION command starts a multiline section that contains a Spatial Operations Script. It must be closed with a END_DEFINE_SPATIAL_OPERATION command, and called with a RUN_SPATIAL_OPERATION. Spatial Operations scripts can defines new layers or new selections of features based on spatial overlay operations, spatial predicates, transformations and/ or attribute filtering applied to vector data.

To define and run a spatial operation in a single set of commands use BEGIN_SPATIAL_OPERATION and END_SPATIAL_OPERATION to wrap the series of commands detailing the operation(s) to be executed These are like DEFINE_SPATIAL_OPERATION and END_DEFINE_SPATIAL_OPERATION, in that you use them to wrap up a number of spatial scripting commands, but with the new commands, they will be executed immediately, rather than needing to use the RUN_SPATIAL_OPERATION command to execute it.

For more information on spatial operations scripting see Spatial Operations Scripting

  •  SPATIAL_OPERATION_NAME - Required when using DEFINE_SPATIAL_OPERATION. Provide a name for the spatial operation. This name will be used when running the spatial operation.

Feature Collection

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

<feature collection> = <collection expression>

  • LAYER "layerName" - create a new layer by setting it equal to a collection expression.
  • set - A set is defined by entering a name set equal to an expression made up of functions, reference layers, etc.

Expressions

An output layer or set is defined equal to an expression made up of one or more functions.

Spatial Operations

Spatial operations output new geometry based on two input layers or sets, defined inside the parenthesis. The inputs can be layers, listed in quotes, or sets listed without quotes. The results[] parameter can be added as a third value to specify the geometry type for the resulting layer of features.

  • INTERSECTION("layer1","layer2")
    The Intersection operation creates a new layer consisting of overlapping regions of the two input layers. New features receive attributes from both layers.
  • UNION("layer1","layer2")
    The Union operation creates a new layer consisting of all regions from the two input layers. Regions that overlap are split from their containing features. Attributes of non-overlapping regions will come from their original layer; attributes from overlapping regions will come from the features that participated in the overlap.
  • DIFFERENCE("layer1","layer2")
    The difference operation subtracts "layer 2" from "layer 1".
  • SYMMETRICDIFFERENCE("layer1","layer2")
    A symmetrical difference finds all areas that are exclusively in one layer OR the other, but not in both.
Spatial Predicates

Predicate operations perform queries on a set of features based on their topological relationship to another set of features. This will return features in layer 1 in their full original shape based on how they touch or overlap features in the second layer. When combined with a SELECT operation, spatial predicates perform a selection by location, also known as a spatial query. The results[] parameter can be added as a third value to specify the geometry type for the resulting layer of features.

  • INTERSECTS("layer1","layer2")
    The Intersects predicate returns the set of features from layer1 that intersects features in layer2. A Layer1 feature intersects a layer2 feature if and only if the Layer1 feature is not disjoint from the layer2 feature. Intersects encompasses all other spatial predicates except disjoint.
  • OVERLAPS("layer1","layer2")
    The Overlaps predicate returns the set of features from layer1 that overlap features in layer2. Overlap means that the interiors of the features share some common area, but there are also interiors of both features not covered by the other feature. Overlap means partial coverage of the feature, i.e. some shared area and some non-shared area in both features.
  • TOUCHES("layer1","layer2")
    The Touches predicate returns the set of features from layer1 whose boundary intersects the boundary of a feature in layer2, but whose interiors do not overlap. The touches relationship is met when two features intersect, but the interiors of the features do not intersect.
  • CONTAINS("layer1","layer2")
    The Contains predicate returns the set of features from layer1 that wholly contain a feature from layer2. Contains is the opposite of within, i.e. feature A contains feature B if and only if feature B is within feature A.
  • EQUALS("layer1","layer2")
    The Equals predicate returns the set of features from layer1 that have an exact match with the geometry of a feature from layer2. This means the two boundaries, interiors and exteriors match.
  • WITHIN("layer1","layer2")
    The Within predicate returns the set of features from layer1 that are wholly contained by a feature from layer2. A feature is within another feature if the interiors of the features intersect, but the interior of the within feature does not intersect the boundary of the containing feature. The two features can share some boundary.
  • DISJOINT("layer1","layer2")
    The Disjoint predicate returns the set of features from layer1 that do not intersect with any features from layer2. A disjoint feature has no intersection between interior or boundary with another feature.
Results Type

This parameter can be added as a third value to any spatial operation or spatial predicate listed above to specify the geometry type for the resulting layer of features.

  • results[geometry type]
    Valid geometry types are points, lines, and areas. Multiple types can be listed separated by commas.

Feature Transforms
  • HULL(<feature collection>)
    The HULL transform creates a convex hull from each area feature in its collection.
  • MBR(<feature collection>)
    The MBR transform creates a minimum bounding rectangle for each feature in its collection.
  • BUFFER("layer1",distance)
    Creates a new layer of features buffering the feature collection by the specified distance. Specify the distance with a numeric value followed by the unit designation. Valid units 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

Layer Filters

These filters will create a new layer or subset of features based on the filter operation.

  • VALID("layer1")
    Creates a new feature collection of the valid features from the specified layer.
  • INVALID("layer1")
    Creates a new feature collection containing the invalid features from the specified layer.
  • SELECTION
    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.
Filters

Filters can be added to any command where an input layer is specified.

  • "layer1"  WHERE attribute = value
    Filter a layer or set based on a attribute query. The expression after the WHERE command follows the syntax and available functions of the Search Vector Datatool. 
  • "layer1"[geometry type]
    Filter a layer based on geometry type. Accepted values are point, lines, and areas. Multiple types can be listed separated by commas.
  • layer1"[selected]
    Filter a layer based on the currently selected features.

Selection

Selection of features can be passed to the workspace. Note the following commands only have a noticeable effect when using the option Run Script in the Context of the Main View in the Script Processing dialog.
Manage feature selection using the following commands:

  • SELECT<feature collection> - Select features in the specified feature collection with the digitizer tool

  • SELECT ADD <feature collection> - Add features in feature collection to the current selection

  • SELECT CLEAR- Clear the current selection

  • SELECT DELETE <feature collection> - Removes features in feature collection from current selection

Error Handling

When invalid geometries are found performing commands inside of expressions, the ONERROR command specifies how to handle the errors. 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 SKIP

  • ONERROR GEOMETRY

    • SKIP- Skip invalid geometries

    • IGNORE- Ignore geometry errors and use invalid geometries anyways

    • HALT- Halt the script when invalid geometries are encountered

    • REPAIR - attempt to repair invalid geometries before acting on the main command. This can be combined with the above options determine what to do with geometries that are not reparable. For example: For example: ONERROR GEOMETRY SKIP REPAIR.

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

END_DEFINE_SPATIAL_OPERATION

Paired with DEFINE_SPATIAL_OPERATION, END_DEFINE_SPATIAL_OPERATION, end the definition of an operation or series of operations.

END_SPATIAL_OPERATION

Paired BEGIN_SPATIAL_OPERATION, END_SPATIAL_OPERATION ends the operation definition and runs the operation immediately.

RUN_SPATIAL_OPERATION

Workspaces and scripts can store various spatial operations. These are not run until the RUN_SPATIAL_OPERATION command is performed.

  •  SPATIAL_OPERATION_NAME - Run a spatial operation that has been previously defined by calling it by name.

 

SAMPLE

DEFINE_SPATIAL_OPERATION SPATIAL_OPERATION_NAME="intersectselect"

//Create a new layer named risk countaining countries the intersect the hurricane trajectory
Layer "risk" = INTERSECTS("countries.shp","hurricane")

//Select all feature in the new risk layer with the digitizer tool
SELECT "risk"

END_DEFINE_SPATIAL_OPERATION
RUN_SPATIAL_OPERATION SPATIAL_OPERATION_NAME="intersectselect"