API Reference: Utilities

Supporting classes and functions used across the FastPlot library.

ConsoleProgressBar

Hierarchical console progress bar with Unicode/ASCII rendering. Used internally by FastPlot, FastPlotFigure, and FastPlotDock during rendering. Can also be used standalone.

Constructor

pb = ConsoleProgressBar();      % No indentation
pb = ConsoleProgressBar(2);     % 2-space indent (for nested progress)

Properties

All properties have Access = private.

Property	Type	Default	Description
Label	char	`''`	Current text label (max 12 chars displayed)
Current	double	0	Current progress count
Total	double	0	Total progress count
BarWidth	double	30	Character width of the progress bar
Indent	double	0	Number of leading spaces for nesting
IsStarted	logical	false	Whether start() has been called
IsFrozen	logical	false	Whether the bar is frozen (permanent)
LastLen	double	0	Character count of last printed line (for backspace)

Methods

start()

Initialize and render the empty progress bar. Resets frozen/started state and prints the initial bar.

pb = ConsoleProgressBar();
pb.start();

update(current, total) / update(current, total, label)

Update progress. Optionally set a label (labels longer than 12 characters are truncated). Has no visible effect if the bar has not been started or has already been frozen.

pb.update(3, 10);                    % 30% complete
pb.update(3, 10, 'Processing...');   % 30% with label

freeze()

Make the current state permanent (prints newline so bar is not overwritten). Subsequent calls to update() are silently ignored. Does nothing if the bar was never started or is already frozen.

pb.freeze();

finish()

Set to 100%, freeze, and mark as done. Sets IsStarted to false. Does nothing if the bar was never started.

pb.finish();

Rendering

MATLAB: Unicode block characters (U+2588 full block and U+2591 light shade) for smooth progress
GNU Octave: ASCII characters (# and -) for compatibility

The bar redraws in-place using backspace characters (\b) to erase the previous line, avoiding flicker and keeping output on a single console line.

Usage Example — Standalone

pb = ConsoleProgressBar();
pb.start();
for i = 1:100
    pause(0.01);
    pb.update(i, 100, sprintf('Step %d', i));
end
pb.finish();

Usage Example — Nested (Hierarchical)

% Parent progress bar
parentPB = ConsoleProgressBar();
parentPB.start();

for i = 1:3
    parentPB.update(i-1, 3, sprintf('Tab %d', i));

    % Child progress bar (indented)
    childPB = ConsoleProgressBar(2);
    childPB.start();
    for j = 1:5
        pause(0.01);
        childPB.update(j, 5, sprintf('Tile %d', j));
    end
    childPB.finish();
end

parentPB.finish();

This is how FastPlotDock.renderAll() displays hierarchical progress across tabs and tiles.

FastPlotDefaults

Function that returns a struct of global default configuration values. All FastPlot, FastPlotFigure, and FastPlotDock instances inherit these defaults unless overridden at construction.

Values are loaded once per MATLAB session via getDefaults() and cached in a persistent variable. Call clearDefaultsCache() to force a reload after editing this file.

Usage

defaults = FastPlotDefaults();

Fields

Theme Settings

Field	Type	Default	Description
Theme	char	`'default'`	Preset name (`'default'`, `'dark'`, `'light'`, `'industrial'`, `'scientific'`) or a struct of theme overrides
ThemeDir	char	`'themes'`	Folder containing custom theme `.m` files, relative to FastPlotDefaults.m
Verbose	logical	`false`	Print diagnostic messages to the console during plotting operations

Performance Tuning

Field	Type	Default	Description
MinPointsForDownsample	double	5000	Below this, plot raw data without downsampling
DownsampleFactor	double	2	Points per pixel for downsampling; higher values produce denser traces
PyramidReduction	double	100	Compression factor per level of the data pyramid; controls ratio between successive LOD levels

Line Defaults

Field	Type	Default	Description
DefaultDownsampleMethod	char	`'minmax'`	Downsampling algorithm: `'minmax'` preserves extremes, `'lttb'` (Largest-Triangle-Three-Buckets) preserves visual shape

Axis Scale

Field	Type	Default	Description
XScale	char	`'linear'`	Default X-axis scale (`'linear'` or `'log'`)
YScale	char	`'linear'`	Default Y-axis scale (`'linear'` or `'log'`)

Live Mode

Field	Type	Default	Description
LiveInterval	double	2.0	Polling interval in seconds for live-updating data sources

Dashboard Layout (normalized figure units 0..1)

Field	Type	Default	Description
DashboardPadding	1x4 double	`[0.06 0.04 0.01 0.02]`	Edge padding `[left bottom right top]`
DashboardGapH	double	0.03	Horizontal gap between adjacent tiles
DashboardGapV	double	0.06	Vertical gap between adjacent tiles

Dock Layout

Field	Type	Default	Description
TabBarHeight	double	0.03	Normalized height of the tab bar in docked figure mode

Customizing Defaults

Edit FastPlotDefaults.m directly to change project-wide defaults:

function defaults = FastPlotDefaults()
    defaults.Theme = 'dark';           % Change default theme
    defaults.DownsampleFactor = 3;     % More points per pixel
    defaults.LiveInterval = 1.0;       % Faster polling
    % ...
end

Resetting Cached Defaults

Call clearDefaultsCache() to force a reload after editing FastPlotDefaults.m:

clearDefaultsCache();

binary_search (Private Utility)

Fast binary search for finding an index in a sorted array. Available as both a pure-MATLAB function and a MEX-accelerated version (binary_search_mex). The MEX availability check is performed once per session and cached in a persistent variable.

Usage

idx = binary_search(x, val, 'left');   % First index where x(idx) >= val
idx = binary_search(x, val, 'right');  % Last index where x(idx) <= val

Parameter	Type	Description
x	1xN double	Sorted (monotonically increasing) array
val	double	Scalar value to search for
direction	char	`'left'` for lower-bound (first index where `x(idx) >= val`) or `'right'` for upper-bound (last index where `x(idx) <= val`)
idx	double	Positive integer index, always clamped to `[1, numel(x)]`

Examples

x = [1 3 5 7 9 11];
binary_search(x, 6, 'left')    % returns 4 (x(4) = 7 >= 6)
binary_search(x, 6, 'right')   % returns 3 (x(3) = 5 <= 6)

Performance: O(log N) time complexity with O(1) auxiliary space vs O(N) for find(). The MEX version (binary_search_mex) provides additional speedup.

build_mex

Script to compile all C MEX accelerators. Auto-detects architecture, selects the best available compiler, and sets appropriate SIMD flags.

Usage

cd libs/FastPlot
build_mex();

Compiled MEX Files

Source File	Description
`binary_search_mex.c`	O(log n) binary search on sorted arrays
`minmax_core_mex.c`	SIMD MinMax downsampling kernel
`lttb_core_mex.c`	SIMD Largest-Triangle-Three-Buckets kernel
`violation_cull_mex.c`	Fused threshold violation detection + pixel culling

Source files are located in private/mex_src/ and compiled outputs go to private/.

Architecture Detection

The function normalizes platform strings from MATLAB (maca64, maci64, glnxa64, win64) and Octave (aarch64-..., x86_64-...) into canonical labels.

SIMD Flags

Architecture	GCC/Clang Flags	MSVC Flags
arm64 (Apple Silicon)	NEON intrinsics (implicit on Clang, explicit `-mcpu=apple-m3` on GCC)	`/O2 /fp:fast` (NEON by default)
x86_64	`-O3 -mavx2 -mfma -ftree-vectorize -ffast-math`	`/O2 /arch:AVX2 /fp:fast`
x86_64 (SSE2 fallback)	`-O3 -msse2 -ftree-vectorize -ffast-math`	`/O2 /arch:SSE2 /fp:fast`
unknown	`-O3 -ffast-math`	`/O2 /fp:fast`

On x86_64, if AVX2 compilation fails (e.g., on older hardware), the function automatically retries with SSE2 flags.

Compiler Selection

Runtime	Compiler	Rationale
GNU Octave	Real GCC (searched via `find_gcc`)	Superior auto-vectorization; falls back to system default
MATLAB (macOS/Linux)	Xcode Clang (MATLAB default)	MATLAB passes Clang-specific linker flags that GCC may reject
MATLAB (Windows)	MSVC (MATLAB default)	Standard MATLAB Windows compiler

Post-Compilation

After compilation, shared MEX files needed by the SensorThreshold library are automatically copied into ../SensorThreshold/private/.

setup.m

Project path setup script. Run once per MATLAB/Octave session, or add a call to your startup.m for automatic initialization.

Usage

cd FastPlot
setup;

Directories Added to Path

Directory	Description
`libs/FastPlot`	Core plotting library
`libs/SensorThreshold`	Sensor and threshold system
`libs/EventDetection`	Event detection library
`libs/Dashboard`	Dashboard engine and widgets
`libs/WebBridge`	TCP server for web-based visualization

API Reference: Utilities

API Reference: Utilities

ConsoleProgressBar

Constructor

Properties

Methods

start()

update(current, total) / update(current, total, label)

freeze()

finish()

Rendering

Usage Example — Standalone

Usage Example — Nested (Hierarchical)

FastPlotDefaults

Usage

Fields

Theme Settings

Performance Tuning

Line Defaults

Axis Scale

Live Mode

Dashboard Layout (normalized figure units 0..1)

Dock Layout

Customizing Defaults

Resetting Cached Defaults

binary_search (Private Utility)

Usage

Examples

build_mex

Usage

Compiled MEX Files

Architecture Detection

SIMD Flags

Compiler Selection

Post-Compilation

setup.m

Usage

Directories Added to Path

See Also

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally