diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 492c75d..7264c3b 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -74,6 +74,7 @@ export default defineConfig({ items: [ { text: 'Hello World', link: '/reference/output/HelloWorld' }, { text: 'Line Chart', link: '/reference/output/ChartLine' }, + { text: 'Area Chart', link: '/reference/output/ChartArea' }, { text: 'Secure Modem', link: '/reference/output/SecureModem' }, { text: 'Custom', link: '/reference/output/Custom' }, { text: 'Grafana', link: '/reference/output/Grafana' }, diff --git a/docs/assets/plotter-chartarea.webp b/docs/assets/plotter-chartarea.webp new file mode 100644 index 0000000..89b9b25 Binary files /dev/null and b/docs/assets/plotter-chartarea.webp differ diff --git a/docs/reference/middleware/Custom.md b/docs/reference/middleware/Custom.md index f065a2e..9768aa4 100644 --- a/docs/reference/middleware/Custom.md +++ b/docs/reference/middleware/Custom.md @@ -5,7 +5,9 @@ outline: deep # Custom Middleware ```lua -telem.middleware.custom (handler: fun(collection: MetricCollection): MetricCollection) +telem.middleware.custom ( + handler: fun(collection: MetricCollection): MetricCollection +) ``` This middleware wraps a user-provided function for custom middleware implementations. Need to calculate the ratio between two metrics? Count the total number of items from an adapter? Measure a metric relative to an in-game day? Anything is possible! diff --git a/docs/reference/output/ChartArea.md b/docs/reference/output/ChartArea.md new file mode 100644 index 0000000..8e84cf4 --- /dev/null +++ b/docs/reference/output/ChartArea.md @@ -0,0 +1,113 @@ +--- +outline: deep +--- + +# Area Chart Output + +```lua +telem.output.plotter.area ( + win: window, + filter: string, + bg: color, + fg: color, + baseline: number, + maxEntries: number +) +``` + +::: tip +This adapter is [cacheable](/reference/Backplane#cache). +::: + +Search the available metrics using the syntax defined in [`find`](/reference/MetricCollection#find) and output an area chart to a specified window. If a matching metric is found, the metric value is pushed to the chart buffer. + +The X axis (horizontal value) represents the number of data points recorded, and has a default width of `50`, which can be overridden by passing `maxEntries` in the constructor. The Y axis (vertical) represents the value of the metric over time. Once the fixed width of the graph is reached, the oldest values will be dropped from the buffer when new values are added. The minimum and maximum range of the Y axis is determined by the minimum and maximum metric values in the graph buffer. The background of the widget and all labels will be `bg`, and the graph/text color will be `fg`. + +The `baseline` parameter sets the Y value at which the area will be bounded, and defaults to `0`. Values between the baseline and the metric value will be filled with the `fg` color. + +The minimum and maximum labels are designed to shorten themselves using SI suffixes to fit within the available width. + + + + + + + +## Usage + +```lua{18} +local telem = require 'telem' + +local mon = peripheral.wrap('top') +mon.setTextScale(0.5) +local monw, monh = mon.getSize() +local win = window.create(mon, 1, 1, monw, monh) + +local step = 1 + +local backplane = telem.backplane() + :addInput('custom_rand', telem.input.custom(function () + step = step + 1 + + return { + rand = math.sin(2 * math.pi * (step / 50)) + } + end)) + :addOutput('monitor_rand1', telem.output.plotter.area(win, 'rand', colors.black, colors.red, 0)) + +parallel.waitForAny( + backplane:cycleEvery(0.1) +) +``` + +## Behavior + +![Plotter Area Chart output](/assets/plotter-chartarea.webp) \ No newline at end of file diff --git a/docs/reference/output/ChartLine.md b/docs/reference/output/ChartLine.md index f17e3f6..2a1bfc2 100644 --- a/docs/reference/output/ChartLine.md +++ b/docs/reference/output/ChartLine.md @@ -2,7 +2,7 @@ outline: deep --- -# Plotter Line Chart Output +# Line Chart Output ```lua telem.output.plotter.line (