Skip to content

effusive.config

config

Configuration loading and persistence for Effusive.

Provides dataclasses for all tunable parameters and two-file persistence: default_config.toml ships with the package and is never modified; the user's ~/.config/effusive/current_config.toml is created on first run and updated when the widget closes or when a reset-to-defaults button is pressed.

Classes:

Functions:

Attributes:

  • USER_CONFIG_DIR –

    Platform-appropriate user config directory (XDG on Linux, AppData on Windows).

  • USER_CONFIG_PATH –

    User-writable config file; created from defaults on first run.

USER_CONFIG_DIR module-attribute 

USER_CONFIG_DIR = Path(platformdirs.user_config_dir('effusive'))

Platform-appropriate user config directory (XDG on Linux, AppData on Windows).

USER_CONFIG_PATH module-attribute 

USER_CONFIG_PATH = USER_CONFIG_DIR / 'current_config.toml'

User-writable config file; created from defaults on first run.

AcquisitionConfig dataclass

Live-adjustable acquisition parameter defaults.

Attributes:

  • voltage_v (float) –

    Default transmit voltage in volts.

  • tx_aperture_percent (int) –

    Default TX aperture as a percentage of the full array.

  • rx_aperture_percent (int) –

    Default RX aperture as a percentage of the full array.

  • svd_threshold_percent (int) –

    Default SVD clutter-filter threshold as a percentage.

  • tgc_control_points (list of int) –

    Eight TGC control-point values in the range 0–1023.

BidsConfig dataclass

Persistent BIDS-like recording metadata defaults.

Attributes:

  • subject (str) –

    Default subject label without the sub- prefix.

  • session (str) –

    Default session label without the ses- prefix.

  • task (str) –

    Default task label without the task- prefix.

  • acq (str) –

    Default acquisition label without the acq- prefix.

  • proc (str) –

    Default processing label without the proc- prefix.

  • run (int) –

    Default run value for recordings.

CropConfig dataclass

Persisted crop ROI shape.

Attributes:

  • vertices (list of list of float) –

    Four [row, col] vertices of the last applied rectangle in pixel coordinates. An empty list means no crop ROI is saved.

EffusiveConfig dataclass

Top-level Effusive configuration.

Attributes:

  • probe_names (list of str) –

    Ordered list of available probe model names.

  • system (SystemConfig) –

    System-level settings.

  • probe_defaults (dict of str to ProbeConfig) –

    Per-probe sequence defaults keyed by probe name.

  • sequence (SequenceConfig) –

    Probe-independent sequence defaults.

  • acquisition (AcquisitionConfig) –

    Live-adjustable acquisition defaults.

  • stack (StackConfig) –

    Z-stack acquisition defaults.

  • bids (BidsConfig) –

    BIDS-like storage defaults and entity labels.

  • crop (CropConfig) –

    Last applied crop ROI vertices.

Methods:

  • get_probe –

    Return the config for a probe, falling back to the first available.

get_probe 

get_probe(name: str) -> ProbeConfig

Return the config for a probe, falling back to the first available.

Parameters:

  • name
    (str) –

    Probe model name.

Returns:

  • ProbeConfig –

    Config for name if present, otherwise the first entry.

ProbeConfig dataclass

Sequence defaults for a single probe model.

Attributes:

  • transmit_frequency_mhz (float) –

    Default transmit centre frequency in MHz.

  • txrx_frame_rate_hz (int) –

    Default TX/RX frame rate in Hz.

  • n_transmissions (int) –

    Default number of plane-wave transmissions per ensemble.

  • n_repeats (int) –

    Default ensemble size (number of TX/RX cycles).

  • planewave_opening_angle_deg (int) –

    Default compound plane-wave opening half-angle in degrees.

SequenceConfig dataclass

Sequence parameters that are probe-independent.

Attributes:

  • transmit_pulse_length (int) –

    Default pulse length in half-cycles.

  • imaging_depth_mm (float) –

    Default desired end depth in millimetres.

StackConfig dataclass

Z-stack acquisition defaults.

Attributes:

  • step_mm (float) –

    Default inter-slice step size in millimetres.

  • n_slices (int) –

    Default number of slices.

  • frames_per_slice (int) –

    Default number of Power Doppler frames to accumulate per slice.

  • settle_ms (int) –

    Default motor settle time in milliseconds.

  • motor_min_mm (float) –

    Minimum allowed absolute motor position in millimetres.

  • motor_max_mm (float) –

    Maximum allowed absolute motor position in millimetres.

SystemConfig dataclass

Persistent system-level settings.

Attributes:

  • default_probe (str) –

    Probe name selected at startup.

  • storage_path (str) –

    Default directory for saved data.

  • matlab_root (str) –

    Optional MATLAB installation root override.

  • vantage_root (str) –

    Optional Vantage (Verasonics) installation root override.

  • echoframe_mex_root (str) –

    Optional EchoFrame runtime-MEX files directory override.

  • simulate_mode (bool) –

    Whether simulate mode is on at startup.

  • udp_control_enabled (bool) –

    Whether the napari-side UDP control server starts with acquisition.

  • udp_control_port (int) –

    UDP port used by the napari-side UDP control server.

load_config 

load_config() -> EffusiveConfig

Load the user config, creating it from defaults if it does not exist.

Returns:

  • EffusiveConfig –

    Config populated from ~/.config/effusive/current_config.toml, or from the shipped defaults if no user config exists yet.

load_default_config 

load_default_config() -> EffusiveConfig

Load the shipped read-only default configuration.

Returns:

save_config 

save_config(config: EffusiveConfig) -> None

Write a config object to the user config file.

Creates ~/.config/effusive/ if it does not exist.

Parameters:

Returns:

  • None –

    Writes ~/.config/effusive/current_config.toml in place.

update_config_from_widget 

update_config_from_widget(widget: 'EffusiveWidget') -> None

Collect current widget values into widget._config and save to disk.

Reads all slider/spinbox values from the widget and writes them into the corresponding config fields, then calls save_config. Attributes are checked with hasattr so this is safe to call before all panels are built.

Parameters:

  • widget

    (EffusiveWidget) –

    Widget instance owning the UI controls and _config.

Returns:

  • None –

    Mutates widget._config in place and writes the user config file.

validate_crop_vertices 

validate_crop_vertices(vertices: list) -> bool

Return True if vertices is a valid saved crop rectangle.

A valid entry is a list of exactly four [row, col] pairs where both values are finite numbers. This guards against hand-edited config files that contain malformed data.

Parameters:

  • vertices

    (list) –

    Value read from the crop.vertices config field.

Returns:

  • bool –

    True when the vertices can safely be passed to the shapes layer.