openlifu.xdc.transducer.Transducer

class openlifu.xdc.transducer.Transducer(id: "Annotated[str, OpenLIFUFieldData('Transducer ID', 'Unique identifier for transducer')]" = 'transducer', name: "Annotated[str, OpenLIFUFieldData('Transducer name', 'Human readable name for transducer')]" = '', elements: "Annotated[List[Element], OpenLIFUFieldData('Elements', 'Collection of transducer Elements')]" = <factory>, frequency: "Annotated[float, OpenLIFUFieldData('Frequency (Hz)', 'Nominal array frequency (Hz)')]" = 400600.0, units: "Annotated[str, OpenLIFUFieldData('Units', 'Native units of transducer local coordinate space')]" = 'm', attrs: "Annotated[Dict[str, Any], OpenLIFUFieldData('Attributes', 'Additional transducer attributes')]" = <factory>, registration_surface_filename: "Annotated[str | None, OpenLIFUFieldData('Registration surface filename', 'Relative path to an open surface of the transducer to be used for registration')]" = None, transducer_body_filename: "Annotated[str | None, OpenLIFUFieldData('Transducer body filename', 'Relative path to the closed surface mesh for visualizing the transducer body')]" = None, standoff_transform: 'Annotated[np.ndarray, OpenLIFUFieldData(\'Standoff transform\', \'Affine transform representing the way in which the standoff for this transducer displaces the transducer.\\n\\nA "standoff transform" applies a displacement in transducer space that moves a transducer to where it would\\nbe situated with the standoff in place. The idea is that if you start with a transform that places a transducer\\ndirectly against skin, then pre-composing that transform by a "standoff transform" serves to nudge the transducer\\nsuch that there is space for the standoff to be between it and the skin.\\n\\nSee also `openlifu.geo.create_standoff_transform`.\\n\\nThe units of this transform are assumed to be the native units of the transducer, the `Transducer.units` field.\')]' = <factory>, sensitivity: "Annotated[float | None, OpenLIFUFieldData('Sensitivity', 'Sensitivity of the element (Pa/V)')]" = None, crosstalk_frac: "Annotated[float, OpenLIFUFieldData('Crosstalk fraction', 'Fraction of the signal that leaks into other elements due to crosstalk')]" = 0.0, crosstalk_dist: "Annotated[float, OpenLIFUFieldData('Crosstalk distance', 'Distance within which elements experience crosstalk')]" = 0.0, impulse_response: "Annotated[np.ndarray | None, OpenLIFUFieldData('Impulse response', 'Impulse response of the element')]" = None, impulse_dt: "Annotated[float | None, OpenLIFUFieldData('Impulse response timestep', 'Impulse response timestep')]" = None, module_invert: "Annotated[List[bool], OpenLIFUFieldData('Invert polarity', 'Whether to invert the polarity of the transducer output, per module')]" = <factory>)

Bases: object

attrs: Annotated[Dict[str, Any], OpenLIFUFieldData(name='Attributes', description='Additional transducer attributes')]

Additional transducer attributes

convert_transform(matrix: ndarray, units: str) → ndarray

Given a transform matrix in some units, convert it to this transducer’s native units.

Parameters:

• matrix – 4x4 affine transform matrix

• units – units of the coordinate space on which the provided transform matrix operates

Returns: 4x4 affine transform matrix, now operating on a the transducer’s native coordinate space

(i.e. in the transducer’s native units)

crosstalk_dist: Annotated[float, OpenLIFUFieldData(name='Crosstalk distance', description='Distance within which elements experience crosstalk')] = 0.0

Distance within which elements experience crosstalk

crosstalk_frac: Annotated[float, OpenLIFUFieldData(name='Crosstalk fraction', description='Fraction of the signal that leaks into other elements due to crosstalk')] = 0.0

Fraction of the signal that leaks into other elements due to crosstalk

elements: Annotated[List[Element], OpenLIFUFieldData(name='Elements', description='Collection of transducer Elements')]

Collection of transducer Elements

frequency: Annotated[float, OpenLIFUFieldData(name='Frequency (Hz)', description='Nominal array frequency (Hz)')] = 400600.0

Nominal array frequency (Hz)

static from_json(json_string: str) → Transducer

Load a Transducer from a json string

static gen_matrix_array(nx=2, ny=2, pitch=1, kerf=0, units='mm', **kwargs)

Generate a 2D flat matrix array

Parameters:

• nx – number of elements in the x direction

• ny – number of elements in the y direction

• pitch – distance between element centers

• kerf – distance between element edges

• units – units of the array dimensions

• impulse_response – impulse response of the elements

• impulse_dt – time step of the impulse response

• id – unique identifier

• name – name of the array

• attrs – additional attributes

Returns: a Transducer object representing the array

get_effective_origin(apodizations: ndarray, units: str | None = None)

Get the centroid of the effective active region of the transducer based on apodizations.

Parameters:

• apodizations – vector of apodizations for the transducer elements

• units – units in which to describe the centroid. If not provided then transducer native units are used.

Returns: a 3-element array describing the centroid in the transducer coordinate system

get_polydata(transform: ndarray | None = None, units: str | None = None, facecolor=None)

Get a vtk polydata of the transducer. Optionally provide a transform, and units in which to interpret that transform. If a transform is provided with no units specified, it is assumed that the units are the same as those of the transducer itself. Optionally provide an RGBA color to set.

get_standoff_transform_in_units(units: str) → ndarray

Get the transducer’s standoff transform in the desired units.

id: Annotated[str, OpenLIFUFieldData(name='Transducer ID', description='Unique identifier for transducer')] = 'transducer'

Unique identifier for transducer

impulse_dt: Annotated[float | None, OpenLIFUFieldData(name='Impulse response timestep', description='Impulse response timestep')] = None

Impulse response timestep. If impulse_response is an array, this is the time step of the impulse response.

impulse_response: Annotated[ndarray | None, OpenLIFUFieldData(name='Impulse response', description='Impulse response of the element')] = None

Impulse response of the element, can be a single value or an array of values. If an array, impulse_dt must be set to the time step of the impulse response. Is convolved with the input signal.

module_invert: Annotated[List[bool], OpenLIFUFieldData(name='Invert polarity', description='Whether to invert the polarity of the transducer output, per module')]

Whether to invert the polarity of the transducer output

name: Annotated[str, OpenLIFUFieldData(name='Transducer name', description='Human readable name for transducer')] = ''

Human readable name for transducer

registration_surface_filename: Annotated[str | None, OpenLIFUFieldData(name='Registration surface filename', description='Relative path to an open surface of the transducer to be used for registration')] = None

Relative path to an open surface of the transducer to be used for registration

sensitivity: Annotated[float | None, OpenLIFUFieldData(name='Sensitivity', description='Sensitivity of the element (Pa/V)')] = None

Sensitivity of the element (Pa/V)

sort_by_index()

Sort the elements of the transducer by their element number.

sort_by_pin()

Sort the elements of the transducer by their pin number.

standoff_transform: Annotated[ndarray, OpenLIFUFieldData(name='Standoff transform', description='Affine transform representing the way in which the standoff for this transducer displaces the transducer.\n\nA "standoff transform" applies a displacement in transducer space that moves a transducer to where it would\nbe situated with the standoff in place. The idea is that if you start with a transform that places a transducer\ndirectly against skin, then pre-composing that transform by a "standoff transform" serves to nudge the transducer\nsuch that there is space for the standoff to be between it and the skin.\n\nSee also `openlifu.geo.create_standoff_transform`.\n\nThe units of this transform are assumed to be the native units of the transducer, the `Transducer.units` field.')]

Affine transform representing the way in which the standoff for this transducer displaces the transducer.

A “standoff transform” applies a displacement in transducer space that moves a transducer to where it would be situated with the standoff in place. The idea is that if you start with a transform that places a transducer directly against skin, then pre-composing that transform by a “standoff transform” serves to nudge the transducer such that there is space for the standoff to be between it and the skin.

See also openlifu.geo.create_standoff_transform.

The units of this transform are assumed to be the native units of the transducer, the Transducer.units field.

to_json(compact: bool = False) → str

Serialize a Transducer to a json string

Parameters:

compact – if enabled then the string is compact (not pretty). Disable for pretty.

Returns: A json string representing the complete Transducer object.

transducer_body_filename: Annotated[str | None, OpenLIFUFieldData(name='Transducer body filename', description='Relative path to the closed surface mesh for visualizing the transducer body')] = None

Relative path to the closed surface mesh for visualizing the transducer body

units: Annotated[str, OpenLIFUFieldData(name='Units', description='Native units of transducer local coordinate space')] = 'm'

Native units of transducer local coordinate space