Skip to main content

DEFINE_SPATIAL_OPERATION and BEGIN_SPATIAL_OPERATION

Updated

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.

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

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. UNION can also be executed on a single layer to find overlapping areas between the features in one layer, UNION("layer1").
  • 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.
  • RELATE("layer1","layer 2","DE-9IM string")
    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.
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

Transforms are used to create new geometries by transforming the original geometries from a single layer in some way. Using a transform on a collection of geometries creates new, separate geometries in a different collection.

  • Spatial transforms are executed on groups of features within a layer. The following grouping options are available:
    • grouping:none
      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.
    • grouping:partition("attribute list")
      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. Multiple attributes can be used, separated by a comma, for example: grouping: partition( "Attribute1", "Attribute2").
    • grouping:alll
      All will consider all the features in the layer as a single group.

Transforms

  • MBR("layer1" ,grouping:grouping)
    The MBR transform creates a minimum bounding rectangle for each feature in its collection.
  • BUFFER("layer1",distance:value, grouping:grouping)
    Creates a new layer of features buffering the feature collection by the specified distance. Specify the distance with a numeric value in the defined DEFAULT UNITS or followed by the unit designation.
  • CENTER("layer1" ,grouping:grouping)
    The CENTER transform generates the center point of the MBR of each of the geometry groups.
  • CENTROID("layer1" ,grouping:grouping)
    The CENTROID transform generates the geometric center point of each of the geometry groups.
  • CIRCLE("layer1",radius:value, grouping:grouping)
    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. Specify the radius with a numeric value in the defined DEFAULT UNITS or followed by the unit designation.
  • CONVEXHULL("layer1" ,grouping:grouping)
    The CONVEXHULL transform creates a convex hull from each area feature in its collection.
  • CONCAVEHULL("layer1",radius:value, grouping:grouping)
    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.
  • DISSOLVE("layer1" ,grouping:grouping)
    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.
Units
  • DEFAULT UNITS units
    The linear units to be used throughout the script can be specified with DEFAULT UNITS. 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
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

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.

  • <feature collection> attribute ADD <attribute-name = attribute-formula> - Adds a new attribute using the specified formula. To create a formula see the Formula Calculator 
  • <feature collection> attribute DELETE <attribute-name> - Deletes an attribute for the set of features
  • <feature collection> attribute RENAME <attribute-name> <new-attribute-name> - Renames an attribute

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"

Related articles