Enrich points with raster

Enrich Points with Raster augments your input point DataFrame by adding values from a specified raster column. For each point, the tool locates the corresponding raster cell and extracts its value. The result DataFrame retains all original records and attributes, with additional columns containing the raster values at each point’s location.

Usage notes

• Any records that don't fall within the raster extent will be included in the result but will get assigned a null value.

• All fields in the points Dataframe will be included in the output result.

• If the points Dataframe and the rasters dataframe are in a different spatial reference, the function will automatically transform the rasters into the spatial reference of the points.

• Depending on the output mode set, the tool adds some additional fields. If the output mode is set to Long, the tool result will include two new fields: band_id and value. The value for each band in the raster will be returned in separate rows in the result DataFrame. If the output mode is set to Wide, the tool will return the band_{id} field. A new column is added for each band in the input raster. If the output mode is set to Array, the tool will return the values field which represents the cell values for all bands in a single array column.

• Internally, GeoAnalytics Engine aligns rasters on the same grid (spatial reference, cell size, and origin) before running enrich points. If the rasters are not aligned, a shift of up to half a pixel may occur. This is similar to a 0.5 mosaicking tolerance in ArcGIS Pro's Mosaic tool. To avoid this, align rasters before computing, and transform the geometry into the spatial reference of the rasters before calling the Enrich Points with Raster tool.

Limitations

• You can only enrich point geometries.

Results

All fields from the input DataFrame are included in the output records.

In addition, when the output mode is Long, these fields are included:

When the output mode is Wide, these fields are included:

When the output mode is Array, these fields are included:

Performance notes

Improve the performance of Enrich Points With Raster 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

The following tools complete raster related operations:

• Bins to Raster
• Geometry to Raster

Syntax

For more details, go to the GeoAnalytics Engine API reference for enrich points with raster.

Examples

Run Enrich Points With Raster

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

# Imports
from geoanalytics.tools import EnrichPointsWithRaster
from geoanalytics.tools import BinsToRaster
from geoanalytics.sql import functions as ST
from pyspark.sql import functions as F

# Path to the US Major cities data
data_path = r"https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/USA_Major_Cities_/FeatureServer/0"

# Create a Dataframe with the cities in the area of California
df = spark.read.format("feature-service").load(data_path).filter(F.col("STATE_ABBR") == "CA")

# Path to the Earthquakes data
data_path = r"https://sampleserver6.arcgisonline.com/arcgis/rest/services/Earthquakes_Since1970/FeatureServer/0"

# earthquakes in the area of California with a magnitude > 3
earthquakes_df = spark.read.format("feature-service").load(data_path).where(ST.bbox_intersects("shape", xmin=-124.48, xmax=-114.13, ymin=32.53, ymax=42.01)).filter(F.col("magnitude") > 3)

# Create bins for the earthquakes with 0.6 degrees size
bins = earthquakes_df\
  .withColumn("bin", ST.square_bin("shape", 0.6))\
  .groupBy("bin").count()\
  .withColumn("count", F.col("count").cast("int"))

# Use the BinsToRaster tool to convert bins to raster
raster = BinsToRaster()\
  .setBinColumn("bin")\
  .setBandValueColumns("count")\
  .setTileSize(10, 10)\
  .run(bins)

# Use the Enrich points with raster tool to enrich the California cities dataframe with the values from the raster.
# The result will show how many earthquakes affected or took place very close to a California city
result = EnrichPointsWithRaster()\
  .setRasterColumn("raster")\
  .setBandIds(1)\
  .setOutputMode("long")\
  .run(df, raster)

# show the first 5 results. The cities shown below are affected or are close to 4 earthquakes
result.select("NAME", "POPULATION", "value").sort("value", ascending=False).show(5, truncate=False)

1
2
3
4
5
6
7
8
9
10
+---------------+----------+-----+
|NAME           |POPULATION|value|
+---------------+----------+-----+
|Avocado Heights|13317     |4.0  |
|Bell Gardens   |39501     |4.0  |
|Azusa          |50000     |4.0  |
|Artesia        |16395     |4.0  |
|Baldwin Park   |72176     |4.0  |
+---------------+----------+-----+
only showing top 5 rows

Plot results

1
2
3
4
5
6

# plot the California cities on top of the earthquakes raster
margin = 2
ax = df.st.plot(sr=4326, zorder=2, figsize=(8,8))
result_plot = raster.rt.plot(ax=ax, cmap="prism", sr=4326, zorder=1, basemap="streets", extent=(-124.48 - margin, 32.53 - margin, -114.13 + margin, 42.01 + margin))
result_plot.set_title("California cities that were close to earthquakes", {'fontsize': 8})

Version table

Links to helpful information

• Raster functions
• Raster data