Overlay

Overlay combines two DataFrames into a single DataFrame using one of five overlay types: Intersect, Erase, Union, Identity, or Symmetric Difference.

ol workflow

Usage notes

  • Overlay requires that two inputs are specified using the input_dataframe and overlay_dataframe parameters in the run() method. The two supported overlay types and input geometries are described in the following tables:

    IntersectEraseUnionIdentitySymmetric Difference
    Point and point
    Point and linestring
    Point and polygon
    Linestring and point
    Linestring and linestring
    Linestring and polygon
    Polygon and point
    Polygon and linestring
    Polygon and polygon
    Full supportPartial supportNo support
    • The following table summarizes the overlay operations:

      Overlay typeDescription
      ol intersect IntersectThe geometries or portions of geometries in the overlay DataFrame that overlap the input DataFrame are returned. This is the default.
      ol erase EraseThe geometries or portions of geometries in the input DataFrame that do not overlap the overlay DataFrame are returned.
      ol union UnionThe result will contain a geometric union of the input DataFrame and overlay DataFrame. All geometries and attributes will be returned.
      ol identity IdentityThe result will contain geometries or portions of geometries that overlap in both the input DataFrame and overlay DataFrame.
      ol symdif Symmetric DifferenceThe result will contain geometries or portions of geometries of the input DataFrame and the overlay DataFrame that do not overlap.
    • When applying the indentity, intersect, symmetric difference, or union overlay types, fields from both DataFrames (input_dataframe and overlay_dataframe) are in the result. If the inputs have the same field names, the overlay fields will be renamed fieldname_overlay. For example, if your input_dataframe had the fields county and state, and the overlay_dataframe had the field county, your output DataFrame would have the fields county, state, and county_overlay.

    Limitations

    Sliver results may be excluded based on the tolerance of the processing spatial reference.

    Results

    The tool outputs records that include the following fields in addition to the input_dataframe fields:

    FieldDescription
    overlay_geometryIf your input had a geometry column, a new field named geometry is created.
    Fields from the overlay_dataframeWhen you use identity, intersect, symmetric difference, or union overlay type.

    Performance notes

    Improve the performance of Overlay by doing one or more of the following:

    • Only analyze the records in your area of interest. You can pick the records of interest by using one of the following SQL functions:

      • ST_Intersection—Clip to an area of interest represented by a polygon. This will modify your input records.
      • ST_BboxIntersects—Select records that intersect an envelope.
      • ST_EnvIntersects—Select records having an evelope that intersects the envelope of another geometry.
      • ST_Intersects—Select records that intersect another dataset or area of intersect represented by a polygon.

    Similar capabilities

    Use the Spatiotemporal join tool if you want to join two DataFrames based on their spatial relationship.

    The following functions complete spatial overlay operations:

    Syntax

    For more details, go to the GeoAnalytics Engine API reference for overlay.

    SetterDescriptionRequired
    run(input_dataframe, overlay_dataframe)Runs the Overlay tool using the provided DataFrames.Yes
    setOverlayType(overlay_type)Sets the type of overlay to be performed. The default is intersect.No

    Examples

    Run Overlay

    Python
    Use dark colors for code blocksCopy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    # Log in
    import geoanalytics
    geoanalytics.auth(username="myusername", password="mypassword")
    
    # Imports
    from geoanalytics.tools import Overlay
    from geoanalytics.sql import functions as ST
    
    # Paths to development area and planned pathway datasets
    development_path="https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/" \
                "/services/DevelopmentProjectArea/FeatureServer/0"
    pathway_path="https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/" \
                "services/DevA_Pathways/FeatureServer/1"
    
    # Create a DataFrame for the development areas and pathways
    development_df=spark.read.format("feature-service").load(development_path)
    pathway_df=spark.read.format("feature-service").load(pathway_path)
    
    # Use Overlay to union the pathways with the development area.
    # The result will be a DataFrame containing the development area enhanced with
    #    planned pathway geometries and information
    overlay_result=Overlay() \
                .setOverlayType(overlay_type="Union") \
                .run(input_dataframe=development_df, overlay_dataframe=pathway_df)
    overlay_result.filter(overlay_result["shapeType"] == 'Street') \
                  .select("OBJECTID", "shapeType", "Z_Min", "Z_Max") \
                  .sort("Z_Max", "Z_Min", ascending=False) \
                  .show(5)
    
    Result
    Use dark colors for code blocksCopy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    +--------+---------+----------------+----------------+
    |OBJECTID|shapeType|           Z_Min|           Z_Max|
    +--------+---------+----------------+----------------+
    |       1|   Street|50.1885900000052|52.4717399999936|
    |       1|   Street|42.6825300000055|52.4717399999936|
    |       1|   Street|35.4103199999954|50.1885900000052|
    |       1|   Street|47.8472699999984|48.1978600000002|
    |       1|   Street|34.7740400000039|48.1978600000002|
    +--------+---------+----------------+----------------+
    only showing top 5 rows

    Plot results

    Python
    Use dark colors for code blocksCopy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    # Plot the resulting development and pathway areas
    result_plot=overlay_result.st.plot(facecolor="lightblue",
                                         edgecolors="navy",
                                         figsize=(16,10),
                                         basemap="light")
    result_plot.set_title("Development area (Multnomah, Oregon) enhanced with" \
             "information for planned pathways")
    result_plot.set_xlabel("X (Meters)")
    result_plot.set_ylabel("Y (Meters)")
    Plotting example for an Overlay result. Unioned polygons are shown.

    Version table

    ReleaseNotes

    1.0.0

    Tool introduced

    Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.