Spatial Structures#

WindKit uses xarray.Dataset and xarray.DataArray for array data, and geopandas.GeoDataFrame for vector data.

WindKit defines specific variable, dimension, and coordinate naming conventions (schemas) to represent domain-specific data. This page documents the four spatial structures that form the foundation for all WindKit xarray objects.

All spatial structures require a crs variable containing the coordinate reference system.

Point Structure#

Points in 3D space, where each point has its own x, y, and z coordinate:

Dimensions:  (point, ...)
Coordinates:
    west_east    (point)   - x coordinate
    south_north  (point)   - y coordinate
    height       (point)   - z coordinate (meters above ground)

Use cases:

  • Single measurement locations

  • Scattered turbine positions

  • Individual site points

Detection and conversion:

# Create a point dataset
point_ds = wk.spatial.create_point(
    west_east=[10.0, 11.0, 12.0],
    south_north=[56.0, 57.0, 58.0],
    height=[80.0, 80.0, 100.0],
    crs="EPSG:4326"
)
point_ds

<xarray.Dataset> Size: 97B
Dimensions:      (point: 3)
Coordinates:
    height       (point) float64 24B 80.0 80.0 100.0
    south_north  (point) float64 24B 56.0 57.0 58.0
    west_east    (point) float64 24B 10.0 11.0 12.0
    crs          int8 1B 0
Dimensions without coordinates: point
Data variables:
    output       (point) float64 24B 0.0 0.0 0.0
Attributes:
    Conventions:  CF-1.8
    history:      2026-01-29T09:30:04+00:00:\twindkit==2.0.1\t"point")
# Check if dataset has point structure
is_point = wk.spatial.is_point(point_ds)
print(f"Is point structure: {is_point}")

Is point structure: True

Stacked Point Structure#

2D points with multiple vertical levels. Points share the same height values:

Dimensions:  (stacked_point, height, ...)
Coordinates:
    west_east    (stacked_point)  - x coordinate
    south_north  (stacked_point)  - y coordinate
    height       (height)         - vertical levels

Use cases:

  • Met mast data with multiple boom heights

  • Vertical profiles at scattered locations

  • Time series wind climates

Detection and conversion:

# Create a stacked point dataset
stacked_ds = wk.spatial.create_stacked_point(
    west_east=[10.0, 11.0],
    south_north=[56.0, 57.0],
    height=[50.0, 80.0, 100.0],
    crs="EPSG:4326"
)
stacked_ds

<xarray.Dataset> Size: 105B
Dimensions:      (height: 3, stacked_point: 2)
Coordinates:
  * height       (height) float64 24B 50.0 80.0 100.0
    south_north  (stacked_point) float64 16B 56.0 57.0
    west_east    (stacked_point) float64 16B 10.0 11.0
    crs          int8 1B 0
Dimensions without coordinates: stacked_point
Data variables:
    output       (height, stacked_point) float64 48B 0.0 0.0 0.0 0.0 0.0 0.0
Attributes:
    Conventions:  CF-1.8
    history:      2026-01-29T09:30:04+00:00:\twindkit==2.0.1\t"stacked_point")
# Check if dataset has stacked_point structure
is_stacked = wk.spatial.is_stacked_point(stacked_ds)
print(f"Is stacked_point structure: {is_stacked}")

Is stacked_point structure: True

Raster Structure#

Regular 2D grid with uniform spacing:

Dimensions:  (south_north, west_east, ...)
Coordinates:
    west_east    (west_east)    - x grid coordinates
    south_north  (south_north)  - y grid coordinates

Use cases:

  • Elevation maps

  • Resource grids

  • Land cover classifications

Detection and conversion:

# Create a raster dataset
raster_ds = wk.spatial.create_raster(
    west_east=np.linspace(0, 1000, 11),
    south_north=np.linspace(0, 1000, 11),
    crs="EPSG:32632"
)
raster_ds

<xarray.Dataset> Size: 1kB
Dimensions:      (height: 1, south_north: 11, west_east: 11)
Coordinates:
  * height       (height) int64 8B 0
  * south_north  (south_north) float64 88B 0.0 100.0 200.0 ... 800.0 900.0 1e+03
  * west_east    (west_east) float64 88B 0.0 100.0 200.0 ... 800.0 900.0 1e+03
    crs          int8 1B 0
Data variables:
    output       (height, south_north, west_east) float64 968B 0.0 0.0 ... 0.0
Attributes:
    Conventions:  CF-1.8
    history:      2026-01-29T09:30:04+00:00:\twindkit==2.0.1\t"cuboid")
# Check if dataset has raster structure
is_raster = wk.spatial.is_raster(raster_ds)
print(f"Is raster structure: {is_raster}")

Is raster structure: True

Cuboid Structure#

Regular 3D grid with uniform spacing in all dimensions:

Dimensions:  (south_north, west_east, height, ...)
Coordinates:
    west_east    (west_east)    - x grid coordinates
    south_north  (south_north)  - y grid coordinates
    height       (height)       - vertical levels

Use cases:

  • 3D flow fields

  • Volumetric resource data

  • Multi-level resource grids

Detection and conversion:

# Create a cuboid dataset
cuboid_ds = wk.spatial.create_cuboid(
    west_east=np.linspace(0, 1000, 11),
    south_north=np.linspace(0, 1000, 11),
    height=[50.0, 80.0, 100.0],
    crs="EPSG:32632"
)
cuboid_ds

<xarray.Dataset> Size: 3kB
Dimensions:      (height: 3, south_north: 11, west_east: 11)
Coordinates:
  * height       (height) float64 24B 50.0 80.0 100.0
  * south_north  (south_north) float64 88B 0.0 100.0 200.0 ... 800.0 900.0 1e+03
  * west_east    (west_east) float64 88B 0.0 100.0 200.0 ... 800.0 900.0 1e+03
    crs          int8 1B 0
Data variables:
    output       (height, south_north, west_east) float64 3kB 0.0 0.0 ... 0.0
Attributes:
    Conventions:  CF-1.8
    history:      2026-01-29T09:30:04+00:00:\twindkit==2.0.1\t"cuboid")
# Check if dataset has cuboid structure
is_cuboid = wk.spatial.is_cuboid(cuboid_ds)
print(f"Is cuboid structure: {is_cuboid}")

Is cuboid structure: True

Converting Between Structures#

WindKit provides functions to convert between spatial structures:

# Convert point to stacked_point (if heights can be factored)
# This works when all points share common height values
point_uniform = wk.spatial.create_point(
    west_east=[10.0, 10.0, 11.0, 11.0],
    south_north=[56.0, 56.0, 57.0, 57.0],
    height=[80.0, 100.0, 80.0, 100.0],
    crs="EPSG:4326"
)
stacked_from_point = wk.spatial.to_stacked_point(point_uniform)
stacked_from_point

<xarray.Dataset> Size: 81B
Dimensions:      (height: 2, stacked_point: 2)
Coordinates:
  * height       (height) float64 16B 80.0 100.0
    south_north  (stacked_point) float64 16B 56.0 57.0
    west_east    (stacked_point) float64 16B 10.0 11.0
    crs          int8 1B 0
Dimensions without coordinates: stacked_point
Data variables:
    output       (height, stacked_point) float64 32B 0.0 0.0 0.0 0.0
Attributes:
    Conventions:  CF-1.8
    history:      2026-01-29T09:30:04+00:00:\twindkit==2.0.1\t"point")\n2026-...
# Convert stacked_point back to point
point_from_stacked = wk.spatial.to_point(stacked_from_point)
print(f"Converted back to point structure: {wk.spatial.is_point(point_from_stacked)}")

Converted back to point structure: True

Structure Comparison#

Spatial structure comparison#

Structure

Dimensions

Use case

Data type

point

(point)

Scattered 3D points

Turbine sites, met masts

stacked_point

(stacked_point, height)

2D points + vertical levels

Mast profiles, wind climates

raster

(south_north, west_east)

Regular 2D grid

Elevation, land cover

cuboid

(south_north, west_east, height)

Regular 3D grid

3D resource data