|
| 1 | +# class of sparklines in CircuitPython |
| 2 | +# created by Kevin Matocha - Copyright 2020 (C) |
| 3 | + |
| 4 | +# See the bottom for a code example using the `sparkline` Class. |
| 5 | + |
| 6 | +# # File: display_shapes_sparkline.py |
| 7 | +# A sparkline is a scrolling line graph, where any values added to sparkline using ` |
| 8 | +# add_value` are plotted. |
| 9 | +# |
| 10 | +# The `sparkline` class creates an element suitable for adding to the display using |
| 11 | +# `display.show(mySparkline)` |
| 12 | +# or adding to a `displayio.Group` to be displayed. |
| 13 | +# |
| 14 | +# When creating the sparkline, identify the number of `max_items` that will be |
| 15 | +# included in the graph. When additional elements are added to the sparkline and |
| 16 | +# the number of items has exceeded max_items, any excess values are removed from |
| 17 | +# the left of the graph, and new values are added to the right. |
| 18 | +""" |
| 19 | +`sparkline` |
| 20 | +================================================================================ |
| 21 | +
|
| 22 | +Various common shapes for use with displayio - Sparkline! |
| 23 | +
|
| 24 | +
|
| 25 | +* Author(s): Kevin Matocha |
| 26 | +
|
| 27 | +Implementation Notes |
| 28 | +-------------------- |
| 29 | +
|
| 30 | +**Software and Dependencies:** |
| 31 | +
|
| 32 | +* Adafruit CircuitPython firmware for the supported boards: |
| 33 | + https://github.com/adafruit/circuitpython/releases |
| 34 | +
|
| 35 | +""" |
| 36 | + |
| 37 | +import displayio |
| 38 | +from adafruit_display_shapes.line import Line |
| 39 | + |
| 40 | + |
| 41 | +class Sparkline(displayio.Group): |
| 42 | + # pylint: disable=too-many-arguments |
| 43 | + """A sparkline graph. |
| 44 | +
|
| 45 | + :param width: Width of the sparkline graph in pixels |
| 46 | + :param height: Height of the sparkline graph in pixels |
| 47 | + :param max_items: Maximum number of values housed in the sparkline |
| 48 | + :param y_min: Lower range for the y-axis. Set to None for autorange. |
| 49 | + :param y_max: Upper range for the y-axis. Set to None for autorange. |
| 50 | + :param x: X-position on the screen, in pixels |
| 51 | + :param y: Y-position on the screen, in pixels |
| 52 | + :param color: Line color, the default value is 0xFFFFFF (WHITE) |
| 53 | + """ |
| 54 | + |
| 55 | + def __init__( |
| 56 | + self, |
| 57 | + width, |
| 58 | + height, |
| 59 | + max_items, |
| 60 | + y_min=None, # None = autoscaling |
| 61 | + y_max=None, # None = autoscaling |
| 62 | + x=0, |
| 63 | + y=0, |
| 64 | + color=0xFFFFFF, # line color, default is WHITE |
| 65 | + ): |
| 66 | + |
| 67 | + # define class instance variables |
| 68 | + self.width = width # in pixels |
| 69 | + self.height = height # in pixels |
| 70 | + self.color = color # |
| 71 | + self._max_items = max_items # maximum number of items in the list |
| 72 | + self._spark_list = [] # list containing the values |
| 73 | + self.y_min = y_min # minimum of y-axis (None: autoscale) |
| 74 | + self.y_max = y_max # maximum of y-axis (None: autoscale) |
| 75 | + self.y_bottom = y_min |
| 76 | + # y_bottom: The actual minimum value of the vertical scale, will be |
| 77 | + # updated if autorange |
| 78 | + self.y_top = y_max |
| 79 | + # y_top: The actual minimum value of the vertical scale, will be |
| 80 | + # updated if autorange |
| 81 | + self._x = x |
| 82 | + self._y = y |
| 83 | + |
| 84 | + super().__init__( |
| 85 | + max_size=self._max_items - 1, x=x, y=y |
| 86 | + ) # self is a group of lines |
| 87 | + |
| 88 | + def add_value(self, value): |
| 89 | + """Add a value to the sparkline. |
| 90 | + :param value: The value to be added to the sparkline |
| 91 | + """ |
| 92 | + |
| 93 | + if value is not None: |
| 94 | + if ( |
| 95 | + len(self._spark_list) >= self._max_items |
| 96 | + ): # if list is full, remove the first item |
| 97 | + self._spark_list.pop(0) |
| 98 | + self._spark_list.append(value) |
| 99 | + self.update() |
| 100 | + |
| 101 | + # pylint: disable=no-else-return |
| 102 | + @staticmethod |
| 103 | + def _xintercept( |
| 104 | + x_1, y_1, x_2, y_2, horizontal_y |
| 105 | + ): # finds intercept of the line and a horizontal line at horizontalY |
| 106 | + slope = (y_2 - y_1) / (x_2 - x_1) |
| 107 | + b = y_1 - slope * x_1 |
| 108 | + |
| 109 | + if slope == 0 and y_1 != horizontal_y: # does not intercept horizontalY |
| 110 | + return None |
| 111 | + else: |
| 112 | + xint = ( |
| 113 | + horizontal_y - b |
| 114 | + ) / slope # calculate the x-intercept at position y=horizontalY |
| 115 | + return int(xint) |
| 116 | + |
| 117 | + def _plotline(self, x_1, last_value, x_2, value, y_bottom, y_top): |
| 118 | + |
| 119 | + y_2 = int(self.height * (y_top - value) / (y_top - y_bottom)) |
| 120 | + y_1 = int(self.height * (y_top - last_value) / (y_top - y_bottom)) |
| 121 | + self.append(Line(x_1, y_1, x_2, y_2, self.color)) # plot the line |
| 122 | + |
| 123 | + # pylint: disable= too-many-branches, too-many-nested-blocks |
| 124 | + |
| 125 | + def update(self): |
| 126 | + """Update the drawing of the sparkline.""" |
| 127 | + |
| 128 | + # get the y range |
| 129 | + if self.y_min is None: |
| 130 | + self.y_bottom = min(self._spark_list) |
| 131 | + else: |
| 132 | + self.y_bottom = self.y_min |
| 133 | + |
| 134 | + if self.y_max is None: |
| 135 | + self.y_top = max(self._spark_list) |
| 136 | + else: |
| 137 | + self.y_top = self.y_max |
| 138 | + |
| 139 | + if len(self._spark_list) > 2: |
| 140 | + xpitch = (self.width - 1) / ( |
| 141 | + len(self._spark_list) - 1 |
| 142 | + ) # this is a float, only make int when plotting the line |
| 143 | + |
| 144 | + for _ in range(len(self)): # remove all items from the current group |
| 145 | + self.pop() |
| 146 | + |
| 147 | + for count, value in enumerate(self._spark_list): |
| 148 | + if count == 0: |
| 149 | + pass # don't draw anything for a first point |
| 150 | + else: |
| 151 | + x_2 = int(xpitch * count) |
| 152 | + x_1 = int(xpitch * (count - 1)) |
| 153 | + |
| 154 | + if (self.y_bottom <= last_value <= self.y_top) and ( |
| 155 | + self.y_bottom <= value <= self.y_top |
| 156 | + ): # both points are in range, plot the line |
| 157 | + self._plotline( |
| 158 | + x_1, last_value, x_2, value, self.y_bottom, self.y_top |
| 159 | + ) |
| 160 | + |
| 161 | + else: # at least one point is out of range, clip one or both ends the line |
| 162 | + if ((last_value > self.y_top) and (value > self.y_top)) or ( |
| 163 | + (last_value < self.y_bottom) and (value < self.y_bottom) |
| 164 | + ): |
| 165 | + # both points are on the same side out of range: don't draw anything |
| 166 | + pass |
| 167 | + else: |
| 168 | + xint_bottom = self._xintercept( |
| 169 | + x_1, last_value, x_2, value, self.y_bottom |
| 170 | + ) # get possible new x intercept points |
| 171 | + xint_top = self._xintercept( |
| 172 | + x_1, last_value, x_2, value, self.y_top |
| 173 | + ) # on the top and bottom of range |
| 174 | + |
| 175 | + if (xint_bottom is None) or ( |
| 176 | + xint_top is None |
| 177 | + ): # out of range doublecheck |
| 178 | + pass |
| 179 | + else: |
| 180 | + # Initialize the adjusted values as the baseline |
| 181 | + adj_x_1 = x_1 |
| 182 | + adj_last_value = last_value |
| 183 | + adj_x_2 = x_2 |
| 184 | + adj_value = value |
| 185 | + |
| 186 | + if value > last_value: # slope is positive |
| 187 | + if xint_bottom >= x_1: # bottom is clipped |
| 188 | + adj_x_1 = xint_bottom |
| 189 | + adj_last_value = self.y_bottom # y_1 |
| 190 | + if xint_top <= x_2: # top is clipped |
| 191 | + adj_x_2 = xint_top |
| 192 | + adj_value = self.y_top # y_2 |
| 193 | + else: # slope is negative |
| 194 | + if xint_top >= x_1: # top is clipped |
| 195 | + adj_x_1 = xint_top |
| 196 | + adj_last_value = self.y_top # y_1 |
| 197 | + if xint_bottom <= x_2: # bottom is clipped |
| 198 | + adj_x_2 = xint_bottom |
| 199 | + adj_value = self.y_bottom # y_2 |
| 200 | + |
| 201 | + self._plotline( |
| 202 | + adj_x_1, |
| 203 | + adj_last_value, |
| 204 | + adj_x_2, |
| 205 | + adj_value, |
| 206 | + self.y_bottom, |
| 207 | + self.y_top, |
| 208 | + ) |
| 209 | + |
| 210 | + last_value = value # store value for the next iteration |
| 211 | + |
| 212 | + def values(self): |
| 213 | + """Returns the values displayed on the sparkline.""" |
| 214 | + |
| 215 | + return self._spark_list |
0 commit comments