signalk-polar-performance-plugin 0.0.57 → 0.0.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-polar-performance-plugin",
-  "version": "0.0.57",
+  "version": "0.0.59",
   "description": "A plugin that calculates performance information based on a (CSV) polar diagram.",
   "main": "plugin/index.js",
   "scripts": {

package/plugin/index.js

@@ -243,89 +243,132 @@ module.exports = function (app) {
       }
 
       if (BSP) {
-        addValue('performance.boatSpeedDamped', BSP, { units: 'm/s' })
+        addValue('performance.boatSpeedDamped', BSP, { 
+          units: 'm/s',
+          description: 'Boat speed after applying damping factor (see Polar Performance Plugin settings).'
+       })
       }
 
       if (TWA) {
         addValue('environment.wind.angleTrueWaterDamped', TWA * port, {
-          units: 'rad'
+          units: 'rad',
+          description: 'True Wind Angle after applying damping factor, negative to port (see Polar Performance Plugin settings).'
         })
       }
 
       if (typeof perfObj.beatAngle !== 'undefined') {
         if (options.beatAngle === true) {
-          addValue('performance.beatAngle', perfObj.beatAngle * port)
+          addValue('performance.beatAngle', perfObj.beatAngle * port, {
+            units: 'rad',
+            description: 'The optimal beat/upwind angle for current TWS, negative to port.'
+          })
         }
         if (options.targetTWA === true) {
-          addValue('performance.targetAngle', perfObj.beatAngle * port)
+          addValue('performance.targetAngle', perfObj.beatAngle * port, {
+            units: 'rad',
+            description: 'The combined and automatic switching optimal beat or run angle for current TWS, negative to port.'
+          })
         }
       }
 
-      if (typeof perfObj.beatVMG !== 'undefined') {
-        addValue('performance.beatAngleVelocityMadeGood', perfObj.beatVMG)
+      if (typeof perfObj.runAngle !== 'undefined') {
+        if (options.beatAngle === true) {
+          addValue('performance.gybeAngle', perfObj.runAngle * port, {
+            units: 'rad',
+            description: 'The optimal run/downwind angle for current TWS, negative to port.'
+          })
+        }
         if (options.targetTWA === true) {
-          addValue('performance.targetVelocityMadeGood', perfObj.beatVMG, {
-            units: 'm/s'
+          addValue('performance.targetAngle', perfObj.runAngle * port, {
+            units: 'rad',
+            description: 'The combined and automatic switching optimal beat or run angle for current TWS, negative to port.'
           })
         }
       }
 
-      if (typeof perfObj.runAngle !== 'undefined') {
-        if (options.beatAngle === true) {
-          addValue('performance.gybeAngle', perfObj.runAngle * port)
-        }
+      if (typeof perfObj.beatVMG !== 'undefined') {
+        addValue('performance.beatAngleVelocityMadeGood', perfObj.beatVMG, {
+          units: 'm/s',
+          description: 'The beat/upwind Velocity Made Good for current boat speed and heading.'
+        })
         if (options.targetTWA === true) {
-          addValue('performance.targetAngle', perfObj.runAngle * port)
+          addValue('performance.targetVelocityMadeGood', perfObj.beatVMG, {
+            units: 'm/s',
+            description: 'The combined and automatic switching beat or run Velocity Made Good for current boat speed and heading.'
+          })
         }
       }
 
       if (typeof perfObj.runVMG !== 'undefined') {
-        addValue('performance.gybeAngleVelocityMadeGood', perfObj.runVMG)
+        addValue('performance.gybeAngleVelocityMadeGood', perfObj.runVMG, {
+          units: 'm/s',
+          description: 'The run/downwind Velocity Made Good for current boat speed and heading.'
+        })
         if (options.targetTWA === true) {
           addValue('performance.targetVelocityMadeGood', perfObj.runVMG, {
-            units: 'm/s'
+            units: 'm/s',
+            description: 'The combined and automatic switching beat or run Velocity Made Good for current TWS and TWA.'
           })
         }
       }
 
       if (typeof perfObj.optimumWindAngle !== 'undefined') {
         addValue('performance.optimumWindAngle', perfObj.optimumWindAngle, {
-          units: 'rad'
+          units: 'rad',
+          description: 'The optimum wind angle, negative to port (diff between TWA and environment.wind.directionTrue).'
         })
       }
 
       if (typeof perfObj.targetSpeed !== 'undefined') {
-        addValue('performance.targetSpeed', perfObj.targetSpeed)
+        addValue('performance.targetSpeed', perfObj.targetSpeed, { 
+            units: 'm/s',
+            description: 'Target boat speed based on current TWA.'
+           }
+        )
       }
 
       if (typeof perfObj.polarSpeed !== 'undefined') {
-        addValue('performance.polarSpeed', perfObj.polarSpeed)
-        addValue('performance.polarSpeedRatio', perfObj.polarSpeedRatio)
+        addValue('performance.polarSpeed', perfObj.polarSpeed, { 
+          units: 'm/s',
+          description: 'The polar chart boat speed as per the polar chart for current TWS and TWA.'
+        })
+        addValue('performance.polarSpeedRatio', perfObj.polarSpeedRatio, {
+          units: 'ratio',
+          description: 'The ratio between actual boat speed and polar chart boat speed for current TWS and TWA.'
+        })
         if (typeof perfObj.velocityMadeGood !== 'undefined') {
-          addValue('performance.velocityMadeGood', perfObj.velocityMadeGood)
-          addValue(
-            'performance.polarVelocityMadeGood',
-            perfObj.polarVelocityMadeGood,
-            { units: 'm/s' }
-          )
-          addValue(
-            'performance.polarVelocityMadeGoodRatio',
-            perfObj.polarVelocityMadeGoodRatio,
-            { units: 'ratio' }
-          )
+          addValue('performance.velocityMadeGood', perfObj.velocityMadeGood, {
+            units: 'm/s',
+            description: 'The actual Velocity Made Good based on current heading and boat speed.'
+          })
+          addValue('performance.polarVelocityMadeGood', perfObj.polarVelocityMadeGood, {
+            units: 'm/s',
+            description: 'The polar chart Velocity Made Good indicated in the polar for current TWS and TWA.'
+          })
+          addValue('performance.polarVelocityMadeGoodRatio', perfObj.polarVelocityMadeGoodRatio, {
+            units: 'ratio',
+            description: 'The ratio between actual Velocity Made Good and polar chart indicated Velocity Made Good for current TWS and TWA.'
+          })
         }
       }
 
       if (typeof perfObj.maxSpeed !== 'undefined') {
-        addValue('performance.maxSpeed', perfObj.maxSpeed, { units: 'm/s' })
+        addValue('performance.maxSpeed', perfObj.maxSpeed, { 
+          units: 'm/s',
+          description: 'Maximum boat speed as per polar chart.'
+        })
         addValue('performance.maxSpeedAngle', perfObj.maxSpeedAngle, {
-          units: 'rad'
+          units: 'rad',
+          description: 'The angle to achieve maximum boat speed (not the VMG), based on current TWS, negative to port.'
         })
       }
 
       if (options.tackTrue === true) {
         if (typeof perfObj.tackTrue !== 'undefined') {
-          addValue('performance.tackTrue', perfObj.tackTrue)
+          addValue('performance.tackTrue', perfObj.tackTrue, {
+            units: 'rad',
+            description: 'The Opposite Tack\'s heading relative to True North, based on current TWS.'
+          })
         }
       }
 
@@ -429,7 +472,7 @@ module.exports = function (app) {
           }
           // Calculate opposite Tack True
           // app.debug('tackTrue: port: %d HDG: %d targetTWA: %d', port, radToDeg(HDG), radToDeg(targetTWA))
-          if (port) {
+          if (port < 0) {
             let tackTrue = HDG - targetTWA
             if (tackTrue < 0) {
               tackTrue = tackTrue + 2 * Math.PI
@@ -545,15 +588,39 @@ module.exports = function (app) {
       var polar = {}
       var beat = false
 
+      function upsertTwa (polarIndex, twaObj, angleDeg) {
+        const twaArray = polar[polarIndex].twa
+        const existingIndex = twaArray.findIndex(entry => entry.twa === twaObj.twa)
+        if (existingIndex >= 0) {
+          app.error(
+            'Duplicate TWA %s deg for TWS %s kts, keeping last value',
+            angleDeg,
+            msToKts(polar[polarIndex].tws).toFixed(1)
+          )
+          twaArray[existingIndex] = twaObj
+        } else {
+          twaArray.push(twaObj)
+        }
+      }
+
       // Create array of arrays from csv
       csv.split('\n').forEach(row => {
-        csvArray.push(row.split(';'))
+        const trimmedRow = row.trim()
+        if (!trimmedRow) {
+          return
+        }
+        const cells = trimmedRow.split(';').map(cell => cell.trim())
+        if (!cells[0]) {
+          return
+        }
+        csvArray.push(cells)
       })
       // app.debug('csvArray: %s', JSON.stringify(csvArray))
 
       // Populate the polar object from CSV rows
       csvArray.forEach(row => {
-        if (row[0] == 'twa/tws') {
+        const rowKey = row[0].trim().toLowerCase()
+        if (rowKey == 'twa/tws') {
           // The row with TWS columns
           // Create empty TWS objects in polar object
           app.debug('First row with TWS columns')
@@ -566,7 +633,8 @@ module.exports = function (app) {
         } else if (row.filter(i => i === '0').length > 1) {
           app.debug('beat and run angles are included')
           // Beat / Run angle
-          let angle = degToRad(Number(row[0]))
+          let angleDeg = Number(row[0])
+          let angle = degToRad(angleDeg)
           let angleName
           let VMGName
           app.debug('angle < halfPi   %d < %d', angle, halfPi)
@@ -581,17 +649,23 @@ module.exports = function (app) {
           }
 
           for (let index = 0; index < row.length - 1; index++) {
-            if (row[index + 1] != 0) {
+            if (!row[index + 1]) {
+              continue
+            }
+            const tbsCell = Number(row[index + 1])
+            if (Number.isNaN(tbsCell) || tbsCell === 0) {
+              continue
+            }
+            if (tbsCell != 0) {
               polar[index][angleName] = angle
-              let tbs =
-                ktsToMs(Number(row[index + 1])) * (options.perfAdjust || 1)
+              let tbs = ktsToMs(tbsCell) * (options.perfAdjust || 1)
               let vmg = tbs * Math.abs(Math.cos(angle))
               polar[index][VMGName] = roundDec(vmg)
               if (typeof polar[index]['twa'] == 'undefined') {
                 polar[index]['twa'] = []
               }
               let Obj = { twa: angle, tbs: tbs, vmg: vmg }
-              polar[index]['twa'] = polar[index]['twa'].concat(Obj)
+              upsertTwa(index, Obj, angleDeg)
               app.debug('Finding max speed')
               if (
                 typeof polar[index]['Max speed'] == 'undefined' ||
@@ -605,17 +679,24 @@ module.exports = function (app) {
           }
         } else {
           // Normal line
-          let angle = degToRad(Number(row[0])) // CSV deg to internal rad
+          let angleDeg = Number(row[0])
+          let angle = degToRad(angleDeg) // CSV deg to internal rad
           for (let index = 0; index < row.length - 1; index++) {
             if (typeof polar[index].twa == 'undefined') {
               polar[index].twa = []
             }
-            let tbs =
-              ktsToMs(Number(row[index + 1])) * (options.perfAdjust || 1)
+            if (!row[index + 1]) {
+              continue
+            }
+            const tbsCell = Number(row[index + 1])
+            if (Number.isNaN(tbsCell)) {
+              continue
+            }
+            let tbs = ktsToMs(tbsCell) * (options.perfAdjust || 1)
             let vmg = tbs * Math.abs(Math.cos(angle))
             let Obj = { twa: angle, tbs: tbs, vmg: vmg }
             // app.debug('Adding Obj: %s', JSON.stringify(Obj))
-            polar[index]['twa'] = polar[index]['twa'].concat(Obj)
+            upsertTwa(index, Obj, angleDeg)
             // See if we need to set/overwrite beat/run angle
 
             // See if this a new Max speed