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

At this time spatial operations only work on area features.

For more information on spatial operations scripting see Spatial Operations Scripting

  •  SPATIAL_OPERATION_NAME - Required. 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.

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

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

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

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

The END_DEFINE_SPATIAL_OPERATION 

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"