sfs.util¶
Various utility functions.
Module Attributes
|
A tuple of audio data, sampling rate and start time. |
Functions
|
Make sure that the given argument can be used as a signal. |
|
Convert components to |
|
Squeeze the input and check if the result is one-dimensional. |
|
Convert to 2D array, turn column vector into row vector. |
|
Broadcast arguments to the same shape and then use |
|
Cartesian to spherical coordinate transform. |
|
Convert x to decibel. |
|
Compute normal vector from azimuth, colatitude. |
|
Image source method for a cuboid room. |
Maximum order of 2D/2.5D HOA. |
|
Maximum order of 3D HOA. |
|
|
Normalize sound field wrt position xnorm. |
Normalize a 1D vector. |
|
|
Determine the value at position x in the sound field p. |
|
Compute rotation matrix for rotation from n1 to n2. |
Select all secondary sources. |
|
|
Secondary source selection for a focused source. |
|
Secondary source selection for a line source. |
|
Secondary source selection for a plane wave. |
|
Secondary source selection for a point source. |
|
Spherical to cartesian coordinate transform. |
|
Spherical Hankel function of 2nd kind. |
|
Like |
|
Compute the wavenumber for a given radial frequency. |
|
Create a grid with given range and spacing. |
Classes
|
A tuple of audio data, sampling rate and start time. |
|
Triple (or pair) of components: x, y, and optionally z. |
- sfs.util.rotation_matrix(n1, n2)[source]¶
Compute rotation matrix for rotation from n1 to n2.
- Parameters
n1, n2 ((3,) array_like) – Two vectors. They don’t have to be normalized.
- Returns
(3, 3)
numpy.ndarray
– Rotation matrix.
- sfs.util.direction_vector(alpha, beta=1.5707963267948966)[source]¶
Compute normal vector from azimuth, colatitude.
- sfs.util.sph2cart(alpha, beta, r)[source]¶
Spherical to cartesian coordinate transform.
\[\begin{split}x = r \cos \alpha \sin \beta \\ y = r \sin \alpha \sin \beta \\ z = r \cos \beta\end{split}\]with \(\alpha \in [0, 2\pi), \beta \in [0, \pi], r \geq 0\)
- Parameters
alpha (float or array_like) – Azimuth angle in radiants
beta (float or array_like) – Colatitude angle in radiants (with 0 denoting North pole)
r (float or array_like) – Radius
- Returns
x (float or
numpy.ndarray
) – x-component of Cartesian coordinatesy (float or
numpy.ndarray
) – y-component of Cartesian coordinatesz (float or
numpy.ndarray
) – z-component of Cartesian coordinates
- sfs.util.cart2sph(x, y, z)[source]¶
Cartesian to spherical coordinate transform.
\[\begin{split}\alpha = \arctan \left( \frac{y}{x} \right) \\ \beta = \arccos \left( \frac{z}{r} \right) \\ r = \sqrt{x^2 + y^2 + z^2}\end{split}\]with \(\alpha \in [-pi, pi], \beta \in [0, \pi], r \geq 0\)
- Parameters
x (float or array_like) – x-component of Cartesian coordinates
y (float or array_like) – y-component of Cartesian coordinates
z (float or array_like) – z-component of Cartesian coordinates
- Returns
alpha (float or
numpy.ndarray
) – Azimuth angle in radiantsbeta (float or
numpy.ndarray
) – Colatitude angle in radiants (with 0 denoting North pole)r (float or
numpy.ndarray
) – Radius
- sfs.util.asarray_1d(a, **kwargs)[source]¶
Squeeze the input and check if the result is one-dimensional.
Returns a converted to a
numpy.ndarray
and stripped of all singleton dimensions. Scalars are “upgraded” to 1D arrays. The result must have exactly one dimension. If not, an error is raised.
- sfs.util.asarray_of_rows(a, **kwargs)[source]¶
Convert to 2D array, turn column vector into row vector.
Returns a converted to a
numpy.ndarray
and stripped of all singleton dimensions. If the result has exactly one dimension, it is re-shaped into a 2D row vector.
- sfs.util.as_xyz_components(components, **kwargs)[source]¶
Convert components to
XyzComponents
ofnumpy.ndarray
s.The components are first converted to NumPy arrays (using
numpy.asarray()
) which are then assembled into anXyzComponents
object.- Parameters
components (triple or pair of array_like) – The values to be used as X, Y and Z arrays. Z is optional.
**kwargs – All further arguments are forwarded to
numpy.asarray()
, which is applied to the elements of components.
- sfs.util.as_delayed_signal(arg, **kwargs)[source]¶
Make sure that the given argument can be used as a signal.
- Parameters
arg (sequence of 1 array_like followed by 1 or 2 scalars) – The first element is converted to a NumPy array, the second element is used as the sampling rate (in Hertz) and the optional third element is used as the starting time of the signal (in seconds). Default starting time is 0.
**kwargs – All keyword arguments are forwarded to
numpy.asarray()
.
- Returns
DelayedSignal
– A named tuple consisting of anumpy.ndarray
containing the audio data, followed by the sampling rate (in Hertz) and the starting time (in seconds) of the signal.
Examples
Typically, this is used together with tuple unpacking to assign the audio data, the sampling rate and the starting time to separate variables:
>>> import sfs >>> sig = [1], 44100 >>> data, fs, signal_offset = sfs.util.as_delayed_signal(sig) >>> data array([1]) >>> fs 44100 >>> signal_offset 0
- sfs.util.strict_arange(start, stop, step=1, *, endpoint=False, dtype=None, **kwargs)[source]¶
Like
numpy.arange()
, but compensating numeric errors.Unlike
numpy.arange()
, but similar tonumpy.linspace()
, providingendpoint=True
includes both endpoints.- Parameters
start, stop, step, dtype – See
numpy.arange()
.endpoint – See
numpy.linspace()
.Note
With
endpoint=True
, the difference between start and end value must be an integer multiple of the corresponding spacing value!**kwargs – All further arguments are forwarded to
numpy.isclose()
.
- Returns
numpy.ndarray
– Array of evenly spaced values. Seenumpy.arange()
.
- sfs.util.xyz_grid(x, y, z, *, spacing, endpoint=True, **kwargs)[source]¶
Create a grid with given range and spacing.
- Parameters
x, y, z (float or pair of float) – Inclusive range of the respective coordinate or a single value if only a slice along this dimension is needed.
spacing (float or triple of float) – Grid spacing. If a single value is specified, it is used for all dimensions, if multiple values are given, one value is used per dimension. If a dimension (x, y or z) has only a single value, the corresponding spacing is ignored.
endpoint (bool, optional) – If
True
(the default), the endpoint of each range is included in the grid. UseFalse
to get a result similar tonumpy.arange()
. Seestrict_arange()
.**kwargs – All further arguments are forwarded to
strict_arange()
.
- Returns
XyzComponents
– A grid that can be used for sound field calculations.
See also
- sfs.util.db(x, *, power=False)[source]¶
Convert x to decibel.
- Parameters
x (array_like) – Input data. Values of 0 lead to negative infinity.
power (bool, optional) – If
power=False
(the default), x is squared before conversion.
- class sfs.util.XyzComponents(components)[source]¶
Triple (or pair) of components: x, y, and optionally z.
Instances of this class can be used to store coordinate grids (either regular grids like in
xyz_grid()
or arbitrary point clouds) or vector fields (e.g. particle velocity).This class is a subclass of
numpy.ndarray
. It is one-dimensional (like a plainlist
) and has a length of 3 (or 2, if no z-component is available). It usesdtype=object
in order to be able to store othernumpy.ndarray
s of arbitrary shapes but also scalars, if needed. Because it is a NumPy array subclass, it can be used in operations with scalars and “normal” NumPy arrays, as long as they have a compatible shape. Like any NumPy array, instances of this class are iterable and can be used, e.g., in for-loops and tuple unpacking. If slicing or broadcasting leads to an incompatible shape, a plainnumpy.ndarray
withdtype=object
is returned.To make sure the components are NumPy arrays themselves, use
as_xyz_components()
.- Parameters
components ((3,) or (2,) array_like) – The values to be used as X, Y and Z data. Z is optional.
- property x¶
x-component.
- property y¶
y-component.
- property z¶
z-component (optional).
- apply(func, *args, **kwargs)[source]¶
Apply a function to each component.
The function func will be called once for each component, passing the current component as first argument. All further arguments are passed after that. The results are returned as a new
XyzComponents
object.
- class sfs.util.DelayedSignal(data, samplerate, time)¶
A tuple of audio data, sampling rate and start time.
This class (a
collections.namedtuple
) is not meant to be instantiated by users.To pass a signal to a function, just use a simple
tuple
orlist
containing the audio data and the sampling rate (in Hertz), with an optional starting time (in seconds) as a third item. If you want to ensure that a given variable contains a valid signal, usesfs.util.as_delayed_signal()
.- data¶
Alias for field number 0
- samplerate¶
Alias for field number 1
- time¶
Alias for field number 2
- sfs.util.image_sources_for_box(x, L, N, *, prune=True)[source]¶
Image source method for a cuboid room.
The classical method by Allen and Berkley [AB79].
- Parameters
x ((D,) array_like) – Original source location within box. Values between 0 and corresponding side length.
L ((D,) array_like) – side lengths of room.
N (int) – Maximum number of reflections per image source, see below.
prune (bool, optional) – selection of image sources:
If True (default): Returns all images reflected up to N times. This is the usual interpretation of N as “maximum order”.
If False: Returns reflected up to N times between individual wall pairs, a total number of \(M := (2N+1)^D\). This larger set is useful e.g. to select image sources based on distance to listener, as suggested by [Bor84].
- Returns
xs ((M, D)
numpy.ndarray
) – original & image source locations.wall_count ((M, 2D)
numpy.ndarray
) – number of reflections at individual walls for each source.
- sfs.util.spherical_hn2(n, z)[source]¶
Spherical Hankel function of 2nd kind.
Defined as https://dlmf.nist.gov/10.47.E6,
\[\hankel{2}{n}{z} = \sqrt{\frac{\pi}{2z}} \Hankel{2}{n + \frac{1}{2}}{z},\]where \(\Hankel{2}{n}{\cdot}\) is the Hankel function of the second kind and n-th order, and \(z\) its complex argument.
- Parameters
n (array_like) – Order of the spherical Hankel function (n >= 0).
z (array_like) – Argument of the spherical Hankel function.
- sfs.util.source_selection_plane(n0, n)[source]¶
Secondary source selection for a plane wave.
Eq.(13) from [SRA08]
- sfs.util.source_selection_point(n0, x0, xs)[source]¶
Secondary source selection for a point source.
Eq.(15) from [SRA08]
- sfs.util.source_selection_line(n0, x0, xs)[source]¶
Secondary source selection for a line source.
compare Eq.(15) from [SRA08]
- sfs.util.source_selection_focused(ns, x0, xs)[source]¶
Secondary source selection for a focused source.
Eq.(2.78) from [Wie14]
- sfs.util.max_order_circular_harmonics(N)[source]¶
Maximum order of 2D/2.5D HOA.
It returns the maximum order for which no spatial aliasing appears. It is given on page 132 of [Ahr12] as
\[\begin{split}\mathtt{max\_order} = \begin{cases} N/2 - 1 & \text{even}\;N \\ (N-1)/2 & \text{odd}\;N, \end{cases}\end{split}\]which is equivalent to
\[\mathtt{max\_order} = \big\lfloor \frac{N - 1}{2} \big\rfloor.\]- Parameters
N (int) – Number of secondary sources.