Wind rose

Readings bin by direction into compass sectors; sand settles into stacked annular petal segments, then a solid fill/border resolves on top. The most recent reading is highlighted, and a scrolling time table can stand beside the rose — clicking a row selects that reading's mark, and clicking a mark selects its row.

Constructor

new WindRoseChart(host: HTMLElement, config: WindRoseChartConfig)

Mounts a canvas into host and boots the best backend (WebGPU → Canvas2D). Only data is required. Single series — there is no series dimension, no slider, and no legend isolation; the dim machinery drives selection instead.

Data model — WindDataSet

Additive alongside Point/DataSet and MeshPoint/MeshDataSet, which are untouched.

interface WindPoint<Custom = unknown> {
  t: Date | number;      // the dimension: when the reading was taken
  direction: number;    // indicator 1 — the compass direction the wind comes FROM
  intensity: number;    // indicator 2 — speed / magnitude
  custom?: Custom;       // opaque payload, carried through to events and the table
}

interface WindDataSet<Custom = unknown> {
  points: WindPoint<Custom>[];
  directionUnit?: 'deg' | 'rad';   // default 'deg'
  intensityLabel?: string;         // table header; default 'Speed'
  intensityUnit?: string;          // e.g. 'kt'; labels only
}

Config — top level

sectors — direction binning

petals — what a segment is

radial — what a petal's length measures

bands — intensity bands

Used by petals.mode: 'bands'.

calm — the central circle

highlight — the latest reading(s)

table — the time table

A scrolling list of readings, newest first, mounted on an edge exactly like the legend. Off by default. Placement comes from the shared TableConfig in core/chrome (the table itself is chart-agnostic); the wind rose adds how its columns are formatted.

segments — the solid layer

Mirrors the pie's slices block: fill.opacity (1), border.show (true when a border block is present), border.width (1), border.opacity (1), and reveal — the same particle→solid crossfade every visual shares (start, duration, ease, grainsTo). Off by default; a config without segments renders as pure sand.

animation

Overridable mouse behavior

The chart's built-in pointer behavior is handed to you as defaultAction(), so a hook can run it, run it late, or not at all — overriding behavior without forking the chart.

interface MouseHookContext<M, E> {
  meta: M | null;              // the mark under the pointer, null for background
  native: E;                  // the raw DOM event — modifiers, coordinates, preventDefault
  px: { x: number; y: number };  // pointer in CSS px, relative to the chart element
  defaultAction(): void;      // the built-in behavior; idempotent
}

type MouseHook<M, E> = (ctx: MouseHookContext<M, E>) => boolean | void;

Compass & rings — axes

The shared AxisConfig blocks, re-mapped to polar meanings, so one mental model covers every chart.

Methods

Events

// SegmentMeta — one drawn segment (hover, select, currentValue.format)
{
  segmentId: number;      // grain barId slot
  key: string;            // stable identity: morph, selection and table key
  sector: number;         // -1 for the calm circle
  bearingDeg: number;     bearing: string;   // 315, 'NW'
  band: number;           // -1 in 'observations' mode
  bandLo: number;         bandHi: number;
  aggregated: boolean;    // the merged tail of a capped sector
  calm: boolean;
  observationIds: number[];   // source WindPoint indices
  count: number;
  value: number;          petalValue: number;   // in the measure's units
  intensityMin: number;   intensityMax: number;
  latestT: number;        // newest member's time, epoch ms
  a0: number; a1: number; rInner: number; rOuter: number;
  color: RGBA;
}

// ObservationMeta — one reading (table rows, highlight, onTableRowClick)
{
  id: number;             // index into data.points
  t: number;              directionDeg: number;   bearing: string;
  intensity: number;      custom: Custom | undefined;
  segmentKey: string | null;
}

Examples

Classic frequency rose

new WindRoseChart(el, {
  data: { points, intensityUnit: 'kt' },
  sectors: { count: 16 },
  bands: { derive: 'equal', count: 4 },
  calm: { below: 1, color: '#5b6472' },
  segments: { fill: { opacity: 0.9 }, border: { show: true } },
  axes: { x: { show: true, ticks: 8 }, y: { show: true, ticks: 4 } },
  legend: { show: true },
});

Per-reading petals with a time table

const chart = new WindRoseChart(el, {
  data: { points, intensityUnit: 'kt' },
  petals: { mode: 'observations' },   // every reading is its own addressable mark
  colors: ['#1d3b53', '#2f7fa8', '#5ac8c8', '#e8c45a'],   // read as ramp stops
  highlight: { select: 'latestN', count: 3, mode: 'outline', color: '#fff' },
  table: { show: true, position: 'right', maxRows: 200 },
});

// Clicking a table row selects that exact reading's mark, and vice versa.
chart.on('select', ({ observationId }) => console.log(observationId));

Streaming readings

const chart = new WindRoseChart(el, {
  data: { points: [], intensityUnit: 'kt' },
  animation: { enter: 'grow' },        // the petal grows to take the new reading
  radial: { measure: 'percent', max: 30 },  // hold the scale steady while it streams
});

setInterval(() => {
  chart.add([{ t: new Date(), direction: heading(), intensity: speed() }]);
  if (chart.getData().points.length > 500) chart.remove([0]);
}, 1000);

Overriding a click

new WindRoseChart(el, {
  data,
  interaction: {
    mouse: {
      onPetalClick(ctx) {
        if (ctx.native.shiftKey) {
          openInspector(ctx.meta);
          return false;         // suppress the built-in selection
        }
        ctx.defaultAction();      // otherwise select as usual
      },
    },
  },
});

Raw degrees in the table, plus a custom column

new WindRoseChart<{ station: string }>(el, {
  data: { points },   // points carry custom: { station: 'stn-07' }
  table: {
    show: true,
    directionFormat: (deg) => `${Math.round(deg)}°`,
    customColumn: { label: 'Station', format: (c) => (c as any).station },
  },
});