Skip to content

Installation

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

Installation

Requirements

  • MATLAB R2020b+ or GNU Octave 7+
  • C compiler (optional, for MEX acceleration):
    • macOS: Xcode Command Line Tools (xcode-select --install)
    • Linux: GCC (apt install build-essential)
    • Windows: MSVC (included with MATLAB)
  • No toolbox dependencies — pure MATLAB/Octave with optional C acceleration

Supported Platforms

Platform Architecture SIMD Support Status
macOS 12+ Apple Silicon (arm64) NEON ✅ Tested
macOS 10.13+ Intel x86_64 AVX2/SSE2 ✅ Tested
Ubuntu 18.04+ x86_64 AVX2/SSE2 ✅ Tested
Windows 10+ x86_64 AVX2/SSE2 ✅ Tested
Raspberry Pi OS armv7l NEON (limited) ⚠️ Pure MATLAB only

Quick Start

1. Add to Path and Initialize

cd /path/to/FastPlot
install

This command:

  • Adds five library paths (FastSense, SensorThreshold, EventDetection, Dashboard, WebBridge)
  • Verifies core classes are accessible
  • Performs JIT warmup on first run
  • Is safe to run multiple times (idempotent)

2. Verify Installation

Run the test suite:

addpath tests
run_all_tests

Expected output:

================== Test Summary ====================
Totals: 450 Passed, 0 Failed, 2 Skipped
===================================================

Or run a quick example:

example_basic

Detailed Installation Methods

Method 1: Package Manager (pip)

If installing the Python WebBridge client in isolation:

pip install fastsense-bridge
fastsense-bridge --matlab-port 9000 --http-port 8000

Requires: Python 3.11+, FastAPI, uvicorn, websockets, numpy

Method 2: From Source (Git)

Clone and set up from the repository:

git clone https://github.com/mathworks/FastPlot.git
cd FastPlot

Then in MATLAB/Octave:

install

Method 3: Docker

Build and run FastPlot in a containerized environment:

docker build -t fastsense:latest .
docker run -it --rm fastsense:latest matlab -r "install; example_basic"

Includes:

  • MATLAB R2025b runtime
  • GCC and build tools
  • Pre-compiled MEX binaries for Linux x86_64

To access the web bridge:

docker run -p 8000:8000 -p 9000:9000 fastsense:latest bash
# Inside container:
matlab -r "install; pb = WebBridge(); pb.serve(9000, 8000)"

Method 4: Offline Installation

For air-gapped environments:

  1. On connected machine:

    git clone https://github.com/mathworks/FastPlot.git
cd FastPlot
tar -czf FastPlot-offline.tar.gz .

  2. Transfer FastPlot-offline.tar.gz to target system

  3. On target machine:

    tar -xzf FastPlot-offline.tar.gz
cd FastPlot
matlab -r "install"

MEX Compilation (Optional but Recommended)

Enable C acceleration with SIMD intrinsics for 3–50x faster downsampling:

cd libs/FastSense
build_mex

The build script will:

  1. Auto-detect architecture:

    Architecture: x86_64
Detected SIMD: AVX2

  2. Compile four MEX files:

    Compiling binary_search_mex.c ... [✓]
Compiling minmax_core_mex.c ... [✓]
Compiling lttb_core_mex.c ... [✓]
Compiling violation_cull_mex.c ... [✓]

  3. Test for regressions:

    MEX parity check: All tests passed [✓]

Compilation Details

Supported architectures:

  • x86_64 (Intel/AMD): Tries AVX2 first (-mavx2 -mfma), falls back to SSE2 (-msse2)
  • arm64 (Apple Silicon, AWS Graviton): NEON enabled by default
  • armv7l (Raspberry Pi): Falls back to scalar C (no SIMD)

Compiler selection:

  • MATLAB: Uses system compiler (MSVC on Windows, GCC/Clang on Unix)
  • Octave: Uses available GCC/Clang

Troubleshooting compilation:

If build_mex fails, pure-MATLAB fallbacks remain active:

% Verify fallback is working
[x, y] = minmax_downsample([1:1e6], randn(1,1e6), 100);
disp("Downsampling works (MEX or MATLAB)");

Check which path is active:

exist('minmax_core_mex', 'file')  % Returns 0 if not compiled

System-Specific Setup

macOS

Intel:

install  % Auto-detects AVX2
build_mex  % Compiles with -mavx2

Apple Silicon:

install
build_mex  % Auto-detects NEON

If using non-official MATLAB (e.g., Octave via Homebrew):

brew install octave
cd /path/to/FastPlot
octave --eval "install; build_mex"

Linux (Ubuntu/Debian)

Install build tools:

sudo apt update
sudo apt install build-essential

Then in MATLAB/Octave:

install
build_mex

Windows

MATLAB includes MSVC; no additional tools needed:

install
build_mex

For GNU Octave on Windows, install MinGW:

choco install mingw  # via Chocolatey

Then run:

install
build_mex

Docker

Pre-built image with MEX compiled for Linux x86_64:

docker run -it mathworks/fastsense:latest
matlab -r "install; example_basic"

To build custom image:

FROM mathworks/matlab:r2025b
RUN apt-get update && apt-get install -y build-essential
COPY . /root/FastPlot
WORKDIR /root/FastPlot
RUN matlab -r "install; build_mex; exit"

Python WebBridge Client

Install the optional Python bridge for web-based visualization:

# From PyPI
pip install fastsense-bridge

# From source
cd bridge/python
pip install -e .

Dependencies:

  • Python 3.11+
  • FastAPI, uvicorn, websockets, numpy

Quick start:

In MATLAB:

install
pb = WebBridge();
pb.serve(9000);  % Listen on port 9000

In Python (separate terminal):

fastsense-bridge --matlab-port 9000 --http-port 8000
# Open http://localhost:8000 in browser

Verification Steps

1. Core Classes Accessible

install
s = Sensor('test');           % SensorThreshold library
e = Event(0, 1, 'sensor', 'threshold', 'high');  % EventDetection library
fp = FastSense();             % FastSense library
de = DashboardEngine();       % Dashboard library

Expected: No errors, four objects created.

2. Data Processing

x = linspace(0, 100, 1e6);
y = sin(x);
fp = FastSense();
fp.addLine(x, y);
fp.render();

Expected: Figure appears with smooth sine wave, zoom/pan is fluid.

3. MEX Status

fprintf("MinMax MEX: %s\n", iif(exist('minmax_core_mex','file')==3, "✓ Compiled", "⚠ Fallback"));
fprintf("LTTB MEX: %s\n", iif(exist('lttb_core_mex','file')==3, "✓ Compiled", "⚠ Fallback"));
fprintf("BinSearch MEX: %s\n", iif(exist('binary_search_mex','file')==3, "✓ Compiled", "⚠ Fallback"));

Expected: Either "✓ Compiled" for all (if build_mex succeeded) or "⚠ Fallback" for all (pure MATLAB).

4. Full Test Suite

addpath tests
results = run_all_tests();
fprintf("\nSummary: %d passed, %d failed\n", ...
    results.NumPassed, results.NumFailed);

Expected: All tests pass (skipped tests on Octave are normal).

5. Example Scripts

Run 3+ examples to verify end-to-end functionality:

example_basic              % 10M points, threshold, violations
example_dashboard          % Multi-tile grid layout
example_sensor_registry    % State-dependent thresholds
example_event_detection_live  % Live event monitoring

Expected: Figures appear, interactive zoom/pan works, no errors.

Troubleshooting

"Undefined function or variable 'FastSense'"

Cause: Libraries not added to path.

Fix:

cd /path/to/FastPlot
install  % Re-run to ensure paths are set

"MEX file not found: minmax_core_mex"

Expected behavior — pure-MATLAB fallback is used automatically. No action needed unless you want MEX acceleration:

build_mex  % Compile MEX

Compilation fails: "error: unknown argument: '-mavx2'"

Cause: Compiler doesn't support AVX2 (very old CPU or cross-compilation).

Fix: Fallback to SSE2 or scalar:

mex -v COMPFLAGS='$COMPFLAGS -msse2' libs/FastSense/private/mex_src/minmax_core_mex.c

Or accept pure-MATLAB mode (no MEX), which is fully functional.

"Too many input arguments" or MATLAB version error

Cause: Old MATLAB version (< R2020b).

Fix: Upgrade MATLAB or use GNU Octave 7+.

Octave: "warning: file not found in load path"

Cause: MEX files compiled for MATLAB don't load in Octave (or vice versa).

Fix: Recompile for Octave:

pkg load signal  % Load Octave packages
system("cd libs/FastSense && mkoctfile --mex private/mex_src/minmax_core_mex.c -o private/minmax_core_mex.mex")

Or run in pure-MATLAB mode (no MEX).

Performance Tuning

After installation, these settings control performance:

% Get current defaults
defaults = FastSenseDefaults();
disp(defaults.MinPointsForDownsample);  % Threshold for downsampling
disp(defaults.DownsampleFactor);        % Points per pixel (lower = sharper)
disp(defaults.DefaultDownsampleMethod); % 'minmax' or 'lttb'

Key parameters:

Parameter Default Effect
MinPointsForDownsample 5000 Lines with fewer points skip downsampling
DownsampleFactor 2 Target 2 points per pixel; increase for coarser, faster rendering
DefaultDownsampleMethod 'minmax' 'minmax' (fast, preserves extrema) or 'lttb' (shape-preserving)
PyramidReduction 100 Multi-resolution pyramid reduction factor (balance memory vs. zoom-out speed)

To customize globally:

% Create custom defaults file
% (in libs/FastSense/private/FastSenseDefaults.m, edit the struct)
clearDefaultsCache  % Invalidate cache
defaults = FastSenseDefaults()  % Reload

Uninstall / Reset

To remove FastPlot from your MATLAB/Octave path:

rmpath(genpath('/path/to/FastPlot/libs'));
rmpath(genpath('/path/to/FastPlot/tests'));
rmpath(genpath('/path/to/FastPlot/examples'));

Or restart MATLAB/Octave (paths are not persisted across sessions).

To clean up compiled MEX files:

cd /path/to/FastPlot/libs/FastSense/private
rm -f *.mex* *.o *.so *.dylib

Advanced: Docker Compose

For the full stack (MATLAB + WebBridge + web UI):

# docker-compose.yml
version: '3.8'
services:
  matlab:
    image: mathworks/matlab:r2025b
    volumes:
      - ./FastPlot:/root/FastPlot
    ports:
      - "9000:9000"
    command: >
      matlab -r "
        cd /root/FastPlot;
        install;
        pb = WebBridge();
        pb.serve(9000, 8000);
      "

  web:
    build: ./bridge/web
    ports:
      - "8000:8000"
    environment:
      - MATLAB_HOST=matlab
      - MATLAB_PORT=9000
    depends_on:
      - matlab

Run with:

docker-compose up
# Open http://localhost:8000

Support and Documentation

  • API Reference: See wiki/API-Reference-*.md
  • Examples: examples/ directory (80+ runnable scripts)
  • Getting Started: wiki/Getting-Started.md
  • Performance: wiki/Performance.md
  • GitHub Issues: Submit bugs and feature requests
  • Discussions: Community support forum

FastSense Wiki

API Reference

Guides

Use Cases

Internals

Resources

Clone this wiki locally