signalk-racer 1.3.0 → 1.3.2

package/README.md

@@ -25,7 +25,8 @@ This plugin calculates and publishes the following Signal K paths:
 | `navigation.racing.bestVmg.toPortEnd`      | Best VMG along the line towards the port end (pin)                     | `m/s`                                              |     |
 | `navigation.racing.bestVmg.toStbEnd`       | Best VMG along the line towards the stb end (boat)                     | `m/s`                                              |     |
 | `navigation.racing.bestVmg.*.override`     | The manual adjustment behind each best VMG, `null` when not adjusted   | `m/s`                                              |     |
-| `navigation.racing.bestApproach`           | The course actually sailed that achieved the best VMG towards the line | `{rad,m/s}`                                        |     |
+| `navigation.racing.effectiveVmg.toLine`    | VMG the perpendicular leg of the time to line is divided by            | `m/s`                                              |     |
+| `navigation.racing.effectiveVmg.alongLine` | VMG the along-line leg is divided by, 0 when inside the start zone     | `m/s`                                              |     |
 | `navigation.racing.startLinePort`          | Location of the port (pin) end of the start line                       | `{latitude,longitude}`                             | Y   |
 | `navigation.racing.startLineStb`           | Location of the starboard (boat) end of the start line                 | `{latitude,longitude}`                             | Y   |
 | `navigation.racing.nextLegHeading`         | True heading for the next leg of the course                            | `rad`                                              |     |
@@ -60,6 +61,7 @@ You can configure the plugin via the Signal K web interface or by editing `setti
 | `period`                  | How often to update values (in milliseconds)                            | `1000`        |
 | `updateStartLineWaypoint` | Should the waypoints be updated if the line is set/adjusted             | `true`        |
 | `createStartLineWaypoint` | Should the waypoints be created if the line is set                      | `true`        |
+| `minEffectiveVmg`         | Floor under each effective VMG used for time to line (in knots)         | `0.5`         |
 | `lines`                   | Array of named lines                                                    | null          |
 
 ---
@@ -97,18 +99,13 @@ If `navigation.headingTrue` is not available, then `navigation.courseOverGroundT
 
  - Uses the effective VMG as the maximum VMG of either the current COG/SOG or the 90th percentile of the VMG recently achieved (approx in the last 10 minutes).
    This allows a boat to luff / delay without changing the time to line.
+ - Each effective VMG is floored at `minEffectiveVmg` (default 0.5 knots), so a direction
+   with nothing collected yet - or a drifting boat - still yields a time rather than none.
+   The floor is not applied to the along-line leg when the boat is inside the start zone,
+   there being no such leg to sail.
  - A boat within the start zone has the time calculated by the perpendicular distance to the line divided by their effective VMG to the line.
  - A boat outside the start zone also has the perpendicular time plus the time calculated by the parallel distance to the zone divided by their effective VMG in that direction.
  - If the line is changed, then the samples used to calculate the effective VMGs are cleared.
- - Every sample keeps the `cog` and `sog` that produced it, so the course behind the 90th
-   percentile VMG towards the line can be recovered and is published as
-   `navigation.racing.bestApproach`. The direction is chosen exactly as the time to line
-   chooses its legs, and is reported alongside the course:
-     - Inside the start zone the line is closed across it, so `toCourseSide` is used, or
-       `fromCourseSide` when OCS.
-     - Outside the start zone the boat must first run along the line, so the along-line
-       samples are used, in the direction *away* from the closest end: beyond the pin it
-       must travel towards the starboard end, so `toStbEnd` governs, and vice versa.
  - The four collected VMGs are published under `navigation.racing.bestVmg.*` and may be manually
    adjusted. An adjustment stands in for the 90th percentile of the samples, but the VMG the boat
    is actually sailing still wins if it is better, so an adjustment can never make the estimate
@@ -145,11 +142,11 @@ line and the boat, so it zooms as the boat closes. The line length and the headi
 the line are marked on the line itself, and the boat is drawn as a triangle pointing along its
 heading, amber when OCS.
 
-Two projections run from the boat. Both start at the boat and are drawn to the same scale as the
-rest of the drawing, so their **tips can be read directly against the line**. Hovering the boat
-reports its SOG and COG and names whichever of the two lines are currently drawn.
+A projection runs from the boat, drawn to the same scale as the rest of the drawing, so its **tip
+can be read directly against the line**. Hovering the boat reports its SOG and COG and names the
+line running from it.
 
-#### Thick line — "Current cog/sog to start"
+#### Course projection — "Current cog/sog to start"
 
 Runs along the boat's present `navigation.courseOverGroundTrue`. While the start timer is counting
 down, its length is `SOG × timeToStart`: the distance the boat will cover before the gun if nothing
@@ -162,24 +159,6 @@ changes. Its tip is therefore **where the boat will be when the start fires**:
 With no timer running there is nothing to project against, so it degrades to a short fixed-length
 stub showing course only.
 
-#### Thin faint line — "Best VMG to start"
-
-Runs along `navigation.racing.bestApproach`, with its length that course's own
-`SOG × timeToStart`. This is **not** a synthetic best case: it is a course the boat has genuinely
-sailed in the last few minutes, being the `cog`/`sog` recorded against the 90th percentile VMG
-sample for the direction that actually matters (across the line, or along it when outside the start
-zone — see [Time To Line](#time-to-line-navigationracingtimetoline)). Because it is a real point of
-sail it runs on its **own bearing**, not the current one, so it will diverge from the thick line
-whenever the boat is not sailing as well as it recently has.
-
-Comparing the two tips is the point of the pair: if the thin line reaches the line and the thick one
-falls short, then sailing the boat as well as it has already been sailed would get you there, and
-the difference between the tips is what is being left on the table. If no samples have been
-collected yet, or the timer is not running, this line is not drawn.
-
-Over a long countdown both projections run well off the drawing and are simply clipped at its edge;
-the part that matters — where they cross the line — stays visible.
-
 ---
 
 ## 🌐 API Access
@@ -226,14 +205,15 @@ Used to **adjust** or **reset** the best VMGs used to estimate the time to line.
   "vmg": "toCourseSide" | "fromCourseSide" | "toPortEnd" | "toStbEnd",
   "value": 5.0,
   "delta": 0.0514,
-  "command": "reset"
+  "command": "reset" | "clear"
 }
 ```
 
 - `vmg`: which best VMG to adjust. Optional for `reset`, which otherwise clears all four.
 - `value`: absolute best VMG in `m/s`.
 - `delta`: adjustment in `m/s` applied to the current best VMG.
-- `command`: `"reset"` to clear the override and revert to the collected samples.
+- `command`: `"reset"` to clear the override and revert to the collected samples, or
+  `"clear"` to throw away the collected samples themselves and start again.
 
 An absolute value may also be put directly to `navigation.racing.bestVmg.<name>`.
 

package/ReleaseNotes.md

@@ -1,4 +1,33 @@
-## 1.2.0 Visualize line and best VMGs
+## 1.3.2 Distance to length
+ + Set the metadata for distance to line as a length rather than as a distance.
+
+## 1.3.1 Start line approach
+ + Fixed the distance to the start zone being measured against a 54.7 degree wedge while
+   the zone itself was tested at 45 degrees, so `distanceStartline` and `timeToLine`
+   jumped by 0.29 times the offset as a boat crossed the boundary. They are now continuous
+   and the along-line leg reaches zero exactly at the wedge
+ + The start zone geometry moved from `index.js` into `racer.js` as `startZoneDistances`,
+   where it is unit tested - it had no coverage at all, which is how the above survived
+ + `navigation.racing.timeToBurn` is now published when OCS as well. The time to line is
+   then the time to get back over the line from the course side, so the spare time before
+   you have to turn and do it is just as real, and goes negative once it is too late
+ + Removed `navigation.racing.bestApproach` and the `cog`/`sog` each VMG sample carried
+   to produce it. It described one course the boat had genuinely sailed, which was useful
+   but not the path the time to line is computed over, so it read as a second answer to a
+   question that already had one. Best VMG angles will be revisited once the polar plugin
+   offers an API for them, by which point the shape is likely to be quite different
+ + Each effective VMG is now floored at a configurable minimum, `minEffectiveVmg`,
+   defaulting to 0.5 knots. A direction with nothing collected reported no VMG at all, which
+   left the time to line falling back to the time to start rather than estimating anything
+ + `navigation.racing.setBestVmg` accepts `command: "clear"`, which discards the collected
+   samples themselves rather than just the manual adjustments
+ + Published the two VMGs the time to line is actually divided by as
+   `navigation.racing.effectiveVmg.{toLine,alongLine}`: the collected best for each
+   direction, or the VMG being sailed right now when that is better. `bestVmg.*` reports
+   only the collected half, so a client drawing the approach from it disagreed with the
+   published time whenever the boat was going well
+
+## 1.3.0 Visualize line and best VMGs
  + Added `navigation.racing.swapStartLine` to swap the port and starboard ends of the line,
    carrying the collected VMG samples across with the ends
  + Published the four best VMGs behind the time to line as `navigation.racing.bestVmg.`
@@ -18,6 +47,8 @@
  + Fixed the start line bias not being cleared when the line is lost
  + Fixed the webapp race countdown never being displayed
 
+## 1.2.0 Never released
+
 ## 1.1.2 TTL fixes
  + use a FIFO queue for VMGs towards the line.
  + avoid undefined values in deltas

package/index.js

@@ -5,7 +5,7 @@ module.exports = (app) => {
         // Last published best VMGs, so we only send deltas when they actually change.
         publishedBestVmg: {toCourseSide: null, fromCourseSide: null, toPortEnd: null, toStbEnd: null},
         publishedBestVmgOverrides: {toCourseSide: null, fromCourseSide: null, toPortEnd: null, toStbEnd: null},
-        publishedBestApproach: 'null',
+        publishedEffectiveVmg: {toLine: null, alongLine: null},
     };
     const geolib = require('geolib')
     const racerSchema = {
@@ -62,6 +62,11 @@ module.exports = (app) => {
                 title: 'Minimum VMG component in m/s for a sample to be collected in that direction',
                 default: 0.01
             },
+            minEffectiveVmg: {
+                type: 'number',
+                title: 'Minimum effective VMG in knots used to estimate time to line',
+                default: 0.5
+            },
             maxDistance: {
                 type: 'number',
                 title: 'Maximum distance to line and/or line zone in meters to consider for VMG calculations',
@@ -116,13 +121,14 @@ module.exports = (app) => {
         collectVmgSamples,
         resetVmgSamples,
         computeTimeToLine,
+        startZoneDistances,
+        effectiveVmg,
         vmgNames,
         getAllBestVmg,
         getBestVmgOverrides,
         setBestVmg,
         clearBestVmgOverrides,
         swapVmgEnds,
-        getBestApproach
     } = require('./racer');
 
     const unsubscribes = [];
@@ -139,11 +145,23 @@ module.exports = (app) => {
                         "value": {
                             "type": "number",
                             "units": "m",
+                            "displayUnits": { "category": "length" },
                             "description": "Length of the start line",
                             "displayName": "Length of the start line",
                             "shortName": "SLL"
                         }
                     },
+                    {
+                        "path": "navigation.racing.distanceStartline",
+                        "value": {
+                            "type": "number",
+                            "units": "m",
+                            "displayUnits": { "category": "length" },
+                            "description": "The minimum distance from the bow to the start line, via perpendicular approach",
+                            "displayName": "Distance to the start line",
+                            "shortName": "DTL"
+                        }
+                    },
                     {
                         "path": "navigation.racing.startLineBearing",
                         "value": {
@@ -155,12 +173,23 @@ module.exports = (app) => {
                         }
                     },
                     {
-                        "path": "navigation.racing.bestApproach",
+                        "path": "navigation.racing.effectiveVmg.toLine",
                         "value": {
-                            "type": "object",
-                            "description": "The course actually sailed that achieved the best VMG towards the line: {cog in rad, sog in m/s, direction}",
-                            "displayName": "Best approach course",
-                            "shortName": "Approach"
+                            "type": "number",
+                            "units": "m/s",
+                            "description": "VMG the perpendicular leg of the time to line was divided by: the collected best across the line, or the VMG being sailed right now if that is better",
+                            "displayName": "Effective VMG to line",
+                            "shortName": "VMG>Line"
+                        }
+                    },
+                    {
+                        "path": "navigation.racing.effectiveVmg.alongLine",
+                        "value": {
+                            "type": "number",
+                            "units": "m/s",
+                            "description": "VMG the along-line leg of the time to line was divided by, zero when inside the start zone",
+                            "displayName": "Effective VMG along line",
+                            "shortName": "VMG>Zone"
                         }
                     },
                     {
@@ -208,6 +237,7 @@ module.exports = (app) => {
                         "value": {
                             "type": "number",
                             "units": "m",
+                            "displayUnits": { "category": "length" },
                             "description": "Bias of the start line for the starboard end",
                             "displayName": "Bias of the start line for the starboard end",
                             "shortName": "Bias"
@@ -322,9 +352,6 @@ module.exports = (app) => {
     function publishBestVmg(position = {}) {
         const best = state.startLine ? getAllBestVmg() : null;
         const overrides = state.startLine ? getBestVmgOverrides() : null;
-        const approach = state.startLine
-            ? getBestApproach(position.ocs, position.toZoneVz, position.closestEnd)
-            : null;
         const deltas = [];
 
         for (const name of Object.keys(vmgNames)) {
@@ -344,17 +371,20 @@ module.exports = (app) => {
             }
         }
 
-        // The actual course behind the best VMG towards the line, rounded so a sample
-        // change rather than float noise is what triggers a delta.
-        const rounded = approach ? {
-            cog: Math.round(approach.cog * 10000) / 10000,
-            sog: Math.round(approach.sog * 1000) / 1000,
-            direction: approach.direction
-        } : null;
-        const approachJson = JSON.stringify(rounded);
-        if (state.publishedBestApproach !== approachJson) {
-            state.publishedBestApproach = approachJson;
-            deltas.push({path: 'navigation.racing.bestApproach', value: rounded});
+        // The two VMGs the time to line was actually divided by. These are what a client
+        // needs to draw the legs the estimate was built from; the collected bests above
+        // are only half the story, since the boat sailing better than its history right
+        // now wins. Only published once there is a position to resolve them against.
+        if (position.lineBearing != null) {
+            const effective = effectiveVmg(position.cog, position.sog, position.lineBearing,
+                position.toZoneVz, position.ocs, position.closestEnd);
+            for (const leg of ['toLine', 'alongLine']) {
+                const value = state.startLine ? Math.round(effective[leg] * 1000) / 1000 : null;
+                if (state.publishedEffectiveVmg[leg] !== value) {
+                    state.publishedEffectiveVmg[leg] = value;
+                    deltas.push({path: `navigation.racing.effectiveVmg.${leg}`, value});
+                }
+            }
         }
 
         if (deltas.length > 0)
@@ -720,6 +750,14 @@ module.exports = (app) => {
             if (!args)
                 return complete(callback, 400, 'Failed to set best VMG: no value');
 
+            if (args.command === 'clear') {
+                // Throw away everything collected, not just the manual adjustments, so
+                // the estimate starts again from what the boat does next.
+                resetVmgSamples();
+                publishBestVmg();
+                return complete(callback, 200, 'Cleared best VMG samples: OK');
+            }
+
             if (args.command === 'reset') {
                 // No vmg name clears every override.
                 if (!clearBestVmgOverrides(args.vmg))
@@ -1036,12 +1074,11 @@ module.exports = (app) => {
                 angle = 180 - (bearingToEnd - startLine.bearing);
             }
             angle = ((angle + 180) % 360 + 360) % 360 - 180;
-            const ocs = angle < 0;
 
-            // We define a start zone which includes a 45° wedge off each end of the line.
-            // - If the boat is inside the start zone, distanceToLine = perpendicular to line (or extension).
-            // - If the boat is outside the start zone, distanceToLine = distance parallel to the line to enter the zone +
-            //   perpendicular distance to the line (or extension).
+            // The start zone is a 45 degree wedge off each end of the line.
+            // - Inside the zone, distanceToLine = perpendicular to the line (or extension).
+            // - Outside it, distanceToLine = distance parallel to the line out to the
+            //   wedge, plus that perpendicular distance: an L whose corner sits on the 45.
             // This is illustrated for the starboard closest end of the line below:
             //     \                                     /
             //      \                                   /
@@ -1053,24 +1090,10 @@ module.exports = (app) => {
             //  /                                           \
             //
             // P=pin; B=boat; x=extension; b=perpToBoat; z=zoneEntry; V=vessel; N=north
-            // bearing = NBP
-            // PBz == 135
-            // bBz == zBx == 45
-            // Bb == bz == Vx == perpendicular distance to the line or extension.
-            // PBV = abs(angle)
-            // VBx = 180 - PBV
-            // Vx = toEnd * sin (VBx)
-            // bBV = 90 - VBx
-            // Vb = toEnd * sin (bBV)
-            // zb = sqrt((Vx * Vx) / 2)
-            // Vz = Vb - zb
-            const anglePBV = Math.abs(angle);
-            const inStartZone = anglePBV <= 135;
-            const angleVBx = 180 - anglePBV;
-            const perpToLineVx = toEnd * Math.sin(toRadians(angleVBx));
-            let toZoneVz = inStartZone ? 0 : ( toEnd * Math.sin(toRadians(90 - angleVBx)) - Math.sqrt(perpToLineVx * perpToLineVx / 2.0));
-            const toLine = Math.round( 10 * (toZoneVz + perpToLineVx)) / 10;
-            const distanceToLine = ocs ? -toLine : toLine;
+            // bearing = NBP, PBz == 135, bBz == zBx == 45, Bb == bz == Vx == perpendicular
+            // distance to the line or extension, PBV = abs(angle), VBx = 180 - PBV.
+            // The geometry itself lives in racer.js so it can be unit tested.
+            const {ocs, perpToLineVx, toZoneVz, distanceToLine} = startZoneDistances(toEnd, angle);
             app.debug('distanceToLine:' + distanceToLine);
             state.distanceToLine = distanceToLine;
 
@@ -1081,14 +1104,18 @@ module.exports = (app) => {
                 collectVmgSamples(cog, sog, startLine.bearing, toZoneVz, perpToLineVx);
             }
             const ttl = computeTimeToLine(cog, sog, startLine.bearing, toZoneVz, perpToLineVx, ocs, closestEnd, state.timeToStart ?? 0);
-            const ttb = !ocs && state.timerRunning && state.timeToStart > 0 && ttl != null ? (state.timeToStart - ttl) : null;
+            // Time to burn stands when OCS too: the time to line is then the time to get
+            // back over the line from the course side, so the spare time before you have
+            // to turn and do it is just as real - and goes negative when you have left it
+            // too late, which is exactly when it is worth reading.
+            const ttb = state.timerRunning && state.timeToStart > 0 && ttl != null ? (state.timeToStart - ttl) : null;
 
             sendDeltas([
                 {path: 'navigation.racing.distanceStartline', value: distanceToLine},
                 {path: "navigation.racing.timeToLine", value: ttl},
                 {path: "navigation.racing.timeToBurn", value: ttb}
             ]);
-            publishBestVmg({ocs, toZoneVz, closestEnd});
+            publishBestVmg({ocs, toZoneVz, closestEnd, cog, sog, lineBearing: startLine.bearing});
 
         } else if (state.distanceToLine) {
             state.distanceToLine = null;
@@ -1242,6 +1269,7 @@ module.exports = (app) => {
             initRacer({
                 minSog: options.minSog ?? 1.0,
                 minVmg: options.minVmg ?? 0.01,
+                minEffectiveVmg: (options.minEffectiveVmg ?? 0.5) * 0.514444,
                 maxDistance: options.maxDistance ?? 2000,
                 maxSamples: options.maxSamples ?? 600,
                 percentile: options.percentile ?? 0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-racer",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Signalk plugin to calculate values of interest to sail racers, such as: Time to Start; Time of Start, Time to Burn; Distance to Line; Next leg TWA.",
   "main": "index.js",
   "repository": {