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

Usage notes
-
Overlay requires that two inputs are specified using the
input_
anddataframe overlay_
parameters in thedataframe run()
method. The two supported overlay types and input geometries are described in the following tables:Intersect Erase Union Identity Symmetric 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 type Description Intersect
The geometries or portions of geometries in the overlay DataFrame that overlap the input DataFrame are returned. This is the default. Erase
The geometries or portions of geometries in the input DataFrame that do not overlap the overlay DataFrame are returned. Union
The result will contain a geometric union of the input DataFrame and overlay DataFrame. All geometries and attributes will be returned. Identity
The result will contain geometries or portions of geometries that overlap in both the input DataFrame and overlay DataFrame. Symmetric Difference
The 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_
anddataframe overlay_
) are in the result. If the inputs have the same field names, the overlay fields will be renameddataframe fieldname_
. For example, if youroverlay input_
had the fieldsdataframe county
andstate
, and theoverlay_
had the fielddataframe county
, your output DataFrame would have the fieldscounty
,state
, andcounty_
.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_
fields:
Field | Description |
---|---|
overlay_ | If your input had a geometry column, a new field named geometry is created. |
Fields from the overlay_ | When 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_EnvIntersects—Select records that intersect an envelope.
- 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:
- ST_Aggr_Intersection
- ST_Aggr_union
- ST_Contains
- ST_Crosses
- ST_Difference
- ST_Dwithin
- ST_Equals
- ST_Intersection
- ST_Intersects
- ST_Overlaps
- ST_SymDifference
- ST_Touches
- ST_Union
- ST_Within
Syntax
For more details, go to the GeoAnalytics Engine API reference for overlay.
Setter | Description | Required |
---|---|---|
run(input_ | Runs the Overlay tool using the provided DataFrames. | Yes |
set | Sets the type of overlay to be performed. The default is intersect. | No |
Examples
Run Overlay
# 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)
+--------+---------+----------------+----------------+
|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
# 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)")

Version table
Release | Notes |
---|---|
1.0.0 | Tool introduced |