spharpy.spherical¶
Functions:
|
Calculate the spherical harmonic order n and degree m for a linear coefficient index, according to the Ambisonics Channel Convention [1]_. |
|
Aperture function for a vibrating cap with radius \(r_c\) in a rigid sphere with radius \(r_s\) 5, 6 |
|
Modal strenght function for microphone arrays. |
|
Calculate the linear index coefficient for a spherical harmonic order n and degree m, according to the Ambisonics Channel Convention [1]_. |
|
Radiation function in SH for a vibrating sphere including the radiation impedance and the propagation to a arbitrary distance from the sphere. |
|
Calulcates the complex valued spherical harmonic basis matrix of order Nmax for a set of points given by their elevation and azimuth angles. |
|
Calulcates the gradient on the unit sphere of the complex valued spherical harmonic basis matrix of order N for a set of points given by their elevation and azimuth angles. |
Calulcates the gradient on the unit sphere of the real valued spherical harmonic basis matrix of order N for a set of points given by their elevation and azimuth angles. |
|
|
Calulcates the real valued spherical harmonic basis matrix of order Nmax for a set of points given by their elevation and azimuth angles. |
- spharpy.spherical.acn2nm(acn)[source]¶
Calculate the spherical harmonic order n and degree m for a linear coefficient index, according to the Ambisonics Channel Convention [1]_.
\[ \begin{align}\begin{aligned}n = \lfloor \sqrt{acn + 1} \rfloor - 1\\m = acn - n^2 -n\end{aligned}\end{align} \]References
- 1
C. Nachbar, F. Zotter, E. Deleflie, and A. Sontacchi, “Ambix - A Suggested Ambisonics Format (revised by F. Zotter),” International Symposium on Ambisonics and Spherical Acoustics, vol. 3, pp. 1–11, 2011.
- Parameters
n (integer, ndarray) – Spherical harmonic order
m (integer, ndarray) – Spherical harmonic degree
- Returns
acn – Linear index
- Return type
integer, ndarray
- spharpy.spherical.aperture_vibrating_spherical_cap(n_max, rad_sphere, rad_cap)[source]¶
Aperture function for a vibrating cap with radius \(r_c\) in a rigid sphere with radius \(r_s\) 5, 6
\[a_n (r_{s}, \alpha) = 4 \pi \begin{cases} \displaystyle \left(2n+1\right)\left[ P_{n-1} \left(\cos\alpha\right) - P_{n+1} \left(\cos\alpha\right) \right], & {n>0} \newline \displaystyle (1 - \cos\alpha)/2, & {n=0} \end{cases}\]where \(\alpha = \arcsin \left(\frac{r_c}{r_s} \right)\) is the aperture angle.
- Parameters
n_max (integer, ndarray) – Maximal spherical harmonic order
r_sphere (double, ndarray) – Radius of the sphere
r_cap (double) – Radius of the vibrating cap
- Returns
A – Aperture function in diagonal matrix form with shape \([(n_{max}+1)^2~\times~(n_{max}+1)^2]\)
- Return type
double, ndarray
References
- 5(1,2,3,4)
Williams, Fourier Acoustics. Academic Press, 1999.
- 6(1,2,3)
B. Rafaely and D. Khaykin, “Optimal Model-Based Beamforming and Independent Steering for Spherical Loudspeaker Arrays,” IEEE Transactions on Audio, Speech, and Language Processing, vol. 19, no. 7, pp. 2234-2238, 2011
Notes
Eq. (3) in Ref. 6 contains an error, here, the power of 2 on pi is omitted on the normalization term.
- spharpy.spherical.modal_strength(n_max, kr, arraytype='rigid')[source]¶
Modal strenght function for microphone arrays.
\[b(kr) = \begin{cases} \displaystyle 4\pi i^n j_n(kr), & \text{open} \newline \displaystyle 4\pi i^{(n-1)} \frac{1}{(kr)^2 h_n^\prime(kr)}, & \text{rigid} \newline \displaystyle 4\pi i^n (j_n(kr) - i j_n^\prime(kr)), & \text{cardioid} \end{cases}\]Notes
This implementation uses the second order Hankel function, see 4 for an overview of the corresponding sign conventions.
References
- 4
V. Tourbabin and B. Rafaely, “On the Consistent Use of Space and Time Conventions in Array Processing,” vol. 101, pp. 470–473, 2015.
- Parameters
n (integer, ndarray) – Spherical harmonic order
kr (double, ndarray) – Wave number * radius
arraytype (string) – Array configuration. Can be a microphones mounted on a rigid sphere, on a virtual open sphere or cardioid microphones on an open sphere.
- Returns
B – Modal strength diagonal matrix
- Return type
double, ndarray
- spharpy.spherical.nm2acn(n, m)[source]¶
Calculate the linear index coefficient for a spherical harmonic order n and degree m, according to the Ambisonics Channel Convention [1]_.
\[acn = n^2 + n + m\]References
- 1
C. Nachbar, F. Zotter, E. Deleflie, and A. Sontacchi, “Ambix - A Suggested Ambisonics Format (revised by F. Zotter),” International Symposium on Ambisonics and Spherical Acoustics, vol. 3, pp. 1–11, 2011.
- Parameters
n (integer, ndarray) – Spherical harmonic order
m (integer, ndarray) – Spherical harmonic degree
- Returns
acn – Linear index
- Return type
integer, ndarray
- spharpy.spherical.radiation_from_sphere(n_max, rad_sphere, k, distance, density_medium=1.2, speed_of_sound=343.0)[source]¶
Radiation function in SH for a vibrating sphere including the radiation impedance and the propagation to a arbitrary distance from the sphere. The sign and phase conventions result in a positive pressure response for a positive cap velocity with the intensity vector pointing away from the source.
TODO: This function does not have a test yet.
References
- 7
Williams, Fourier Acoustics. Academic Press, 1999.
- 8
F. Zotter, A. Sontacchi, and R. Höldrich, “Modeling a spherical loudspeaker system as multipole source,” in Proceedings of the 33rd DAGA German Annual Conference on Acoustics, 2007, pp. 221-222.
- Parameters
n_max (integer, ndarray) – Maximal spherical harmonic order
r_sphere (double, ndarray) – Radius of the sphere
k (double, ndarray) – Wave number
distance (double) – Distance from the origin
density_medium (double) – Density of the medium surrounding the sphere. Default is 1.2 for air.
speed_of_sound (double) – Speed of sound in m/s
- Returns
R – Radiation function in diagonal matrix form with shape \([K \times (n_{max}+1)^2~\times~(n_{max}+1)^2]\)
- Return type
double, ndarray
- spharpy.spherical.spherical_harmonic_basis(n_max, coords)[source]¶
Calulcates the complex valued spherical harmonic basis matrix of order Nmax for a set of points given by their elevation and azimuth angles. The spherical harmonic functions are fully normalized (N3D) and include the Condon-Shotley phase term \((-1)^m\) [2]_, 3.
\[Y_n^m(\theta, \phi) = \sqrt{\frac{2n+1}{4\pi} \frac{(n-m)!}{(n+m)!}} P_n^m(\cos \theta) e^{i m \phi}\]References
- 2
Williams, Fourier Acoustics. Academic Press, 1999.
- 3
B. Rafaely, Fundamentals of Spherical Array Processing, vol. 8. Springer, 2015.
- Parameters
n_max (integer) – Spherical harmonic order
coordinates (Coordinates) – Coordinate object with sampling points for which the basis matrix is calculated
- Returns
Y – Complex spherical harmonic basis matrix
- Return type
double, ndarray, matrix
- spharpy.spherical.spherical_harmonic_basis_gradient(n_max, coords)[source]¶
Calulcates the gradient on the unit sphere of the complex valued spherical harmonic basis matrix of order N for a set of points given by their elevation and azimuth angles. The spherical harmonic functions are fully normalized (N3D) and include the Condon-Shotley phase term \((-1)^m\) [2]_. This implementation avoids singularities at the poles using identities derived in 5.
References
- 2
Williams, Fourier Acoustics. Academic Press, 1999.
- 9
J. Du, C. Chen, V. Lesur, and L. Wang, “Non-singular spherical harmonic expressions of geomagnetic vector and gradient tensor fields in the local north-oriented reference frame,” Geoscientific Model Development, vol. 8, no. 7, pp. 1979–1990, Jul. 2015.
- Parameters
n_max (integer) – Spherical harmonic order
coordinates (Coordinates) – Coordinate object with sampling points for which the basis matrix is calculated
- Returns
grad_elevation (double, ndarray, matrix) – Gradient with regard to the elevation angle.
grad_azimuth (double, ndarray, matrix) – Gradient with regard to the azimuth angle.
- spharpy.spherical.spherical_harmonic_basis_gradient_real(n_max, coords)[source]¶
Calulcates the gradient on the unit sphere of the real valued spherical harmonic basis matrix of order N for a set of points given by their elevation and azimuth angles. The spherical harmonic functions are fully normalized (N3D) and follow the AmbiX phase convention [1]_. This implementation avoids singularities at the poles using identities derived in 5.
References
- 1
C. Nachbar, F. Zotter, E. Deleflie, and A. Sontacchi, “Ambix - A Suggested Ambisonics Format (revised by F. Zotter),” International Symposium on Ambisonics and Spherical Acoustics, vol. 3, pp. 1–11, 2011.
- 9
J. Du, C. Chen, V. Lesur, and L. Wang, “Non-singular spherical harmonic expressions of geomagnetic vector and gradient tensor fields in the local north-oriented reference frame,” Geoscientific Model Development, vol. 8, no. 7, pp. 1979–1990, Jul. 2015.
- Parameters
n_max (integer) – Spherical harmonic order
coordinates (Coordinates) – Coordinate object with sampling points for which the basis matrix is calculated
- Returns
Y – Complex spherical harmonic basis matrix
- Return type
double, ndarray, matrix
- spharpy.spherical.spherical_harmonic_basis_real(n_max, coords)[source]¶
Calulcates the real valued spherical harmonic basis matrix of order Nmax for a set of points given by their elevation and azimuth angles. The spherical harmonic functions are fully normalized (N3D) and follow the AmbiX phase convention [1]_.
\[Y_n^m(\theta, \phi) = \sqrt{\frac{2n+1}{4\pi} \frac{(n-|m|)!}{(n+|m|)!}} P_n^{|m|}(\cos \theta) \begin{cases} \displaystyle \cos(|m|\phi), & \text{if $m \ge 0$} \newline \displaystyle \sin(|m|\phi) , & \text{if $m < 0$} \end{cases}\]References
- 1
C. Nachbar, F. Zotter, E. Deleflie, and A. Sontacchi, “Ambix - A Suggested Ambisonics Format (revised by F. Zotter),” International Symposium on Ambisonics and Spherical Acoustics, vol. 3, pp. 1–11, 2011.
- Parameters
n (integer) – Spherical harmonic order
coordinates (Coordinates) – Coordinate object with sampling points for which the basis matrix is calculated
- Returns
Y – Real valued spherical harmonic basis matrix
- Return type
double, ndarray, matrix