effusive.matlab_worker¶

Effusive MATLAB engine worker subprocess.

Runs as a subprocess of the napari viewer process so that MATLAB's bundled Qt libraries (loaded via LD_LIBRARY_PATH) never enter the napari/Qt process.

Startup sequence: 1. Set Linux GUI and library environment variables for MATLAB. 2. Import and start matlab.engine. 3. Add EchoFrame and Effusive paths to the MATLAB session. 4. Write initial acquisition parameters to the MATLAB base workspace. 5. Call cf_setup: synchronous, fast; writes nz/nx to the metadata segment. 6. Call VSX: blocks for the duration of the acquisition session. 7. Quit the engine and exit.

Runtime control (freeze, vsExit, SVD threshold, ...) flows through the command shared-memory segment, which processRuntimeControl reads every frame. No workspace writes are sent after VSX is called.

Usage (from the viewer / subprocess.Popen):

python matlab_worker.py '<JSON config string>'

JSON config keys (all optional, defaults shown): - matlabRoot: Path to MATLAB installation root. Required: MATLAB_ROOT env var or explicit config. - matlabStartupOptions: Extra command-line options passed to MATLAB engine startup. Default: empty. - echoFrameMexRoot: Directory containing EchoFrame runtime MEX files (echoframe_mex.*). Required: ECHOFRAME_MEX_ROOT env var or explicit config. - effusiveRoot: Path to Effusive repo root. Default: auto-detected (2 levels above this file). - vantageRoot: Path to Vantage (Verasonics) installation. Required: VERASONICS_VPF_ROOT env var or explicit config. - probeName: Ultrasound probe model name. Default: 'L22-14v'. - transmitFrequency: Transmit frequency [MHz]. Default: probe-specific. - storagePath: Root directory for per-session output folders. Default: /tmp/effusive. - sessionId: Session identifier shared across the viewer log, VSX MAT file, and MATLAB session folder. Default: generated by the viewer. - bidsSubject: Default BIDS subject label without the sub- prefix. - bidsSession: Default BIDS session label without the ses- prefix. - bidsTask: Default BIDS task label without the task- prefix. - bidsAcq: Default BIDS acquisition label without the acq- prefix. - bidsProc: Default BIDS processing label without the proc- prefix. - bidsRun: Default run value for recordings. - voltage: Acquisition voltage (V). Default: 1.6. - transmitAperturePercentage: Initial TX aperture [%]. Default: 100. - receiveAperturePercentage: Initial RX aperture [%]. Default: 100. - txrxFrameRate: Acquisition frame rate [Hz]. Default: probe-specific. - transmitPulseLength: Pulse length [half cycles]. Default: 3. - nTransmissions: Number of compounded transmit angles. Default: probe-specific. - nRepeats: Ensemble size. Default: probe-specific. - planewaveOpeningAngle: Total steering angle range [deg]. Default: probe-specific. - desiredEndDepthMm: Imaging depth [mm]. Default: 12. - tgcGain: Initial TGC gain. Default: 900. - tgcControlPoints: Initial Verasonics TGC control points. Default: eight points at tgcGain. - simulateMode: 0 = real hardware, 1 = Media simulation, 2 = replay preloaded RcvData. Default: derived from system.simulate_mode in default_config.toml. - rcvDataMatFile: Path to a MAT file containing RcvData for simulateMode=2. Default: empty.

Functions:

• main –

  Run the MATLAB engine worker subprocess.

main(cfg: dict) -> None