Skip to content

Installation

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

Installation

Requirements

  • MATLAB R2020b+ or GNU Octave 7+
  • C compiler (optional) for MEX acceleration:
    • macOS: Xcode Command Line Tools
    • Linux: GCC (apt-get install build-essential)
    • Windows: Microsoft Visual C++ Build Tools
  • No toolbox dependencies — pure MATLAB/Octave implementation with optional C acceleration

Quick Start

1. Clone the Repository

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

2. Add to Path (MATLAB)

install;

This command:

  • Adds all library directories to your MATLAB path
  • Detects your system architecture and compiler
  • Compiles MEX accelerators if a C compiler is available (optional)
  • Verifies core classes are loadable
  • Performs JIT warmup on critical functions

3. Add to Path (GNU Octave)

install;

Same behavior as MATLAB, with automatic fallback to pure-Octave implementations if MEX compilation is unavailable.

Installation Methods

Package Manager (if available)

Currently, FastSense must be installed from source. Conda/pip packages may be available in future releases.

Installing from Source

git clone https://github.com/HanSur94/FastSense.git
cd FastSense
matlab -batch install
% or: octave --eval install

The install.m script automatically:

  1. Adds libs/FastSense, libs/Dashboard, libs/SensorThreshold, libs/EventDetection, libs/WebBridge to path
  2. Detects your CPU architecture (x86_64 or ARM64)
  3. Attempts MEX compilation via build_mex.m (skipped if no compiler or FASTSENSE_SKIP_BUILD=1)
  4. Verifies class availability with which('FastSense'), which('Sensor'), etc.
  5. Runs warmup cycles on core functions

Skipping MEX compilation:

export FASTSENSE_SKIP_BUILD=1
matlab -batch install

This is useful in CI pipelines where compilation is slow or unavailable. Pure-MATLAB versions work identically, just slower.

Docker Setup

A Dockerfile is provided for containerized environments:

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

The image includes:

  • MATLAB R2024b or GNU Octave 9.1
  • Build tools (GCC, CMake)
  • All dependencies pre-installed
  • FastSense libraries pre-compiled

System-Specific Installation

macOS (Apple Silicon / M1-M3)

install;

build_mex.m automatically detects arm64 and uses NEON intrinsics. Xcode Command Line Tools are required:

xcode-select --install

macOS (Intel x86_64)

Same as above. AVX2 is detected automatically; SSE2 fallback used if AVX2 fails.

Linux (x86_64)

sudo apt-get install build-essential
matlab -batch install
% or: octave --eval install

GCC is required for MEX compilation. The script auto-detects and uses available SIMD (AVX2 preferred, SSE2 fallback).

Linux (ARM64 / Raspberry Pi)

sudo apt-get install build-essential
octave --eval install

NEON intrinsics are used on ARM64. Compilation takes longer on ARM processors but MEX speedups are still significant.

Windows (MSVC)

  1. Install Microsoft Visual C++ Build Tools (MSVC 2019+):

  2. In MATLAB Command Window:

mex -setup
install;

The script detects MSVC and attempts AVX2; falls back to SSE2 if needed.

Windows (MinGW / GCC)

Not officially supported. MEX compilation with MinGW may work but is untested.

MEX Acceleration (Optional)

Build from Source

cd libs/FastSense
build_mex;

This script:

  1. Detects architecture: feature('getOS') → determines x86_64 vs arm64
  2. Selects SIMD: AVX2 on Intel, NEON on ARM64
  3. Compiles five MEX files:
    • binary_search_mex.c — visibility range computation (10-20x speedup)
    • minmax_core_mex.c — screen-resolution downsampling (3-10x speedup)
    • lttb_core_mex.c — Largest-Triangle-Three-Buckets downsampling (10-50x speedup)
    • compute_violations_mex.c — threshold violation detection (5-15x speedup)
    • violation_cull_mex.c — fused violation + pixel culling (3-8x speedup)
  4. Falls back gracefully: If AVX2 fails, retries with SSE2. If all fail, pure-MATLAB versions remain.
  5. Copies to dependent libs: Shared MEX files are copied to libs/SensorThreshold/private/

Compiler Compatibility

Architecture Compiler SIMD Support Status
x86_64 GCC 9+ AVX2, SSE2 ✓ Tested
x86_64 MSVC 2019+ AVX2, SSE2 ✓ Tested
x86_64 Clang 12+ AVX2, SSE2 ✓ Works
arm64 GCC 9+ NEON ✓ Tested (M1/M2/M3)
arm64 ARM GCC (Raspberry Pi) NEON ✓ Works, slower compile

Troubleshooting MEX Compilation

Error: "mex: command not found" (Octave)

pkg install -forge image signal
% Ensure mkoctfile is in PATH
system('which mkoctfile');
build_mex;

Error: "MSVC not found" (Windows) Run mex -setup in MATLAB first and select a compiler. Then run build_mex.

Error: "AVX2 not supported" build_mex automatically retries with SSE2. If SSE2 also fails, pure-MATLAB versions are used — no error.

Verify MEX installation:

install;
which binary_search_mex
% Should return a .mexmaca64, .mexa64, or .mexw64 file path
% If not found, pure-MATLAB fallback is active

Verify Installation

Test Suite (Recommended)

install;
addpath('tests');
run_all_tests;

This runs 200+ unit tests across:

  • FastSense core (rendering, downsampling, zoom/pan)
  • Sensors and thresholds (state channels, rule evaluation)
  • Event detection (violation grouping, statistics)
  • Dashboard widgets (serialization, live mode)
  • MEX parity (compiled vs pure-MATLAB)

Expected output:

════════════════════════════════════════════════════════════
Test Suite Results
════════════════════════════════════════════════════════════
Passed:  247
Failed:  0
Skipped: 18 (Octave-specific or MEX-optional tests)
════════════════════════════════════════════════════════════

Quick Example

install;
example_basic;

This renders a 10 million-point sine wave with upper/lower thresholds, demonstrating:

  • Real-time rendering (sub-5ms per frame)
  • Dynamic zoom/pan
  • Threshold violation markers
  • Interactive toolbar

Command-Line Verification

matlab -batch "install; run_all_tests" -logfile test_results.txt
# Check test_results.txt for pass/fail counts

Uninstall / Clean Up

Remove FastSense from the MATLAB/Octave path:

rmpath(genpath('libs'));
% Save path if desired
savepath;

Or simply close MATLAB/Octave without saving path changes (temporary addition only).

To remove compiled MEX files:

rm -f libs/FastSense/private/mex_src/*.mex*
rm -f libs/SensorThreshold/private/*.mex*

Pure-MATLAB fallbacks will activate automatically.

Docker Usage

Build Image

docker build -t fastsense:latest .

Run Interactive Session

docker run -it fastsense:latest matlab

Run Tests in Container

docker run --rm fastsense:latest matlab -batch "install; run_all_tests"

Mount Local Directory (for development)

docker run -it -v $(pwd):/workspace fastsense:latest bash
cd /workspace
octave --eval install

Environment Variables

Variable Default Purpose
FASTSENSE_SKIP_BUILD 0 Set to 1 to skip MEX compilation in install.m
FASTSENSE_THEME default Default theme on startup ('dark', 'light', 'industrial', 'scientific', 'ocean')
FASTSENSE_MEX_VERBOSE 0 Set to 1 for verbose MEX compilation output

Example:

export FASTSENSE_SKIP_BUILD=1
export FASTSENSE_THEME=dark
matlab -batch install

Version Support

Platform Version Status
MATLAB R2020b–R2024b ✓ Fully tested
MATLAB R2019b–R2020a ⚠ Likely works, not tested
Octave 7.x–9.x ✓ Fully tested
Octave 6.x ⚠ Likely works, some features limited

Troubleshooting

"Path does not contain required files" Error

Run install.m from the FastSense root directory (where this file exists).

"Class not found: FastSense"

Verify path was added:

which FastSense

If empty, re-run install. If install.m fails, check the console for errors.

MEX files not loading

Verify MEX was compiled:

which binary_search_mex

If not found, MEX was either not compiled or compilation failed. Pure-MATLAB fallbacks are active (no impact on functionality, only speed).

Out of Memory on Large Datasets

Enable disk-backed storage:

fp.StorageMode = 'disk';

This uses SQLite to store data beyond 1GB (configurable) without loading all into RAM.

Slow Initial Load

First time calling FastSense.render() is slow (MEX warmup, theme loading). Subsequent renders are fast. Add ForceMexBuild=true to install() to pre-warm all MEX functions during setup.

Next Steps

  1. Quick start: Run example_basic or run_all_examples
  2. Tutorials: See Getting Started
  3. API Reference: FastSense API
  4. Examples: 80+ examples for every use case

Support & Contributing

FastSense Wiki

API Reference

Guides

Use Cases

Internals

Resources

Clone this wiki locally