Skip to content

Installation

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

Installation

System Requirements

FastPlot supports:

  • MATLAB: R2020b and later
  • GNU Octave: 7.0 and later
  • Operating Systems: macOS (Apple Silicon & Intel), Linux, Windows
  • Compiler (optional): C compiler for MEX acceleration
    • macOS: Xcode Command Line Tools (xcode-select --install)
    • Linux: GCC/Clang (apt-get install build-essential or equivalent)
    • Windows: MSVC (included with Visual Studio Community)

No MATLAB or Octave toolboxes are required. All functionality is pure MATLAB/Octave or self-contained C code.

Installation Methods

Method 1: From Source (Git Clone)

The recommended approach for full functionality and development:

git clone https://github.com/HanSur94/FastSense.git
cd FastSense

Then in MATLAB/Octave:

install;

This command:

  1. Adds the five core libraries to your path
  2. Detects and optionally compiles MEX accelerators
  3. Verifies core classes are accessible
  4. Runs JIT warmup on MATLAB for optimal performance
graph LR
    A["Clone Repository"] --> B["Run install.m"]
    B --> C["Add Library Paths"]
    B --> D["Detect Compiler"]
    D --> E["Compile MEX Optional"]
    B --> F["Verify Installation"]
    C --> G["Ready to Use"]
    E --> G
    F --> G
Loading

Method 2: Direct Path Addition

If you prefer manual setup:

repo_root = '/path/to/FastSense';
addpath(genpath(fullfile(repo_root, 'libs')));
addpath(fullfile(repo_root, 'examples'));
addpath(fullfile(repo_root, 'tests'));

Then verify:

help FastSense  % Should display class documentation

Optional: MEX Acceleration

For maximum performance (3-50x speedups on downsampling and search), compile the C MEX kernels:

cd /path/to/FastSense/libs/FastSense
build_mex();

What Gets Compiled

MEX Function Purpose Speedup
binary_search_mex Visible range lookup on sorted time arrays 10-20x
minmax_core_mex Per-pixel MinMax downsampling with SIMD 3-10x
lttb_core_mex Largest-Triangle-Three-Buckets downsampling 10-50x
violation_cull_mex Violation detection + pixel-density culling 5-20x
mksqlite SQLite interface with typed BLOB storage 2-3x

SIMD Architecture Support

The build system auto-detects your CPU and applies appropriate optimizations:

  • Apple Silicon (arm64): NEON intrinsics (2 doubles/instruction)
  • Intel/AMD x86_64: AVX2 with SIMD intrinsics (4 doubles/instruction), falls back to SSE2
  • Fallback (scalar): Pure C loops if no SIMD detected

If compilation fails, pure-MATLAB implementations are used automatically — all algorithms produce identical numerical results.

Build Troubleshooting

MATLAB on Windows:

setenv('VS160COMNTOOLS', 'C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\Tools\');
build_mex();

Octave on macOS:

brew install gcc  # If not installed
export CC=gcc-12
octave --eval "cd libs/FastSense; build_mex();"

Disable MEX and use pure MATLAB:

% Edit libs/FastSense/build_mex.m, line 5:
% useMex = false;  % Force pure-MATLAB mode
build_mex();

Quick Verification

Minimal Test (1 minute)

install;

% Create a simple plot
x = linspace(0, 2*pi, 1e6);
y = sin(x);

fp = FastSense('Title', 'Test Plot');
fp.addLine(x, y, 'DisplayName', 'sin(x)');
fp.addThreshold(0.5, 'Direction', 'upper', 'Label', 'Threshold');
fp.render();

fprintf('✓ FastSense core working\n');

Comprehensive Test Suite (5 minutes)

install;
cd tests
run_all_tests();

Expected output:

====== Test Summary ======
Total tests: 287
Passed: 287
Failed: 0
Skipped: 12 (Octave listener incompatibilities)
======== SUCCESS =========

Run an Example

install;
example_basic;  % 10M point basic plot
% or
example_dashboard_engine;  % Widget gallery
% or
example_event_detection_live;  % Event monitoring

Project Structure

After installation, your FastPlot directory contains:

FastSense/
├── install.m                 # Setup script (run this first)
├── setup.m                   # Path configuration
│
├── libs/                     # Core libraries
│   ├── FastSense/           # Ultra-fast plotting engine
│   ├── SensorThreshold/     # Sensor data + threshold rules
│   ├── EventDetection/      # Violation-based event detection
│   ├── Dashboard/           # Widget-based dashboard UI
│   └── WebBridge/           # TCP server for web visualization
│
├── examples/                 # 80+ runnable examples
│   ├── example_basic.m
│   ├── example_dashboard_engine.m
│   ├── example_event_detection_live.m
│   └── ...
│
├── tests/                    # 287+ unit and integration tests
│   ├── suite/               # MATLAB unittest classes
│   ├── test_*.m             # Octave-compatible function tests
│   └── run_all_tests.m
│
├── bridge/                   # Python/web components
│   ├── python/              # FastAPI bridge server
│   └── web/                 # Vanilla JS + uPlot frontend
│
├── docs/                     # Design documents and benchmarks
├── wiki/                     # GitHub wiki content (Markdown)
└── scripts/                  # Build, test, and utility scripts

Data Storage (Disk-Backed Rendering)

For datasets exceeding available RAM, FastSense automatically uses SQLite disk storage:

install;

% 100M points — too large for RAM (~800 MB)
x = linspace(0, 100, 1e8);
y = sin(x) + 0.1*randn(1, 1e8);

fp = FastSense();
fp.addLine(x, y, 'StorageMode', 'auto', 'MemoryLimit', 500e6);  % 500 MB limit
fp.render();
% Data automatically spilled to disk, visible region loaded on zoom

Disk storage creates .fpdb files (SQLite with indexed chunks) in your temp directory, automatically cleaned up on completion.

Python Bridge Setup (Web Dashboard)

For web-based visualization:

cd FastSense/bridge/python
pip install -e .

# Start the bridge (MATLAB must be running WebBridge server)
fastsense-bridge --matlab-port 9000 --http-port 8080
# Open http://localhost:8080 in browser

Or in MATLAB:

install;
dashboard = DashboardEngine('Title', 'Production Monitor');
% ... add widgets ...
dashboard.serve();  % Starts WebBridge TCP server + Python bridge

Then visit http://localhost:8080 in your browser.

Updating FastPlot

Pull the latest changes:

cd /path/to/FastSense
git pull origin main

Then re-run setup:

install;
build_mex();  % Recompile MEX if source files changed

Troubleshooting

"undefined function or variable 'FastSense'"

Make sure install; was run in the FastSense directory:

cd /path/to/FastSense
install;
addpath(genpath('libs'));  % Manual fallback

MEX compilation fails

Use pure-MATLAB mode as fallback:

% Create a file: libs/FastSense/private/useMexDisabled.txt
% Then MEX functions will auto-fallback to MATLAB implementations
build_mex();  % Will skip MEX compilation

"Permission denied" errors on macOS/Linux

chmod +x /path/to/FastSense/install.m
chmod -R u+w /path/to/FastSense/libs  # Ensure write permissions

Out of memory on large datasets

Use disk-backed storage:

fp = FastSense('StorageMode', 'disk');  % Force disk storage
fp.addLine(x, y);  % Data written to SQLite

Next Steps

After successful installation:

  1. Quick Start (5 min): Read Getting Started Guide
  2. Learn Core API (30 min): Run example_basic.m and example_dashboard_engine.m
  3. Explore Features (1 hour): Try example_visual_features.m and example_sensor_threshold.m
  4. Deep Dive: Read Architecture for design principles

Performance Notes

Typical performance on modern hardware (M1 Mac, 2024 Windows laptop):

  • 10M point plot: 4.7ms refresh (212 FPS), 99.96% point reduction
  • 100M point disk-backed: <10ms zoom with automatic viewport loading
  • Dashboard with 30 widgets: <500ms initial load, <50ms live updates

These metrics assume MEX compilation. Pure-MATLAB mode adds ~2-3x overhead but remains responsive for typical datasets (<10M points).

Getting Help

  • Documentation: Wiki
  • Examples: examples/ directory with 80+ runnable scripts
  • API Reference: wiki/API-Reference-*.md files
  • Issues: GitHub Issues

FastSense Wiki

API Reference

Guides

Use Cases

Internals

Resources

Clone this wiki locally