JSignage:Graph:Circular gauges

From SpinetiX Support Wiki

Jump to: navigation, search

This page is related to jSignage Graph API.

Introduction

A basic circular gauge represents a single data item by rotating an indicator along a circular path to point to the current data value.

A circular bar gauge represents one or more data item values by filling a progress bar with a solid color from the baseline to the current value along a circular path.


Note Notes:

  • The main axis is a continuous axis representing the possible values for the data item(s) on a circle that occupies the whole "chart area" and is centered on it. An optional alternative axis might also be used to represent the same values with alternative units.
  • One or more "threshold" bars can be drawn next to the axes.
  • The fill color of each bar in a group or stack is adjusted separately.
  • If labels are provided then a legend box can be included in the layer next to the graph area.
  • Text can be drawn at configurable positions in the gauge. This is can be static text or text representing the current value with a configurable formatting (only available for singular data).
  • If the gauge is made dynamic, its value(s) can change in real-time, with or without an animation of the bars and indicator (if any).

Classification

Data size Basic circular gauges Circular bar gauges
Single value $.Graph.circularGauge() $.Graph.circularBarGauge()
Multiple values $.Graph.groupedCircularBarGauge()
$.Graph.stackedCircularBarGauge()
$.Graph.stackedAndGroupedCircularBarGauge()

Gallery of circular gauges

.Graph.circularGauge()

$.Graph.circularGauge( attributes );

Returns: jSignage Object

Description

Draws a circular gauge layer displaying a single data item by rotating an indicator along a circular axis defined by the user, to point to the current data value. An indicator is always present on this type of gauge and a thresholds bar is typically used to represent the expected normal range of the value.

Parameters

.Graph.circularBarGauge()

$.Graph.circularBarGauge( attributes );

Returns: jSignage Object

Description

Draws a circular bar gauge layer displaying a single data item by filling a progress bar with a solid color from the baseline to the current value along a circular axis defined by the user. The color of the bar can be made dependent on the current value according to a defined set of colors for different thresholds. For dynamic gauges, the color changes gradually from the first color to the color corresponding to the current value.

An indicator is optional for this type of gauge.

Parameters

  • attributes
    Type: Plain Object.
    The circular bar gauge layer attributes, containing any of the common attributes of circular gauges and the following attributes:
    • data (required)
      Type: Number. Default: 0.
      The value to be displayed.
    • color
      Type: Color.
      Defines the color to be used for a solid fill of the bar.
    • colors
      Type: Array.<Plain Object>.
      Array of objects that define different colors that the bar might have depending on data value to be displayed. Each object has the following properties:
      • color
        Type: Color.
        Defines the color to apply within the range of values.
      • from
        Type: Number. Default: The to value of the previous range (if any) or dataMin.
        Minimum value for which this color applies.
      • to
        Type: Number. Default: The from value of the next range (if any) or dataMax.
        Maximum value (not inclusive) to which this color applies.
    • indicator
      An indicator styling object.

.Graph.groupedCircularBarGauge()

$.Graph.groupedCircularBarGauge( attributes );

Returns: jSignage Object

Description

Draws a layer with one or more circular bar gauges grouped together. The fill color of each bar can be adjusted separately. This type of gauge cannot display an indicator.

Parameters

  • attributes
    Type: Plain Object.
    The grouped circular bar gauge layer attributes, containing any of the common attributes of circular gauges and the following attributes:
    • data (required)
      Type: Array.<Number>. Default: [].
      Array of numbers, where each value corresponds to a bar gauge.
    • colors
      Type: Array.<Color>.
      Defines the colors to be used for a solid fill of each bar.
    • labels
      Type: Array.<String>.
      Defines the labels to be used for each bar gauge.

.Graph.stackedCircularBarGauge()

$.Graph.stackedCircularBarGauge( attributes );

Returns: jSignage Object

Description

Draws a layer with one or more circular bar gauges stacked together. The fill color of each bar can be adjusted separately. This type of gauge cannot display an indicator.

Parameters

  • attributes
    Type: Plain Object.
    The stacked circular bar gauge layer attributes, containing any of the common attributes of circular gauges and the following attributes:
    • data (required)
      Type: Array.<Number>. Default: [].
      Array of numbers, where each value corresponds to a bar gauge.
    • colors
      Type: Array.<Color>.
      Defines the colors to be used for a solid fill of each bar.
    • labels
      Type: Array.<String>.
      Defines the labels to be used for each bar gauge.

.Graph.stackedAndGroupedCircularBarGauge()

$.Graph.stackedAndGroupedCircularBarGauge( attributes );

Returns: jSignage Object

Description

Draws a layer with one or more circular bar gauges stacked and grouped together. This type of gauge cannot display an indicator.

Parameters

  • attributes
    Type: Plain Object.
    The stacked and grouped circular bar gauge layer attributes, containing any of the common attributes of circular gauges and the following attributes:
    • data (required)
      Type: Array.<Array.<Number>>. Default: [].
      2D array of numbers, where each set of values corresponds to a group of stacked bar gauges and each value inside corresponds to a bar gauge. The first dimension is the position along the major axis (i.e. the group), the second dimension is the position within the stack.
    • colors
      Type: Array.<Color>.
      Defines the colors to be used for a solid fill of each bar.
    • labels
      Type: Array.<String>.
      Defines the labels to be used for each bar gauge.

Common attributes

See also Graph styling attributes page.

The following attributes are common to circular gauges:

  • altAxis
    Type: Plain Object. Default: null.
    Continuous axis object configuring an alternative axis. The default position for the alternative axis is 'out'.
  • animationDur
    Type: Number or String. Default: 0 (no animation).
    Defines the animation time as a number of seconds or as a text (e.g. '500ms'). The dynamic attribute must be set to true to be considered.
  • axis
    Type: Plain Object.
    Continuous axis object configuring the main axis. Note that for bar gauges, the axis circle is not displayed by default and axis.axis must be set to true to draw it. Three additional axis properties are specific to circular gauges:
    • offset
      Type: Number or String. Default: 0.
      Offset from the selected position in pixels or as a percentage of the layer size.
    • position
      Type: Number or String. Default: 'in'.
      Determines on which side of the bar the axis is drawn. It can be either 'in' or 'out'.
    • reverse
      Type: Boolean. Default: false.
      Defines whether the gauge is drawn clockwise (false) or anticlockwise (true).
  • axisStrokeStyle
    Type: Plain Object.
    Stroke styling object which serves as a default for drawing axis circles.
  • backColor
    Type: Color. Default: null.
    Defines the color to be used for a solid fill of the bar gauge background area. This doesn't apply for basic circular gauges.
  • barWidth
    Type: Number or String. Default: '100%'.
    Width occupied by the bar either in pixels or as a percentage relative to the gauge radius. This doesn't apply for basic circular gauges.
  • chartArea
    Type: Plain Object. Default: null.
    Object with top, left, width and height attributes to define the position of the circle within the layer. By default the chart will occupy as much space as possible without overlapping the legend box.
  • dataMax
    Type: Number. Default: 1.
    Maximum value for data items to be displayed on the axis.
  • dataMin
    Type: Number. Default: 0.
    Minimum value for data items to be displayed on the axis.
  • dynamic
    Type: Boolean. Default: false.
    Defines whether the gauge is dynamic. When set to true, the gauge can be animated and updated (i.e. the gauge layer has an update() function; calling this method updates the gauge with new data, then redraws it with or without an animation depending on animation parameters).
  • endAngle
    Type: Number. Default: 135.
    Angle at which the circle ends.
  • fontFamily, fontSize, fontStyle, fontVariant, fontWeight
    Type: String or Number.
    Default text styling attributes for gauge text, axis text and legend. The fontSize is set by default to 5% of layer size.
  • gaugeRadius
    Type: Number or String. Default: 1/6th of layer size.
    Width of the bar area as a number of pixels or percentage of the layer size. This doesn't apply for basic circular gauges.
  • legend
    Type: Plain Object.
    Legend styling object.
  • startAngle
    Type: Number. Default: -135.
    Angle at which the circle starts.
  • text
    Type: Plain Object or Array.<Plain Object>.
    One or more text description objects with the following properties:
    • angle
      Type: Number. Default: (startAngle + endAngle)/2.
      Defines the angle at which the center of the text is positioned.
    • format
      Type: String. Default: default numerical format of the chart locale.
      Number format string to display the current data as text.
    • placement
      Type: String. Default: 'inside'.
      Position of the text relative to the chart area, one of:
      • 'inside' to adjust the position of the text so that it lies entirely inside a virtual circle determined by the text's radius property. To do this, the text may be drawn closer to the center of the chart.
      • 'outside' to adjust the position of the text so that it lies entirely outside a virtual circle determined by the text's radius property. To do this, the text may be drawn farther from the center of the chart.
      • 'center' to draw the text at the specified position.
    • radius
      Type: Number or String. Default: chart radius.
      Distance from the center at which the center of the text is positioned, as a number of pixel or percentage of the chart radius.
    • style
      Type: Plain Object.
      Text styling object to customize the text.
    • text
      Type: String.
      Static text to display. Use of the format property will override it.
  • thresholds
    Type: Plain Object or Array.<Plain Object>.
    One or more gauge thresholds bar styling objects to display one or more bars with thresholds indications.

Common functions

.update()

gauge_layer.update( data );

Returns: undefined

Description

Updates the gauge data attribute, then redraws the gauge layer, with or without an animation of the bars and indicator (if any), depending on animation parameters. This function becomes available for the gauge layer when the dynamic gauge attribute is set to true.

  • The type of the data parameter must be identical to the data attribute detailed under each circular gauge function.
  • See an example of usage for this function.

Examples

Circular gauge
Circular gauge
// draw a circular gauge
$.Graph.circularGauge( {
    data: 75, dataMax: 100,
    top: 80, width: 1280, height: 640,
    axis: {
        position: 'in',
        tickMarks: { length: '5%' },
        minorTickMarks: { length: '75%' }
    },
    text: {
        text: 'Gauge Meter', radius: '40%',
        style: { color: '#888', fontStyle: 'italic' }
    }
} ).addTo('svg');

Circular gauge with thresholds bar
Circular gauge with thresholds bar
// draw a circular gauge having a thresholds bar
$.Graph.circularGauge( {
    data: 75, dataMax: 100,
    top: 80, width: 1280, height: 640,
    axis: {
        axis: false, position: 'in',
        tickMarks: { length: '7%', strokeStyle: { color: '#fff' } },
        minorTickMarks: { count: 4, length: '50%' },
        textStyle: { color: '#666' }
    },
    thresholds: {
        position: 'out', size: '6%',
        zones: [ { to:  40, color: '#0e0'},
                 { to:  80, color: '#fe0'},
                 { to: 100, color: '#e00'}
        ]
    }    
} ).addTo('svg');

Circular bar gauge with dynamic colors
Circular bar gauge with dynamic colors
// draw a circular bar gauge with dynamic colors 
var gaugeChart = 
$.Graph.circularBarGauge( {
    data: 60, dataMax: 100,
    top: 100, width: 1280, height: 1000,
    startAngle: -90, endAngle: 90, backColor: '#ccc', gaugeRadius: '15%',
    dynamic: true, animationDur: 1,
    axis: { textPlacement: 'none' },
    colors: [ { color: '#0e0', to: 40 },
              { color: '#fe0', to: 80 },
              { color: '#e00' }
    ],
    text: [ { format: '#', radius: '40%', angle: 0,
              style: { fontSize: 120, fontWeight: 'bold' } }, 
            { text: 'Visitors/min', radius: '20%', angle: 0,
              style: { fontSize: 60, color: '#888' } }, 
            { text: '0', radius: '86%', angle: -95,
              style: { fontSize: 60, color: '#888' } }, 
            { text: '100', radius: '86%', angle: 95,
              style: { fontSize: 60, color: '#888' } }
    ]
} ).addTo('svg');  

// update the gauge data every 2s with a random number
$.setInterval( function() {
    gaugeChart.update( Math.random()*100 );
}, 2000 );

Circular bar gauge with indicator and axis
Circular bar gauge with indicator and axis
// draw a circular bar gauge
$.Graph.circularBarGauge( {
    data: 750, dataMax: 1000,
    width: 1280, height: 740,
    backColor: '#ccc', fontSize: 24, barWidth: '80%', gaugeRadius: '15%',
    axis: { 
        axis: true, position: 'out', offset: '1%', minorTickMarks: true,
        tickMarks: { length: '5%' }
    },
    axisStrokeStyle: { lineWidth: 2 },
    indicator: {
        shape: 'arrow', position: 'out', offset: '1%', 
        color: $.Graph.red
    },
    text: [ { radius: 60, angle: 0,
              style: { fontWeight: 'bold', fontSize: 60 } }, 
            { text: 'RPM', radius: 60, angle: 180,
              style: { fontWeight: 'bold', fontSize: 40, color: '#888' } }
    ]
} ).addTo('svg');

Grouped circular bar gauge
Grouped circular bar gauge
// draw a grouped circular bar gauge
$.Graph.groupedCircularBarGauge( {
    data: [ 750, 600 ], dataMax: 1000,
    width: 1280, height: 740,
    backColor: '#ccc', fontSize: 24, barWidth: '80%', 
    axis: { 
        axis: true, position: 'out', offset: '1%', minorTickMarks: true,
        tickMarks: { length: '5%' }
    },
    axisStrokeStyle: { lineWidth: 2 },
    labels: [ 'Left engine', 'Right engine' ],
    legend: {
        position: { top: 660, width: 1280, height: 120 },
        alignment: 'center', orientation: 'horizontal'
    },
    text: { 
        text: 'RPM', radius: 0,
        style: { fontWeight: 'bold', fontSize: 40, color: '#888' }
    }
} ).addTo('svg');

Stacked circular bar gauge
Stacked circular bar gauge
// draw a stacked circular bar gauge
$.Graph.stackedCircularBarGauge( {
    data: [ 250, 150, 300, 200 ],
    dataMax: 1000,
    width: 1280, height: 740,
    backColor: '#ccc', fontSize: 24, barWidth: '80%',
    axis: { 
        axis: true, position: 'out', offset: '1%',
        minorTickMarks: true,
        tickMarks: { length: '5%' }
    },
    axisStrokeStyle: { lineWidth: 2 }
} ).addTo('svg');

Retrieved from "https://support.spinetix.com/w/index.php?title=JSignage:Graph:Circular_gauges&oldid=12403"
This page was last modified on 19 October 2016, at 12:15.