FlowStudio is organized as a real-time processing pipeline: each incoming frame updates motion, per-cell signals, frequency maps, spectra, and the optional region (“blob”) oscillator. The UI configures parameters and visualizes outputs; the measurement chain itself is the same whether the source is a live camera or a video file.
Source (Camera / Video file) ↓ frames @ FPS → dt = 1/FPS Preprocess (optional: Blur / CLAHE) ↓ Optical Flow (frame t → t+1) [see §6] ↓ Reliability / Mask (photoErr, FB, gradient, MAD…) [see §7] ↓ Grid reduction (cell aggregation + EMA smoothing + stability) [see §8] ↓ Per-cell signal x[n] (magnitude / U / V) + optional decimation D → fs_eff = FPS/D [see §9–§10] ↓ Rapid Oscillation Analyzer (band-pass + autocorr peak → f0, corr, rms, stable) [see §10] ↓ Maps & Overlay (f0/corr/rms/stable → color overlay + debug maps) [see §11] Entropy diagnostics (H(t), H_local map, Ṡ proxy) [see §12] ↓ ↓ Aggregation & decisions ├─ Spectrum / Waterfall (histogram over active cells) [see §13] ├─ Blob Oscillator (Hz(t), Coh(t) over stable cells) [see §11.2] └─ Baseline/Change detector → Event recorder → CSV exports / Before–After summary [see §14–§18]
HH:MM:SS.mmm, reset on Start/Stop and when opening/restarting a video.FlowStudio analyzes a stream of images (camera or video file) to measure tiny motion and, in particular, rapid oscillatory motion (e.g., tremor-like motion, vibration, micro-movements) within a selected region. The key idea is:
FlowStudio outputs both visual information (overlay, vectors, maps, spectrum/waterfall) and numbers (statistics, events, Before/After summaries).
Between frame t and frame t+1, FlowStudio estimates a displacement vector v(x,y) = (u, v) for each pixel (or a dense subset), meaning “this point moved by u pixels horizontally and v pixels vertically”.
If a point moves back-and-forth periodically, its displacement magnitude (or one component) over time behaves like a wave. The frequency is “how many cycles per second” (Hz).
A video is a sequence of frames. If the acquisition runs at FPS frames per second, then the time between frames is:
dt = 1 / FPS (seconds)
Example: 200 FPS ⇒ dt = 0.005 s (5 ms).
If you want to measure an oscillation at frequency f, you must sample fast enough. A fundamental rule is the Nyquist limit: roughly, you need FPS > 2·f. In practice you want more than 2× (e.g., 5×–10×) for robust detection.
Most internal computations are in pixels per frame (px/frame). To convert to physical units, you provide a calibration:
um_per_px = micrometers represented by 1 pixel
Then speeds convert as:
speed_um_per_s = (speed_px_per_frame) * FPS * um_per_px
Note: If you do not know the calibration, you can still compare relative values across conditions, but you cannot report µm/s reliably.
.sqlite database with per-frame QC metrics and (optionally) per-cell grid flow vectors. See §15.5.| Command | Meaning |
|---|---|
| Start | Start processing from the selected source (camera or file). |
| Stop | Stop processing and release the source. |
| Open Video… | Open a video file. |
| Open Recent | Reopen one of the last used video files (up to 16). |
| Restart Video | Restart playback/processing from the beginning of the current file. |
| Pause / Resume | Freeze/unfreeze processing. When resuming, the chain is resynchronized. |
| Resync | Clear short-term history and restart internal timing (useful after ROI/seek changes). |
| Reset | Reset all internal states and counters (analysis, histograms, detector baselines). |
| Clear ROI | Disable the ROI and return to full-frame processing. |
| Fit docks | Restore the default panel arrangement. |
| Select Camera... | Select the UVC/DirectShow camera device (Windows). Useful when multiple cameras are connected. |
| Camera Resolution... | Select camera resolution/format. Prefer doing this before Start to stabilize FPS and quality (especially on USB2/USB3). |
| Camera Settings... | Opens the system driver property pages (UVC/DirectShow, Windows). Often used to disable auto-exposure/auto-gain if available. |
| Video hardcopy | Records the whole window (menus + docks + status bar) to a video file. Useful for documenting sessions exactly as seen. |
| Session recording (SQLite)... | Creates/updates a SQLite session file (.sqlite) with one row per processed frame (table frames) and one row per run/segment (table runs). Tip: enable recording and then Restart Video / Start camera for a clean take. [see §15.5] |
| Record grid flow (heavy) | If enabled, also logs per-cell flow vectors (table grid_flow). This can grow fast and increase load: prefer a higher hop and/or a less dense grid. |
| Verify session DB integrity... | Runs PRAGMA integrity_check plus basic statistics on a selected session file and prints results into the Log. Useful to confirm the recording is complete. |
| AI Request... | Creates a bundle (report + structured data) for external evaluation: PDF/JSON/CSV/images. It doesn’t change analysis, it’s export-only. |
| Help | Opens this help. |
Shortcuts are designed for fast tuning during live observation:
An ROI is a rectangular sub-area of the image used for analysis. Everything (motion, frequency, spectrum) is computed only inside the ROI.
Changing ROI changes the geometry and the history buffers. After ROI changes (or after seeking in a file), use Resync to avoid mixing data from incompatible regions/time segments.
FlowStudio estimates motion between consecutive grayscale frames. The underlying model is the classical brightness constancy assumption: a point keeps approximately the same intensity as it moves.
Let I(x,y,t) be pixel intensity. If a point moves by (u,v) between frames:
I(x, y, t) ≈ I(x + u, y + v, t + dt)
An optical-flow algorithm finds (u,v) that best satisfies this constraint over neighborhoods and multiple scales. FlowStudio uses a dense, multi-scale method that is robust for small-to-medium motions.
Before motion estimation, frames can be preprocessed to improve robustness:
Not all motion vectors are reliable. FlowStudio computes a mask and a confidence so that unreliable pixels/cells do not contribute to frequency estimates.
Several cues are combined; each has an intuitive interpretation:
photoErr(x,y) = | I2(x,y) − warp(I1, flow12)(x,y) |Low error means the motion explains the intensity changes.
fbErr ≈ | flow12(p) + flow21(p + flow12(p)) |Large fbErr indicates occlusions, blur, or wrong matches.
Each cue has a threshold (Tphoto, Tfb, Tdev, Tgrad, Tmad). A pixel passes the mask if it satisfies the enabled criteria. After building the mask, optional morphological cleanup removes isolated speckles.
A simple global quality value is the fraction of pixels/cells that pass reliability checks. This is displayed in summaries as quality (%).
Dense flow produces a vector per pixel. Frequency analysis per pixel would be too heavy and too noisy. FlowStudio therefore aggregates vectors inside square cells of size Cell size.
Inside each cell, only masked (reliable) pixels are used. The cell vector is a robust estimate:
A cell becomes valid only if it has at least Min samples reliable pixels.
Cell vectors still fluctuate. A simple exponential moving average (EMA) smooths them:
v_smooth[t] = α · v_new[t] + (1 − α) · v_smooth[t−1]
Additionally, a max jump parameter limits unrealistic sudden changes: if |v_new − v_prev| is too large, the update is rejected or clamped.
For oscillation estimation, you want cells that keep a coherent motion signal over multiple frames. Persistence maintains a stable counter per cell: the counter increases when motion changes little (within epsilon) and drops when it becomes inconsistent or missing.
Once you have one vector per cell and per frame, you can convert it into a 1D time signal x[n]. FlowStudio offers three choices:
Why would you use a component instead of magnitude? A signed component preserves direction (back-and-forth becomes a clean oscillation around zero), while magnitude can “rectify” motion and introduce harmonics.
This is the core frequency engine. For each cell, FlowStudio maintains a short history buffer and estimates the dominant oscillation frequency.
If input FPS is high (e.g., 200 FPS), you can optionally decimate by a factor D: average D consecutive vectors to produce one sample. This reduces noise and decreases computational cost.
fs_eff = FPS / D
All frequency computations use fs_eff.
Raw motion contains slow drift (posture, camera drift) and fast noise. FlowStudio uses a simple band-pass built from:
These are standard 1st-order filters in discrete time. Conceptually:
high-pass: y[n] = a · ( y[n−1] + x[n] − x[n−1] ) low-pass: y[n] = y[n−1] + b · ( x[n] − y[n−1] )
The cutoffs are in Hz and are interpreted using fs_eff.
Each cell keeps a circular buffer of length N samples. The time span covered is:
window_duration = N / fs_eff (seconds)
The analyzer updates every Hop samples, so the update rate is approximately:
updates_per_second ≈ fs_eff / Hop
Small N gives fast reactions but poorer frequency resolution; larger N stabilizes estimation but reacts slower.
To find a periodicity, FlowStudio computes the normalized autocorrelation of the windowed signal. First remove the mean (so oscillations center at zero). Then, for each lag L:
corr(L) = Σ_{i=0..M−1} x[i]·x[i+L] / sqrt( Σ x[i]^2 · Σ x[i+L]^2 )
where M = N − L
This is a correlation coefficient between the signal and a delayed copy. It lies roughly in [−1, +1]. FlowStudio uses the positive peak as a periodicity score.
FlowStudio searches only within a frequency band [fMin, fMax]. Frequencies correspond to lags:
L ≈ fs_eff / f lagMin = floor(fs_eff / fMax) lagMax = ceil (fs_eff / fMin)
The analyzer picks the lag with maximum corr(L) inside [lagMin, lagMax].
Before trusting corr peaks, FlowStudio checks that the signal has enough energy:
RMS = sqrt( mean( x[i]^2 ) )
If RMS is below RMS thr, the cell is considered inactive (no meaningful oscillation).
Lag is discrete, but true period might be between two lags. FlowStudio refines the best lag with a small parabolic interpolation using corr(L−1), corr(L), corr(L+1). Then the dominant frequency is:
f0 = fs_eff / lagFrac
Even after gating, frequency can jump due to noise. FlowStudio keeps a per-cell stable counter: if |f0 − previous_f0| ≤ freqTol, the counter increases; otherwise it resets. This “stable” value is used as an additional reliability measure.
After analyzing all cells, FlowStudio builds grid maps:
The overlay is a visualization that blends:
Transparency (alpha) is computed from corr, rms and stable, with the main thresholds:
if corr < CorrThr or rms < RmsThr → alpha = 0 cc = (corr − CorrThr) / (1 − CorrThr) clipped to [0,1] rr = (rms − RmsThr ) / (3·RmsThr) clipped to [0,1] ss = min(1, stable / stableNeed) alpha = alphaBase · cc · rr · ss · AlphaBoost clipped to [0,1]
Then the final view mixes B/W and color:
output = (1−alpha)·(BW·BWgain) + alpha·(COLOR·ColorGain)
This means “stronger, more periodic, more stable oscillations” become more visible and more saturated.
Besides estimating a frequency per cell, FlowStudio can also estimate an equivalent oscillator for the whole ROI/blob: a single frequency trace Hz(t) plus a coherence number Coh(t) that tells how much the region behaves like “one oscillator” (high coherence) versus a mixture of unrelated phases/noise (low coherence).
Where to find it in the UI. The time plot is shown in the Oscillator Plot tab (docked together with Spectrum/Waterfall and Log). Debug images are in the F0 Map dock → sub-tab Oscillator (Amp/Phase/Contrib/Mask). To save CPU, the entire block is disabled when Enable blob oscillator (heavy) is unchecked.
The Blob Oscillator uses only the cells that are already considered reliable by the Rapid Oscillation Analyzer. Let each cell i have: corri (periodicity), rmsi (energy), and stablei (persistence counter). Then the active set is:
S = { i | corr_i ≥ CorrThr and rms_i ≥ RmsThr and stable_i ≥ stableNeed }
If |S| is too small, the oscillator output is marked invalid for that update (no trustworthy region-level estimate).
For each cell in S, FlowStudio already maintains a short, band-pass filtered time signal xi[n] (the same filtering/decimation used by the per-cell analyzer; see Sections 10.1–10.3). The equivalent region signal is the average:
y[n] = (1 / |S|) · Σ_{i∈S} x_i[n]
Intuition: y[n] suppresses uncorrelated noise (averaging) and emphasizes motion that is common to many stable cells.
On each update (every Hop samples), FlowStudio computes the discrete Fourier transform (DFT) of y[n] over the current window:
Y[k] = Σ_{n=0..N−1} y[n] · exp( −j · 2π · k · n / N )
f_k = k · fs_eff / N
The peak bin is searched only inside the user band [fMin, fMax] (the same band used for per-cell f0):
kMin = ceil( fMin · N / fs_eff )
kMax = floor( fMax · N / fs_eff )
k* = argmax_{k ∈ [kMin..kMax]} |Y[k]|
Hz = f_{k*}
Amp = |Y[k*]| (relative amplitude)
Amp is a relative spectral magnitude for the region. If you need calibrated physical units, combine it with your px→µm calibration and FPS.
Once the region peak bin k* is known, each stable cell contributes a complex coefficient at that frequency:
X_i = Σ_{n=0..N−1} x_i[n] · exp( −j · 2π · k* · n / N )
Coherence is computed as a phase-alignment ratio (0..1):
Coh = | Σ_{i∈S} X_i | / Σ_{i∈S} |X_i|
If Compute debug maps is enabled, FlowStudio builds per-cell maps at the peak frequency k*:
C_i = |X_i| · cos( φ_i − φ_ref ), where φ_ref = arg( Σ_{i∈S} X_i )
Positive (in-phase) vs negative (anti-phase) contributions become visually obvious.
The region peak search uses one FFT/DFT on the region signal y[n] to find the best bin k* inside [fMin, fMax]. After k* is known, the per-cell complex coefficients Xi at that single bin can be computed in two equivalent ways:
The single-bin DFT is exactly:
X_i(k*) = Σ_{n=0..N−1} x_i[n] · exp( −j · ω · n ), with ω = 2π · k* / N
The Goertzel recursion computes the same value using a second-order filter:
s[n] = x[n] + 2·cos(ω)·s[n−1] − s[n−2] with s[−1]=s[−2]=0 X(k*) = s[N−1] − exp(−j·ω)·s[N−2]
In FlowStudio, the FFT on y[n] is used to pick k* (Hz). The same k* is then used to compute Coh and (optionally) the debug maps using the single-bin coefficients Xi. This gives the same mathematics as a full FFT, with lower CPU cost.
This panel adds a complementary family of measurements based on entropy, intended as a diagnostic of how concentrated or spread the oscillatory activity is in frequency and space. In FlowStudio, “entropy” is used in the Shannon sense (information entropy) applied to distributions built from the existing maps (f0, corr, rms, stable) and the frequency histogram.
At each update, FlowStudio already builds a frequency histogram by counting how many cells have a valid dominant frequency f0 (only cells that pass the same gates used for “valid oscillation”: band + CorrThr + RmsThr + StableNeed). Let the histogram have K bins and counts ck. Convert counts to probabilities:
p_k = c_k / Σ c_k H = − Σ p_k · log(p_k) (Shannon entropy; base e) H01 = H / log(K) (normalized to 0..1)
While H(t) is a region-level summary, Hlocal(x,y) is a map. For each cell (x,y), FlowStudio looks at a square neighborhood of radius R (in grid cells) and builds a small histogram of f0 values inside the neighborhood, after quantizing them into K bins (same “bins” parameter). Then it computes the Shannon entropy (normalized 0..1) of that local distribution.
Formally, for a neighborhood N(x,y):
p_k(x,y) = count of cells in N(x,y) whose f0 falls in bin k / total valid cells in N(x,y) H_local(x,y) = − Σ p_k(x,y) · log(p_k(x,y)) H_local01(x,y)= H_local(x,y) / log(K)
A thermodynamic entropy production rate would be:
Ṡ ≈ P_diss / T
However, from images alone you typically do not have direct access to calibrated dissipated power. FlowStudio therefore provides a proxy that correlates with “how much oscillatory activity is happening” and can be visualized as a map. A practical default is:
powerProxy(x,y) = rms(x,y)^2 · corr(x,y) (only on valid/gated cells) P_proxy(t) = Σ powerProxy(x,y) Sdot_proxy(t) = powerScale · P_proxy(t) / T
Notes. rms is after band-pass filtering; corr is the autocorrelation peak score. The factor powerScale is a user scale to make the plot readable. If you have a calibrated mechanical model (mass, stiffness, damping) or a direct estimate of Pdiss, you can replace the proxy with the physical expression while keeping the same visualization.
t_s, H01, Sdot.Metric Space is a 3D view that turns the time evolution of many metrics (frequencies, entropy, quality, triggers, etc.) into a trajectory in space. Each point represents a time sample (one every Hop frames) and is colored by the selected scalar. The goal is not to “measure a new quantity”, but to see the system state at a glance: stable regimes, transitions, clusters, and Before/After differences.
FlowStudio builds a 16-dimensional feature vector (robust-normalized with median and MAD over a time window) including, among others:
That vector is then embedded into 3D:
| Parameter | What it does | Practical notes |
|---|---|---|
| Enable | Enables trajectory generation. | If off, the view stays unchanged. |
| Hop frames | Temporal decimation: 1 point every N frames. | Increase to reduce load (e.g. 3–10). |
| Window (sec) | Window used for robust normalization and (if not frozen) PCA updates. | Longer = steadier basis, less reactive. |
| Embed | PCA or LMDS. | LMDS is more expensive; keep landmarks moderate. |
| Freeze basis | Locks normalization + basis once enough history is collected. | Recommended for comparisons and to avoid geometry “jumps”. |
| View mode | 3D curve or time-axis (z=t), rendered as line/points, ribbon, tube, or density. | Ribbon/tube improve readability; density shows an “attractor”. |
| Color | Colors points by Time, Peak Hz, Entropy H, Osc Hz, Quality, Global speed, Osc Coh. | Great to see what changes along the trajectory. |
| Max points | History cap (maximum kept points). | Prevents unlimited growth in long sessions. |
| Landmarks (LMDS) | Landmark count for LMDS. | 256 is often a good trade-off. |
| Reset | Clears trajectory and restarts. | Use after changing source or conditions. |
In Density cloud mode, points are voxelized into a 3D grid (bins^3) and shown as a weighted cloud. The Iso overlay draws an iso-surface over the densest regions: it behaves like a 3D signature of the trajectory.
.mhd + .raw)
plus meta.json. Typical outputs: normalized/raw density, scalar mean, gradient magnitude.Each cell that passes gating contributes to a histogram bin. A bin represents a frequency, with a user-defined scale:
bin = round( f0 · scale ) (scale = bins per Hz)
Only frequencies inside [Hist fMin, Hist fMax] are accumulated.
A cell can contribute a simple count (COUNT) or be weighted by reliability/strength:
Weighting helps emphasize strong, periodic oscillations and suppress weak/noisy ones.
The peak bin (maximum histogram value) defines the “dominant frequency” for the current frame:
peakHz = peakBin / scale
The waterfall is a time–frequency display: each row is a histogram, and rows scroll with time. It helps you see whether the frequency is stable, drifting, or intermittent.
The detector triggers events when the dominant frequency changes beyond normal variability. It maintains a baseline mean (mu) and variance (var) using an exponential moving average (EWMA).
mu[t] = (1−α)·mu[t−1] + α·f[t] var[t] = (1−α)·var[t−1] + α·(f[t]−mu[t])^2 sigma = sqrt(var)
A smaller α means “longer memory” (baseline changes slowly).
A change is significant if:
|f − mu| > max( absHz, rel·mu, kSigma·sigma )
Baseline and trigger are updated only when the frame contains enough valid oscillatory cells. This prevents the baseline from being “polluted” by idle/noisy frames.
When the detector triggers, the event recorder saves image sequences around the event:
At the trigger moment, it can also save a one-time snapshot of diagnostics: overlay, corr map, f0 map, and mask.
In addition to event snapshots (Event recorder), FlowStudio can log a full measurement session into a SQLite database.
The resulting .sqlite file contains per-frame QC metrics and, optionally, per-cell grid flow vectors.
.sqlite file. The action stays checked (recording is armed).grid_flow).name.sqlite-wal and name.sqlite-shm. During recording, the main .sqlite
can stay relatively small: this is expected. On stop, FlowStudio runs a checkpoint to fold data back into the main file.
If you need to copy a session while recording, copy -wal and -shm together with the .sqlite.
| Table | Content |
|---|---|
meta | Key/value pairs: schema, version, creation time, meta_json (UI-provided JSON), source_meta_json (source information). |
runs | One record per run/segment: start timestamps and source snapshot (fps, size, etc.). |
frames | One row per frame with key QC metrics: peak/baseline Hz, quality, activity, fps, drops, luminance/blur/saturation, ROI, etc. |
grid_flow | (Optional) Sparse grid vectors: per frame (optionally subsampled by hop) stores (cx,cy,u,v,conf,stable). |
events | Lightweight JSON events: run_start/run_end, roi_changed, and future markers. |
To quickly confirm the file is valid and complete, use File → Verify session DB integrity...:
FlowStudio runs PRAGMA integrity_check; and prints basic counters/ranges (runs/frames) into the Log.
-- how many rows were written SELECT COUNT(*) FROM frames; -- frames per run SELECT run_id, COUNT(*) AS n FROM frames GROUP BY run_id ORDER BY run_id; -- time range (UTC microseconds) for run 1 SELECT MIN(t_us), MAX(t_us) FROM frames WHERE run_id=1; -- mean peak and mean quality (run 1) SELECT AVG(peak_hz) AS peakHz_mean, AVG(quality01) AS q_mean FROM frames WHERE run_id=1;
Exports the last N samples of:
Exports the last N histograms, but only non-zero bins: each output row includes time, frame index, activeCount, weightSum, bin index, Hz and count. This is efficient for large bin counts (e.g., 1024).
Sonata analysis is a “session summary” of spectral content. It uses the accumulated histogram history to find the most prominent frequencies over time.
Conceptually:
Parameters:
During recording, each processed frame contributes:
Let FPS_seg be the measured FPS during the recorded segment. Pixel speeds are converted to µm/s by:
value_um_s = value_px_frame · FPS_seg · um_per_px
| Metric | Meaning |
|---|---|
| RMS speed (µm/s) | Global motion speed is computed each frame as |globalMotion|. RMS speed is the root-mean-square of that per-frame speed, converted to µm/s. It represents overall motion intensity. |
| Drift (µm/min) | Mean global speed converted to µm/min. It represents slow drift or sustained displacement. |
| Dominant frequency (Hz) | Mean of peakHz across frames. Represents the typical oscillation frequency. |
| Frequency stability (Hz) | Standard deviation of peakHz across frames. Lower means more stable frequency. |
| Peak amplitude (µm/s) | Uses bestRms (px/frame) of the best cell, converted to µm/s. It is a proxy of oscillation amplitude/strength. |
| Peak/Band ratio | peakToBand averaged across frames. Closer to 1 means “a single sharp frequency dominates”. Lower means “spread spectrum / mixed frequencies”. |
| Events/min | How often the frequency-change detector triggered during the segment, normalized per minute. |
| Micro-activity (µm/s) | Mean residual motion magnitude after removing global translation. It reflects “local micro-movement” inside the ROI rather than whole-ROI drift. |
| Active area (%) | Fraction of residual samples whose magnitude exceeds a small threshold (~0.5 px/frame), averaged across frames, expressed in percent. |
| Quality (%) | Average inlier ratio (reliable motion fraction) expressed in percent. Low quality means the measurement is likely unreliable. |
In addition to the main detector, FlowStudio characterizes “jerk-like” periods using global speed statistics: it tracks a running mean and standard deviation of speed, then opens an event when speed exceeds mean + 3·std, and closes it when speed stays below mean + 2·std for a few frames (hysteresis).
From these events it reports:
During recording, FlowStudio also measures:
A simple quality flag is produced:
Coh is designed as a phase-alignment metric:
Coh = | Σ_{i∈S} X_i | / Σ_{i∈S} |X_i| (0..1)
| Acronym / term | Meaning in FlowStudio |
|---|---|
| ROI | Region Of Interest: the rectangle where analysis runs (everything outside is ignored). |
| FPS | Frames per second (sampling rate of the video stream). |
| dt | Time step between frames: dt = 1/FPS. |
| Nyquist | Sampling rule: the highest resolvable frequency is roughly FPS/2 (more margin is better in practice). |
| Optical flow | Frame-to-frame displacement estimation; outputs a vector (u,v) per pixel or per region. |
| (u,v) | Horizontal/vertical displacement components, typically in px/frame. |
| px/frame | Pixels per frame: internal motion unit (before converting to physical units). |
| um_per_px | Calibration: micrometers per pixel (µm/px). Enables physical units (µm, µm/s). |
| Mask / inliers | Set of reliable pixels/cells that pass confidence checks and therefore contribute to estimates. |
| photoErr | Photometric error after warping; low values mean the flow explains intensity changes well. |
| FB / fbErr | Forward–backward consistency error; large values signal occlusions/blur/mismatch. |
| MAD | Median Absolute Deviation: robust dispersion measure used for cell stability/outlier rejection. |
| EMA | Exponential Moving Average: temporal smoothing of cell vectors/signals. |
| Decimation (D) | Optional averaging of D consecutive frames/samples to reduce noise and CPU cost. |
| fs_eff | Effective sampling rate after decimation: fs_eff = FPS/D. |
| N | Window length (number of samples) used for frequency estimation. |
| Hop | Update step (in samples) between consecutive window analyses. |
| Band [fMin,fMax] | Frequency search band (Hz) used by the analyzer and (optionally) other blocks. |
| HP / LP | High-pass / low-pass filters used to form a simple band-pass (cutoffs: hpCut / lpCut). |
| RMS | Root Mean Square energy of the filtered signal (activity/energy gate). |
| Corr / corr(L) | Normalized autocorrelation peak; “periodicity score” used as a gate and for alpha. |
| CorrThr | Correlation threshold: minimum periodicity score required to accept a cell. |
| f0 | Dominant frequency estimate per cell (Hz). 0 means “no valid frequency”. |
| stable / stableNeed | Persistence counter and its threshold: how long a cell kept a consistent frequency. |
| Active cells | Cells that pass corr/rms/stable gates in the current update and contribute to maps/histograms. |
| Spectrum / histogram | Distribution of per-cell frequencies in the ROI (possibly weighted by corr/rms). |
| Waterfall | Time history of spectra; useful to see drifts, bursts and band changes. |
| Blob oscillator | ROI-level oscillator estimate: produces Hz(t) and Coh(t) over the stable-cell set. |
| Hz(t) | Region dominant frequency trace (one value per update) from the blob oscillator. |
| Coh | Coherence (0..1): phase-alignment ratio across stable cells; high means “single-oscillator-like”. |
| DFT / FFT | Discrete Fourier Transform / Fast Fourier Transform used for peak search in spectra. |
| Goertzel | Efficient single-bin DFT (often used when only one frequency bin is needed). |
| UVC | USB Video Class (standard USB camera interface on Windows). |
| BW gain / Color gain / Alpha boost | Visualization gains that control background brightness, color saturation and overlay transparency strength. |
| quality (%) | Overall inlier ratio (fraction of pixels/cells considered reliable), shown as a quick acquisition health indicator. |
End of document.
This appendix clarifies a common source of confusion: a camera output format (what the UVC device streams over USB) is not the same as a file format (what you save on disk). UVC cameras typically stream either:
When you save a recording, you usually choose a container (e.g., MP4 or AVI) and a codec (e.g., H.264 or MJPG). The application (through OpenCV / OS multimedia backends) encodes the incoming frames into that codec.
UVC (USB Video Class) is a standard that allows cameras to expose video streams with a set of supported formats and frame sizes. Typical format families:
“YUV” (more precisely Y′CbCr) describes pixel organization (how luma/chroma samples are stored), not a file container. MP4 is a container that usually carries compressed video streams (e.g., H.264/H.265/AV1). You generally do not store raw YUY2 inside MP4. So the real chain is:
UVC camera outputs YUY2 (raw frames) → application decodes to BGR/gray → encoder compresses to H.264 → MP4 file
Or, if the camera outputs MJPG:
UVC camera outputs MJPG (compressed frames) → decoder to BGR/gray → (optional) re-encode → MP4/AVI file
| Container | Common codecs | Notes |
|---|---|---|
| MP4 | H.264 (AVC), H.265 (HEVC), AV1 | Efficient; can introduce compression artifacts at low bitrate; often VFR pitfalls if not handled carefully. |
| AVI | MJPG, XVID/DivX, uncompressed | Simple and widely supported; good for MJPG recordings; file size can be large if uncompressed. |
| MKV | H.264/H.265, VP9, AV1 | Flexible container; depends on the chosen backend/support. |
The actual available codecs depend on the OS backend (Windows Media Foundation / DirectShow) and your OpenCV build.
FlowStudio follows the standard QMainWindow (Qt) model: one central view plus several dock widgets (dockable panels) around it. If you are not used to Qt, this appendix explains how to bring panels back, move and resize them.