sonosk 0.1.0__py3-none-any.whl

sonosk/__init__.py

@@ -0,0 +1,32 @@
+"""SonoSK: simulation of medical ultrasound imaging and therapy.
+
+Modules
+-------
+grid        regular grids in 1, 2 and 3 dimensions
+transducer  single elements, annular, linear, phased, convex, matrix and
+            cylindrical sources
+field       CW pressure fields (Rayleigh integral, angular spectrum)
+medium      materials and property maps
+phantom     shapes, label maps and point scatterers
+imaging     pulse-echo simulation, beamforming and B-mode images
+thermal     heat source, Pennes bioheat equation, thermal dose, lesions
+stack       piezoelectric stack model (Mason) for probe design
+safety      acoustic output quantities and regulatory limits
+quality     resolution, contrast, CNR, gCNR and speckle measures
+analytic    closed-form reference fields
+water       properties of water
+plot        figures (needs matplotlib)
+"""
+
+__version__ = "0.1.0"
+
+from . import (analytic, field, imaging, medium, phantom, quality, safety, stack,
+               thermal, transducer, water)
+from .grid import Grid
+from .medium import Material, Medium
+
+__all__ = [
+    "Grid", "Material", "Medium",
+    "analytic", "field", "imaging", "medium", "phantom", "quality", "safety",
+    "stack", "thermal", "transducer", "water", "__version__",
+]

sonosk/analytic.py

@@ -0,0 +1,66 @@
+"""Closed-form on-axis pressure of circular sources in a lossless fluid.
+
+These solutions are used as references for the numerical field code.
+Results are pressure amplitudes normalised by p0 = rho c u0, where u0 is
+the normal velocity amplitude of the source surface.
+
+References
+----------
+Kinsler L.E., Frey A.R., Coppens A.B., Sanders J.V. Fundamentals of
+Acoustics, 4th ed. Wiley, 2000.
+
+O'Neil H.T. Theory of focusing radiators. J. Acoust. Soc. Am.
+21(5):516-526, 1949.
+"""
+
+import numpy as np
+
+
+def wavenumber(f, c=1500.0):
+    return 2.0 * np.pi * f / c
+
+
+def piston_axial(z, a, f, c=1500.0):
+    """Pressure amplitude p/p0 on the axis of a baffled flat piston.
+
+    z distance from the piston face [m], a piston radius [m],
+    f frequency [Hz], c sound speed [m/s].
+    """
+    z = np.asarray(z, dtype=float)
+    k = wavenumber(f, c)
+    return 2.0 * np.abs(np.sin(0.5 * k * (np.sqrt(z * z + a * a) - z)))
+
+
+def piston_last_maximum(a, f, c=1500.0):
+    """Position of the last on-axis maximum of a flat piston [m]."""
+    lam = c / f
+    return a * a / lam - lam / 4.0
+
+
+def bowl_depth(a, roc):
+    """Depth h of a spherical bowl of aperture radius a and curvature roc."""
+    if a > roc:
+        raise ValueError("aperture radius larger than radius of curvature")
+    return roc - np.sqrt(roc * roc - a * a)
+
+
+def focal_gain(a, roc, f, c=1500.0):
+    """Linear pressure gain k h at the geometric focus of a bowl."""
+    return wavenumber(f, c) * bowl_depth(a, roc)
+
+
+def bowl_axial(z, a, roc, f, c=1500.0):
+    """Pressure amplitude p/p0 on the axis of a focused bowl (O'Neil 1949).
+
+    z is measured from the apex of the bowl [m], a is the aperture radius
+    and roc the radius of curvature [m]. The geometric focus is at z = roc.
+    """
+    z = np.asarray(z, dtype=float)
+    k = wavenumber(f, c)
+    h = bowl_depth(a, roc)
+    r = np.sqrt((z - h) ** 2 + a * a)
+    q = 1.0 - z / roc
+    near = np.abs(q) < 1e-9
+    qs = np.where(near, 1.0, q)
+    p = np.abs(2.0 / qs * np.sin(0.5 * k * (r - z)))
+    return np.where(near, k * h, p)

sonosk/field.py

@@ -0,0 +1,140 @@
+"""Continuous-wave pressure fields.
+
+rayleigh() sums the Rayleigh integral over the patches of a transducer,
+
+    p(r) / p0 = (j k / 2 pi) sum_n w_n A_n exp(-(j k + a) R_n) / R_n,
+
+where p0 = rho c u0, w_n is the complex patch weight (apodization and
+delay), A_n the patch area, R_n the distance and a the amplitude
+attenuation of a homogeneous medium. For curved sources this is the usual
+approximation that treats each patch as part of a baffled plane.
+
+angular_spectrum() propagates a field given on a plane by the angular
+spectrum method.
+
+Time convention: exp(j omega t).
+
+References
+----------
+O'Neil H.T. Theory of focusing radiators. J. Acoust. Soc. Am.
+21(5):516-526, 1949.
+
+Zeng X., McGough R.J. Evaluation of the angular spectrum approach for
+simulations of near-field pressures. J. Acoust. Soc. Am. 123(1):68-76, 2008.
+"""
+
+import numpy as np
+
+from .medium import attenuation_np
+
+
+def rayleigh(transducer, points, f, c=1540.0, alpha0=0.0, y=1.0, max_pairs=4_000_000):
+    """Complex pressure p/p0 at points.
+
+    Parameters
+    ----------
+    transducer : Transducer
+    points : (M, 3) array
+        Field points [m].
+    f : float
+        Frequency [Hz].
+    c : float
+        Sound speed [m/s].
+    alpha0, y : float
+        Power-law attenuation of the medium, alpha0 in dB/(cm MHz^y).
+    max_pairs : int
+        Number of point-patch pairs handled at once; lower it if memory is short.
+    """
+    pts = np.asarray(points, dtype=float).reshape(-1, 3)
+    k = 2 * np.pi * f / c
+    a = float(attenuation_np(alpha0, f, y))
+    src = transducer.pos
+    w = transducer.weights(f) * transducer.area
+    g = 1j * k / (2 * np.pi)
+
+    out = np.empty(pts.shape[0], dtype=complex)
+    step = max(1, max_pairs // src.shape[0])
+    for i in range(0, pts.shape[0], step):
+        d = pts[i:i + step, None, :] - src[None, :, :]
+        r = np.sqrt(np.einsum("ijk,ijk->ij", d, d))
+        r = np.maximum(r, 1e-12)
+        out[i:i + step] = (np.exp(-(1j * k + a) * r) / r) @ w
+    return g * out
+
+
+def grid_points(grid, y=0.0):
+    """Field points for a grid: 1-D on the z axis, 2-D in the x-z plane at y,
+    3-D everywhere. Returns an (N, 3) array."""
+    if grid.ndim == 1:
+        z = grid.axis(0)
+        return np.stack([np.zeros_like(z), np.zeros_like(z), z], 1)
+    if grid.ndim == 2:
+        x, z = grid.mesh()
+        return np.stack([x.ravel(), np.full(x.size, y), z.ravel()], 1)
+    x, yy, z = grid.mesh()
+    return np.stack([x.ravel(), yy.ravel(), z.ravel()], 1)
+
+
+def rayleigh_grid(transducer, grid, f, c=1540.0, alpha0=0.0, y=1.0, plane_y=0.0, **kw):
+    """rayleigh() evaluated on a Grid; result has the grid shape."""
+    p = rayleigh(transducer, grid_points(grid, plane_y), f, c, alpha0, y, **kw)
+    return p.reshape(grid.shape)
+
+
+def angular_spectrum(p0, dx, f, z, c=1540.0, alpha0=0.0, y=1.0, pad=2):
+    """Propagate a complex field from the plane z = 0 to the depths z.
+
+    Parameters
+    ----------
+    p0 : 1-D or 2-D complex array
+        Field on a line (x) or a plane (x, y). A 1-D input is a field that
+        does not change along y, so the result is a 2-D (x, z) problem.
+    dx : float
+        Sample spacing of p0 [m], the same along both axes.
+    f : float
+        Frequency [Hz].
+    z : array
+        Depths [m], measured from the input plane.
+    pad : int
+        Zero padding factor against wrap-around.
+
+    Returns
+    -------
+    array of shape (len(z),) + p0.shape
+    """
+    p0 = np.asarray(p0, dtype=complex)
+    z = np.atleast_1d(np.asarray(z, dtype=float))
+    k = 2 * np.pi * f / c
+    a = float(attenuation_np(alpha0, f, y))
+
+    shape = tuple(pad * n for n in p0.shape)
+    axes = tuple(range(p0.ndim))
+    spec = np.fft.fftn(p0, shape, axes=axes)
+    ks = [2 * np.pi * np.fft.fftfreq(n, dx) for n in shape]
+    kk = np.meshgrid(*ks, indexing="ij")
+    kt2 = sum(q * q for q in kk)
+    kz = np.sqrt((k * k - kt2).astype(complex))
+    kz = np.where(kz.imag > 0, np.conj(kz), kz)    # evanescent waves decay
+
+    out = np.empty((z.size,) + p0.shape, dtype=complex)
+    sl = tuple(slice(0, n) for n in p0.shape)
+    for i, zi in enumerate(z):
+        q = np.fft.ifftn(spec * np.exp(-1j * kz * zi), axes=axes)
+        out[i] = q[sl] * np.exp(-a * zi)
+    return out
+
+
+def scale_to_pressure(p_rel, rho=1000.0, c=1540.0, u0=None, power=None, area=None):
+    """Convert p/p0 to pascals from the surface velocity u0 [m/s] or from the
+    radiated acoustic power [W] of a uniform plane source of given area [m^2]."""
+    if u0 is None:
+        if power is None or area is None:
+            raise ValueError("give u0, or power and area")
+        u0 = np.sqrt(2 * power / (rho * c * area))
+    return np.asarray(p_rel) * rho * c * u0
+
+
+def intensity(p, rho=1000.0, c=1540.0):
+    """Time-average intensity [W/m^2] of a CW pressure amplitude p [Pa]
+    in the plane-wave approximation."""
+    return np.abs(p) ** 2 / (2 * rho * c)

sonosk/grid.py

@@ -0,0 +1,82 @@
+"""Regular computational grids in 1, 2 and 3 dimensions.
+
+Units are SI (metres). The last axis is depth (z), so a 2-D grid is
+(x, z) and a 3-D grid is (x, y, z).
+"""
+
+import numpy as np
+
+
+class Grid:
+    """Regular grid.
+
+    Parameters
+    ----------
+    shape : int or tuple of int
+        Number of points along each axis.
+    spacing : float or sequence of float
+        Point spacing along each axis [m].
+    origin : float or sequence of float, optional
+        Coordinate of the first point on each axis [m]. Default 0.
+    """
+
+    def __init__(self, shape, spacing, origin=0.0):
+        shape = tuple(int(n) for n in np.atleast_1d(shape))
+        nd = len(shape)
+        if nd < 1 or nd > 3:
+            raise ValueError("grid must have 1, 2 or 3 dimensions")
+        if min(shape) < 1:
+            raise ValueError("shape must be positive")
+
+        spacing = np.broadcast_to(np.asarray(spacing, dtype=float), (nd,)).copy()
+        if np.any(spacing <= 0):
+            raise ValueError("spacing must be positive")
+        origin = np.broadcast_to(np.asarray(origin, dtype=float), (nd,)).copy()
+
+        self.shape = shape
+        self.spacing = spacing
+        self.origin = origin
+
+    @classmethod
+    def centered(cls, shape, spacing, depth_start=0.0):
+        """Grid centred on the depth axis; depth starts at depth_start."""
+        g = cls(shape, spacing)
+        n = np.array(g.shape)
+        origin = -0.5 * g.spacing * (n - 1)
+        origin[-1] = depth_start
+        g.origin = origin
+        return g
+
+    @property
+    def ndim(self):
+        return len(self.shape)
+
+    @property
+    def size(self):
+        return int(np.prod(self.shape))
+
+    @property
+    def extent(self):
+        """Length covered along each axis [m]."""
+        return self.spacing * (np.array(self.shape) - 1)
+
+    def axis(self, i):
+        return self.origin[i] + self.spacing[i] * np.arange(self.shape[i])
+
+    def axes(self):
+        return [self.axis(i) for i in range(self.ndim)]
+
+    def mesh(self):
+        return np.meshgrid(*self.axes(), indexing="ij")
+
+    def points(self):
+        """All grid points as an (N, ndim) array."""
+        return np.stack([m.ravel() for m in self.mesh()], axis=1)
+
+    def points_per_wavelength(self, c, f):
+        """Smallest number of points per wavelength for speed c and frequency f."""
+        return float(np.min(c) / f / self.spacing.max())
+
+    def __repr__(self):
+        sp = ", ".join(f"{s * 1e3:g}" for s in self.spacing)
+        return f"Grid(shape={self.shape}, spacing=({sp}) mm)"

sonosk/imaging.py

@@ -0,0 +1,279 @@
+"""Pulse-echo simulation and image formation.
+
+The forward model is linear (first-order Born scattering) in a homogeneous
+medium with sound speed c:
+
+- the transmit wave is described by a virtual source: a plane wave with a
+  steering angle, a diverging wave from a point behind the array, or a
+  wave focused on a point in front of it;
+- each receive element is a point receiver with the directivity of a
+  rectangular element in a soft baffle, sinc(w sin(theta) / lambda) cos(theta);
+- spreading is 1/R on the receive path and 1/R from a diverging source;
+  attenuation is applied at the centre frequency along both paths.
+
+The echo of every scatterer is a copy of the pulse delayed by its travel
+time. Signals are kept in analytic (complex) form, so the envelope is the
+modulus of the beamformed image.
+
+Beamforming is delay-and-sum with a receive f-number. Images from several
+transmits can be summed (coherent compounding).
+
+References
+----------
+Montaldo G., Tanter M., Bercoff J., Benech N., Fink M. Coherent plane-wave
+compounding for very high frame rate ultrasonography and transient
+elastography. IEEE Trans. Ultrason. Ferroelectr. Freq. Control
+56(3):489-506, 2009.
+
+Garcia D. SIMUS: an open-source simulator for medical ultrasound imaging.
+Part I: theory & examples. Comput. Methods Programs Biomed. 218:106726, 2022.
+"""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from .medium import attenuation_np
+
+
+@dataclass
+class Pulse:
+    """Gaussian-modulated pulse.
+
+    f0 centre frequency [Hz], bandwidth fractional -6 dB bandwidth of the
+    spectrum (0.6 means 60 %).
+    """
+
+    f0: float
+    bandwidth: float = 0.6
+
+    @property
+    def sigma(self):
+        # spectrum exp(-(2 pi df sigma)^2 / 2) is 0.5 at df = bandwidth f0 / 2
+        return np.sqrt(2 * np.log(2)) / (np.pi * self.bandwidth * self.f0)
+
+    @property
+    def duration(self):
+        """Support used for the simulation, 8 sigma [s]."""
+        return 8 * self.sigma
+
+    def analytic(self, t):
+        t = np.asarray(t, dtype=float)
+        return np.exp(-0.5 * (t / self.sigma) ** 2 + 2j * np.pi * self.f0 * t)
+
+    def __call__(self, t):
+        return self.analytic(t).real
+
+
+class Transmit:
+    """Transmit wave described by a virtual source.
+
+    Use the constructors plane(), diverging() and focused().
+    """
+
+    def __init__(self, kind, angle=0.0, source=None):
+        self.kind = kind
+        self.angle = float(angle)
+        self.source = None if source is None else np.asarray(source, dtype=float)
+
+    @classmethod
+    def plane(cls, angle=0.0):
+        """Plane wave with steering angle [rad] in the x-z plane."""
+        return cls("plane", angle=angle)
+
+    @classmethod
+    def diverging(cls, source):
+        """Diverging wave from a virtual point source behind the array (z < 0)."""
+        return cls("diverging", source=source)
+
+    @classmethod
+    def focused(cls, point):
+        """Wave focused on point (z > 0)."""
+        return cls("focused", source=point)
+
+    def element_delays(self, elements, c):
+        """Firing delays [s] of the elements, the first element at 0."""
+        e = np.asarray(elements, dtype=float)
+        if self.kind == "plane":
+            s = e @ self._dir()
+            return (s - s.min()) / c
+        d = np.linalg.norm(e - self.source, axis=1)
+        if self.kind == "diverging":
+            return (d - d.min()) / c
+        return (d.max() - d) / c
+
+    def _dir(self):
+        return np.array([np.sin(self.angle), 0.0, np.cos(self.angle)])
+
+    def travel(self, points, elements, c):
+        """Arrival time [s] of the transmit wave and its path length [m]
+        and amplitude at points, with time zero at the first firing."""
+        p = np.asarray(points, dtype=float).reshape(-1, 3)
+        e = np.asarray(elements, dtype=float)
+        if self.kind == "plane":
+            n = self._dir()
+            s0 = (e @ n).min()
+            path = p @ n - s0
+            # insonified strip: trace the point back to the array along n
+            x0 = p[:, 0] - p[:, 2] * np.tan(self.angle)
+            amp = ((x0 >= e[:, 0].min()) & (x0 <= e[:, 0].max())).astype(float)
+            return path / c, path, amp
+        d_e = np.linalg.norm(e - self.source, axis=1)
+        r = np.linalg.norm(p - self.source, axis=1)
+        if self.kind == "diverging":
+            path = r - d_e.min()
+            amp = d_e.min() / np.maximum(r, 1e-9)
+            return path / c, path, amp
+        beyond = p[:, 2] > self.source[2]
+        path = d_e.max() + np.where(beyond, r, -r)
+        amp = np.ones(p.shape[0])
+        return path / c, path, amp
+
+
+def _directivity(sin_t, cos_t, width, f0, c):
+    return np.sinc(width * sin_t * f0 / c) * cos_t
+
+
+def _element_frame(array):
+    e = array.centers
+    n = array.element_normals
+    return e, n
+
+
+def simulate(array, transmit, pos, amp, pulse, c=1540.0, fs=None, alpha0=0.0,
+             depth=None, oversample=4, element_chunk=16):
+    """Simulate the received signals of one transmit.
+
+    Every echo is placed as an impulse on a time axis oversample times
+    finer than fs, split between the two nearest samples, then convolved
+    with the pulse and decimated to fs.
+
+    Parameters
+    ----------
+    array : Transducer
+        Linear, phased, convex or matrix array.
+    transmit : Transmit
+    pos, amp : arrays
+        Scatterer positions (N, 3) [m] and amplitudes (N,).
+    pulse : Pulse
+        Two-way pulse (the electrical excitation convolved with both
+        transducer responses).
+    c : float
+        Sound speed [m/s].
+    fs : float, optional
+        Sampling frequency of the output [Hz], default 8 f0.
+    alpha0 : float
+        Attenuation in dB/(cm MHz), applied at f0.
+    depth : float, optional
+        Record at least down to this depth [m].
+    oversample : int
+        Ratio of the internal sampling rate to fs.
+
+    Returns
+    -------
+    rf : complex array (n_elements, n_samples)
+        Analytic received signals; rf.real is the RF signal.
+    fs : float
+    """
+    pos = np.asarray(pos, dtype=float).reshape(-1, 3)
+    amp = np.asarray(amp, dtype=float).ravel()
+    fs = 8 * pulse.f0 if fs is None else float(fs)
+    fh = fs * oversample
+    e, n = _element_frame(array)
+    a = float(attenuation_np(alpha0, pulse.f0, 1.0))
+
+    t_tx, path_tx, amp_tx = transmit.travel(pos, e, c)
+    em = e.mean(axis=0)
+    rmax = np.linalg.norm(pos - em, axis=1).max() + np.linalg.norm(e - em, axis=1).max()
+    t_end = t_tx.max() + rmax / c + pulse.duration
+    if depth is not None:
+        t_end = max(t_end, 2 * depth / c + pulse.duration)
+    ns = int(np.ceil(t_end * fs)) + 1
+    nh = ns * oversample
+
+    base = amp * amp_tx * np.exp(-a * path_tx)
+    imp = np.zeros((array.n_elements, nh))
+    for i0 in range(0, array.n_elements, element_chunk):
+        ee = e[i0:i0 + element_chunk]
+        nn = n[i0:i0 + element_chunk]
+        d = pos[None, :, :] - ee[:, None, :]
+        r = np.linalg.norm(d, axis=2)
+        cos_t = np.einsum("eij,ej->ei", d, nn) / r
+        sin_t = np.sqrt(np.clip(1 - cos_t ** 2, 0, 1))
+        g = base * _directivity(sin_t, cos_t, array.width, pulse.f0, c) * np.exp(-a * r) / r
+        g = np.where(cos_t > 0, g, 0.0)
+        s = (t_tx[None, :] + r / c) * fh
+        k0 = np.floor(s).astype(int)
+        fr = s - k0
+        for j in range(ee.shape[0]):
+            ok = (k0[j] >= 0) & (k0[j] < nh - 1)
+            k = k0[j][ok]
+            w = g[j][ok]
+            imp[i0 + j] = (np.bincount(k, w * (1 - fr[j][ok]), nh)
+                           + np.bincount(k + 1, w * fr[j][ok], nh))
+
+    half = int(np.ceil(0.5 * pulse.duration * fh))
+    kern = pulse.analytic(np.arange(-half, half + 1) / fh)
+    nfft = 1 << int(np.ceil(np.log2(nh + kern.size)))
+    spec = np.fft.fft(imp, nfft, axis=1) * np.fft.fft(kern, nfft)[None, :]
+    full = np.fft.ifft(spec, axis=1)[:, half:half + nh]
+    return full[:, ::oversample].copy(), fs
+
+
+def beamform(rf, fs, array, transmit, x, z, c=1540.0, f_number=1.5, window="hann", y=0.0):
+    """Delay-and-sum image on the grid x by z (2-D, at elevation y).
+
+    Returns the complex image of shape (len(z), len(x)); its modulus is the
+    envelope.
+    """
+    x = np.asarray(x, dtype=float)
+    z = np.asarray(z, dtype=float)
+    zz, xx = np.meshgrid(z, x, indexing="ij")
+    pts = np.stack([xx.ravel(), np.full(xx.size, y), zz.ravel()], 1)
+    e, n = _element_frame(array)
+    t_tx, _, _ = transmit.travel(pts, e, c)
+
+    img = np.zeros(pts.shape[0], dtype=complex)
+    ns = rf.shape[1]
+    for i in range(array.n_elements):
+        d = pts - e[i]
+        r = np.linalg.norm(d, axis=1)
+        ax = d @ n[i]
+        lat = np.sqrt(np.maximum(r * r - ax * ax, 0))
+        u = np.where(ax > 0, lat * f_number / np.maximum(ax, 1e-12), np.inf)
+        if window == "hann":
+            w = np.where(u <= 0.5, np.cos(np.pi * u) ** 2, 0.0)
+        else:
+            w = (u <= 0.5).astype(float)
+        if not w.any():
+            continue
+        s = (t_tx + r / c) * fs
+        k0 = np.floor(s).astype(int)
+        fr = s - k0
+        ok = (k0 >= 0) & (k0 < ns - 1) & (w > 0)
+        k = k0[ok]
+        v = rf[i, k] * (1 - fr[ok]) + rf[i, k + 1] * fr[ok]
+        img[ok] += w[ok] * v
+    return img.reshape(zz.shape)
+
+
+def compound(rfs, fs, array, transmits, x, z, c=1540.0, **kw):
+    """Sum of beamformed images over several transmits."""
+    out = 0
+    for rf, tx in zip(rfs, transmits):
+        out = out + beamform(rf, fs, array, tx, x, z, c, **kw)
+    return out
+
+
+def log_compress(image, dynamic_range=60.0):
+    """Envelope in dB relative to its maximum, clipped at -dynamic_range."""
+    env = np.abs(image)
+    db = 20 * np.log10(np.maximum(env / env.max(), 1e-12))
+    return np.maximum(db, -dynamic_range)
+
+
+def plane_wave_angles(n, span):
+    """n steering angles [rad] spread evenly over +-span/2."""
+    if n == 1:
+        return np.array([0.0])
+    return np.linspace(-span / 2, span / 2, n)