Custom Transducers¶

BabelBrain can load your own transducer designs alongside its built-in devices. You describe the transducer in a YAML file then BabelBrain:

• Validates file
• Generates necessary transducer files
• Runs a Rayleigh simulation in water so you can check the geometry and the beam before using it.

Workflow¶

1. In the file-selection dialog, choose the computing engine (local GPU or remote server). It is used for the Rayleigh simulations during creation.

2. In the Transducer drop-down, choose ➕ Add / remove custom transducer…   

3. The Manage Custom Transducers dialog lists the custom transducers already installed. From here you can:

   • Add… a new transducer (next step).
   • Remove the selected transducer. After confirmation its folder is deleted.
   • Move up / Move down to change the order in which custom transducers appear in the drop-down

   

4. In the Add Custom Transducer dialog, click Select Config file, choose your YAML file and click Create Transducer.

5. BabelBrain validates the file:
   • If there is a problem, an error dialog shows the offending YAML line and the reason. After you close it, the Add Custom Transducer dialog reopens with the same file selected, so you can fix the file and click Create Transducer again.
   • If a custom transducer with the same <ClassName> already exists, you are asked whether to overwrite it.

6. If the file has no PlanTUS tables, BabelBrain estimates them with Rayleigh simulations (see PlanTUS parameters). This can take a while for transducers with many frequencies or a wide steering range.

7. The verification window shows the transducer geometry (with the focal spot and the out-plane marked) next to the simulated water field. Click Continue to keep the transducer, or Cancel to discard it. If you were overwriting an existing transducer, cancelling restores the previous version.

   

The transducer then appears in the drop-down as Custom: <ClassName>, where <ClassName> is the PascalCase form of name (e.g. my-tx_500 → MyTx500). Its generated files are saved in ~/.config/BabelBrain/Transducers/babel_<ClassName>/. Do not edit these files by hand; change the YAML file and add the transducer again instead.

Units and conventions¶

PyYAML only reads scientific notation as a number if it has a decimal point and a signed exponent. Anything else is read as text and fails validation:

Plain decimals (0.064, 500000.0) are safest.

Templates¶

Ready-to-edit templates are available in custom_tx_templates/. Each is a valid file that reproduces a built-in device, with every parameter explained inline. Copy one, rename the transducer and replace the values.

Every file must contain a Template Version: <number> line (e.g. # Template Version: 1.0).

Common parameters¶

Type-specific parameters¶

Simple Focused¶

No extra parameters. There is no electronic steering, and the focal length and diameter shown in Step 2 are fixed to the values in the file.

Dead space is not supported for this type: Step 2 always places the out-plane at the rim, so its out-plane distance is focal_length − h. Leave distance_tx_bottom_to_outplane and distance_outplane_to_focus out of the file.

Transducer Diagram:

Example Transducer Yaml:

# Template Version: 1.0
name: MySingleTx
geometry_type: simple_focused
frequencies:
    - 500000
aperture_size: 0.050
focal_length: 0.050

Corresponding Plot:

Flat Annular Array¶

• There is no natural focus: focal_length and distance_outplane_to_focus are not used. The verification simulation focuses at the middle of steering.z.
• Automatic PlanTUS estimation is not available for this type; enter the PlanTUS tables yourself to use PlanTUS.

Transducer Diagram:

Example Transducer Yaml:

# Template Version: 1.0
name: MyFlatAnnular
geometry_type: flat_annular_array
frequencies:
    - 500000
aperture_size: 0.0336
num_elements: 2
annular:
    inner_ring_diameters: [0.0,     0.0240]
    outer_ring_diameters: [0.0233,  0.0336]
steering:
    z: [0.025, 0.095]

Corresponding Plot:

Focused Annular Array¶

Same parameters as flat_annular_array, with two differences:

• Ring diameters are measured in projection onto the x-y plane, not along the curved surface. focal_length must be ≥ half the largest outer diameter.
• steering.z is an offset from the natural focus; negative moves towards the transducer and abs(min) ≤ focal_length. The GUI's TPO range is focal_length + steering.z (30–82.5 mm below).

Transducer Diagram:

Example Transducer Yaml:

# Template Version: 1.0
name: MyFocusedAnnular
geometry_type: focused_annular_array
frequencies:
    - 500000
    - 545000
aperture_size: 0.064
focal_length: 0.06294
distance_outplane_to_focus: 0.05238
num_elements: 4
annular:
    inner_ring_diameters: [0.0,     0.0316988, 0.0442688, 0.0536688]
    outer_ring_diameters: [0.03114, 0.04371,   0.05311,   0.06083]
steering:
    z: [-0.03294, 0.01956]

Corresponding Plot:

Flat Array 2D¶

• Origin: the centre of the array, in the plane of the element faces.
• distance_tx_bottom_to_outplane is applied automatically to move the out-plane away from the element plane.
• There is no natural focus: focal_length and distance_outplane_to_focus are not used. The verification simulation focuses at the middle of steering.z.
• Keep the pitch close to one wavelength (3 mm at 500 kHz) to avoid grating lobes. The 4 × 4 example below only shows the format.

Transducer Diagram:

Example Transducer Yaml:

# Template Version: 1.0
name: MyFlatMatrix
geometry_type: flat_array_2D
frequencies:
    - 500000
aperture_size: 0.040
distance_tx_bottom_to_outplane: 0.0012
num_elements: 16
element_size: 0.0095
elements:   # 4 x 4 grid, 10 mm pitch, centred on the origin
    x: [-0.015, -0.005, 0.005, 0.015, -0.015, -0.005, 0.005, 0.015, -0.015, -0.005, 0.005, 0.015, -0.015, -0.005, 0.005, 0.015]
    y: [-0.015, -0.015, -0.015, -0.015, -0.005, -0.005, -0.005, -0.005, 0.005, 0.005, 0.005, 0.005, 0.015, 0.015, 0.015, 0.015]steering:
    x: [-0.020, 0.020]
    y: [-0.020, 0.020]
    z: [0.020, 0.090]

Corresponding Plot:

Focused Array¶

• Origin: the geometric focus. Elements lie on a sphere of radius focal_length and face the focus; the bowl apex is at (0, 0, focal_length), so element z values are positive.
• Steering uses a different frame: steering.x, .y, .z are offsets from the natural focus with +z pointing from the transducer towards the target, the opposite of the element +z. A negative steering.z moves the focus towards the transducer, as for focused_annular_array.
• Cartesian: x² + y² + z² = focal_length².
• Spherical: theta is the polar angle from the beam axis (0° = apex, increasing towards the rim); phi is the azimuth from +x towards +y. x = r·sin(theta)·cos(phi), y = r·sin(theta)·sin(phi), z = r·cos(theta).
• Only the direction of each position is used to place the element; its distance from the focus (including r) is not checked. Positions in mm or from the wrong origin give a wrong layout without an error, so check the verification window.
• distance_outplane_to_focus is the default Distance Cone to Focus in Step 2.

Transducer Diagram:

Example Transducer Yaml:

# Template Version: 1.0
name: MyFocusedArray
geometry_type: focused_array
frequencies:
    - 500000
aperture_size: 0.064
focal_length: 0.070
num_elements: 7
element_size: 0.015
element_coordinate_system: spherical
elements:   # centre element plus a ring of six at 20 degrees
    r:     [0.070, 0.070, 0.070, 0.070, 0.070, 0.070, 0.070]
    theta: [0.0,   20.0,  20.0,  20.0,  20.0,  20.0,  20.0]
    phi:   [0.0,   0.0,   60.0,  120.0, 180.0, 240.0, 300.0]
steering:
    x: [-0.010, 0.010]
    y: [-0.010, 0.010]
    z: [-0.015, 0.015]

The same elements in cartesian coordinates:

element_coordinate_system: cartesian
elements:
    x: [0.0,     0.02394, 0.01197, -0.01197, -0.02394, -0.01197,  0.01197]
    y: [0.0,     0.0,     0.02073,  0.02073,  0.0,     -0.02073, -0.02073]
    z: [0.070,   0.06578, 0.06578,  0.06578,  0.06578,  0.06578,  0.06578]

Corresponding Plot:

Optional parameters¶

PlanTUS¶

PlanTUS is optional and gives the PlanTUS integration focal distances and matching FHML (full-length at half maximum) values, in metres, for every frequency in frequencies. Both lists must be the same length and contain no negative values.

PlanTUS:
    500000:
        FocalDistanceList: [0.030, 0.035, 0.040, 0.045, 0.050]
        FHMLList:          [0.018, 0.030, 0.038, 0.050, 0.060]

If PlanTUS is omitted, BabelBrain estimates the tables with Rayleigh simulations in water for each frequency (except for flat_annular_array):

• Steerable types are swept in 2 mm steps over the steering.z range (as absolute depths for flat types, or focal_length + steering.z for focused types).
• simple_focused uses a single point at focal_length.