`effusive.shared_memory`¶

shared_memory ¶

Effusive shared-memory protocol.

The napari viewer creates a fresh set of seven shared-memory segments before each acquisition run and passes the resolved names to the MATLAB worker. Default logical channel names are exposed as module-level constants (cf_meta, cf_bmode, cf_pdi, cf_cmd, cf_rf, cf_stack, cf_ack), but runtime code can override them with a session token to avoid collisions between acquisitions.

This module defines the binary layouts, lifecycle helpers, and the Python-side reader and writer utilities used by the napari process.

Classes:

ShmReader –

Open existing shared memory segments for reading (napari side).

Functions:

close_segments –

Close and optionally unlink shared memory segments.
create_segments –

Create all shared-memory segments, replacing any stale ones.
resolve_segment_names –

Return the effective shared-memory names for one acquisition session.

Attributes:

BMODE_CONTRAST_LIMITS –

B-mode layer contrast limits (dB, relative to the current frame's peak).
CMD_FIELDS –

Command channel fields in CMD_FORMAT unpack order.
CMD_FIELD_INDEX –

Map cf_cmd field names to their unpacked tuple indices.
DEFAULT_SEGMENT_NAMES –

Default shared-memory segment names keyed by logical channel.
META_FLAG_FREEZE_ACTIVE –

Runtime flag bit indicating that acquisition is currently frozen in VSX.
META_FLAG_SAVE_ACTIVE –

Runtime flag bit indicating that EchoFrame is actively saving to disk.
PDI_CONTRAST_LIMITS –

Power Doppler layer contrast limits (dB, relative to the current frame's peak).

BMODE_CONTRAST_LIMITS `module-attribute` ¶

BMODE_CONTRAST_LIMITS = (-60.0, 0.0)

B-mode layer contrast limits (dB, relative to the current frame's peak).

CMD_FIELDS `module-attribute` ¶

CMD_FIELDS = ('vsExit', 'freeze', 'save_to_disk', 'svd_update_flag', 'svd_threshold', 'voltage_update_flag', 'voltage_v', 'tx_aperture_update_flag', 'rx_aperture_update_flag', 'tx_aperture', 'rx_aperture', 'show_rf', 'crop_update_flag', 'crop_reset_flag', 'roi_top', 'roi_bottom', 'roi_left', 'roi_right', 'save_rf', 'save_rf_time_tag', 'save_bf', 'save_pdi', 'tgc_update_flag', 'tgc_point_1', 'tgc_point_2', 'tgc_point_3', 'tgc_point_4', 'tgc_point_5', 'tgc_point_6', 'tgc_point_7', 'tgc_point_8', 'stack_start_flag', 'stack_abort_flag', 'stack_use_dummy_motor', 'stack_start_um', 'stack_step_um', 'stack_n_slices', 'stack_npdi_per_slice', 'stack_settle_ms', 'stack_jog_um', 'freeze_req_id', 'save_req_id', 'svd_req_id', 'voltage_req_id', 'tx_aperture_req_id', 'rx_aperture_req_id', 'tgc_req_id', 'crop_req_id', 'stack_req_id')

Command channel fields in CMD_FORMAT unpack order.

CMD_FIELD_INDEX `module-attribute` ¶

CMD_FIELD_INDEX = {name: idx for idx, name in (enumerate(CMD_FIELDS))}

Map cf_cmd field names to their unpacked tuple indices.

DEFAULT_SEGMENT_NAMES `module-attribute` ¶

DEFAULT_SEGMENT_NAMES = {'meta': SHARED_MEMORY_META_NAME, 'bmode': SHARED_MEMORY_BMODE_NAME, 'pdi': SHARED_MEMORY_PDI_NAME, 'cmd': SHARED_MEMORY_CMD_NAME, 'rf': SHARED_MEMORY_RF_NAME, 'stack': SHARED_MEMORY_STACK_NAME, 'ack': SHARED_MEMORY_ACK_NAME}

Default shared-memory segment names keyed by logical channel.

META_FLAG_FREEZE_ACTIVE `module-attribute` ¶

META_FLAG_FREEZE_ACTIVE = 1 << 1

Runtime flag bit indicating that acquisition is currently frozen in VSX.

META_FLAG_SAVE_ACTIVE `module-attribute` ¶

META_FLAG_SAVE_ACTIVE = 1 << 0

Runtime flag bit indicating that EchoFrame is actively saving to disk.

PDI_CONTRAST_LIMITS `module-attribute` ¶

PDI_CONTRAST_LIMITS = (-30.0, 0.0)

Power Doppler layer contrast limits (dB, relative to the current frame's peak).

ShmReader ¶

Open existing shared memory segments for reading (napari side).

Parameters:

names ¶
(dict[str, str], default: None ) –

Optional per-channel name overrides keyed like "meta" or "cmd".

Methods:

close –

Close all shared memory segment handles.
read_ack –

Read command acknowledgements from shared memory.
read_bmode –

Read raw B-mode amplitude from shared memory and log-compress it to dB.
read_cmd –

Read the current cf_cmd command channel contents from shared memory.
read_meta –

Read metadata from shared memory.
read_pdi –

Read raw power Doppler power from shared memory and log-compress it to dB.
read_rf –

Copy RF snapshot from shared memory as an int16 array.
read_rf_header –

Read the RF segment header from shared memory.
read_stack_status –

Read z-stack status from shared memory.

close ¶

close() -> None

Close all shared memory segment handles.

Shared-memory handles are unregistered from Python's automatic cleanup tracker as soon as they are opened, so shutdown is entirely managed by Effusive's explicit close/unlink paths.

read_ack ¶

read_ack() -> tuple[int, int, int, int, int, int, int, int, int]

Read command acknowledgements from shared memory.

Returns:

tuple[int, int, int, int, int, int, int, int, int] –

A tuple containing the acknowledgement counters in ACK_FIELDS order.

read_bmode ¶

read_bmode(nz: int, nx: int) -> NDArray

Read raw B-mode amplitude from shared memory and log-compress it to dB.

MATLAB sends the raw (un-normalized) B-mode amplitude; this converts it to dB relative to the current frame's own peak (20 * log10(raw / raw.max())), matching the fixed BMODE_CONTRAST_LIMITS colorbar.

Parameters:

nz ¶
(int) –

Number of rows (z-dimension).
nx ¶
(int) –

Number of columns (x-dimension).

Returns:

ndarray –

A (nz, nx) float32 array in dB, clipped to BMODE_CONTRAST_LIMITS.

read_cmd ¶

read_cmd() -> tuple

Read the current cf_cmd command channel contents from shared memory.

This reflects the last values napari wrote (or MATLAB's own defaults if napari has not written yet), in CMD_FIELDS order. Intended for diagnostics: comparing this against what the GUI intended to send.

Returns:

tuple –

A tuple containing the command channel values in CMD_FIELDS order.

read_meta ¶

read_meta() -> tuple[int, int, int, float, float, float, float, int, float]

Read metadata from shared memory.

Returns:

tuple[int, int, int, float, float, float, float, int, float] –

A tuple containing (frame_counter, nz, nx, z_start_mm, z_end_mm, x_start_mm, x_end_mm, runtime_flags, ensemble_time_s).

read_pdi ¶

read_pdi(nz: int, nx: int) -> NDArray

Read raw power Doppler power from shared memory and log-compress it to dB.

MATLAB sends the raw (un-normalized) PDI power; this converts it to dB relative to the current frame's own peak (10 * log10(raw / raw.max())), matching the fixed PDI_CONTRAST_LIMITS colorbar.

Parameters:

nz ¶
(int) –

Number of rows (z-dimension).
nx ¶
(int) –

Number of columns (x-dimension).

Returns:

ndarray –

A (nz, nx) float32 array in dB, clipped to PDI_CONTRAST_LIMITS.

read_rf ¶

read_rf(nsamples: int, ncols: int) -> NDArray

Copy RF snapshot from shared memory as an int16 array.

Parameters:

nsamples ¶
(int) –

Number of samples (rows).
ncols ¶
(int) –

Number of channels/columns.

Returns:

ndarray –

A (nsamples, ncols) int16 array.

read_rf_header ¶

read_rf_header() -> tuple[int, int, int]

Read the RF segment header from shared memory.

Returns:

tuple[int, int, int] –

A tuple containing (rf_counter, nsamples, ncols).

read_stack_status ¶

read_stack_status() -> tuple[int, int, int, int, int, int]

Read z-stack status from shared memory.

Returns:

tuple[int, int, int, int, int, int] –

A tuple containing (stack_active, stack_error, status_code, current_slice, total_slices, target_position_um).

close_segments ¶

close_segments(*shms: SharedMemory, unlink: bool = True) -> None

Close and optionally unlink shared memory segments.

Parameters:

*shms ¶
(SharedMemory, default: () ) –

Variable number of shared memory segments to close.
unlink ¶
(bool, default: True ) –

Whether to unlink (remove) the segments after closing.

create_segments ¶

create_segments(names: dict[str, str] | None = None) -> tuple[SharedMemory, ...]

Create all shared-memory segments, replacing any stale ones.

Parameters:

names ¶
(dict[str, str], default: None ) –

Optional per-channel name overrides keyed like "meta" or "cmd".

Returns:

tuple[SharedMemory, ...] –

A tuple containing (shm_meta, shm_bmode, shm_pdi, shm_cmd, shm_rf, shm_stack, shm_ack).

resolve_segment_names ¶

resolve_segment_names(names: dict[str, str] | None = None) -> dict[str, str]

Return the effective shared-memory names for one acquisition session.

Parameters:

names ¶
(dict[str, str], default: None ) –

Optional per-channel name overrides keyed like "meta" or "cmd".

Returns:

dict[str, str] –

Complete logical-channel to shared-memory-name mapping.

`effusive.shared_memory`¶

shared_memory ¶

BMODE_CONTRAST_LIMITS `module-attribute` ¶

CMD_FIELDS `module-attribute` ¶

CMD_FIELD_INDEX `module-attribute` ¶

DEFAULT_SEGMENT_NAMES `module-attribute` ¶

META_FLAG_FREEZE_ACTIVE `module-attribute` ¶

META_FLAG_SAVE_ACTIVE `module-attribute` ¶

PDI_CONTRAST_LIMITS `module-attribute` ¶

ShmReader ¶

`names` ¶

close ¶

read_ack ¶

read_bmode ¶

`nz` ¶

`nx` ¶

read_cmd ¶

read_meta ¶

read_pdi ¶

`nz` ¶

`nx` ¶

read_rf ¶

`nsamples` ¶

`ncols` ¶

read_rf_header ¶

read_stack_status ¶

close_segments ¶

**`*shms`** ¶

`unlink` ¶

create_segments ¶

`names` ¶

resolve_segment_names ¶

`names` ¶

effusive.shared_memory¶

shared_memory ¶

BMODE_CONTRAST_LIMITS module-attribute ¶

CMD_FIELDS module-attribute ¶

CMD_FIELD_INDEX module-attribute ¶

DEFAULT_SEGMENT_NAMES module-attribute ¶

META_FLAG_FREEZE_ACTIVE module-attribute ¶

META_FLAG_SAVE_ACTIVE module-attribute ¶

PDI_CONTRAST_LIMITS module-attribute ¶

ShmReader ¶

names ¶

close ¶

read_ack ¶

read_bmode ¶

nz ¶

nx ¶

read_cmd ¶

read_meta ¶

read_pdi ¶

nz ¶

nx ¶

read_rf ¶

nsamples ¶

ncols ¶

read_rf_header ¶

read_stack_status ¶

close_segments ¶

*shms ¶

unlink ¶

create_segments ¶

names ¶

resolve_segment_names ¶

names ¶

`effusive.shared_memory`¶

BMODE_CONTRAST_LIMITS `module-attribute` ¶

CMD_FIELDS `module-attribute` ¶

CMD_FIELD_INDEX `module-attribute` ¶

DEFAULT_SEGMENT_NAMES `module-attribute` ¶

META_FLAG_FREEZE_ACTIVE `module-attribute` ¶

META_FLAG_SAVE_ACTIVE `module-attribute` ¶

PDI_CONTRAST_LIMITS `module-attribute` ¶

`names` ¶

`nz` ¶

`nx` ¶

`nz` ¶

`nx` ¶

`nsamples` ¶

`ncols` ¶

**`*shms`** ¶

`unlink` ¶

`names` ¶

`names` ¶