@pond-ts/fit 0.31.0

package/dist/geo/index.d.ts

@@ -0,0 +1,358 @@
+/**
+ * Geospatial operators on a pond-ts `TimeSeries` — the geo layer of
+ * `@pond-ts/fit`. The thesis: a GPS track is already a time-keyed series of
+ * `number` columns, so the geospatial value lives in operators over those
+ * columns, not in a new storage primitive.
+ *
+ * Built strictly on pond's PUBLIC surface: two `number` columns for lat/lng,
+ * `column(name).toFloat64Array()` for zero-copy reads, and column reductions.
+ * Two places reach past what pond expresses directly today:
+ *   - Scalar / plain-array results are computed over the raw typed arrays rather
+ *     than attached back as derived columns — a deliberate choice (no row
+ *     rebuild). Where a derived column IS wanted, pond's `withColumn` covers it.
+ *   - Distance-axis aggregation: value-axis histograms (zones / distribution)
+ *     are pond-native via `byColumn`, but per-interval *splits* (many metrics
+ *     per distance bucket) and contiguous-run segmentation still walk the arrays
+ *     — candidate pond primitives (a multi-metric value-axis aggregate; a
+ *     `scan` / run-length family). See `splitsByDistance` / `segmentsInRange`.
+ */
+import { TimeSeries } from 'pond-ts';
+/**
+ * The canonical activity schema: time key + lat/lng, with every other per-sample
+ * channel optional (present iff the source recorded it). This is the single
+ * source the compute layer reads — the "consume the series directly" seam:
+ * power/cadence/temp live IN the series alongside ele/hr, not as orphaned
+ * parallel arrays.
+ */
+export declare const TRACK_SCHEMA: readonly [{
+    readonly name: "time";
+    readonly kind: "time";
+}, {
+    readonly name: "lat";
+    readonly kind: "number";
+    readonly required: false;
+}, {
+    readonly name: "lng";
+    readonly kind: "number";
+    readonly required: false;
+}, {
+    readonly name: "ele";
+    readonly kind: "number";
+    readonly required: false;
+}, {
+    readonly name: "hr";
+    readonly kind: "number";
+    readonly required: false;
+}, {
+    readonly name: "power";
+    readonly kind: "number";
+    readonly required: false;
+}, {
+    readonly name: "cadence";
+    readonly kind: "number";
+    readonly required: false;
+}, {
+    readonly name: "temp";
+    readonly kind: "number";
+    readonly required: false;
+}, {
+    readonly name: "distance";
+    readonly kind: "number";
+    readonly required: false;
+}];
+export type TrackSeries = TimeSeries<typeof TRACK_SCHEMA>;
+/**
+ * One sample as a tuple matching {@link TRACK_SCHEMA}. Every channel is optional
+ * — including lat/lng, absent for a GPS-less indoor activity (the series is then
+ * just time + the recorded channels). Absent values are `undefined`: the
+ * constructor accepts `undefined` for `required: false` columns and records it in
+ * the validity bitmap (lossless); as of pond 0.29 `RowForSchema` honors
+ * `required: false` so the row type admits it too. It rejects `null` and `NaN`.
+ */
+export type TrackPoint = [
+    timeMs: number,
+    lat: number | undefined,
+    lng: number | undefined,
+    ele: number | undefined,
+    hr: number | undefined,
+    power: number | undefined,
+    cadence: number | undefined,
+    temp: number | undefined,
+    distance: number | undefined
+];
+/** Build a pond track from parallel sample tuples (already time-sorted). */
+export declare function buildTrack(name: string, points: ReadonlyArray<TrackPoint>): TrackSeries;
+/**
+ * The raw typed-array columns of an activity — the zero-copy read path the whole
+ * compute layer reads from. `lat`/`lng` are present only for a GPS activity; the
+ * other channels are present iff the source recorded them (missing cells are
+ * NaN). Optional channels are absent from the object when the source had none.
+ */
+export interface TrackColumns {
+    /** Positions — present (length n) for a GPS activity, EMPTY for a GPS-less one
+     *  (the `cols.lat.length` hasTrack signal). */
+    lat: Float64Array;
+    lng: Float64Array;
+    ele: Float64Array;
+    /** Absolute sample times in seconds (key column, ms → s). */
+    timeSec: Float64Array;
+    hr?: Float64Array;
+    power?: Float64Array;
+    cadence?: Float64Array;
+    temp?: Float64Array;
+    /** Device-recorded cumulative distance (m); present iff the source carried it
+     *  (a GPS-less ride's distance axis). */
+    distance?: Float64Array;
+}
+/**
+ * Read a track's columns as `Float64Array`s. lat/lng off the packed value
+ * columns (required — never missing); the time axis off the key column via
+ * `keyColumn().begin` (a `Float64Array` of ms-since-epoch). Optional channels
+ * are read validity-aware and included only when the column carried any value.
+ */
+export declare function readColumns(track: TrackSeries): TrackColumns;
+/** Great-circle distance between two WGS84 points, in metres. */
+export declare function haversineMeters(lat1: number, lng1: number, lat2: number, lng2: number): number;
+/** Per-step distances (step[0] = 0), in metres. */
+export declare function stepDistances(lat: Float64Array, lng: Float64Array): Float64Array;
+/** Running total of a per-step series (cumulative[0] = step[0]). */
+export declare function cumulative(step: Float64Array): Float64Array;
+/** Total track distance, in metres. */
+export declare function totalDistanceMeters(lat: Float64Array, lng: Float64Array): number;
+/**
+ * Cumulative elevation gain/loss with a hysteresis threshold to reject the
+ * metre-scale jitter in barometric/GPS elevation. We only commit a move once it
+ * exceeds `thresholdMeters` from the last committed reference — the standard way
+ * to keep noise from inflating "gain" (raw positive-diff sums overcount wildly).
+ * NaN samples (missing ele) are skipped.
+ */
+export declare function elevationGainLoss(ele: Float64Array, thresholdMeters?: number): {
+    gainMeters: number;
+    lossMeters: number;
+};
+/**
+ * Moving time: sum of inter-sample intervals where instantaneous speed is at or
+ * above `speedThresholdMps` (default 0.5 m/s ≈ 1.8 km/h — below this you're
+ * stopped/drifting). This is what separates "moving time" from "elapsed time".
+ */
+export declare function movingTimeSeconds(step: Float64Array, timeSec: Float64Array, speedThresholdMps?: number): number;
+/** Bounding box as `[[minLat, minLng], [maxLat, maxLng]]`. */
+export declare function boundsOf(lat: Float64Array, lng: Float64Array): [[number, number], [number, number]];
+/** A contiguous window of an activity, in cumulative distance (metres). */
+export interface Segment {
+    startMeters: number;
+    endMeters: number;
+}
+/** Cumulative distance (m) at each polyline vertex; `[0] = 0`. */
+export declare function polylineCumulative(polyline: ReadonlyArray<[number, number]>): number[];
+/** The `[lat,lng]` point at cumulative distance `meters` along the polyline,
+ *  linearly interpolated between the bracketing vertices. Clamps to the ends;
+ *  non-finite `meters` resolves to the start; null for an empty polyline.
+ *  `cum` may be passed to avoid recomputation — it MUST correspond to
+ *  `polyline` (same length/order); a mismatch yields silently wrong results. */
+export declare function interpolateAtDistance(polyline: ReadonlyArray<[number, number]>, meters: number, cum?: number[]): [number, number] | null;
+/**
+ * The sub-polyline covering `[startMeters, endMeters]` of the route, with the
+ * endpoints interpolated to the exact distances (so a highlight begins and ends
+ * where the segment does, not at the nearest vertex) plus every vertex strictly
+ * between. Range is clamped to the track and normalized (start ≤ end). Returns
+ * the two interpolated endpoints for a zero-length range, `[]` for an empty
+ * polyline.
+ *
+ * `opts.domainTotal` is the length of the ruler `start`/`end` are measured in
+ * when that differs from this polyline's own length — laps come in FIT
+ * odometer metres and splits in raw-track haversine metres, but the polyline is
+ * Douglas–Peucker-simplified and a fraction shorter, so feeding those metres in
+ * raw would drift the highlight (≈1 km late on a 180 km ride). Given
+ * `domainTotal`, the window is rescaled proportionally onto the polyline so the
+ * same FRACTION of the route is sliced. `opts.cum`, if passed, MUST correspond
+ * to `polyline`.
+ */
+export declare function polylineSlice(polyline: ReadonlyArray<[number, number]>, startMeters: number, endMeters: number, opts?: {
+    domainTotal?: number;
+    cum?: number[];
+}): Array<[number, number]>;
+/**
+ * Bounding box via pond's column min/max reductions — the pond-native path,
+ * over the public column API.
+ */
+export declare function boundsViaPond(track: TrackSeries): [[number, number], [number, number]];
+/**
+ * Douglas–Peucker polyline simplification with a metre tolerance, for the map
+ * overview line. Returns the kept `[lat, lng]` points (endpoints always kept).
+ * Perpendicular distance is approximated in a local equirectangular projection
+ * (fine at track scale; we are not a projection engine — RFC §6 non-goals).
+ */
+export declare function simplify(points: ReadonlyArray<[number, number]>, toleranceMeters: number): Array<[number, number]>;
+/** A per-interval split (the per-km/per-mile row). */
+export interface Split {
+    /** 1-based split index. */
+    index: number;
+    /** Distance covered in this split, metres (the last split may be short). */
+    distanceMeters: number;
+    /** Elapsed seconds within the split. */
+    durationSeconds: number;
+    /** Elevation gain within the split, metres. */
+    elevationGainMeters: number;
+    /** Elevation loss within the split, metres (same ±3 m hysteresis as gain,
+     *  reference carried across split boundaries). */
+    elevationLossMeters: number;
+    /** Normalized power over the split, watts — present only with a power meter
+     *  (caller passes the 30 s-rolled power; see `splitsByDistance`). */
+    normalizedWatts?: number | undefined;
+    /** Per-split channel aggregates (mean of finite samples; max of finite
+     *  samples) — present only when the matching stream is supplied to
+     *  `splitsByDistance` via `extras`. Speed is m/s. */
+    avgHeartrate?: number | undefined;
+    maxHeartrate?: number | undefined;
+    avgWatts?: number | undefined;
+    maxWatts?: number | undefined;
+    avgCadence?: number | undefined;
+    avgSpeedMps?: number | undefined;
+    maxSpeedMps?: number | undefined;
+}
+/** Optional per-sample channels for `splitsByDistance` to aggregate per split
+ *  (avg = mean of finite samples, max = max finite). All aligned to `step`. */
+export interface SplitExtras {
+    heartrate?: Float64Array | undefined;
+    watts?: Float64Array | undefined;
+    cadence?: Float64Array | undefined;
+    /** Derived instantaneous speed (m/s); index 0 is typically NaN. */
+    speed?: Float64Array | undefined;
+}
+/**
+ * Per-interval splits over the DISTANCE axis (per-km, per-mile). A split is a
+ * bucket over *cumulative distance* (a derived, monotonic, non-key column) that
+ * carries MANY metrics per bucket — time, elevation gain/loss, NP, and avg/max
+ * of arbitrary extra channels. `byColumn` bins a single reducer over a value
+ * column; this multi-metric-per-bucket shape isn't a single `byColumn` call, so
+ * it walks the arrays here. A multi-metric value-axis aggregate is a candidate
+ * pond primitive.
+ */
+export declare function splitsByDistance(step: Float64Array, timeSec: Float64Array, ele: Float64Array, intervalMeters?: number, 
+/** Optional 30 s-rolled power (NP smoothing) aligned to the samples; when
+ *  given, each split gets `normalizedWatts = (mean of rolled^4)^¼`. */
+npRolled?: Float64Array, 
+/** Optional raw channels to aggregate per split (avg + max). See {@link SplitExtras}. */
+extras?: SplitExtras): Split[];
+/** A point on the elevation-vs-distance profile. */
+export interface ProfilePoint {
+    distanceMeters: number;
+    elevationMeters: number;
+}
+/**
+ * The elevation-vs-distance profile, resampled onto an even distance grid
+ * (distance-domain, not time). We average elevation within each distance bucket.
+ * Used for the profile chart and as the downsample for drawing.
+ */
+export declare function elevationProfile(cumDist: Float64Array, ele: Float64Array, bucketMeters?: number): ProfilePoint[];
+/** A `(distance, value)` sample on a distance-domain channel profile. */
+export interface ProfileSample {
+    distanceMeters: number;
+    /** Median of the raw samples in the bucket — robust to anomalies. */
+    value: number;
+    /** Outer band edge (low) — a low percentile, not the raw min. NaN if empty. */
+    bandLo: number;
+    /** Outer band edge (high) — a high percentile, not the raw max. */
+    bandHi: number;
+    /** Inner band edge (low) — the 25th percentile (the typical-range floor). */
+    innerLo: number;
+    /** Inner band edge (high) — the 75th percentile (the typical-range ceiling). */
+    innerHi: number;
+}
+/**
+ * Resample ANY per-sample channel (elevation, hr, power, cadence, speed, …)
+ * onto an even distance grid — the generalization of {@link elevationProfile}
+ * to any value column. Per bucket: `value` is the **median** (robust), and
+ * `bandLo`/`bandHi` are the central-90% **percentiles** (not raw min/max), so
+ * a single anomalous sample can't set the band or the chart scale. `NaN`
+ * (missing) samples are skipped; the last bucket carries forward so the line
+ * stays continuous. Distance-domain bucketing of a value array — like the
+ * `byColumn` histograms, but emitting a median + percentile band per bucket.
+ */
+export declare function profileByDistance(cumDist: Float64Array, values: Float64Array, bucketMeters?: number): ProfileSample[];
+/**
+ * Like {@link profileByDistance} but buckets ONLY the samples whose cumulative
+ * distance falls in `[startMeters, endMeters]`, at `bucketMeters` resolution.
+ * Returned `distanceMeters` are absolute (offset by `startMeters`), so the
+ * output drops straight into the same distance axis as the full-activity
+ * profile. This is what lets the chart reveal fine detail when zoomed to a
+ * locked split/lap — the bucket can be far finer than the whole-activity grid
+ * (e.g. ~10 m vs 100 m) without paying to re-bucket the entire track. Buckets
+ * here are aligned to `startMeters`, an independent grid from profileByDistance.
+ */
+export declare function profileByDistanceWindow(cumDist: Float64Array, values: Float64Array, startMeters: number, endMeters: number, bucketMeters?: number): ProfileSample[];
+/** Percentile spread of the raw samples around a point — the variance band. */
+export interface Spread {
+    /** Outer envelope (p5..p95) — the full excursions. NaN if no samples. */
+    bandLo: number;
+    bandHi: number;
+    /** Inner band (p25..p75) — the dense typical range. */
+    innerLo: number;
+    innerHi: number;
+}
+/**
+ * Rolling percentile spread of a raw per-sample channel, evaluated at each
+ * `distance` over a FIXED ±`radiusMeters` window of the raw samples — NOT the
+ * chart's buckets. This is what makes the variance underlay zoom-stable: the
+ * band measures the same real span of churn whether the chart is bucketed at
+ * 100 m (whole ride) or 10 m (a locked split), so it blooms where effort was
+ * genuinely punchy and pinches where steady, identically at every zoom. The
+ * within-bucket percentiles in {@link profileByDistance} can't do this — their
+ * width scales with bucket duration.
+ *
+ * pond 0.30's `rollingByColumn('dist', { radius, at: distances }, …)` owns the
+ * whole thing: the raw samples are the rows, and `at` evaluates the ±radius
+ * window + the four percentiles at each chart-grid center directly (one record
+ * per center) — no interleave, no read-back bookkeeping. `cum` and `distances`
+ * must both ascend (rollingByColumn enforces it). The `{ at }` option (added in
+ * pond 0.30) evaluates the window at each grid center directly.
+ */
+export declare function rollingSpread(cumDist: Float64Array, values: Float64Array, distances: number[], radiusMeters: number): Spread[];
+/** Canonical distances (metres) for a run's best-efforts table: 400 m, ½ mi,
+ *  1 K, 1 mi, 2 mi, 5 K, 10 K, half, full. */
+export declare const BEST_EFFORT_DISTANCES: number[];
+/** A fastest-over-distance effort: the quickest time to cover `meters`. */
+export interface DistanceEffort {
+    meters: number;
+    /** Fastest time over any window covering ≥ `meters`, seconds. */
+    seconds: number;
+    /** Mean HR over that fastest window, when an `hr` channel is supplied. */
+    avgHeartrate?: number;
+    /** Inclusive sample range of the fastest window — for focusing the chart/map
+     *  on where the effort happened (maps to distance via `cumDist`). */
+    startIndex?: number;
+    endIndex?: number;
+}
+/**
+ * Best efforts over distance: for each target distance, the fastest time over
+ * any window covering at least that distance. The distance-axis analogue of the
+ * power curve — a two-pointer over cumulative distance keeps the window just ≥
+ * the target while minimising elapsed time, O(n) per distance. Times are clamped
+ * non-decreasing across the (ascending) distance list. Walks the arrays: it's a
+ * fastest-window search over a derived monotonic axis swept across many target
+ * distances — beyond pond's single-window `rolling` (a multi-window sweep is a
+ * candidate pond primitive). `hr` (optional) yields the mean heart rate over each
+ * fastest window.
+ * Precondition: `distances` must be ascending — the `> total` early-exit and the
+ * non-decreasing-time clamp both rely on it (`BEST_EFFORT_DISTANCES` is).
+ */
+export declare function bestEffortsByDistance(cumDist: Float64Array, timeSec: Float64Array, distances?: number[], hr?: Float64Array): DistanceEffort[];
+/**
+ * The contiguous track pieces where a per-sample channel falls within
+ * `[lo, hi]` (inclusive) — the selection driver behind zone / power-distribution
+ * highlighting. A value predicate over the series yields the scattered stretches
+ * of the ride that match (e.g. "every part in the Tempo HR band"). Non-finite
+ * samples are out of range (they break a run). `cumDist` and `values` are
+ * sample-aligned. Adjacent runs separated by ≤ `bridgeMeters` of out-of-range
+ * distance merge into one (default 0 = faithful, no merge) so a momentary
+ * excursion doesn't shatter the selection into hundreds of slivers. Each run
+ * spans [cum at its first in-range sample, cum at its last]; a lone sample is a
+ * zero-length segment at its point.
+ *
+ * Run-length encoding of a predicate over a value column. pond has no
+ * contiguous-run / RLE-by-predicate primitive yet — a `scan` / segmentation
+ * family is a candidate pond primitive; until then this walks the arrays.
+ */
+export declare function segmentsInRange(cumDist: Float64Array, values: ArrayLike<number>, lo: number, hi: number, bridgeMeters?: number): Segment[];
+//# sourceMappingURL=index.d.ts.map