Skip to content
Spatial.Properties

Raster Processing

Prerequisites

Section titled “Prerequisites”
  • spatialpack CLI installed (pip install -e ".[full]")
  • GDAL installed (included with the [full] extras)
  • A DEM raster file (GeoTIFF format)

Steps

Section titled “Steps”

1. Create a VRT mosaic from multiple raster tiles

Section titled “1. Create a VRT mosaic from multiple raster tiles”

When your DEM data spans multiple files (common for large areas), combine them into a Virtual Raster (VRT). A VRT is a lightweight XML file that references the original rasters without copying data.

Terminal window
spatialpack raster vrt zone50.tif zone51.tif -o wa_dem.vrt

Expected output:

VRT Mosaic Created
  Inputs:  2 raster files
  Output:  wa_dem.vrt
  Bounds:  [112.0, -35.5, 129.0, -13.5]

The VRT acts as a single dataset for downstream processing. No pixel data is duplicated — the VRT file is typically a few kilobytes regardless of how large the source rasters are.

2. Convert to a Cloud Optimized GeoTIFF

Section titled “2. Convert to a Cloud Optimized GeoTIFF”

Cloud Optimized GeoTIFF (COG) adds internal tiling and overviews to a standard GeoTIFF. This enables efficient streaming and partial reads over HTTP. Use the COG action to clip and reformat your raster.

Terminal window
spatialpack raster cog wa_dem.vrt -o perth_dem.tif \
  --bbox "115.65,-32.15,116.15,-31.65" \
  --compression zstd

Expected output:

COG Conversion
  Input:       wa_dem.vrt
  Output:      perth_dem.tif
  BBox:        [115.65, -32.15, 116.15, -31.65]
  Compression: zstd
  Size:        12.4 MB

The --bbox option clips the raster to the specified bounding box (minx, miny, maxx, maxy in WGS84). Compression options include deflate, lzw, and zstd — use zstd for the best compression ratio on large rasters.

3. Compute slope from a DEM

Section titled “3. Compute slope from a DEM”

Slope measures the steepness of terrain at each pixel. Output can be in percent (default) or degrees.

Terminal window
spatialpack raster slope perth_dem.tif -o slope.tif --units percent

Expected output:

Slope Computation
  Input:   perth_dem.tif
  Output:  slope.tif
  Units:   percent
  Range:   0.0 - 245.3%

Flat terrain has a slope of 0%. A 100% slope equals 45 degrees. Slope maps are useful for identifying areas suitable for construction, solar installations, or agriculture.

4. Compute aspect from a DEM

Section titled “4. Compute aspect from a DEM”

Aspect measures the compass direction a slope faces, in degrees from north (0-360). North = 0/360, East = 90, South = 180, West = 270.

Terminal window
spatialpack raster aspect perth_dem.tif -o aspect.tif

Expected output:

Aspect Computation
  Input:   perth_dem.tif
  Output:  aspect.tif
  Range:   0.0 - 360.0 degrees

In the Southern Hemisphere, north-facing slopes receive more direct sunlight. Aspect is critical for solar feasibility analysis — north-facing land is preferred for photovoltaic installations in Australia.

5. Compute hillshade from a DEM

Section titled “5. Compute hillshade from a DEM”

Hillshade creates a shaded relief visualization by simulating illumination from a light source. The default light position is northwest at 45 degrees altitude.

Terminal window
spatialpack raster hillshade perth_dem.tif -o hillshade.tif \
  --azimuth 315 --altitude 45

Expected output:

Hillshade Computation
  Input:    perth_dem.tif
  Output:   hillshade.tif
  Azimuth:  315 (NW)
  Altitude: 45 degrees

The azimuth controls the compass direction of the light source (315 = northwest, the cartographic convention). The altitude controls how high the light is above the horizon. The z_factor applies vertical exaggeration — set it to a value greater than 1.0 to emphasize terrain relief in flat areas.

6. Build a complete raster pipeline

Section titled “6. Build a complete raster pipeline”

Combine all raster processing steps into a single Pipeline YAML for a reproducible, automated workflow.

pipeline.yaml
pipeline:
  name: terrain-analysis
  version: "1.0"


pack:
  id: "my-org:demo:terrain:v1"
  version: "1.0.0"
  title: "Terrain Analysis Pack"
  theme: terrain
  geography: demo
  license: CC-BY-4.0
  region:
    bbox: [115.65, -32.15, 116.15, -31.65]
    crs: "EPSG:4326"


sources:
  dem_z50:
    path: "./data/zone50.tif"
    license: CC-BY-4.0
    format: tif


  dem_z51:
    path: "./data/zone51.tif"
    license: CC-BY-4.0
    format: tif


stages:
  - name: mosaic_dem
    action: raster.vrt
    inputs: [dem_z50, dem_z51]
    output: "staging/dem_mosaic.vrt"


  - name: clip_dem
    action: raster.cog
    input: mosaic_dem
    depends_on: [mosaic_dem]
    output: "rasters/terrain_dem.tif"
    options:
      bbox: ${pack.region.bbox}
      compression: zstd
    layer:
      id: terrain_dem
      title: "Terrain DEM"
      type: raster


  - name: compute_slope
    action: raster.slope
    input: clip_dem
    depends_on: [clip_dem]
    output: "rasters/terrain_slope.tif"
    options:
      units: percent
      compression: zstd
    layer:
      id: terrain_slope
      title: "Terrain Slope"
      type: raster


  - name: compute_aspect
    action: raster.aspect
    input: clip_dem
    depends_on: [clip_dem]
    output: "rasters/terrain_aspect.tif"
    options:
      compression: zstd
    layer:
      id: terrain_aspect
      title: "Terrain Aspect"
      type: raster

Build the pack:

Terminal window
spatialpack pack build pipeline.yaml -o ./terrain-pack/

This runs all stages in dependency order: mosaic, clip, slope, and aspect. The output directory contains the processed rasters and a spatialpack.json manifest.

7. Verify the output

Section titled “7. Verify the output”

Inspect the resulting pack to confirm all raster layers were produced.

Terminal window
ls ./terrain-pack/rasters/

Expected output:

terrain_dem.tif
terrain_slope.tif
terrain_aspect.tif

Each file is a Cloud Optimized GeoTIFF with internal tiling and compression, ready for streaming or local analysis.

Next steps

Section titled “Next steps”