@hotlap.ai/telemetry 1.2.0 → 1.3.0

package/dist/lap-points.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Canonical lap point extraction — produces the per-sample telemetry series
+ * (byDist / byTime) that the UI charts and the backend lap_bundles store.
+ *
+ * Output shape matches the deployed IbtLapPoint contract exactly
+ * (UI/src/lib/ibt-extract.ts and BACKEND process-job convertToIbtLapData):
+ *  - Speed m/s → km/h, Throttle/Brake 0–1 → 0–100 %, SteeringWheelAngle rad → deg
+ *  - distanceKm normalized per lap: (LapDist − min LapDist) / 1000
+ *  - timeSec normalized per lap: SessionTime − min SessionTime
+ *  - tire temps LFtempM.. with LFtempCM.. carcass fallback (process-job behavior)
+ *
+ * CANONICAL DECISION — tire wear is percent 0–100 (×100 from the raw 0–1
+ * channel), matching process-job and therefore every stored lap bundle. The
+ * UI's ibt-extract.ts left wear at raw 0–1; that was the divergent one.
+ *
+ * RFC-0001 C8: extraction runs at FULL resolution; downsampling to maxPoints
+ * happens last and is presentation-only — never an input to metrics.
+ *
+ * RUNTIME NEUTRALITY: this module must not import Bun/Deno/Node APIs.
+ */
+import type { IbtSource, NormalizedLap } from './normalize';
+/** Matches the UI/backend IbtLapPoint contract field-for-field. */
+export interface LapPoint {
+    distanceKm: number;
+    timeSec: number;
+    speedKmh: number | null;
+    throttlePct: number | null;
+    brakePct: number | null;
+    brakeABSactive: boolean | null;
+    gear: number | null;
+    rpm: number | null;
+    steeringDeg: number | null;
+    lat: number | null;
+    lon: number | null;
+    altitudeM: number | null;
+    tireTempLF: number | null;
+    tireTempRF: number | null;
+    tireTempLR: number | null;
+    tireTempRR: number | null;
+    tirePressureLF: number | null;
+    tirePressureRF: number | null;
+    tirePressureLR: number | null;
+    tirePressureRR: number | null;
+    tireWearLF: number | null;
+    tireWearRF: number | null;
+    tireWearLR: number | null;
+    tireWearRR: number | null;
+}
+export interface ExtractLapPointsResult {
+    /** Points sorted ascending by distanceKm (downsampled). */
+    byDist: LapPoint[];
+    /** Points sorted ascending by timeSec (downsampled). */
+    byTime: LapPoint[];
+    /** Number of valid full-resolution points before downsampling. */
+    downsampledFrom: number;
+}
+export interface ExtractLapPointsOptions {
+    /** Maximum points per series after downsampling. Default 500. */
+    maxPoints?: number;
+}
+/**
+ * Extract the telemetry point series for one normalized lap.
+ *
+ * Iterates lap.firstSampleIndex..lastSampleIndex; when the Lap / SessionNum
+ * channels are available, only indices whose Lap equals lap.lapNumber (and
+ * whose SessionNum matches the lap's own session, read at firstSampleIndex)
+ * are honored. Without those channels the whole contiguous range is accepted.
+ */
+export declare function extractLapPoints(source: IbtSource, lap: NormalizedLap, opts?: ExtractLapPointsOptions): ExtractLapPointsResult;
+//# sourceMappingURL=lap-points.d.ts.map

package/dist/lap-points.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lap-points.d.ts","sourceRoot":"","sources":["../src/lap-points.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAM5D,mEAAmE;AACnE,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,2DAA2D;IAC3D,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,wDAAwD;IACxD,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,kEAAkE;IAClE,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA8CD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,aAAa,EAClB,IAAI,CAAC,EAAE,uBAAuB,GAC7B,sBAAsB,CA8IxB"}

package/dist/neutral/lap-points.js

@@ -0,0 +1,149 @@
+// src/lap-points.ts
+var DEFAULT_MAX_POINTS = 500;
+function channel(source, key) {
+  const typed = source.getAllTyped(key);
+  if (typed)
+    return typed;
+  return source.getAll(key);
+}
+function channelWithFallback(source, ...keys) {
+  for (const key of keys) {
+    const c = channel(source, key);
+    if (c)
+      return c;
+  }
+  return null;
+}
+function readNum(arr, i) {
+  if (!arr)
+    return null;
+  const v = arr[i];
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+function readBool(arr, i) {
+  if (!arr)
+    return null;
+  const v = arr[i];
+  if (typeof v === "boolean")
+    return v;
+  if (v === 1)
+    return true;
+  if (v === 0)
+    return false;
+  return null;
+}
+function extractLapPoints(source, lap, opts) {
+  const maxPoints = Math.max(1, Math.floor(opts?.maxPoints ?? DEFAULT_MAX_POINTS));
+  const timeArr = channel(source, "SessionTime");
+  const distArr = channel(source, "LapDist");
+  if (!timeArr || !distArr || source.recordCount === 0) {
+    return { byDist: [], byTime: [], downsampledFrom: 0 };
+  }
+  const lapArr = channel(source, "Lap");
+  const sessArr = channel(source, "SessionNum");
+  const speedArr = channel(source, "Speed");
+  const throttleArr = channel(source, "Throttle");
+  const brakeArr = channel(source, "Brake");
+  const absArr = channel(source, "BrakeABSactive");
+  const gearArr = channel(source, "Gear");
+  const rpmArr = channel(source, "RPM");
+  const steerArr = channel(source, "SteeringWheelAngle");
+  const latArr = channel(source, "Lat");
+  const lonArr = channel(source, "Lon");
+  const altArr = channel(source, "Alt");
+  const tempLF = channelWithFallback(source, "LFtempM", "LFtempCM");
+  const tempRF = channelWithFallback(source, "RFtempM", "RFtempCM");
+  const tempLR = channelWithFallback(source, "LRtempM", "LRtempCM");
+  const tempRR = channelWithFallback(source, "RRtempM", "RRtempCM");
+  const pressLF = channel(source, "LFpressure");
+  const pressRF = channel(source, "RFpressure");
+  const pressLR = channel(source, "LRpressure");
+  const pressRR = channel(source, "RRpressure");
+  const wearLF = channel(source, "LFwearM");
+  const wearRF = channel(source, "RFwearM");
+  const wearLR = channel(source, "LRwearM");
+  const wearRR = channel(source, "RRwearM");
+  const first = Math.max(0, lap.firstSampleIndex);
+  const last = Math.min(source.recordCount - 1, lap.lastSampleIndex);
+  const expectedSess = readNum(sessArr, first);
+  const indices = [];
+  for (let i = first;i <= last; i++) {
+    if (lapArr) {
+      const l = readNum(lapArr, i);
+      if (l != null && l !== lap.lapNumber)
+        continue;
+    }
+    if (sessArr && expectedSess != null) {
+      const s = readNum(sessArr, i);
+      if (s != null && s !== expectedSess)
+        continue;
+    }
+    indices.push(i);
+  }
+  let minTime = Infinity;
+  let minDist = Infinity;
+  for (const i of indices) {
+    const t = readNum(timeArr, i);
+    const d = readNum(distArr, i);
+    if (t == null || d == null)
+      continue;
+    if (t < minTime)
+      minTime = t;
+    if (d < minDist)
+      minDist = d;
+  }
+  if (!Number.isFinite(minTime) || !Number.isFinite(minDist)) {
+    return { byDist: [], byTime: [], downsampledFrom: 0 };
+  }
+  const points = [];
+  for (const i of indices) {
+    const t = readNum(timeArr, i);
+    const d = readNum(distArr, i);
+    if (t == null || d == null)
+      continue;
+    const speed = readNum(speedArr, i);
+    const throttle = readNum(throttleArr, i);
+    const brake = readNum(brakeArr, i);
+    const steerRad = readNum(steerArr, i);
+    const wLF = readNum(wearLF, i);
+    const wRF = readNum(wearRF, i);
+    const wLR = readNum(wearLR, i);
+    const wRR = readNum(wearRR, i);
+    points.push({
+      distanceKm: (d - minDist) / 1000,
+      timeSec: t - minTime,
+      speedKmh: speed != null ? speed * 3.6 : null,
+      throttlePct: throttle != null ? throttle * 100 : null,
+      brakePct: brake != null ? brake * 100 : null,
+      brakeABSactive: readBool(absArr, i),
+      gear: readNum(gearArr, i),
+      rpm: readNum(rpmArr, i),
+      steeringDeg: steerRad != null ? steerRad * 180 / Math.PI : null,
+      lat: readNum(latArr, i),
+      lon: readNum(lonArr, i),
+      altitudeM: readNum(altArr, i),
+      tireTempLF: readNum(tempLF, i),
+      tireTempRF: readNum(tempRF, i),
+      tireTempLR: readNum(tempLR, i),
+      tireTempRR: readNum(tempRR, i),
+      tirePressureLF: readNum(pressLF, i),
+      tirePressureRF: readNum(pressRF, i),
+      tirePressureLR: readNum(pressLR, i),
+      tirePressureRR: readNum(pressRR, i),
+      tireWearLF: wLF != null ? wLF * 100 : null,
+      tireWearRF: wRF != null ? wRF * 100 : null,
+      tireWearLR: wLR != null ? wLR * 100 : null,
+      tireWearRR: wRR != null ? wRR * 100 : null
+    });
+  }
+  const valid = points.filter((p) => Number.isFinite(p.distanceKm) && Number.isFinite(p.timeSec) && p.distanceKm >= 0 && p.timeSec >= 0);
+  const byDistFull = [...valid].sort((a, b) => a.distanceKm - b.distanceKm);
+  const byTimeFull = [...valid].sort((a, b) => a.timeSec - b.timeSec);
+  const stride = Math.max(1, Math.ceil(valid.length / maxPoints));
+  const byDist = stride > 1 ? byDistFull.filter((_, i) => i % stride === 0) : byDistFull;
+  const byTime = stride > 1 ? byTimeFull.filter((_, i) => i % stride === 0) : byTimeFull;
+  return { byDist, byTime, downsampledFrom: valid.length };
+}
+export {
+  extractLapPoints
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotlap.ai/telemetry",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "High-performance iRacing telemetry library for Bun - IBT file parsing and live data streaming",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,6 +32,11 @@
       "import": "./dist/neutral/session-yaml.js",
       "default": "./dist/neutral/session-yaml.js"
     },
+    "./points": {
+      "types": "./dist/lap-points.d.ts",
+      "import": "./dist/neutral/lap-points.js",
+      "default": "./dist/neutral/lap-points.js"
+    },
     "./live": {
       "types": "./dist/live.d.ts",
       "import": "./dist/live.js",
@@ -55,7 +60,7 @@
   "scripts": {
     "build": "bun run build:js && bun run build:types",
     "build:js": "bun build ./src/index.ts ./src/ibt.ts ./src/live.ts ./src/constants.ts ./src/cli.ts ./src/telemetry-server.ts ./src/types.ts ./src/binary-reader.ts --outdir ./dist --target bun --splitting && bun run build:neutral",
-    "build:neutral": "bun build ./src/ibt.ts ./src/normalize.ts ./src/session-yaml.ts --outdir ./dist/neutral --target browser --splitting",
+    "build:neutral": "bun build ./src/ibt.ts ./src/normalize.ts ./src/session-yaml.ts ./src/lap-points.ts --outdir ./dist/neutral --target browser --splitting",
     "build:types": "tsc --emitDeclarationOnly --declaration --declarationMap --outDir ./dist",
     "build:server": "bun build ./src/telemetry-server.ts --compile --outfile ./dist/hotlap-telemetry",
     "clean": "rm -rf dist",