Skip to main content

stl2bem

Computes the sound pressure on and around a rigid object from a closed STL mesh, with the boundary element method. It runs on a CPU or an NVIDIA GPU and writes tables over directions and frequencies, for example the response of every microphone on a device, as HDF5 or SOFA files.

stl2bem: an STL triangle mesh in, the sound pressure on its surface out

star, 4 kHz toy boat, 3 kHz mug, 2.5 kHz
star, 4 kHztoy boat, 3 kHzmug, 2.5 kHz
wine bottle, 144 Hz bell, 2.5 kHz elbow pipe, 1.4 kHz
wine bottle, 144 Hzbell, 2.5 kHzelbow pipe, 1.4 kHz

Plane waves passing six objects modeled in Fusion (3,800 to 12,000 triangles each): real part of the total pressure on a slice through each object, over one period. Surface pressure and cavity resonances of the same objects are in docs/validation.md.

Install

git clone https://github.com/Kwon-Junhyeong/stl2bem
cd stl2bem
pip install .                    # NumPy, SciPy, h5py (CPU)
pip install ".[prep,sofa]"       # optional: merging CAD parts, SOFA export
pip install cupy-cuda12x         # optional GPU backend; pick the CuPy package of your CUDA version

Quick start

stl2bem --stl device.stl --units mm --mics mics.csv --out out/ --dry_run   # check mesh, microphones, resources
stl2bem --stl device.stl --units mm --mics mics.csv --out out/             # 0-8 kHz, 1-degree direction grid
stl2bem --stl device.stl --units mm --mics mics.csv --out out/ --source_distance 0.5   # sources 0.5 m away

mics.csv has one x, y, z row per microphone, in the STL units; each microphone is moved to the closest point of the surface. Without --source_distance the sources are plane waves (far field). The dry run prints the distance 2D²/λ beyond which that holds for your body; closer sources need --source_distance. It also estimates the run time: the default grid of 65,160 directions takes minutes on a GPU but hours on a CPU, and --n_el 19 (10 degrees in elevation) makes a CPU run about eight times faster. stl2bem --help lists all options.

From Python:

import numpy as np
from stl2bem import build_mesh, surface_receivers, solve_table, spherical_doa_grid

mesh = build_mesh("device.stl", units="mm", recenter="none")
mics, weights, _ = surface_receivers(np.loadtxt("mics.csv", delimiter=",") / 1000, mesh)
doa, az, el = spherical_doa_grid(360, 19)                 # 1 deg azimuth, 10 deg elevation
freqs = np.linspace(0, 4000, 129)
solve_table(mesh.verts, mesh.tris, mesh.centroids, mesh.normals, mesh.areas, freqs, doa, "table.h5",
            receivers=mics, receiver_elements=weights)

The pressure on a plane through the body, as in the gallery:

from stl2bem.viz import plane_grid, field_on_points
pts, shape = plane_grid(center=(0, 0, 0), u=(1, 0, 0), v=(0, 0, 1), half=(0.2, 0.2), n=(241, 241))
field = field_on_points(mesh, 2000.0, doa=(1, 0, 0), points=pts).reshape(shape)   # NaN inside the body

The localization error that the body causes for a free-field SRP-PHAT:

from stl2bem.analysis import load_table, free_field, doa_error, summarize
body = load_table("table.h5", elevations=[0])
print(summarize(doa_error(body, free_field(body), band=(300, 3000), method="srp-phat", search="azimuth")))

Output

One HDF5 file per body:

dataset shape meaning
p (R, D, F) complex64 total pressure at receiver r for source d at frequency f, relative to the incident pressure at the origin
doa_grid (D, 3) unit vectors towards the sources; az x el grids are stored az-major (i_az * n_el + i_el)
source_positions (D, 3) point sources only: their positions (m)
freqs (F,) Hz
positions (R, 3) where p is evaluated (m, mesh frame); centroids is an older name for the same array
chief_points (N_c, 3) only when CHIEF is used: the interior points

Attributes hold the mesh report, the solver options and the convention. --sofa (or python -m stl2bem.sofa table.h5) also writes the table as a SOFA file (AES69, GeneralTF).

Convention. e^{+jωt}, incident wave exp(+jk d·r). For a source signal s(t) from direction d, the FFT/STFT bin (usual e^{-jωt} kernel) at microphone m is S(ω)·p[m, d, ω], so tables and FFT-domain signals combine directly without conjugation. The phase reference is the center of the bounding box (--recenter bbox); --recenter none keeps the CAD origin.

Accuracy

sphere field

Rigid sphere with 5,120 elements at ka = 3.7 against the exact solution: the median difference is 8.6 × 10⁻⁴ of the incident amplitude. The singular part of the integrals is evaluated exactly, and microphones on the surface are second-order accurate, also on edges and vertices.

cross-check

The six gallery meshes solved again with bempp-cl, which uses a different formulation (Burton-Miller, linear elements): the fields differ by 0.01-0.4 % (median) and the resonance frequencies by at most 0.5 %. One frequency with 6,840 directions takes 1 s for 4,800 elements and 11 s for 14,700 on an RTX 4060 Ti (8 GB).

Convergence, the comparison with the original code, resonances and timings: docs/validation.md. Equations and implementation: docs/method.md.

Preparing CAD

The solver needs one closed, consistently oriented surface. A single solid exported from CAD usually is one (all gallery models are); an assembly usually is not, because its parts overlap. stl2bem-prep merges the parts:

stl2bem-prep chassis.stl board.stl battery.stl --pitch 8 --units mm --out body.stl

It voxelizes the parts (pitch = element size), fills enclosed cavities and extracts a closed surface. Features smaller than the pitch disappear and thin plates become one pitch thick; --align_z keeps a flat microphone board flat. In Fusion, set the maximum edge length of the STL export to about λ/6 at the highest frequency; the mesh report prints the frequency limit from the mean edge length.

Limits

  • Rigid bodies in free space: no absorption, no vibrating surfaces, no floor or walls.
  • Dense matrices: for N elements the GPU needs about 2.5 GB + 20 bytes × N² (an 8 GB GPU handles about 15,000 elements) and the CPU about 1.5 GB + 55 bytes × N² of RAM; time grows with N³. The dry run prints both.
  • CHIEF points need room inside the body. Thin-walled objects (in the gallery, the bottle and the pipe) are solved with the CBIE alone, which is safe there: their irregular frequencies start near c / 2t for wall thickness t, far above the band the mesh resolves.
  • --formulation burton-miller is experimental: as accurate as the default away from resonances, but it damps sharp cavity resonances. See docs/method.md.

Used in

An earlier version of this solver computed the microphone responses of a robot body in:

License

MIT (see LICENSE).

Metadata

Release files for stl2bem 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for stl2bem 0.1.0
File Size Uploaded Provenance Actions
stl2bem-0.1.0.tar.gz 53.2 kB With provenance Details for stl2bem-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for stl2bem 0.1.0
File Interpreter ABI Platform Actions
stl2bem-0.1.0-py3-none-any.whl Python 3 none any Details for stl2bem-0.1.0-py3-none-any.whl

Total release size: 104.6 kB

Release files / stl2bem-0.1.0.tar.gz

Download URL stl2bem-0.1.0.tar.gz
Size 53.2 kB
Tags Source
SHA-256 checksum
How to use checksums
5176a726ee2111231fd0830a0c39500c9d8dccc9db50ec5f0a29a80a27ee9aea
BLAKE2b-256 checksum
How to use checksums
b104b7cf700c57bf4dc4261905ef90fb577628ea04505dcbc08d4afeb2fb36fc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / stl2bem-0.1.0-py3-none-any.whl

Download URL stl2bem-0.1.0-py3-none-any.whl
Size 51.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
93b2326a579eb6525ff644529c19affd99042aaecfac6e341cc7a0f5ecbec570
BLAKE2b-256 checksum
How to use checksums
1c87accd54240c08c24371ac2ea69aaebd9571b166927b6ee6ed13091a339643
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for stl2bem 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for stl2bem-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page