spharpy.spherical

Functions:

acn2nm(acn)	Calculate the spherical harmonic order n and degree m for a linear coefficient index, according to the Ambisonics Channel Convention [1]_.
aperture_vibrating_spherical_cap(n_max, ...)	Aperture function for a vibrating cap with radius \(r_c\) in a rigid sphere with radius \(r_s\) [5], [6]
modal_strength(n_max, kr[, arraytype])	Modal strenght function for microphone arrays.
nm2acn(n, m)	Calculate the linear index coefficient for a spherical harmonic order n and degree m, according to the Ambisonics Channel Convention [1]_.
radiation_from_sphere(n_max, rad_sphere, k, ...)	Radiation function in SH for a vibrating sphere including the radiation impedance and the propagation to a arbitrary distance from the sphere.
spherical_harmonic_basis(n_max, coords)	Calulcates the complex valued spherical harmonic basis matrix of order Nmax for a set of points given by their elevation and azimuth angles.
spherical_harmonic_basis_gradient(n_max, coords)	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.
spherical_harmonic_basis_gradient_real(...)	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.
spherical_harmonic_basis_real(n_max, coords)	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)

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)

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)

5. 7. 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')

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)

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)

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]

5. 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)

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]

5. 7. 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 (spharpy.samplings.Coordinates, pf.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)

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]

5. 7. 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 (spharpy.samplings.Coordinates, pf.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)

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 (spharpy.samplings.Coordinates, pf.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)

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 (spharpy.samplings.Coordinates, pf.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