analyze_envelope
Screen bearing faults by performing envelope-spectrum analysis on a stored vibration signal. Bandpass filter, Hilbert envelope, and FFT identify top spectral peaks for fault detection.
Instructions
Envelope-spectrum analysis of a stored signal (bearing fault screening).
THE unified envelope tool: bandpass filter -> Hilbert
envelope -> mean subtraction + Hann window -> FFT -> top peaks.
The mean subtraction/window step is an intentional U9 fix: the
envelope's DC leakage used to bury the low-frequency FTF zone.
Requires the signal loaded via load_signal() first; the sampling
rate comes from the stored signal metadata.
The requested band must fit the signal: an invalid band (low <= 0,
low >= high, high > Nyquist) raises a ValueError — it is NEVER
silently clamped. The band used is echoed in the result.
By default analyzes the LEADING 1.0-second segment (deterministic:
two identical calls return identical results). Set
segment_duration=None to analyze the entire signal, or pass
random_seed to sample a seeded random segment position instead.
No reference bearing frequencies are assumed: compare the returned
peaks against frequencies computed for the actual bearing and
shaft speed (check_bearing_faults or
calculate_bearing_characteristic_frequencies).
Args:
ctx: MCP context for user communication
signal_id: ID of the stored signal (from load_signal).
filter_low: Bandpass low edge in Hz (default: 500).
filter_high: Bandpass high edge in Hz (default: 5000). Must
not exceed the signal's Nyquist frequency.
num_peaks: Number of top peaks to return (default: 5).
segment_duration: Duration in seconds to analyze (default:
leading 1.0 s). None analyzes the full signal.
random_seed: Seed for random segment position (default: None =
deterministic leading segment).
Returns:
EnvelopeResult with the band actually used, top peaks, and
comparison guidance.
Raises:
ValueError: If the signal_id is not loaded, the stored signal
has no sampling rate, or the band is invalid vs Nyquist.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| num_peaks | No | ||
| signal_id | Yes | ||
| filter_low | No | ||
| filter_high | No | ||
| random_seed | No | ||
| segment_duration | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| diagnosis | Yes | Peak listing and comparison guidance. No reference bearing frequencies are assumed — compare against frequencies computed for the actual bearing and shaft speed. | |
| signal_id | Yes | Signal identifier used | |
| top_peaks | Yes | Top peaks in the envelope spectrum, sorted by frequency | |
| filter_band | Yes | Bandpass filter band (Hz) actually used — echoed from the request | |
| num_samples | Yes | Number of samples analyzed (envelope length) | |
| sampling_rate | Yes | Sampling rate (Hz) |