Visual & Display

Quick Reference ✨

• set_visual_mode(ctx, mode) / get_visual_mode(ctx) — switch the primary visualization preset.
• set_visual_auto_scale(ctx, bool) / set_visual_scale(ctx, scale) — control display amplitude scaling.
• set_visual_enable_field(ctx, field, bool) — show or hide individual fields in the renderer.
• set_phase_mode(ctx, mode) / get_phase_mode(ctx) — select the phase-portrait rendering style (requires phase_portrait visual mode).
• set_phase_coherence_* — global phase coherence configuration used by the statistics system.

---

Visual Modes 🎨

Mode Palette

phase_magnitude also accepts the aliases phase_mag and phase+magnitude.

spectrum also accepts the aliases spectral and fourier_spectrum.

Note

Older error text still mentions flux_lens as a visual-mode string, but the current Lua binding does not accept "flux_lens" in set_visual_mode. Use the Flux Lens diagnostic APIs on the dedicated Flux Lens page.

set_visual_mode(ctx, mode)

Set the active visualization preset. Accepts any mode string from the table above, or an integer mode code.

ooc.set_visual_mode(ctx, "phase_portrait")
ooc.set_visual_mode(ctx, "phase_magnitude")
ooc.set_visual_mode(ctx, "spectrum")

get_visual_mode(ctx)

Returns mode_code, mode_name — both the integer code and the canonical string name.

local code, name = ooc.get_visual_mode(ctx)
ooc.log("visual mode: %d → %s", code, name)

Display Scale 🔭

set_visual_auto_scale(ctx, enabled)

Enable or disable automatic amplitude scaling. When true, the renderer adjusts the display range to fit the field’s current value range. Returns true on success.

ooc.set_visual_auto_scale(ctx, true)    -- auto-scale to field range
ooc.set_visual_auto_scale(ctx, false)   -- use fixed scale

set_visual_scale(ctx, scale)

Set a fixed display scale factor (used when auto-scale is disabled). Returns true on success.

ooc.set_visual_scale(ctx, 2.5)   -- amplify display by 2.5×

---

Field Visibility 🔍

set_visual_enable_field(ctx, field, enabled)

Show or hide an individual field in the renderer. field may be a field handle or a 0-based integer index. Returns true on success.

local f0 = ooc.get_field(ctx, 0)
ooc.set_visual_enable_field(ctx, f0, false)   -- hide field 0
ooc.set_visual_enable_field(ctx, 1, true)     -- show field 1

---

Phase Portrait Sub-modes 🌀

When visual_mode is phase_portrait, you can select a rendering style with set_phase_mode. Calling set_phase_mode while a different visual mode is active raises a Lua error.

Phase Mode Palette

set_phase_mode(ctx, mode)

Set the phase-portrait rendering style. Must be called after set_visual_mode(ctx, "phase_portrait").

ooc.set_visual_mode(ctx, "phase_portrait")
ooc.set_phase_mode(ctx, "rosette")

get_phase_mode(ctx)

Returns mode_code, mode_name. Returns nil if no phase mode is set.

local code, name = ooc.get_phase_mode(ctx)
ooc.log("phase mode: %d → %s", code, name)

---

Phase Coherence Configuration 📡

These five functions configure the global phase coherence system used by field_stats and the statistics pipeline. They accept a ctx argument but operate on process-wide state — settings apply to all contexts in the process.

Note

These functions are convenience wrappers. The same settings can also be set atomically through field_stats_set_phase_config (see the Field Methods page).

set_phase_coherence_thresholds(ctx, abs_threshold, rel_threshold)

Set the amplitude thresholds for phase sample inclusion:

• abs_threshold — minimum absolute amplitude for a sample to count.
• rel_threshold — minimum amplitude relative to the current field max_abs.

ooc.set_phase_coherence_thresholds(ctx, 0.01, 0.05)

set_phase_coherence_weighted(ctx, weighted)

When true, weight each phase sample by its amplitude when computing coherence. Amplitude-weighted coherence is more robust for fields with large dynamic range.

ooc.set_phase_coherence_weighted(ctx, true)

set_phase_coherence_lock_thresholds(ctx, on_threshold, off_threshold)

Set the hysteresis thresholds for the phase-lock state machine:

• on_threshold — coherence level required to enter the locked state.
• off_threshold — coherence level at which the lock is released (must be ≤ on_threshold).

ooc.set_phase_coherence_lock_thresholds(ctx, 0.85, 0.70)

set_phase_coherence_smoothing(ctx, smoothing_seconds)

Set the EMA smoothing time constant for phase_coherence_ema. Larger values produce slower, more stable estimates.

ooc.set_phase_coherence_smoothing(ctx, 0.5)   -- 0.5-second EMA window

set_phase_coherence_deramp(ctx, enabled)

Enable or disable phase-ramp detrending before computing coherence. Useful when the field has a dominant linear phase drift that would otherwise suppress the coherence estimate.

ooc.set_phase_coherence_deramp(ctx, true)

---

Examples 📖

Switching modes during a run

ooc.set_visual_mode(ctx, "waveform")
for i = 1, 100 do ooc.step(ctx) end

ooc.set_visual_mode(ctx, "frequency")
for i = 1, 100 do ooc.step(ctx) end

ooc.set_visual_mode(ctx, "spectrum")

Phase portrait with rosette rendering

ooc.set_visual_mode(ctx, "phase_portrait")
ooc.set_phase_mode(ctx, "rosette")

local code, name = ooc.get_phase_mode(ctx)
ooc.log("rendering as: %s", name)   -- "rosette"

Fixed scale with selective field display

ooc.set_visual_auto_scale(ctx, false)
ooc.set_visual_scale(ctx, 4.0)

-- Two fields; only show field 0
ooc.set_visual_enable_field(ctx, 0, true)
ooc.set_visual_enable_field(ctx, 1, false)

Full phase coherence setup before a run

-- Amplitude thresholds: ignore samples below 1% of max
ooc.set_phase_coherence_thresholds(ctx, 0.0, 0.01)
-- Weight by amplitude for dynamic-range robustness
ooc.set_phase_coherence_weighted(ctx, true)
-- Hysteresis: lock at 85%, release at 70%
ooc.set_phase_coherence_lock_thresholds(ctx, 0.85, 0.70)
-- Smooth over ~1 second of simulation time
ooc.set_phase_coherence_smoothing(ctx, 1.0)
-- Detrend linear phase ramps
ooc.set_phase_coherence_deramp(ctx, true)

for i = 1, 1000 do ooc.step(ctx) end