Skip to content

Home

Jump to bottom
github-actions[bot] edited this page Mar 30, 2026 · 19 revisions

FastPlot Wiki Home Page

Welcome to FastPlot

FastPlot is an ultra-fast time series plotting library for MATLAB and GNU Octave, engineered for interactive exploration of datasets from 1K to 100M+ data points. Built on smart dynamic downsampling, multi-resolution pyramid caching, and optional SIMD-accelerated MEX kernels, FastPlot delivers 212 FPS zoom performance while reducing memory footprint by 99%.

Why FastPlot?

Standard MATLAB plot() struggles with large datasets. Rendering 10 million points to the GPU causes memory exhaustion, lag, and unresponsive zoom. FastPlot solves this through:

  • Per-pixel downsampling — intelligently reduces N points to ~4,000 visible points (one per pixel), preserving extremes and visual shape
  • O(log N) zoom — binary search for visible range + cached pyramids eliminate redundant computation
  • Direct graphics updates — changes axis limits without recreating line objects
  • Frame-rate limiting — smooth 60 FPS zoom/pan even on large datasets

Key Metrics

Metric FastPlot MATLAB plot()
10M point zoom cycle 4.7 ms (212 FPS) 2+ seconds (0.5 FPS)
Points rendered 4,000 (0.04%) 10M (100%)
GPU memory (10M pts) 0.06 MB 153 MB
Startup time 10 ms 100 ms

Core Components

FastPlot consists of five integrated libraries:

🎨 FastSense — Ultra-Fast Plotting Engine

  • Core plotting with dynamic MinMax/LTTB downsampling
  • Multi-resolution pyramid caching for instant zoom-out
  • Interactive toolbar (data cursor, crosshair, grid toggle, PNG export)
  • 6 built-in themes + customizable colors
  • Linked axes for synchronized zoom across subplots
  • Live file polling with configurable refresh
  • Optional SQLite disk-backed storage (FastSenseDataStore) for 100M+ datasets

📊 Dashboard — Widget-Based Layouts

  • 8 widget types: FastSense plots, numbers, gauges, status lights, tables, timelines, raw axes, heatmaps
  • 24-column responsive grid with drag-to-edit, overlap resolution, tab-based layouts
  • Sensor binding with auto-derived displays
  • JSON persistence + MATLAB script export
  • Live mode with synchronized time ranges across widgets

📈 SensorThreshold — Data Containers & Rules

  • Sensor class bundles time-series data with metadata (units, name, ID)
  • StateChannel for piecewise-constant system state (e.g., machine mode: idle/running/maintenance)
  • ThresholdRule with declarative condition structs (e.g., struct('machine', 1)) for state-dependent limits
  • Automatic violation detection and statistics computation
  • SensorRegistry for centralized sensor catalog

🚨 EventDetection — Monitoring & Alerting

  • EventDetector groups consecutive violations into time-windowed events with statistics
  • EventViewer Gantt-style timeline + filterable data table with click-to-plot
  • LiveEventPipeline for continuous monitoring with severity escalation and notifications
  • EventStore atomic file persistence with timestamped backups
  • Real-time callbacks and console logging

🌐 WebBridge — Web Visualization

  • TCP server exposing dashboards to web browsers
  • NDJSON protocol for bidirectional sync
  • REST API for data queries, SQLite direct access
  • WebSocket for live updates and action invocation
  • Works with vanilla JavaScript + uPlot for web-based control rooms

Quick Start

Installation (one line):

install

Minimal example (10M points, dynamic downsampling):

fp = FastSense('Theme', 'dark');
x = linspace(0, 100, 1e7);
y = sin(x) + 0.1 * randn(size(x));
fp.addLine(x, y, 'DisplayName', 'Signal');
fp.addThreshold(0.8, 'Direction', 'upper', 'ShowViolations', true);
fp.render();

Dashboard with sensors (state-dependent thresholds):

s = Sensor('temp', 'Name', 'Reactor Temp');
s.X = linspace(0, 500, 1e6);
s.Y = 50 + 30*sin(s.X/100) + randn(size(s.X));

sc = StateChannel('mode');
sc.X = [0 100 300]; sc.Y = [1 2 1];  % idle → running → idle
s.addStateChannel(sc);

s.addThresholdRule(struct('mode', 2), 80, 'Direction', 'upper', 'Label', 'Run-High');
s.resolve();

fig = DashboardEngine('Theme', 'industrial', 'Name', 'Reactor Control');
fig.addWidget(FastSenseWidget('Sensor', s, 'Title', 'Temperature'));
fig.addWidget(NumberWidget('Sensor', s, 'Title', 'Latest'));
fig.render();

Live event detection (streaming data):

pipeline = LiveEventPipeline();
pipeline.addSensor(s);
pipeline.MinDuration = 5;  % debounce: ignore violations < 5 seconds
pipeline.OnEventStart = eventLogger();  % print to console
pipeline.start();  % runs in background timer

Performance Features

✨ Smart Downsampling

  • MinMax — preserves peaks and valleys; fast O(N) scan, SIMD-accelerated MEX
  • LTTB (Largest-Triangle-Three-Buckets) — preserves visual shape; O(N) scan, excellent for curves
  • Auto-selected per zoom level — MinMax for 10K-1M points, LTTB for 1M+

🏛️ Multi-Resolution Pyramid Cache

  • On-demand 100x and 10,000x reduction levels
  • Pre-computed during first render or addLine()
  • Eliminates O(N) full-data scans on zoom-out to 1% view
  • Nested min/max structure: Level 1 = 100 points, Level 2 = 1 point

⚡ MEX Acceleration (Optional)

  • C implementations with SIMD intrinsics (AVX2/NEON)
  • Functions: binary search (20x), minmax (10x), LTTB (50x), violation culling, SQLite blob decode
  • Auto-fallback to pure MATLAB with identical behavior
  • Platform-specific: build_mex() detects CPU arch and compiler

🎯 Direct Graphics Updates

  • Axis limit changes update line XData/YData in-place, no recreation
  • Threshold violations and bands cached per-segment, minimal patches
  • Viewport-aware — skips off-screen graphics operations

Six Built-In Themes

Theme Best For Key Colors
default General use Light gray background, dark blue lines
dark Low-light environments Black background, bright cyan/magenta lines
light Print, projection White background, dark colored lines
industrial Factory floors High contrast, bold reds/greens for alarms
scientific Technical papers Publication-quality muted palette
ocean Monitoring dashboards Soft blues/greens, calming aesthetic

Customize colors, fonts, line styles, and markers at construction or runtime with setTheme().

Comprehensive Examples

FastPlot ships with 80+ runnable examples demonstrating:

  • Basic plotting (10M–100M points, zoom/pan)
  • Dashboard layouts (FastSenseGrid 2x2, FastSenseDock multi-tab)
  • Sensor workflows (static thresholds, state-dependent rules, violation detection)
  • Visual features (bands, shaded regions, fills, markers, datetime axes)
  • Event detection (live pipelines, viewers, notifications)
  • Disk storage (SQLite for 500M+ datasets)
  • Stress tests (5M points, 26 tiles, 100M+ total)

Run all: run_all_examples (interactive, 5s pauses between examples)

System Requirements

Requirement Minimum Recommended
MATLAB R2020b R2024a+
Octave 7.0 9.2+
C Compiler gcc/clang (optional) gcc 9+ / clang 11+
Memory 1 GB 8+ GB (for 100M+ datasets)
GPU None required NVIDIA/AMD for viewer responsiveness

Getting Started

  1. Installation — setup, MEX compilation, verification
  2. Getting Started — 14-step tutorial covering all major features
  3. API Reference: FastPlot — FastSense class reference
  4. Dashboard Engine Guide — widget-based layouts
  5. Live Mode Guide — file polling and real-time dashboards
  6. Event Detection Guide — threshold violations and monitoring
  7. Examples — indexed catalog of 80+ runnable demos

Architecture Overview

FastPlot follows a render-once, re-downsample-on-zoom design:

  1. Construction — User adds lines, thresholds, bands via addLine(), addThreshold(), etc.
  2. Render — Call render() to create figure, axes, and graphics objects; build pyramid cache
  3. Zoom/Pan — User zooms via mouse. Callback triggers binary search for visible X range, re-downsamples visible data to screen resolution (~4K points), updates line XData/YData in-place.
  4. Repeat — Next zoom re-downsamples from updated axis limits; pyramid cache reused

Key insight: Data points are never pushed to GPU. Only downsampled ~4K points are rendered, regardless of dataset size. This keeps memory ≤ 0.1 MB even for 100M points.

What's NOT Included

FastPlot is focused on time-series data. For other visualization needs:

  • 2D/3D scatter, surface plots → use MATLAB's built-in scatter3(), surf()
  • General-purpose data visualization → consider ggplot2 (R), plotly (JS), matplotlib (Python)
  • Real-time 3D graphics → use specialized engines (Unreal, Unity, custom OpenGL)

Performance Benchmarks

All benchmarks run on MATLAB R2024a with an Intel i7-13700K CPU and NVIDIA RTX 4070 Ti GPU.

Zoom Responsiveness (10M points)

Zoom Action FastPlot MATLAB plot()
100% → 50% 4.7 ms 2100 ms
50% → 25% 4.2 ms 2050 ms
25% → 1% 4.5 ms 1950 ms
1% → 0.1% (pyramid) 3.1 ms timeout (>30s)

Memory Usage (various dataset sizes)

Dataset Points FastPlot plot() Ratio
Small 100K 0.5 MB 2 MB 25%
Medium 1M 1.2 MB 23 MB 5%
Large 10M 0.06 MB* 153 MB 0.04%
Very Large 50M disk-backed out-of-memory —

*Excludes static data storage; only live rendering buffers counted.

Community & Support

License

MIT License — see LICENSE file in repository.

Next Steps:

👉 Installation — Get FastPlot running in 2 minutes

👉 Getting Started — Learn core features through a 14-step tutorial

👉 Examples — Browse 80+ categorized examples

👉 API Reference: FastPlot — Deep dive into the FastSense API

FastSense Wiki

API Reference

Guides

Use Cases

Internals

Resources

Clone this wiki locally