@motionstudies/core 0.1.0-alpha.15 → 0.1.0-alpha.16

package/README.md

@@ -233,3 +233,23 @@ For timetable-backed vehicle selections, `NetworkVehicleHeroCard` from `@motions
 `mountMotionStudy({ id, theme }, application)` requires presentation identity only; a full `MotionStudyEdition` remains accepted. Applications own their data catalogue and loading lifecycle.
 
 For independent airport infrastructure, `mapStyle.airports.visible` hides the mounted group without rebuilding GPU resources, and `showLabels` controls its labels separately. Both default to `true`. Set these from the edition's layout and label controls; airport abbreviations equal to their IATA code are rendered once.
+
+## Compression at rest in the source store
+
+`capture` and `importCapture` accept `compression: 'gzip'`. The object is stored as `objects/<sha256>.gz` when gzip saves at least ten percent, otherwise raw; the record keeps the raw content hash and byte count as identity and adds `storedBytes` and `encoding`. `readCapture` and the new `readObject(store, hash, expectedBytes)` follow either form, verify the raw hash after expansion, and refuse output beyond the recorded size. `compactObjects(store, { minimumSaving })` compresses existing raw objects in place, verifying each before removing the raw file; records are not rewritten, since reads do not depend on them. Already-compressed sources such as ZIP archives stay raw. Use `storedBytes` for storage accounting and `bytes` for provenance.
+
+## Estimated fields, gridded series, field paths and daylight
+
+These transport-neutral modules came from Zugunruhe's radar-field studies and serve any work that renders a continuous surface between scattered instruments, a gridded weather product, illustrative flow, or the sun's position: modelled electricity demand between substations, rain radar, model wind, or a terminator crossing a national field. They are pure functions with no dependencies. See [the shared-field record](../docs/SHARED-FIELDS.md) for provenance and adoption.
+
+`@motionstudies/core/domain/supported-field` estimates values between stations. `fieldNeighbours` weights stations by a Gaussian kernel with a smooth taper to a finite reach; `estimateField` blends station samples and reports `support`, a fade from the nearest station that supplied a value, and `vectorSupport` for the nearest complete vector. All kilometre scales are `FieldSupportOptions`; `DEFAULT_FIELD_SUPPORT` retains Zugunruhe's 90 km scale, 240 km reach and 120–240 km support fade. Null station values are excluded rather than treated as zero; vector components blend as east/north components, never as bearings. `createFieldGrid` precomputes neighbours for a regular grid whose rows run south to north, `sampleFieldGrid` packs value, east, north and support per cell and level with NaN for unavailable channels, and `sampleFieldGridAt` reads it bilinearly, returning null beside any missing corner. The `movement` flag withholds cells without a complete vector and limits their support to the nearest vector, for path integration.
+
+Render support as opacity or reach, not as confidence in the underlying measurement: it says how far the nearest evidence is, nothing about that evidence's accuracy. The kernel scale is a claim about resolution and belongs in the study's provenance.
+
+`@motionstudies/core/domain/gridded-series` reads a regular latitude/longitude grid of variables at listed instants. `bracketTime` finds the adjacent frames; `sampleGriddedSeries` interpolates bilinearly in space and linearly in time; `meanGriddedSeries` returns an area-weighted mean, with an optional valid range. A missing sample with any weight makes the reading unavailable instead of bridging the gap. Values keep the source's units; the consumer converts percentages or applies its own scale.
+
+`@motionstudies/core/domain/field-paths` integrates illustrative paths through an estimated velocity field. `advanceFieldPath` takes an explicit midpoint step in metres per second, with `secondsPerStep` converting one unit of study time, and refuses to start from, pass through or land on unsupported field. `mixFieldMovement` blends two readings; `visibleTrailSegments` returns the last `trail` steps of a track at a study time with a fade at either end, identical when scrubbing back. Paths are neither observed trajectories nor individual movers and must be labelled as illustration.
+
+`@motionstudies/core/domain/daylight` computes `solarPosition` (altitude and azimuth in degrees, azimuth clockwise from north) from the Astronomy Answers low-precision algorithm, matching SunCalc to a thousandth of a degree without a dependency. `daylightAt` adds a unit `direction` towards the sun in a scene frame with +x east, +y up and +z south, and smooth `twilight`, `warmth` and `daylight` envelopes from `DaylightEnvelopes` (defaults: twilight −18° to −1°, warmth rising −12° to −1° and falling 3° to 15°, daylight −1° to 12°). The envelopes are artistic responses to sun altitude and encode no weather or sky observation. Sample several longitudes to place a terminator across a national field.
+
+The lab's **Fields** specimen renders a synthetic archipelago of seven instruments with a mid-study gap and one vectorless instrument, an invented cover series as haze, integrated trails, and a terminator crossing with the study clock. Brightness is the estimate and opacity is support; clicking reads the estimate, cover and sun altitude at a place.

package/domain/daylight.d.ts

@@ -0,0 +1,32 @@
+/** Sun position and smooth lighting envelopes for a place and instant. The position follows the
+ * low-precision solar algorithm published by Astronomy Answers (as popularised by SunCalc), good
+ * to a fraction of a degree: enough to light a scene and place a terminator, not for astronomy.
+ * The envelopes are artistic colour responses to sun altitude; they encode no weather or sky observation.
+ */
+export interface SolarPosition {
+    /** Degrees above the horizon; negative below. */
+    readonly altitude: number;
+    /** Degrees clockwise from north. */
+    readonly azimuth: number;
+}
+/** Sun-altitude thresholds in degrees. Each envelope rises smoothly between its bounds; warmth also falls again between its last two. */
+export interface DaylightEnvelopes {
+    readonly twilight: readonly [from: number, to: number];
+    readonly warmth: readonly [from: number, to: number, fallFrom: number, fallTo: number];
+    readonly daylight: readonly [from: number, to: number];
+}
+export declare const DEFAULT_DAYLIGHT_ENVELOPES: DaylightEnvelopes;
+export interface Daylight extends SolarPosition {
+    /** Unit vector towards the sun in a scene frame with +x east, +y up and +z south. */
+    readonly direction: readonly [number, number, number];
+    /** 0 in full night, 1 once the sun nears the horizon. */
+    readonly twilight: number;
+    /** Peaks around sunrise and sunset, 0 at night and in full day. */
+    readonly warmth: number;
+    /** 0 below the horizon, 1 once the sun is well up. */
+    readonly daylight: number;
+}
+/** Sun altitude and azimuth for an instant, or null for an invalid instant or place. */
+export declare function solarPosition(time: number | string | Date, latitude: number, longitude: number): SolarPosition | null;
+/** Sun direction and lighting envelopes for a place and instant, or null for an invalid instant or place. */
+export declare function daylightAt(time: number | string | Date, latitude: number, longitude: number, envelopes?: DaylightEnvelopes): Daylight | null;

package/domain/daylight.js

@@ -0,0 +1,32 @@
+export const DEFAULT_DAYLIGHT_ENVELOPES = { twilight: [-18, -1], warmth: [-12, -1, 3, 15], daylight: [-1, 12] };
+const rad = Math.PI / 180, dayMs = 86_400_000, J1970 = 2440588, J2000 = 2451545, obliquity = rad * 23.4397;
+const smooth = (a, b, value) => { const t = Math.max(0, Math.min(1, (value - a) / (b - a))); return t * t * (3 - 2 * t); };
+const instant = (time) => typeof time === 'number' ? time : time instanceof Date ? time.getTime() : Date.parse(time);
+/** Sun altitude and azimuth for an instant, or null for an invalid instant or place. */
+export function solarPosition(time, latitude, longitude) {
+    const ms = instant(time);
+    if (!Number.isFinite(ms) || !Number.isFinite(latitude) || !Number.isFinite(longitude))
+        return null;
+    const days = ms / dayMs - .5 + J1970 - J2000, phi = rad * latitude;
+    const anomaly = rad * (357.5291 + .98560028 * days);
+    const eclipticLongitude = anomaly + rad * (1.9148 * Math.sin(anomaly) + .02 * Math.sin(2 * anomaly) + .0003 * Math.sin(3 * anomaly)) + rad * 102.9372 + Math.PI;
+    const declination = Math.asin(Math.sin(obliquity) * Math.sin(eclipticLongitude));
+    const rightAscension = Math.atan2(Math.sin(eclipticLongitude) * Math.cos(obliquity), Math.cos(eclipticLongitude));
+    const hourAngle = rad * (280.16 + 360.9856235 * days) + rad * longitude - rightAscension;
+    const altitude = Math.asin(Math.sin(phi) * Math.sin(declination) + Math.cos(phi) * Math.cos(declination) * Math.cos(hourAngle));
+    const fromSouth = Math.atan2(Math.sin(hourAngle), Math.cos(hourAngle) * Math.sin(phi) - Math.tan(declination) * Math.cos(phi));
+    return { altitude: altitude / rad, azimuth: ((fromSouth / rad + 180) % 360 + 360) % 360 };
+}
+/** Sun direction and lighting envelopes for a place and instant, or null for an invalid instant or place. */
+export function daylightAt(time, latitude, longitude, envelopes = DEFAULT_DAYLIGHT_ENVELOPES) {
+    const position = solarPosition(time, latitude, longitude);
+    if (!position)
+        return null;
+    const altitude = position.altitude * rad, fromSouth = (position.azimuth - 180) * rad;
+    const [tw0, tw1] = envelopes.twilight, [w0, w1, w2, w3] = envelopes.warmth, [d0, d1] = envelopes.daylight;
+    return { ...position,
+        direction: [-Math.sin(fromSouth) * Math.cos(altitude), Math.sin(altitude), Math.cos(fromSouth) * Math.cos(altitude)],
+        twilight: smooth(tw0, tw1, position.altitude),
+        warmth: smooth(w0, w1, position.altitude) * (1 - smooth(w2, w3, position.altitude)),
+        daylight: smooth(d0, d1, position.altitude) };
+}

package/domain/field-paths.d.ts

@@ -0,0 +1,35 @@
+/** Paths integrated through an estimated velocity field. They illustrate the field; they are not
+ * observed trajectories of anything. Integration refuses to start from, pass through or land on
+ * unsupported field, so a trail ends at a gap instead of crossing it.
+ */
+export interface FieldPoint {
+    readonly latitude: number;
+    readonly longitude: number;
+}
+export interface FieldMovement {
+    readonly value: number;
+    readonly vector: readonly [east: number, north: number];
+    readonly support: number;
+}
+/** Reads the field at a place and study time; null or undefined where it is unavailable. */
+export type FieldMovementSample = (point: FieldPoint, time: number) => FieldMovement | null | undefined;
+export interface FieldTrack {
+    /** Study time of the first point. */
+    readonly start: number;
+    readonly level: number;
+    /** One point per unit step: latitude, longitude and any further channels to interpolate. */
+    readonly points: readonly (readonly number[])[];
+}
+export interface TrailSegment {
+    readonly a: readonly number[];
+    readonly b: readonly number[];
+    readonly tail: number;
+    readonly fade: number;
+    readonly level: number;
+}
+/** Linear blend of two readings. Either side unavailable makes the blend unavailable except at its exact ends. */
+export declare function mixFieldMovement(a: FieldMovement | null | undefined, b: FieldMovement | null | undefined, fraction: number): FieldMovement | null;
+/** Explicit midpoint step. Vectors are metres per second; `secondsPerStep` converts one unit of study time. */
+export declare function advanceFieldPath(point: FieldPoint, time: number, step: number, sample: FieldMovementSample, secondsPerStep?: number): (FieldPoint & FieldMovement) | null;
+/** The part of a track visible at a study time: the last `trail` steps, with a fade at either end of the track. Scrubbing back restores identical segments. */
+export declare function visibleTrailSegments(track: FieldTrack, index: number, trail?: number): TrailSegment[];

package/domain/field-paths.js

@@ -0,0 +1,43 @@
+const rad = Math.PI / 180, kmPerDegree = 6371.0088 * rad;
+const smooth = (t) => { t = Math.max(0, Math.min(1, t)); return t * t * (3 - 2 * t); };
+/** Linear blend of two readings. Either side unavailable makes the blend unavailable except at its exact ends. */
+export function mixFieldMovement(a, b, fraction) {
+    if (fraction === 0)
+        return a ?? null;
+    if (fraction === 1)
+        return b ?? null;
+    if (!a || !b)
+        return null;
+    const mix = (x, y) => x * (1 - fraction) + y * fraction;
+    return { value: mix(a.value, b.value), vector: [mix(a.vector[0], b.vector[0]), mix(a.vector[1], b.vector[1])], support: mix(a.support, b.support) };
+}
+const displace = (p, v, seconds) => ({
+    latitude: p.latitude + v.vector[1] * seconds / 1000 / kmPerDegree,
+    longitude: p.longitude + v.vector[0] * seconds / 1000 / (kmPerDegree * Math.cos(p.latitude * rad)),
+});
+/** Explicit midpoint step. Vectors are metres per second; `secondsPerStep` converts one unit of study time. */
+export function advanceFieldPath(point, time, step, sample, secondsPerStep = 300) {
+    const a = sample(point, time);
+    if (!a || a.support <= 0)
+        return null;
+    const mid = displace(point, a, step * secondsPerStep / 2), b = sample(mid, time + step / 2);
+    if (!b || b.support <= 0)
+        return null;
+    const next = displace(point, b, step * secondsPerStep), value = sample(next, time + step);
+    return value && value.support > 0 ? { ...next, ...value } : null;
+}
+/** The part of a track visible at a study time: the last `trail` steps, with a fade at either end of the track. Scrubbing back restores identical segments. */
+export function visibleTrailSegments(track, index, trail = 15) {
+    const end = track.start + track.points.length - 1;
+    if (index <= track.start || index >= end)
+        return [];
+    const fade = smooth((index - track.start) / 2) * smooth((end - index) / 3), segments = [];
+    for (let i = Math.max(0, Math.floor(index - trail - track.start)); i < track.points.length - 1; i++) {
+        const t = track.start + i, a = Math.max(t, index - trail), b = Math.min(t + 1, index);
+        if (b <= a)
+            continue;
+        const p = track.points[i], q = track.points[i + 1], at = (f) => p.map((v, k) => v * (1 - f) + q[k] * f);
+        segments.push({ a: at(a - t), b: at(b - t), tail: Math.max(0, 1 - (index - (a + b) / 2) / trail), fade, level: track.level });
+    }
+    return segments;
+}

package/domain/gridded-series.d.ts

@@ -0,0 +1,30 @@
+/** A regular latitude/longitude grid of one or more variables at listed instants, such as cloud
+ * cover, rainfall or a model wind component. Values keep the source's own units; null marks a
+ * missing sample. Readings interpolate bilinearly in space and linearly in time, and a missing
+ * sample with any weight makes the whole reading unavailable rather than bridging the gap.
+ */
+export interface GriddedSeriesGrid {
+    readonly west: number;
+    readonly south: number;
+    readonly step: number;
+    readonly width: number;
+    readonly height: number;
+}
+export interface GriddedSeries<K extends string = string> {
+    /** ISO instants in ascending order. */
+    readonly times: readonly string[];
+    readonly grid: GriddedSeriesGrid;
+    /** One frame per instant; rows run south to north. */
+    readonly frames: readonly Readonly<Partial<Record<K, readonly (number | null)[]>>>[];
+}
+export interface TimeBracket {
+    readonly a: number;
+    readonly b: number;
+    readonly fraction: number;
+}
+/** The adjacent frames around an instant. Exact instants bracket themselves; instants outside the series are null. */
+export declare function bracketTime(times: readonly string[], time: string | number): TimeBracket | null;
+/** One variable at a place and instant, or null outside the grid, outside the times, or beside a missing sample. */
+export declare function sampleGriddedSeries<K extends string>(series: GriddedSeries<K>, key: K, latitude: number, longitude: number, time: string | number): number | null;
+/** Area-weighted mean of one variable over the whole grid at an instant. Any missing or out-of-range weighted sample makes the mean unavailable. */
+export declare function meanGriddedSeries<K extends string>(series: GriddedSeries<K>, key: K, time: string | number, range?: readonly [number, number]): number | null;

package/domain/gridded-series.js

@@ -0,0 +1,61 @@
+/** The adjacent frames around an instant. Exact instants bracket themselves; instants outside the series are null. */
+export function bracketTime(times, time) {
+    const value = typeof time === 'number' ? time : Date.parse(time);
+    if (!times.length || !Number.isFinite(value) || value < Date.parse(times[0]) || value > Date.parse(times[times.length - 1]))
+        return null;
+    for (let i = 0; i < times.length; i++) {
+        const stamp = Date.parse(times[i]);
+        if (value === stamp)
+            return { a: i, b: i, fraction: 0 };
+        if (stamp > value)
+            return { a: i - 1, b: i, fraction: (value - Date.parse(times[i - 1])) / (stamp - Date.parse(times[i - 1])) };
+    }
+    return null;
+}
+const valid = (sample, range) => typeof sample === 'number' && Number.isFinite(sample) && (!range || (sample >= range[0] && sample <= range[1]));
+/** One variable at a place and instant, or null outside the grid, outside the times, or beside a missing sample. */
+export function sampleGriddedSeries(series, key, latitude, longitude, time) {
+    const bracket = bracketTime(series.times, time), { west, south, step, width, height } = series.grid, x = (longitude - west) / step, y = (latitude - south) / step;
+    if (!bracket || !(x >= 0 && y >= 0 && x <= width - 1 && y <= height - 1))
+        return null;
+    const x0 = Math.floor(x), y0 = Math.floor(y), fx = x - x0, fy = y - y0;
+    let value = 0;
+    for (const [t, wt] of [[bracket.a, 1 - bracket.fraction], [bracket.b, bracket.fraction]]) {
+        for (const [ix, wx] of [[x0, 1 - fx], [Math.min(x0 + 1, width - 1), fx]])
+            for (const [iy, wy] of [[y0, 1 - fy], [Math.min(y0 + 1, height - 1), fy]]) {
+                const weight = wt * wx * wy;
+                if (weight === 0)
+                    continue;
+                const sample = series.frames[t]?.[key]?.[iy * width + ix];
+                if (!valid(sample))
+                    return null;
+                value += sample * weight;
+            }
+    }
+    return value;
+}
+/** Area-weighted mean of one variable over the whole grid at an instant. Any missing or out-of-range weighted sample makes the mean unavailable. */
+export function meanGriddedSeries(series, key, time, range) {
+    const bracket = bracketTime(series.times, time);
+    if (!bracket)
+        return null;
+    const { south, step, width, height } = series.grid;
+    let sum = 0, weight = 0;
+    for (let y = 0; y < height; y++) {
+        const area = Math.cos((south + y * step) * Math.PI / 180);
+        for (let x = 0; x < width; x++) {
+            let value = 0;
+            for (const [frame, w] of [[bracket.a, 1 - bracket.fraction], [bracket.b, bracket.fraction]]) {
+                if (w === 0)
+                    continue;
+                const sample = series.frames[frame]?.[key]?.[y * width + x];
+                if (!valid(sample, range))
+                    return null;
+                value += sample * w;
+            }
+            sum += value * area;
+            weight += area;
+        }
+    }
+    return weight ? sum / weight : null;
+}

package/domain/supported-field.d.ts

@@ -0,0 +1,78 @@
+/** A continuous estimate between scattered instruments. Values are reconstructed from weighted
+ * neighbouring stations; `support` reports how near the closest contributing evidence is, so a
+ * rendering can fade where its evidence weakens. The estimate is a model choice, not an observation
+ * at the sampled place, and missing station values stay missing rather than becoming zero.
+ */
+export interface FieldStation {
+    readonly latitude: number;
+    readonly longitude: number;
+}
+/** Kilometre scales of the neighbour kernel and the support fade. */
+export interface FieldSupportOptions {
+    /** Gaussian scale of neighbour weights. */
+    readonly scaleKm: number;
+    /** Weights taper smoothly from `reachStartKm` to zero at `reachKm`; stations beyond `reachKm` do not contribute. */
+    readonly reachStartKm: number;
+    readonly reachKm: number;
+    /** Support is 1 within `supportNearKm` of the nearest contributing station and fades to 0 at `supportFarKm`. */
+    readonly supportNearKm: number;
+    readonly supportFarKm: number;
+}
+export declare const DEFAULT_FIELD_SUPPORT: FieldSupportOptions;
+export interface FieldNeighbour {
+    readonly index: number;
+    readonly distanceKm: number;
+    readonly weight: number;
+}
+/** One station's contribution at one instant. A null value excludes the station; an incomplete vector excludes it from the vector estimate only. */
+export interface FieldSample {
+    readonly value: number | null;
+    readonly vector?: readonly [east: number, north: number] | null;
+}
+export interface FieldEstimate {
+    readonly value: number | null;
+    readonly vector: readonly [east: number, north: number] | null;
+    /** Fade from the nearest station that supplied a value. */
+    readonly support: number;
+    /** Fade from the nearest station that supplied a complete vector; 0 when none did. */
+    readonly vectorSupport: number;
+}
+export interface FieldGridBounds {
+    readonly west: number;
+    readonly east: number;
+    readonly south: number;
+    readonly north: number;
+    readonly step: number;
+}
+export interface FieldGridCell {
+    readonly latitude: number;
+    readonly longitude: number;
+    readonly neighbours: readonly FieldNeighbour[];
+}
+export interface FieldGrid {
+    readonly width: number;
+    readonly height: number;
+    readonly bounds: FieldGridBounds;
+    readonly cells: readonly FieldGridCell[];
+}
+/** A bilinear reading of a sampled grid. The vector is null when any contributing corner lacks one. */
+export interface FieldGridSample {
+    readonly value: number;
+    readonly vector: readonly [east: number, north: number] | null;
+    readonly support: number;
+}
+/** Great-circle distance on a spherical Earth. */
+export declare function distanceKm(a: FieldStation, b: FieldStation): number;
+/** Stations within reach of a place, weighted by distance. `exclude` withholds one station, for example to test the estimate against it. */
+export declare function fieldNeighbours(stations: readonly FieldStation[], latitude: number, longitude: number, options?: FieldSupportOptions, exclude?: number): FieldNeighbour[];
+/** Weighted estimate from the supplied station samples. Vector components blend as east/north components, never as bearings. */
+export declare function estimateField(neighbours: readonly FieldNeighbour[], sample: (index: number) => FieldSample | null | undefined, options?: FieldSupportOptions): FieldEstimate;
+/** Precompute neighbours for a regular grid. Rows run south to north; the grid includes both bounds. */
+export declare function createFieldGrid(stations: readonly FieldStation[], bounds: FieldGridBounds, options?: FieldSupportOptions): FieldGrid;
+/** Four channels per cell and level: value, east, north, support; levels are the outer dimension.
+ * Unavailable channels are NaN. With `movement`, a cell without a complete vector is entirely
+ * unavailable and its support also fades from the nearest station with a vector.
+ */
+export declare function sampleFieldGrid(grid: FieldGrid, sample: (index: number, level: number) => FieldSample | null | undefined, levels: number, options?: FieldSupportOptions, movement?: boolean): Float32Array;
+/** Bilinear reading of `sampleFieldGrid` output. Null outside the grid or where any contributing corner lacks a value. */
+export declare function sampleFieldGridAt(data: Float32Array, grid: FieldGrid, latitude: number, longitude: number, level: number): FieldGridSample | null;

package/domain/supported-field.js

@@ -0,0 +1,95 @@
+export const DEFAULT_FIELD_SUPPORT = { scaleKm: 90, reachStartKm: 180, reachKm: 240, supportNearKm: 120, supportFarKm: 240 };
+const rad = Math.PI / 180;
+const smooth = (t) => { t = Math.max(0, Math.min(1, t)); return t * t * (3 - 2 * t); };
+const fade = (distance, near, far) => 1 - smooth((distance - near) / Math.max(far - near, 1e-9));
+/** Great-circle distance on a spherical Earth. */
+export function distanceKm(a, b) {
+    const p = (b.latitude - a.latitude) * rad, q = (b.longitude - a.longitude) * rad;
+    const h = Math.sin(p / 2) ** 2 + Math.cos(a.latitude * rad) * Math.cos(b.latitude * rad) * Math.sin(q / 2) ** 2;
+    return 12742.0176 * Math.asin(Math.min(1, Math.sqrt(h)));
+}
+/** Stations within reach of a place, weighted by distance. `exclude` withholds one station, for example to test the estimate against it. */
+export function fieldNeighbours(stations, latitude, longitude, options = DEFAULT_FIELD_SUPPORT, exclude = -1) {
+    const place = { latitude, longitude }, neighbours = [];
+    stations.forEach((station, index) => {
+        const distance = distanceKm(station, place);
+        if (index === exclude || distance >= options.reachKm)
+            return;
+        neighbours.push({ index, distanceKm: distance, weight: Math.exp(-.5 * (distance / options.scaleKm) ** 2) * fade(distance, options.reachStartKm, options.reachKm) });
+    });
+    return neighbours;
+}
+/** Weighted estimate from the supplied station samples. Vector components blend as east/north components, never as bearings. */
+export function estimateField(neighbours, sample, options = DEFAULT_FIELD_SUPPORT) {
+    let weight = 0, value = 0, vectorWeight = 0, east = 0, north = 0, nearest = Infinity, nearestVector = Infinity;
+    for (const n of neighbours) {
+        const s = sample(n.index);
+        if (!s || s.value === null || !Number.isFinite(s.value))
+            continue;
+        weight += n.weight;
+        value += n.weight * s.value;
+        nearest = Math.min(nearest, n.distanceKm);
+        const v = s.vector;
+        if (v && Number.isFinite(v[0]) && Number.isFinite(v[1])) {
+            vectorWeight += n.weight;
+            east += n.weight * v[0];
+            north += n.weight * v[1];
+            nearestVector = Math.min(nearestVector, n.distanceKm);
+        }
+    }
+    if (weight < 1e-12)
+        return { value: null, vector: null, support: 0, vectorSupport: 0 };
+    return { value: value / weight, vector: vectorWeight ? [east / vectorWeight, north / vectorWeight] : null,
+        support: fade(nearest, options.supportNearKm, options.supportFarKm), vectorSupport: vectorWeight ? fade(nearestVector, options.supportNearKm, options.supportFarKm) : 0 };
+}
+/** Precompute neighbours for a regular grid. Rows run south to north; the grid includes both bounds. */
+export function createFieldGrid(stations, bounds, options = DEFAULT_FIELD_SUPPORT) {
+    const width = Math.round((bounds.east - bounds.west) / bounds.step) + 1, height = Math.round((bounds.north - bounds.south) / bounds.step) + 1, cells = [];
+    for (let y = 0; y < height; y++)
+        for (let x = 0; x < width; x++) {
+            const latitude = bounds.south + y * bounds.step, longitude = bounds.west + x * bounds.step;
+            cells.push({ latitude, longitude, neighbours: fieldNeighbours(stations, latitude, longitude, options) });
+        }
+    return { width, height, bounds, cells };
+}
+/** Four channels per cell and level: value, east, north, support; levels are the outer dimension.
+ * Unavailable channels are NaN. With `movement`, a cell without a complete vector is entirely
+ * unavailable and its support also fades from the nearest station with a vector.
+ */
+export function sampleFieldGrid(grid, sample, levels, options = DEFAULT_FIELD_SUPPORT, movement = false) {
+    const data = new Float32Array(grid.cells.length * levels * 4);
+    data.fill(NaN);
+    for (let level = 0; level < levels; level++)
+        for (let i = 0; i < grid.cells.length; i++) {
+            const e = estimateField(grid.cells[i].neighbours, (index) => sample(index, level), options), o = (level * grid.cells.length + i) * 4;
+            if (e.value === null || (movement && !e.vector))
+                continue;
+            data[o] = e.value;
+            data[o + 3] = movement ? Math.min(e.support, e.vectorSupport) : e.support;
+            if (e.vector) {
+                data[o + 1] = e.vector[0];
+                data[o + 2] = e.vector[1];
+            }
+        }
+    return data;
+}
+/** Bilinear reading of `sampleFieldGrid` output. Null outside the grid or where any contributing corner lacks a value. */
+export function sampleFieldGridAt(data, grid, latitude, longitude, level) {
+    const { width, height, bounds } = grid, x = (longitude - bounds.west) / bounds.step, y = (latitude - bounds.south) / bounds.step;
+    if (!(x >= 0 && x <= width - 1 && y >= 0 && y <= height - 1) || level < 0 || (level + 1) * width * height * 4 > data.length)
+        return null;
+    const x0 = Math.floor(x), y0 = Math.floor(y), fx = x - x0, fy = y - y0, out = [0, 0, 0, 0];
+    let vector = true;
+    for (const [xx, yy, w] of [[x0, y0, (1 - fx) * (1 - fy)], [Math.min(x0 + 1, width - 1), y0, fx * (1 - fy)], [x0, Math.min(y0 + 1, height - 1), (1 - fx) * fy], [Math.min(x0 + 1, width - 1), Math.min(y0 + 1, height - 1), fx * fy]]) {
+        if (w < 1e-10)
+            continue;
+        const o = (level * width * height + yy * width + xx) * 4;
+        if (!Number.isFinite(data[o]) || !Number.isFinite(data[o + 3]))
+            return null;
+        if (!Number.isFinite(data[o + 1]) || !Number.isFinite(data[o + 2]))
+            vector = false;
+        for (let c = 0; c < 4; c++)
+            out[c] += data[o + c] * w;
+    }
+    return { value: out[0], vector: vector ? [out[1], out[2]] : null, support: out[3] };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/core",
-  "version": "0.1.0-alpha.15",
+  "version": "0.1.0-alpha.16",
   "private": false,
   "type": "module",
   "description": "Transport contracts and motion primitives for Motion Studies.",
@@ -179,6 +179,26 @@
       "types": "./domain/vehicle-calls.d.ts",
       "import": "./domain/vehicle-calls.js",
       "default": "./domain/vehicle-calls.js"
+    },
+    "./domain/supported-field": {
+      "types": "./domain/supported-field.d.ts",
+      "import": "./domain/supported-field.js",
+      "default": "./domain/supported-field.js"
+    },
+    "./domain/gridded-series": {
+      "types": "./domain/gridded-series.d.ts",
+      "import": "./domain/gridded-series.js",
+      "default": "./domain/gridded-series.js"
+    },
+    "./domain/field-paths": {
+      "types": "./domain/field-paths.d.ts",
+      "import": "./domain/field-paths.js",
+      "default": "./domain/field-paths.js"
+    },
+    "./domain/daylight": {
+      "types": "./domain/daylight.d.ts",
+      "import": "./domain/daylight.js",
+      "default": "./domain/daylight.js"
     }
   },
   "files": [