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
Forecast/reanalysis collections and their u/v band names. |
|
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. |
|
20-ft wind is the Rothermel input; forecasts publish 10 m. |
Functions
|
Draw the wind field as arrows you can put straight on a map. |
|
Turn a forecast into the |
|
Sample the wind field onto a regular grid — the downsampling step. |
|
Speed and BOTH direction conventions from u/v components. |
|
Return just the wind components, renamed to |
- 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.Imagefrom any collection inUV_BANDS, or one already carryingu/v.u_band – Override the band lookup.
v_band – Override the band lookup.
- Returns:
ee.Imagewith bandsu(eastward m/s) andv(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.Imagecarrying 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 unlessto_mihdirection_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.Imagewith bands
Note
direction_fromanddirection_todiffer 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_monsampleis the whole trick — Earth Engine reduces the field to that resolution and returns one point per cell.- Parameters:
image –
ee.Imagecarrying wind components.region –
ee.Geometryto 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.FeatureCollectionof points, each withu,v,speed,direction_fromanddirection_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()supportspointShapebut 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.Imagecarrying wind components.region –
ee.Geometryto 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.FeatureCollectionofLineStringfeatures carryingspeed,direction_from,direction_to. Style it with.style(color=..., width=1)or drive a palette offspeed.
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
blockslistspread_with_wind_blocksexpects.Averages each period over
regionand converts to the units and key names that function wants — 20-ft wind in mi/h, duration in seconds.direction_torides along so a caller writing their ownros_fncan use it, even though the default isotropic spread ignores it.- Parameters:
collection –
ee.ImageCollectionof forecast steps.region –
ee.Geometryto average over.start –
ee.Dateor ISO strings bounding the forecast.end –
ee.Dateor 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
cumulativeCostdirectional.