feat: differential gauge (#380)

toorshia · Dec 1, 2022 · c2fc3cb · c2fc3cb
1 parent da56338
commit c2fc3cb
Show file tree

Hide file tree

Showing 3 changed files with 82 additions and 7 deletions.
diff --git a/README.md b/README.md
@@ -136,7 +136,8 @@ setInterval(() => {
 | showInnerShadow      | `false`                             | Show inner shadow                                                                                               |
 | humanFriendly        | `false`                             | convert large numbers for min, max, value to human friendly (e.g. 1234567 -> 1.23M)                             |
 | noGradient           | `false`                             | Whether to use gradual color change for value, or sector-based                                                  |
-| donut                | `false`                             | Show donut gauge                                                                                                |
+| donut                | `false`                             | Show donut gauge                  
+| differential         | `false`                             | min must = -max and pointer will be at top when = 0
 | relativeGaugeSize    | `false`                             | Whether gauge size should follow changes in container element size                                              |
 | counter              | `false`                             | Animate text value number change                                                                                |
 | decimals             | `0`                                 | Number of digits after floating point                                                                           |

diff --git a/docs/examples/differential.html b/docs/examples/differential.html
@@ -0,0 +1,35 @@
+<div id="gauge"></div>
+
+<!-- Raphael must be included before justgage -->
+<script type="text/javascript" src="./raphael.min.js"></script>
+<script type="text/javascript" src="./justgage.js"></script>
+
+<script>
+
+  var gauge = new JustGage({
+    id: "gauge", // the id of the html element
+    value: 20,
+    min: -50,
+    max: 50,
+    label: "Amps",
+    decimals: 2,
+    gaugeWidthScale: 0.6,
+    differential: true,
+    pointer: true,
+    pointerOptions: {
+      toplength: -30,
+      bottomlength: 10,
+      bottomwidth: 10,
+      color: '#8e8e93',
+      stroke: '#ffffff',
+      stroke_width: 2,
+      stroke_linecap: 'round'
+    }
+  });
+
+  // update the value randomly
+  setInterval(() => {
+    gauge.refresh(Math.random() * 100 - 50);
+  }, 5000)
+
+</script>
diff --git a/justgage.js b/justgage.js
@@ -252,6 +252,10 @@
       // show full donut gauge
       donut: kvLookup("donut", config, dataset, false),
 
+      // differential : bool
+      // show gauge with 0 at 12 o'clock
+      differential: kvLookup("differential", config, dataset, false),
+
       // relativeGaugeSize : bool
       // whether gauge size should follow changes in container element size
       relativeGaugeSize: kvLookup("relativeGaugeSize", config, dataset, false),
@@ -499,7 +503,7 @@
      * @param {Number} value display value
      * @returns SVG path string for gauge level
      */
-    obj.canvas.customAttributes.pki = function (value) {
+    obj.canvas.customAttributes.pki = function (value, isDiff) {
       let min = obj.config.min;
       let max = obj.config.max;
       const w = obj.params.widgetW;
@@ -509,9 +513,9 @@
       const gws = obj.config.gaugeWidthScale;
       const donut = obj.config.donut;
 
-      let alpha, Ro, Ri, Cx, Cy, Xo, Yo, Xi, Yi, path;
+      let alpha, Ro, Ri, Cx, Cy, So, Si, Xo, Yo, Xi, Yi, path;
 
-      if (min < 0) {
+      if (min < 0 && !isDiff) {
         max -= min;
         value -= min;
         min = 0;
@@ -543,6 +547,36 @@
         path += "A" + Ri + "," + Ri + " 0 0 0 " + (Cx - Ri) + "," + Cy + " ";
         path += "Z ";
 
+        return {
+          path: path,
+        };
+      } else if (isDiff) {
+        // At the moment only works with min = -max
+        // otherwise would need to work out the zero point
+        // Which of course is possible, but haven't done it yet
+        alpha = (1 - (value - min) / (max - min)) * Math.PI;
+        Ro = w / 2 - w / 10;
+        Ri = Ro - (w / 6.666666666666667) * gws;
+
+        Cx = w / 2 + dx;
+        Cy = h / 1.25 + dy;
+
+        Xo = Cx + Ro * Math.cos(alpha);
+        Yo = Cy - Ro * Math.sin(alpha);
+        Xi = Cx + Ri * Math.cos(alpha);
+        Yi = Cy - Ri * Math.sin(alpha);
+
+        So = value < 0 ? 1 : 0;
+        Si = value < 0 ? 0 : 1;
+
+        path = "M" + Cx + "," + (Cy - Ri) + " ";
+        path += "L" + Cx + "," + (Cy - Ro) + " ";
+        path += "A" + Ro + "," + Ro + " 0 0 " + Si + " " + Xo + "," + Yo + " ";
+        path += "L" + Xi + "," + Yi + " ";
+        path +=
+          "A" + Ri + "," + Ri + " 0 0 " + So + " " + Cx + "," + (Cy - Ri) + " ";
+        path += "Z ";
+
         return {
           path: path,
         };
@@ -713,8 +747,12 @@
         obj.config.noGradient,
         obj.config.customSectors
       ),
-      pki: [obj.config.min],
+      pki: [
+        obj.config.differential ? 0 : obj.config.min,
+        obj.config.differential,
+      ],
     });
+
     if (obj.config.donut) {
       obj.level.transform(
         "r" +
@@ -955,9 +993,10 @@
     if (obj.config.reverse) {
       rvl = obj.config.max * 1 + obj.config.min * 1 - obj.config.value * 1;
     }
+
     obj.level.animate(
       {
-        pki: [rvl],
+        pki: [rvl, obj.config.differential],
       },
       obj.config.startAnimationTime,
       obj.config.startAnimationType,
@@ -1148,7 +1187,7 @@
 
     obj.level.animate(
       {
-        pki: [rvl],
+        pki: [rvl, obj.config.differential],
         fill: color,
       },
       obj.config.refreshAnimationTime,