geeViz.fireLib.wind

Wind as a vector — speed, direction, and something you can look at.

The rest of this package treats wind as a scalar: rate_of_spread takes wind_speed_20ft in mi/h and spread_with_wind_blocks chains periods of it. That is deliberate and documented — cumulativeCost assigns cost per pixel, not per edge, so Tier 2 cannot express “cheap downwind, expensive upwind” no matter what direction it is handed.

But wind is a vector everywhere it is published, and the direction is the part a person actually wants to see. Forecast collections carry it as u/v components rather than speed and bearing, so every project rewrites the same hypot / atan2 pair. One such copy used to live in examples/weather_forecast_examples.ipynb, where nothing could import it — and it was wrong: its direction was (atan2(v, u) / pi + 1) * 180, the MATH angle rescaled to 0..360 rather than a compass bearing, which is right on the diagonals and wrong on all four cardinals. That notebook now calls geeViz.weather, which routes here.

This module is the importable version, plus the two things it always gets used for: sampling the field down to a drawable grid, and turning those samples into map geometry.

Direction convention — read this before trusting a number. Meteorology reports the direction wind blows from (“a westerly” comes from the west, 270°). Fire spread cares where it is going to. The two differ by exactly 180°, which is the kind of error that looks plausible on a map and puts the fire on the wrong side of the ridge. Both are returned, named unambiguously, and never abbreviated to “direction”:

direction_from meteorological, 0 = from the north, 90 = from the east direction_to where a parcel travels, = direction_from + 180

On rendering. ee.FeatureCollection.style() has pointShape but no rotation, so a rotated arrow glyph is not available server-side. wind_barbs() therefore draws real line segments — a shaft along the vector with a two-stroke head — which needs no rotation support and renders anywhere geeViz renders vectors. It is a static barb field, not the animated particle advection windy.com does; that is a client-side canvas effect over a u/v texture and does not belong in Earth Engine.

Module Attributes

UV_BANDS

Forecast/reanalysis collections and their u/v band names.

UV_BANDS_PBL

Above the surface layer GFS also carries boundary-layer wind, which is closer to what drives a plume-dominated run than the 10 m value.

WIND_10M_TO_20FT

20-ft wind is the Rothermel input; forecasts publish 10 m.

Functions

wind_barbs(image, region, *[, grid_m, ...])

Draw the wind field as arrows you can put straight on a map.

wind_blocks_from_forecast(collection, ...[, ...])

Turn a forecast into the blocks list spread_with_wind_blocks expects.

wind_grid(image, region, *[, grid_m, ...])

Sample the wind field onto a regular grid — the downsampling step.

wind_speed_direction(image[, u_band, ...])

Speed and BOTH direction conventions from u/v components.

wind_uv(image[, u_band, v_band])

Return just the wind components, renamed to u / v.

geeViz.fireLib.wind.UV_BANDS = {'ECMWF/ERA5/HOURLY': ('u_component_of_wind_10m', 'v_component_of_wind_10m'), 'ECMWF/ERA5_LAND/HOURLY': ('u_component_of_wind_10m', 'v_component_of_wind_10m'), 'ECMWF/NRT_FORECAST/IFS/OPER': ('u_component_of_wind_10m_sfc', 'v_component_of_wind_10m_sfc'), 'NOAA/GFS0P25': ('u_component_of_wind_10m_above_ground', 'v_component_of_wind_10m_above_ground')}

Forecast/reanalysis collections and their u/v band names. Every one of these spells it differently, which is most of why this lookup exists. Verified against the live catalog.

geeViz.fireLib.wind.UV_BANDS_PBL = {'NOAA/GFS0P25': ('u_component_of_wind_planetary_boundary_layer', 'v_component_of_wind_planetary_boundary_layer')}

Above the surface layer GFS also carries boundary-layer wind, which is closer to what drives a plume-dominated run than the 10 m value.

geeViz.fireLib.wind.WIND_10M_TO_20FT = 1.15

20-ft wind is the Rothermel input; forecasts publish 10 m. The log-profile ratio between them over open ground is ~1.15, and the number is small enough that people skip it and large enough to matter on a marginal spread call.

geeViz.fireLib.wind.wind_uv(image, u_band=None, v_band=None)[source]

Return just the wind components, renamed to u / v.

Parameters:
  • image – ee.Image from any collection in UV_BANDS, or one already carrying u / v.

  • u_band – Override the band lookup.

  • v_band – Override the band lookup.

Returns:

ee.Image with bands u (eastward m/s) and v (northward m/s).

geeViz.fireLib.wind.wind_speed_direction(image, u_band=None, v_band=None, *, to_mih=False, to_20ft=False)[source]

Speed and BOTH direction conventions from u/v components.

Parameters:
  • image – ee.Image carrying wind components.

  • u_band – Override the band lookup.

  • v_band – Override the band lookup.

  • to_mih – Return speed in mi/h instead of m/s. Use this when the value is headed for rate_of_spread(), which is unit-bearing English.

  • to_20ft – Scale a 10 m wind to 20 ft by WIND_10M_TO_20FT. Only valid if the input really is 10 m wind — applying it to boundary-layer wind overstates the surface value.

Returns:

  • speed — magnitude, m/s unless to_mih

  • direction_from — degrees the wind blows FROM (meteorological; 270 = a westerly)

  • direction_to — degrees it blows TOWARD; this is the one fire spread follows

Return type:

ee.Image with bands

Note

direction_from and direction_to differ by 180°. Naming one of them “direction” and moving on is how a barb field ends up pointing backwards.

geeViz.fireLib.wind.wind_grid(image, region, *, grid_m=12000, u_band=None, v_band=None)[source]

Sample the wind field onto a regular grid — the downsampling step.

A forecast grid is far denser than anything worth drawing: GFS is 0.25°, and a state-sized region is thousands of cells. Drawing all of them produces a black smear. scale=grid_m on sample is the whole trick — Earth Engine reduces the field to that resolution and returns one point per cell.

Parameters:
  • image – ee.Image carrying wind components.

  • region – ee.Geometry to sample within.

  • grid_m – Spacing in meters — one arrow per cell. 12 km over a county-to-state view is legible; drop it for a small AOI.

Returns:

ee.FeatureCollection of points, each with u, v, speed, direction_from and direction_to.

geeViz.fireLib.wind.wind_barbs(image, region, *, grid_m=12000, seconds=900, head_frac=0.3, head_deg=25.0, u_band=None, v_band=None)[source]

Draw the wind field as arrows you can put straight on a map.

Each grid sample becomes a shaft from the sample point along the wind vector, plus two short strokes forming an arrowhead at the downwind end. Shaft length is proportional to speed, so the field reads the way a barb field should: long arrows are fast.

Line segments rather than glyphs because FeatureCollection.style() supports pointShape but not rotation — there is no way to spin a marker to a bearing server-side. Segments need no rotation support at all.

Parameters:
  • image – ee.Image carrying wind components.

  • region – ee.Geometry to cover.

  • grid_m – Arrow spacing in meters.

  • seconds – Shaft length expressed as travel time — the arrow spans where a parcel would go in this many seconds. This is what makes length physical instead of an arbitrary scale factor: at 900 s a 10 m/s wind draws a 9 km shaft.

  • head_frac – Arrowhead length as a fraction of the shaft.

  • head_deg – Half-angle of the head, degrees.

Returns:

ee.FeatureCollection of LineString features carrying speed, direction_from, direction_to. Style it with .style(color=..., width=1) or drive a palette off speed.

Example

>>> gfs = ee.ImageCollection("NOAA/GFS0P25").filterDate(a, b).first()
>>> barbs = fl.wind_barbs(gfs, aoi, grid_m=12000)
>>> Map.addLayer(barbs.style(color="white", width=1), {}, "Wind")
geeViz.fireLib.wind.wind_blocks_from_forecast(collection, region, *, start, end, block_hours=6, u_band=None, v_band=None, moisture_1h=0.06)[source]

Turn a forecast into the blocks list spread_with_wind_blocks expects.

Averages each period over region and converts to the units and key names that function wants — 20-ft wind in mi/h, duration in seconds. direction_to rides along so a caller writing their own ros_fn can use it, even though the default isotropic spread ignores it.

Parameters:
  • collection – ee.ImageCollection of forecast steps.

  • region – ee.Geometry to average over.

  • start – ee.Date or ISO strings bounding the forecast.

  • end – ee.Date or ISO strings bounding the forecast.

  • block_hours – Length of each wind period.

Returns:

list[dict] — wind_speed (mi/h at 20 ft), duration_s, moisture_1h, direction_to (degrees).

Note

Spread within a block stays isotropic. This makes the SHIFTS available, which is what chaining blocks is for; it does not make cumulativeCost directional.