Skip to content

Commit 2e06766

Browse files
HanSur94claude
HanSur94
and
claude
committed
docs(readme): rewrite for v2.0 Tag API and trim to 160 lines
Replaces the old 307-line README that still referenced the retired Sensor / addThresholdRule / addStateChannel / EventConfig API. New structure foregrounds the Tag domain model (SensorTag / StateTag / MonitorTag / CompositeTag / TagRegistry), drops in-README screenshots, and replaces the Five-Pillars walk-through with a compact "What's in the box" capability list. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 576b134 commit 2e06766

1 file changed

Lines changed: 80 additions & 226 deletions

File tree

‎README.md‎

Lines changed: 80 additions & 226 deletions
Original file line numberDiff line numberDiff line change
@@ -6,22 +6,22 @@
66
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
77
[![MATLAB](https://img.shields.io/badge/MATLAB-R2020b%2B-orange.svg)](https://www.mathworks.com/products/matlab.html)
88
[![Octave](https://img.shields.io/badge/GNU%20Octave-7%2B-blue.svg)](https://octave.org)
9-
[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey.svg)](#installation)
9+
[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey.svg)](#install)
1010

11-
**200+ FPS. 100M+ points. Zero toolbox dependencies.**
11+
> **Sensor data, at the scale you actually have it — in MATLAB.**
1212
13-
Sensor monitoring and dashboarding platform for MATLAB and GNU Octave. Plot massive time series with SIMD-accelerated downsampling, define state-dependent threshold rules, detect violations in real time, and compose interactive dashboards with 21 widget types — all in pure MATLAB.
13+
FastSense is a pure-MATLAB platform for working with massive sensor time-series. Plot 100M+ points without crashing, model sensors as **Tags** with state-aware behaviour, detect events as they happen, and compose interactive dashboards — all without a single toolbox license.
1414

15-
<p align="center">
16-
<img src="docs/images/dashboard.png" alt="FastSense Dashboard" width="800">
17-
</p>
15+
Built for engineers who deal with real industrial data: long recordings, condition-dependent alarm limits, dashboards that need to stay live for hours, and the moment when MATLAB's own `plot()` falls over at 10M points.
1816

19-
## Quick Start
17+
---
18+
19+
## 30 seconds in
2020

2121
```matlab
22-
install; % adds libraries to path + compiles MEX (run once)
22+
install; % run once: adds paths + builds MEX accelerators
2323
24-
x = linspace(0, 100, 1e7);
24+
x = linspace(0, 100, 1e7); % 10 million points
2525
y = sin(x) + 0.1 * randn(size(x));
2626
2727
fp = FastSense('Theme', 'dark');
@@ -30,277 +30,131 @@ fp.addThreshold(0.8, 'Direction', 'upper', 'ShowViolations', true);
3030
fp.render();
3131
```
3232

33-
Build a full dashboard in under 10 lines:
34-
35-
```matlab
36-
d = DashboardEngine('Process Monitor');
37-
d.addWidget('fastsense', 'Position', [1 1 16 8]);
38-
d.addWidget('number', 'Position', [17 1 8 4], 'Label', 'Peak');
39-
d.addWidget('gauge', 'Position', [17 5 8 4], 'Label', 'Pressure');
40-
d.render();
41-
d.save('my_dashboard.json'); % reload later with DashboardEngine.load()
42-
```
43-
44-
---
45-
46-
## Table of Contents
47-
48-
- [Why FastSense?](#why-fastsense)
49-
- [Performance](#performance)
50-
- [Features at a Glance](#features-at-a-glance)
51-
- [Installation](#installation)
52-
- [The Five Pillars](#the-five-pillars)
53-
- [Examples](#examples)
54-
- [Documentation](#documentation)
55-
- [Contributing](#contributing)
56-
- [Citation](#citation)
57-
- [License](#license)
58-
59-
---
60-
61-
## Why FastSense?
62-
63-
MATLAB's built-in `plot()` loads every data point into GPU memory and redraws the entire figure on each zoom or pan. For sensor data at 10M+ points, this means multi-second lag, memory exhaustion, or a crash.
64-
65-
FastSense solves three problems that no existing MATLAB toolbox addresses together:
66-
67-
- **Scale** — render 100M+ point datasets without loading them fully into memory, using SIMD-accelerated MinMax and LTTB downsampling that keeps only the pixels you can actually see
68-
- **Context** — model real industrial sensors where alarm limits change based on machine state (idle vs. running vs. fault), not just static threshold values
69-
- **Organization** — compose multi-widget monitoring dashboards with tabbed pages, collapsible sections, and detachable pop-out windows — without writing layout code
70-
71-
All of this runs in pure MATLAB with no toolbox requirements. MEX C extensions with AVX2/NEON SIMD are optional accelerators; pure MATLAB fallbacks are used automatically.
72-
73-
---
74-
75-
## Performance
76-
77-
FastSense vs. MATLAB's built-in `plot()` on 10M data points:
78-
79-
| | `plot()` | FastSense |
80-
|---|---|---|
81-
| Render time | ~3.2 s | **4.7 ms** |
82-
| Memory usage | 153 MB | **0.06 MB** |
83-
| Zoom/pan FPS | ~2 FPS | **212 FPS** |
84-
| Points displayed | 10,000,000 | ~400 (perceptually identical) |
85-
86-
<sub>MacBook Pro M1 Pro, 16 GB, GNU Octave 11, MEX+NEON. Point reduction: 99.96%. Performance is tracked on every commit — regressions trigger alerts. <a href="https://hansur94.github.io/FastSense/dev/bench/">Live benchmark charts</a></sub>
33+
That renders in **a few milliseconds and stays at 200+ FPS while you zoom and pan**. MATLAB's built-in `plot()` takes ~3 seconds on the same data and crawls at ~2 FPS. ([benchmarks ↓](#performance))
8734

8835
---
8936

90-
## Features at a Glance
91-
92-
**Time Series Engine** — Render 10M+ points at 200+ FPS with automatic per-pixel downsampling. MinMax and LTTB algorithms, linked axes, datetime support, 6 built-in themes. Optional MEX C acceleration (AVX2/NEON) with pure-MATLAB fallback.
37+
## The core idea: Tags
9338

94-
**Sensor Modeling** — State-dependent threshold rules where alarm limits change based on machine state. Automatic violation grouping, statistics, and a sensor registry for predefined catalogs.
39+
Everything in FastSense — sensors, machine states, alarms, derived signals — is a **Tag**. One unified type, four flavours:
9540

96-
**Dashboard Engine** — 21 widget types on a 24-column responsive grid. Multi-page navigation, collapsible sections, detachable pop-out widgets, per-widget info tooltips. JSON persistence and live mode with synchronized refresh.
41+
| Tag | What it is |
42+
|----------------|-------------------------------------------------------------|
43+
| `SensorTag` | A measured time-series (pressure, temperature, …) |
44+
| `StateTag` | A discrete system state (idle / running / fault, recipe) |
45+
| `MonitorTag` | A derived 0/1 alarm signal — "is this sensor out of spec?" |
46+
| `CompositeTag` | An aggregation of other tags |
9747

98-
**Event Detection** — Groups threshold violations into discrete events with debouncing. Peak, mean, RMS, duration statistics per event. Real-time file polling pipeline with interactive Gantt timeline viewer.
99-
100-
**Browser Visualization** — TCP bridge from MATLAB to a FastAPI + uPlot web frontend. Bidirectional callbacks between MATLAB and browser.
101-
102-
---
103-
104-
## Installation
105-
106-
```bash
107-
git clone https://github.com/HanSur94/FastSense.git
108-
cd FastSense
109-
```
110-
111-
Then in MATLAB or Octave:
48+
Tags carry their own metadata (units, criticality, labels) and live in a shared **`TagRegistry`** so every part of the system — plots, dashboards, event detection, the web bridge — speaks the same language.
11249

11350
```matlab
114-
install; % adds paths + compiles MEX accelerators
115-
```
116-
117-
No toolbox dependencies. No internet required. MEX compilation is optional — pure MATLAB fallbacks are used automatically if no C compiler is available.
51+
press = SensorTag('press_a', 'Name', 'Chamber Pressure', 'Units', 'bar');
52+
press.updateData(t, pressure_data);
11853
119-
**Requirements:** MATLAB R2020b+ or GNU Octave 7+ | Linux, macOS, or Windows
120-
121-
---
54+
% Alarm whenever pressure > 55 bar
55+
alarm = MonitorTag('press_high', press, @(x, y) y > 55);
12256
123-
## The Five Pillars
57+
TagRegistry.register(press);
58+
TagRegistry.register(alarm);
12459
125-
### FastSense — Ultra-Fast Time Series Engine
126-
127-
The core plotting engine. Renders 10M+ data points with automatic downsampling (MinMax and LTTB), dynamic thresholds, and interactive zoom/pan — all at 200+ FPS. See [Performance](#performance) for benchmarks.
128-
129-
```matlab
130-
fp = FastSense('Theme', 'dark');
131-
fp.addLine(x, y, 'DisplayName', 'Noisy Sine');
132-
fp.addThreshold(2.0, 'Direction', 'upper', 'ShowViolations', true, ...
133-
'Color', 'r', 'Label', 'Alarm Hi');
134-
fp.addThreshold(-2.0, 'Direction', 'lower', 'ShowViolations', true, ...
135-
'Color', 'r', 'Label', 'Alarm Lo');
60+
fp = FastSense();
61+
fp.addTag(press);
62+
fp.addTag(alarm); % overlaid as a 0/1 step trace
13663
fp.render();
13764
```
13865

139-
- **Smart downsampling** — per-pixel MinMax and LTTB, auto-selected per zoom level
140-
- **MEX acceleration** — optional C with SIMD (AVX2/NEON), auto-fallback to pure MATLAB
141-
- **Linked axes** — synchronized zoom/pan across subplots
142-
- **Datetime support** — datenum and MATLAB datetime with auto-formatting
143-
- **6 built-in themes** — dark, light, industrial, scientific, ocean, colorblind
144-
- **SQLite-backed storage** — disk-backed DataStore for 100M+ datasets exceeding memory
66+
The same `alarm` tag drives event detection, lights up status widgets in the dashboard, fires notifications, and shows up in the browser bridge — without you re-declaring the rule four times. For monitors that depend on multiple parents (e.g., a state-conditional alarm), compose them via `CompositeTag`.
14567

14668
---
14769

148-
### SensorThreshold — State-Dependent Sensor Modeling
70+
## Build a dashboard
14971

150-
Bundles time-series data with discrete system states and condition-based threshold rules. A running machine has different alarm limits than an idle one — SensorThreshold models exactly that.
72+
Compose monitoring dashboards from widgets on a 24-column grid. The same Tags drive the data — no re-wiring.
15173

15274
```matlab
153-
s = Sensor('pressure', 'Name', 'Chamber Pressure', 'ID', 101);
154-
s.X = t; s.Y = pressure_data;
155-
156-
sc = StateChannel('machine_state');
157-
sc.X = [0 25 50 75]; sc.Y = [0 1 2 1]; % idle->running->error->running
158-
s.addStateChannel(sc);
159-
160-
s.addThresholdRule(struct('machine_state', 1), 55, ...
161-
'Direction', 'upper', 'Label', 'HH (running)');
162-
s.resolve();
163-
```
164-
165-
- **State channels** — discrete system states (idle, running, error) as zero-order-hold lookups
166-
- **Condition-based rules** — thresholds that activate only when conditions match
167-
- **Automatic violation grouping** — pre-computed during `resolve()`
168-
- **Sensor registry** — predefined sensor catalog for quick setup
169-
170-
---
171-
172-
### EventDetection — Violation Detection and Live Pipeline
173-
174-
Groups threshold violations into discrete events with statistics, live monitoring, and notifications. Detects when sensors exceed limits, how long, and how severe.
75+
d = DashboardEngine('Process Monitor');
76+
d.Theme = 'dark';
77+
d.addWidget('fastsense', 'Position', [1 1 16 8], 'Tag', press);
78+
d.addWidget('number', 'Position', [17 1 8 4], 'Tag', press, 'Label', 'Pressure');
79+
d.addWidget('gauge', 'Position', [17 5 8 4], 'Tag', press, 'Label', 'Live');
80+
d.addWidget('status', 'Position', [1 9 24 2], 'Tag', alarm, 'Label', 'Alarm');
81+
d.render();
17582
176-
```matlab
177-
cfg = EventConfig();
178-
cfg.MinDuration = 0.5;
179-
cfg.addSensor(sTemp);
180-
cfg.addSensor(sPres);
181-
cfg.setColor('temp warning', [1.0 0.8 0.0]);
182-
events = cfg.runDetection();
83+
d.save('process.json'); % JSON-persist
84+
% later: d = DashboardEngine.load('process.json');
18385
```
18486

185-
- **Event grouping** — consecutive violations merged into events with debouncing
186-
- **Statistics** — peak, mean, RMS, std, duration automatically computed per event
187-
- **Live pipeline** — real-time file polling with streaming event detection
188-
- **Gantt viewer** — interactive timeline UI for event exploration
189-
- **Notifications** — event-triggered callbacks for alerting
87+
- **21 widget types** — plots, numbers, gauges, status lights, gantt timelines, heatmaps, tables, markdown, …
88+
- **Multi-page tabs · collapsible groups · pop-out detached widgets**
89+
- **Live mode** — synchronised refresh on a configurable timer
90+
- **Browser bridge** — `WebBridge(d).serve()` exposes the dashboard over TCP to a FastAPI + uPlot frontend
19091

19192
---
19293

193-
### Dashboard — Widget-Based Dashboard Engine
194-
195-
Build monitoring dashboards from composable widgets on a 24-column grid. Supports live data, JSON persistence, multi-page navigation, collapsible sections, and 21 widget types.
94+
## Performance
19695

197-
```matlab
198-
d = DashboardEngine('Process Monitoring');
199-
d.Theme = 'light';
200-
d.addWidget('fastsense', 'Position', [1 1 16 8], 'Sensor', sTemp);
201-
d.addWidget('number', 'Position', [17 1 8 4], 'Sensor', sTemp, ...
202-
'Label', 'Temperature');
203-
d.addWidget('gauge', 'Position', [17 5 8 4], 'Sensor', sPres, ...
204-
'Label', 'Pressure');
205-
d.render();
206-
d.save('dashboard.json');
207-
```
96+
FastSense vs. MATLAB's built-in `plot()` on 10M data points:
20897

209-
**21 widget types:**
210-
fastsense, number, status, gauge, table, text, barchart, heatmap, histogram, scatter, image, multistatus, eventtimeline, group, rawaxes, divider, markdown, iconcard, chipbar, sparklinecard, and collapsible group.
98+
| | `plot()` | FastSense |
99+
|------------------|------------|-----------------------------|
100+
| Render time | ~3.2 s | **4.7 ms** |
101+
| Memory | 153 MB | **0.06 MB** |
102+
| Zoom/pan FPS | ~2 FPS | **212 FPS** |
103+
| Points displayed | 10 000 000 | ~400 (visually identical) |
211104

212-
**Layout and organization features:**
213-
- **24-column grid** — flexible positioning with `[col, row, width, height]` tuples
214-
- **Multi-page navigation** — tabbed pages for organizing large dashboards
215-
- **Collapsible sections** — fold/unfold grouped widgets with a single click
216-
- **Detachable widgets** — pop any widget into its own independent figure window, live-mirrored from the dashboard
217-
- **Info tooltips** — per-widget Markdown documentation shown on hover or click
105+
<sub>MacBook Pro M1 Pro · GNU Octave 11 · MEX + NEON. Tracked on every commit; regressions trigger alerts. <a href="https://hansur94.github.io/FastSense/dev/bench/">Live benchmark charts</a></sub>
218106

219-
**Data and persistence:**
220-
- **JSON persistence** — save/load complete dashboard configurations
221-
- **Live mode** — synchronized data refresh across all widgets on a configurable timer
222-
- **Script export** — regenerate the dashboard as a `.m` script
107+
The trick: per-pixel **MinMax** and **LTTB** downsampling (SIMD C kernels with pure-MATLAB fallbacks), an SQLite-backed disk store for datasets that don't fit in RAM, and a render pipeline that only touches the points you can actually see.
223108

224109
---
225110

226-
### WebBridge — Browser-Based Visualization
111+
## What's in the box
227112

228-
Exposes dashboards to a web frontend over TCP. MATLAB stays the data engine; the browser handles rendering.
229-
230-
```matlab
231-
bridge = WebBridge(dashboard);
232-
bridge.serve();
233-
bridge.registerAction('update_threshold', @myCallback);
234-
```
235-
236-
- **TCP server** — bridges MATLAB dashboard to web/Electron frontend
237-
- **Bidirectional callbacks** — actions and data-change notifications between MATLAB and browser
238-
- **HTML5 charts** — uPlot-based rendering in the browser
113+
- **Plotting engine** — 100M+ point time-series, 6 themes, linked axes, datetime support, optional MEX SIMD kernels
114+
- **Tag domain model** — `SensorTag`, `StateTag`, `MonitorTag`, `CompositeTag`, shared `TagRegistry`
115+
- **Event detection** — group violations into events, statistics, live pipeline, interactive Gantt viewer, notifications
116+
- **Dashboards** — 21 widget types, JSON persistence, multi-page, collapsible, detachable, live refresh
117+
- **Browser bridge** — TCP → FastAPI → uPlot, bidirectional callbacks
118+
- **Disk-backed storage** — SQLite chunks with WAL for live reads, pyramid-cached downsamples
119+
- **Pure MATLAB / Octave** — no toolboxes, no internet, no licenses
239120

240121
---
241122

242-
## Examples
243-
244-
The [`examples/`](examples/) directory contains 40+ runnable scripts organized by topic:
123+
## Install
245124

246-
| Category | Contents |
247-
|---|---|
248-
| [`01-basics/`](examples/01-basics/) | Core FastSense plotting, themes, linked axes, datetime |
249-
| [`02-sensors/`](examples/02-sensors/) | Sensor modeling, state channels, threshold rules |
250-
| [`03-dashboard/`](examples/03-dashboard/) | Dashboard layouts, live mode, multi-page, info tooltips |
251-
| [`04-widgets/`](examples/04-widgets/) | One script per widget type (21 widget examples) |
252-
| [`05-events/`](examples/05-events/) | Event detection, Gantt viewer, live pipeline |
253-
| [`06-webbridge/`](examples/06-webbridge/) | Browser visualization setup |
254-
| [`07-advanced/`](examples/07-advanced/) | Disk-backed DataStore, 100M+ point datasets |
255-
256-
A categorized guide is in the [wiki](https://github.com/HanSur94/FastSense/wiki/Examples).
257-
258-
---
125+
```bash
126+
git clone https://github.com/HanSur94/FastSense.git
127+
cd FastSense
128+
```
259129

260-
## Documentation
130+
Then in MATLAB or Octave:
261131

262-
Full documentation is available in the [Wiki](https://github.com/HanSur94/FastSense/wiki):
132+
```matlab
133+
install; % adds paths + compiles MEX accelerators
134+
```
263135

264-
- [Getting Started](https://github.com/HanSur94/FastSense/wiki/Getting-Started) — tutorial with examples
265-
- [API Reference: FastSense](https://github.com/HanSur94/FastSense/wiki/API-Reference:-FastSense) — core plotting class
266-
- [API Reference: Dashboard](https://github.com/HanSur94/FastSense/wiki/API-Reference:-Dashboard) — layouts, widgets, engine
267-
- [API Reference: Sensors](https://github.com/HanSur94/FastSense/wiki/API-Reference:-Sensors) — sensor system
268-
- [API Reference: Event Detection](https://github.com/HanSur94/FastSense/wiki/API-Reference:-Event-Detection) — event pipeline
269-
- [Architecture](https://github.com/HanSur94/FastSense/wiki/Architecture) — render pipeline, data flow
270-
- [MEX Acceleration](https://github.com/HanSur94/FastSense/wiki/MEX-Acceleration) — SIMD details
271-
- [Performance](https://github.com/HanSur94/FastSense/wiki/Performance) — benchmarks
136+
MEX is optional — pure-MATLAB fallbacks kick in if no C compiler is available. Requires MATLAB R2020b+ or GNU Octave 7+ on Linux, macOS, or Windows.
272137

273138
---
274139

275-
## Contributing
140+
## Examples & docs
276141

277-
Contributions are welcome! Here's how to get started:
142+
40+ runnable scripts in [`examples/`](examples/), grouped by topic (`01-basics` … `07-advanced`). Run them all with `run_all_examples`.
278143

279-
1. **Report a bug** — open an [issue](https://github.com/HanSur94/FastSense/issues) with a minimal reproducer
280-
2. **Suggest a feature** — open an issue to discuss before writing code
281-
3. **Submit a fix** — fork, branch, and open a pull request
282-
283-
For architecture details and development setup, see the [Architecture wiki page](https://github.com/HanSur94/FastSense/wiki/Architecture). The test suite runs with `run_all_tests` in MATLAB/Octave.
144+
Full reference lives in the [Wiki](https://github.com/HanSur94/FastSense/wiki): Getting Started · API Reference · Architecture · MEX details · Performance.
284145

285146
---
286147

287-
## Citation
288-
289-
If you use FastSense in your research, please cite it:
148+
## Citation · License
290149

291150
```bibtex
292151
@software{fastsense,
293-
author = {Suhr, Hannes},
294-
title = {FastSense: Sensor Monitoring and Dashboarding for MATLAB and GNU Octave},
295-
url = {https://github.com/HanSur94/FastSense},
296-
license = {MIT}
152+
title = {FastSense: Sensor Monitoring and Dashboarding for MATLAB and GNU Octave},
153+
url = {https://github.com/HanSur94/FastSense},
154+
license= {MIT}
297155
}
298156
```
299157

300158
See [`CITATION.cff`](CITATION.cff) for the full citation metadata.
301159

302-
---
303-
304-
## License
305-
306-
[MIT](LICENSE) — Hannes Suhr
160+
Released under the [MIT License](LICENSE).

0 commit comments

Comments
 (0)