signalk-performance-processor 0.0.0-stage → 0.0.2

package/lib/processor.js

@@ -0,0 +1,331 @@
+'use strict'
+
+// The processing pipeline, free of Signal K so it can be tested and replayed against
+// logged data. Units throughout: degrees and knots. Angles are signed, + = starboard;
+// heel + = starboard side down; leeway + = sliding to starboard.
+//
+// Order of work:
+//   input corrections  (CORRECTIONS with stage 'input')
+//   true wind          apparent wind minus boat velocity through the water
+//   true wind corrections (stage 'trueWind')
+//   derived            TWD and current
+//
+// A new correction is one more entry in CORRECTIONS plus its defaults in defaults.js;
+// the pipeline, the Live view and the enable switch pick it up from there.
+
+const { DEFAULTS } = require('./defaults')
+
+const MAX_LEEWAY_DEG = 15
+const MIN_LEEWAY_STW_KN = 1 // below this K x heel / STW^2 blows up; no leeway
+
+const norm360 = d => ((d % 360) + 360) % 360
+const norm180 = d => { const n = norm360(d); return n > 180 ? n - 360 : n }
+const rad = d => d * Math.PI / 180
+const deg = r => r * 180 / Math.PI
+
+// Linear interpolation, holding the end values beyond either end.
+function interp (xs, ys, x) {
+  if (x <= xs[0]) return ys[0]
+  const n = xs.length - 1
+  if (x >= xs[n]) return ys[n]
+  let i = 0
+  while (xs[i + 1] < x) i++
+  const t = (x - xs[i]) / (xs[i + 1] - xs[i])
+  return ys[i] + (ys[i + 1] - ys[i]) * t
+}
+
+// Upwind row in full up to angles.upwind, reach row at angles.reach, downwind row from
+// angles.downwind, linear in |TWA| between.
+function blendRows (absTwa, angles, up, reach, down) {
+  if (absTwa <= angles.upwind) return up
+  if (absTwa <= angles.reach) return up + (reach - up) * (absTwa - angles.upwind) / (angles.reach - angles.upwind)
+  if (absTwa <= angles.downwind) return reach + (down - reach) * (absTwa - angles.reach) / (angles.downwind - angles.reach)
+  return down
+}
+
+function tableLookup (table, angles, absTwa, tws) {
+  return blendRows(absTwa, angles,
+    interp(table.tws, table.upwind, tws),
+    interp(table.tws, table.reach, tws),
+    interp(table.tws, table.downwind, tws))
+}
+
+const fmt = (v, d = 1) => (v > 0 ? '+' : '') + v.toFixed(d)
+
+const CORRECTIONS = [
+  {
+    id: 'stw',
+    stage: 'input',
+    name: 'Boat speed (STW)',
+    apply (c, cfg) {
+      // Linearity starts at its first bin; below that taper to zero at 0 kn, so a
+      // stopped boat is not given speed.
+      const lin = cfg.linearity
+      const add1 = c.stw < lin.stw[0]
+        ? lin.add[0] * Math.max(0, c.stw) / lin.stw[0]
+        : interp(lin.stw, lin.add, c.stw)
+      const add2 = c.heel == null ? 0 : interp(cfg.heel.heel, cfg.heel.add, Math.abs(c.heel))
+      const before = c.stw
+      c.stw = Math.max(0, c.stw + add1 + add2)
+      return {
+        input: `${before.toFixed(2)} kn` + (c.heel == null ? '' : ` · heel ${Math.abs(c.heel).toFixed(0)}°`),
+        detail: `${fmt(add1, 2)} linearity, ${fmt(add2, 2)} heel` + (c.heel == null ? ' (no heel data)' : ''),
+        output: `${c.stw.toFixed(2)} kn`
+      }
+    }
+  },
+  {
+    id: 'leeway',
+    stage: 'input',
+    name: 'Leeway',
+    apply (c, cfg) {
+      if (c.heel == null) return { skipped: 'no heel data' }
+      const k = cfg.k
+      c.leeway = c.stw < MIN_LEEWAY_STW_KN
+        ? 0
+        : Math.max(-MAX_LEEWAY_DEG, Math.min(MAX_LEEWAY_DEG, k * c.heel / (c.stw * c.stw)))
+      return {
+        input: `heel ${c.heel.toFixed(0)}°`,
+        detail: `K ${k} × heel ÷ STW²`,
+        output: `${Math.abs(c.leeway).toFixed(1)}° ${c.leeway < 0 ? 'port' : 'stbd'}`
+      }
+    }
+  },
+  {
+    id: 'twa',
+    stage: 'trueWind',
+    name: 'TWA table',
+    apply (c, cfg) {
+      const abs = Math.abs(c.twa)
+      const add = tableLookup(cfg, cfg.angles, abs, c.tws)
+      const before = c.twa
+      c.twa = Math.sign(c.twa || 1) * Math.max(0, Math.min(180, abs + add))
+      return {
+        input: `TWA ${Math.abs(before).toFixed(1)}° · TWS ${c.tws.toFixed(1)}`,
+        detail: `${fmt(add)}°`,
+        output: `TWA ${Math.abs(c.twa).toFixed(1)}°`
+      }
+    }
+  },
+  {
+    id: 'tws',
+    stage: 'trueWind',
+    name: 'TWS table',
+    apply (c, cfg, all) {
+      const pct = tableLookup(cfg, all.corrections.twa.angles, Math.abs(c.twa), c.tws)
+      const before = c.tws
+      c.tws = c.tws * (1 + pct / 100)
+      return {
+        input: `TWS ${before.toFixed(1)} kn`,
+        detail: `${fmt(pct)}%`,
+        output: `TWS ${c.tws.toFixed(1)} kn`
+      }
+    }
+  }
+]
+
+function runStage (stage, c, config, steps) {
+  for (const corr of CORRECTIONS.filter(x => x.stage === stage)) {
+    const cfg = config.corrections[corr.id]
+    if (!cfg || !cfg.enabled) {
+      steps.push({ id: corr.id, name: corr.name, enabled: false })
+      continue
+    }
+    const r = corr.apply(c, cfg, config)
+    steps.push({ id: corr.id, name: corr.name, enabled: true, ...r })
+  }
+}
+
+// Input corrections only: STW and leeway from raw STW and heel. Used on its own to
+// republish corrected STW as soon as the paddlewheel reports.
+function correctInputs (input, config) {
+  const c = { stw: input.stw, heel: input.heel == null ? null : input.heel, leeway: 0 }
+  const steps = []
+  runStage('input', c, config, steps)
+  return { c, steps }
+}
+
+// input: { awa, aws, stw, heel?, headingMagnetic?, headingTrue?, variation?, sog?, cog? }
+// returns { out: { stw, leeway, twa, tws, heading?, twd?, current? }, steps }
+function process (input, config) {
+  const { c, steps } = correctInputs(input, config)
+
+  // True wind: apparent wind minus the boat's velocity through the water, which points
+  // along the heading turned by leeway.
+  const a = rad(input.awa)
+  const l = rad(c.leeway)
+  const x = input.aws * Math.cos(a) - c.stw * Math.cos(l)
+  const y = input.aws * Math.sin(a) - c.stw * Math.sin(l)
+  c.twa = deg(Math.atan2(y, x))
+  c.tws = Math.hypot(x, y)
+  steps.push({
+    id: 'truewind',
+    name: 'True wind',
+    enabled: true,
+    input: `AWA ${Math.abs(input.awa).toFixed(1)}° · ${input.aws.toFixed(1)} kn`,
+    detail: 'apparent wind − boat velocity',
+    output: `TWA ${Math.abs(c.twa).toFixed(1)}° · ${c.tws.toFixed(1)} kn`
+  })
+
+  runStage('trueWind', c, config, steps)
+
+  const out = { stw: c.stw, leeway: c.leeway, twa: c.twa, tws: c.tws }
+
+  // True heading: from a true-heading source if there is one, otherwise magnetic
+  // heading plus variation, taken from Signal K (the GPS) when available and from the
+  // configured fallback when not.
+  let heading = null
+  if (input.headingTrue != null) {
+    heading = input.headingTrue
+    out.headingFrom = 'true heading'
+  } else if (input.headingMagnetic != null) {
+    const fromSignalK = input.variation != null
+    out.variation = fromSignalK ? input.variation : config.variation
+    out.headingFrom = fromSignalK ? 'magnetic + variation from Signal K' : 'magnetic + fallback variation'
+    heading = input.headingMagnetic + out.variation
+  }
+  if (heading != null) {
+    out.heading = norm360(heading)
+    out.twd = norm360(heading + c.twa)
+    if (input.sog != null && input.cog != null) {
+      // Current = ground velocity - water velocity; set is where it flows to.
+      const cr = rad(input.cog)
+      const wr = rad(heading + c.leeway)
+      const e = input.sog * Math.sin(cr) - c.stw * Math.sin(wr)
+      const n = input.sog * Math.cos(cr) - c.stw * Math.cos(wr)
+      out.current = { drift: Math.hypot(e, n), set: norm360(deg(Math.atan2(e, n))) }
+      steps.push({
+        id: 'current',
+        name: 'Current',
+        enabled: true,
+        input: `SOG ${input.sog.toFixed(1)} · COG ${input.cog.toFixed(0)}°`,
+        detail: 'ground − water velocity',
+        output: `${out.current.drift.toFixed(2)} kn → ${out.current.set.toFixed(0)}°`
+      })
+    }
+  }
+  return { out, steps }
+}
+
+// ---- configuration --------------------------------------------------------
+
+const clone = o => JSON.parse(JSON.stringify(o))
+
+function isPlainObject (o) {
+  return o !== null && typeof o === 'object' && !Array.isArray(o)
+}
+
+// Defaults first, then whatever the stored config sets. Arrays replace, objects merge.
+function merge (base, over) {
+  if (!isPlainObject(over)) return base
+  const out = clone(base)
+  for (const [k, v] of Object.entries(over)) {
+    if (isPlainObject(v) && isPlainObject(out[k])) out[k] = merge(out[k], v)
+    else if (v !== undefined) out[k] = v
+  }
+  return out
+}
+
+function checkAxis (errors, label, xs) {
+  if (!Array.isArray(xs) || xs.length < 1) { errors.push(`${label}: needs at least one value`); return }
+  if (xs.some(v => typeof v !== 'number' || !Number.isFinite(v))) { errors.push(`${label}: every value must be a number`); return }
+  for (let i = 1; i < xs.length; i++) {
+    if (!(xs[i] > xs[i - 1])) { errors.push(`${label}: must increase from left to right`); return }
+  }
+}
+
+function checkRow (errors, label, ys, n) {
+  if (!Array.isArray(ys) || ys.length !== n) { errors.push(`${label}: needs ${n} values, one per column`); return }
+  if (ys.some(v => typeof v !== 'number' || !Number.isFinite(v))) errors.push(`${label}: every value must be a number`)
+}
+
+function checkNumber (errors, label, v) {
+  if (typeof v !== 'number' || !Number.isFinite(v)) errors.push(`${label}: must be a number`)
+}
+
+// ---- file format versions ----------------------------------------------------
+//
+// Every saved config carries `schema`, the version of its shape. When a release changes
+// that shape, bump CONFIG_SCHEMA and add MIGRATIONS[old], a function that turns a
+// config of schema `old` into schema `old + 1`. Older files are then upgraded step by
+// step as they load and saved back in the current shape; nothing is lost or reset.
+//
+// Schema 1 (0.0.1): mode, variation, sources, corrections { stw, leeway, twa, tws }.
+
+const CONFIG_SCHEMA = 1
+const MIGRATIONS = {
+  // 1: cfg => ({ ...cfg, schema: 2, ... }),
+}
+
+// Bring a raw config up to the current schema. A config without `schema` predates the
+// field and has the schema 1 shape. One from a newer release is refused rather than
+// guessed at, since this version cannot know what its fields mean.
+function migrate (raw, migrations = MIGRATIONS, current = CONFIG_SCHEMA) {
+  let cfg = clone(raw)
+  let v = cfg.schema == null ? 1 : cfg.schema
+  if (!Number.isInteger(v) || v < 1) return { error: `schema: "${cfg.schema}" is not a schema version` }
+  if (v > current) return { error: `schema ${v} was saved by a newer version of this plugin (this one reads up to ${current}); update the plugin` }
+  while (v < current) {
+    if (!migrations[v]) return { error: `schema: no upgrade from ${v} to ${v + 1}` }
+    cfg = migrations[v](cfg)
+    v++
+  }
+  cfg.schema = current
+  return { config: cfg }
+}
+
+// Merge a stored or submitted config over the defaults and check it. Numbers typed
+// into a form arrive as strings, so coerce numeric-looking strings first.
+function normalizeConfig (input) {
+  const coerce = v => {
+    if (Array.isArray(v)) return v.map(coerce)
+    if (isPlainObject(v)) return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, coerce(x)]))
+    if (typeof v === 'string' && v.trim() !== '' && Number.isFinite(Number(v))) return Number(v)
+    return v
+  }
+  const migrated = migrate(isPlainObject(input) ? input : {})
+  if (migrated.error) return { config: { ...clone(DEFAULTS), schema: CONFIG_SCHEMA }, errors: [migrated.error] }
+  const raw = migrated.config
+  // Source names are text even when they look numeric.
+  const keepText = { sources: raw.sources, mode: raw.mode }
+  const config = merge({ schema: CONFIG_SCHEMA, ...DEFAULTS }, { ...coerce(raw), ...Object.fromEntries(Object.entries(keepText).filter(([, v]) => v !== undefined)) })
+  const errors = []
+  const k = config.corrections
+
+  if (!['shadow', 'replace'].includes(config.mode)) errors.push('mode: must be shadow or replace')
+  checkNumber(errors, 'variation', config.variation)
+
+  checkAxis(errors, 'STW linearity speeds', k.stw.linearity.stw)
+  checkRow(errors, 'STW linearity values', k.stw.linearity.add, (k.stw.linearity.stw || []).length)
+  checkAxis(errors, 'STW heel angles', k.stw.heel.heel)
+  checkRow(errors, 'STW heel values', k.stw.heel.add, (k.stw.heel.heel || []).length)
+  if (Array.isArray(k.stw.linearity.stw) && !(k.stw.linearity.stw[0] > 0)) errors.push('STW linearity speeds: must start above 0 kn')
+
+  checkNumber(errors, 'Leeway K', k.leeway.k)
+
+  for (const id of ['twa', 'tws']) {
+    const t = k[id]
+    const name = id.toUpperCase() + ' table'
+    checkAxis(errors, `${name} TWS columns`, t.tws)
+    for (const row of ['upwind', 'reach', 'downwind']) checkRow(errors, `${name} ${row} row`, t[row], (t.tws || []).length)
+  }
+  const ang = k.twa.angles
+  ;['upwind', 'reach', 'downwind'].forEach(r => checkNumber(errors, `TWA table ${r} angle`, ang[r]))
+  if (!(ang.upwind < ang.reach && ang.reach < ang.downwind && ang.upwind > 0 && ang.downwind < 180)) {
+    errors.push('TWA table angles: need 0 < upwind < reach < downwind < 180')
+  }
+
+  for (const [id, c] of Object.entries(k)) {
+    if (typeof c.enabled !== 'boolean') errors.push(`${id}: enabled must be true or false`)
+  }
+  return { config, errors }
+}
+
+module.exports = {
+  process,
+  correctInputs,
+  normalizeConfig,
+  CORRECTIONS,
+  CONFIG_SCHEMA,
+  _internals: { interp, blendRows, tableLookup, merge, norm180, migrate }
+}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "signalk-performance-processor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "description": "H5000-style calibration for Signal K: corrects boat speed and leeway, applies TWA and TWS correction tables, and publishes true wind and current. Proof of concept.",
+  "main": "index.js",
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "signalk-node-server-plugin",
+    "signalk-webapp",
+    "signalk-category-utility",
+    "signalk",
+    "sailing",
+    "racing",
+    "true-wind",
+    "calibration",
+    "leeway",
+    "speed-through-water"
+  ],
+  "signalk-plugin-enabled-by-default": false,
+  "signalk": {
+    "displayName": "Performance Processor",
+    "appIcon": "./icon.svg"
+  },
+  "files": [
+    "index.js",
+    "lib/",
+    "public/",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ghotihook/signalk-performance-processor.git"
+  },
+  "homepage": "https://github.com/ghotihook/signalk-performance-processor#readme",
+  "bugs": {
+    "url": "https://github.com/ghotihook/signalk-performance-processor/issues"
+  },
+  "author": "ghotihook",
+  "license": "MIT"
+}