Geometry to raster

Geometry to Raster converts point, line, or polygon geometries into a tiled raster stored as a SQL raster column. The tool converts one or more columns into raster bands using a specified cell size and tile size. Each row in the output DataFrame represents one raster tile.

Usage notes

• The input DataFrame must contain a geometry column with point, line, or polygon geometries. All geometries are converted to rasters defined by the cell size and tile size.

• .setBandValueColumns() specifies one or more attribute columns whose values will be written into the output rasters. Each specified column becomes one raster band in the output, and the band order in the output raster matches the order of columns passed to the setter. Columns must be numeric.

  When multiple geometries contribute to the same raster pixel (for example, multiple points in one pixel or overlapping polygons), the tool selects one geometry for the pixel value.

  If a geometry's band value is NULL, the corresponding raster pixel value is assigned NoData. When multiple geometries contribute to the same cell, NULL values are ignored if at least one non-NULL value exists.

• Use .setTileSize() to specify how many columns and rows each tile contains. Tiles are laid out on a global grid that always starts from the origin (0, 0) in raster coordinates. The tool builds the global grid first, and outputs only the subset of tiles that intersect the input geometry. Because of this, tiles will not "start" at the geometry boundary, and are aligned to a global grid anchored at (0, 0) instead of the input geometry's extent.

• Use .setCellSize() to define the spatial resolution of the output raster in the units of the input coordinate system. Smaller cell sizes produce higher-resolution rasters with more details, and larger cell sizes produce lower-resolution rasters with fewer cells and more generalized results. Cells along feature boundaries may be assigned different values depending on the cell size.

• The .setPixelType() parameter specifies the data type in the output raster pixels. If it is not provided, the tool uses a default pixel type inferred from the input geometry DataFrame. The selected pixel type is applied to all bands in the output raster and affects value precision and supported value range.

  Supported pixel types are uint1, uint2, uint4, uint8, uint16, uint32, int8, int16, int32, float32, and float64. The short version of pixel type is also supported. For example, u1 can be used instead of uint1 or f32 instead of float32. Also, the pixel type representation is bit-based. For example, u1 is one bit and not one byte, which means that it uses one bit per pixel. Choose a pixel type that can represent the expected range of values for the band value columns to avoid overflow or loss of precision.

• You can optionally use .setBandsDefault() to set default values to use for each output raster band when a raster pixel does not receive a value from any input geometry or when the input band value is NULL. One default value must be provided for each band specified in .setBandValueColumns(), and the order of the default values must match the band order.

  If a default value is provided, it is written to the raster cell instead of NoData for that band. If band default is not set, cells with no contributing features or NULL values are written as NoData. Default values must be compatible with selected pixel type. The default NoData value is 0.

• When multiple geometries contribute to the same pixel, use .setCellAssignmentType() to set how the tool assigns a value to the pixel. The default assignment type is any, which assigns the value from any geometry contributing to the pixel in the input DataFrame. You can choose other assignment types listed in the table below.

  Options	Description
  Any	Assigns any value among contributing geometries to the pixel.
  Min	Assigns the minimum value among contributing geometries to the pixel.
  Max	Assigns the maximum value among contributing geometries to the pixel.
  Mean	Assigns the mean value among contributing geometries to the pixel.
  Sum	Assigns the sum value among contributing geometries to the pixel.
  Count	Assigns the number of valid values from contributing geometries and assign to the pixel.
  Range	Assigns the range of valid values from contributing geometries to the pixel.
  StandardDeviation	Calculates the standard deviation among contributing geometries and assigns to the pixel.
  Variance	Calculates the variance among contributing geometries and assigns to the pixel.
  PriorityField	Selects the contributing geometry with the highest value in a specified priority field and uses its value for the pixel.
  MaxLength	(Lines only) Selects the line contributing the greatest length within the pixel and uses its value.
  MaxArea	(Polygons only) Selects the polygon contributing the greatest area within the pixel and uses its value.
  CellCenter	(Polygons only) Uses the polygon that contains the pixel center to determine the pixel value.

Limitations

• Raster tiles are aligned to a global grid anchored at the origin (0, 0). The boundaries are not aligned to the input geometry extent, and the spatial extent of tiles may be beyond the geometry boundary.

Results

The tool returns a DataFrame containing raster tiles generated from the input geometries.

Performance notes

Improve the performance of the Geometry to Raster tool 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.
• Larger cell size will perform better than smaller cell size.

Similar capabilities

Similar tools:

• Bins to Raster

Syntax

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

Examples

Run Geometry to Raster

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# Imports
from geoanalytics.tools import GeometryToRaster
from geoanalytics.sql import functions as ST
from geoanalytics.raster import functions as RT
from pyspark.sql import functions as F

# Path to the Massachusetts population data
data_path = "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/USA_Census_Tracts/FeatureServer/0"

# Create the geometry DataFrame
df = spark.read.format("feature-service").load(data_path)\
          .filter(F.col("STATE_ABBR") == "MA")\
          .withColumn("shape", ST.transform("shape", 2249))

# Run the Geometry to Raster tool
rasters = GeometryToRaster()\
          .setCellSize(100, 100)\
          .setTileSize(1024, 1024)\
          .setBandValueColumns("POPULATION")\
          .run(df)

rasters.show(5)

1
2
3
4
5
6
7
8
9
10
+--------------------+
|              raster|
+--------------------+
|SqlRaster(1x1024x...|
|SqlRaster(1x1024x...|
|SqlRaster(1x1024x...|
|SqlRaster(1x1024x...|
|SqlRaster(1x1024x...|
+--------------------+
only showing top 5 rows

Plot results

1
2
3
4
5

# Visualize the rasters
result_plot = rasters.rt.plot(figsize=(14,14), basemap="light")
result_plot = rasters.select(RT.extent("raster", 2249)).st.plot(ax=result_plot, facecolor="none", edgecolor="red")
result_plot.set_title("Rasterizing the population at the census tract level in Massachusetts")

Version table

Links to helpful information

• Visualizing results