spharpy.samplings

Classes:

Coordinates([x, y, z])	Container class for coordinates in a three-dimensional space, allowing for compact representation and convenient conversion into spherical as well as geospatial coordinate systems.
SamplingSphere([x, y, z, n_max, weights])	Class for samplings on a sphere

Functions:

calculate_sampling_weights(sampling[, ...])	Calculate the sampling weights for numeric integration.
cart2latlon(x, y, z)	Transforms from Cartesian coordinates to Geocentric coordinates
cart2sph(x, y, z)	Transforms from Cartesian to spherical coordinates.
cube_equidistant(n_points)	Create a cuboid sampling with equidistant spacings in x, y, and z.
dodecahedron()	Generate a sampling based on the center points of the twelve dodecahedron faces.
eigenmike_em32()	Microphone positions of the Eigenmike em32 by mhacoustics according to the Eigenstudio user manual on the homepage [6].
equalarea(n_max[, condition_num, n_points])	Sampling based on partitioning into faces with equal area [9].
equiangular(n_max)	Generate an equiangular sampling of the sphere.
gaussian(n_max)	Generate sampling of the sphere based on the Gaussian quadrature.
hyperinterpolation(n_max)	Gives the points of a Hyperinterpolation sampling grid after Sloan and Womersley [1].
icosahedron()	Generate a sampling based on the center points of the twenty icosahedron faces.
icosahedron_ke4()	Microphone positions of the KE4 spherical microphone array.
interior_stabilization_points(kr_max[, ...])	Find points inside the interior domain of an open spherical microphone array that stabilize the array array response at the eigenfrequencies of the array.
latlon2cart(height, latitude, longitude)	Transforms from Geocentric coordinates to Cartesian coordinates
sph2cart(r, theta, phi)	Transforms from spherical to Cartesian coordinates.
spherical_t_design(n_max[, criterion])	Return the sampling positions for a spherical t-design [3] .
spherical_voronoi(sampling[, ...])	Calculate a Voronoi diagram on the sphere for the given samplings points.
spiral_points(n_max[, condition_num, n_points])	Sampling based on a spiral distribution of points on a sphere [10].

class spharpy.samplings.Coordinates(x=None, y=None, z=None)

Bases: object

Container class for coordinates in a three-dimensional space, allowing for compact representation and convenient conversion into spherical as well as geospatial coordinate systems. The constructor as well as the internal representation are only available in Cartesian coordinates. To create a Coordinates object from a set of points in spherical coordinates, please use the Coordinates.from_spherical() method.

Methods:

__init__([x, y, z])	Init coordinates container
find_nearest_point(point)	Find the closest Coordinate point to a given Point.
from_array(values[, coordinate_system])	Create a Coordinates class object from a set of points given as numpy array
from_cartesian(x, y, z)	Create a Coordinates class object from a set of points in the Cartesian coordinate system.
from_pyfar(coords)	Create a spharpy Coordinates object from pyfar Coordinates.
from_spherical(radius, elevation, azimuth)	Create a Coordinates class object from a set of points in the spherical coordinate system.
merge(other)	Merge another coordinates objects into this object.
to_pyfar()	Export to a pyfar Coordinates object.

Attributes:

azimuth	The azimuth angle for each point.
cartesian	Cartesian coordinates of all points.
elevation	The elevation angle for each point
latitude	The latitude angle as used in geospatial coordinates.
longitude	The longitude angle as used in geospatial coordinates.
n_points	Return number of points stored in the object
radius	The radius for each point.
spherical	Spherical coordinates of all points.
x	The x-axis coordinates for each point.
y	The y-axis coordinate for each point.
z	The z-axis coordinate for each point.

__init__(x=None, y=None, z=None)

Init coordinates container

Parameters:

• x (ndarray, double) – x-coordinate

• y (ndarray, double) – y-coordinate

• z (ndarray, double) – z-coordinate

property azimuth

The azimuth angle for each point.

property cartesian

Cartesian coordinates of all points.

property elevation

The elevation angle for each point

find_nearest_point(point)

Find the closest Coordinate point to a given Point. The search for the nearest point is performed using the scipy cKDTree implementation.

Parameters:

point (Coordinates) – Point to find nearest neighboring Coordinate

Returns:

• distance (ndarray, double) – Distance between the point and it’s closest neighbor

• index (int) – Index of the closest point.

classmethod from_array(values, coordinate_system='cartesian')

Create a Coordinates class object from a set of points given as numpy array

Parameters:

• values (double, ndarray) – Array with shape Nx3 where N is the number of points.

• coordinate_system (string) – Coordinate convention of the given values. Can be Cartesian or spherical coordinates.

classmethod from_cartesian(x, y, z)

Create a Coordinates class object from a set of points in the Cartesian coordinate system.

Parameters:

• x (ndarray, double) – x-coordinate

• y (ndarray, double) – y-coordinate

• z (ndarray, double) – z-coordinate

classmethod from_pyfar(coords)

Create a spharpy Coordinates object from pyfar Coordinates.

Parameters:

coords (pf.Coordinates) – A set of coordinates.

Returns:

The same set of coordinates.

Return type:

Coordinates

classmethod from_spherical(radius, elevation, azimuth)

Create a Coordinates class object from a set of points in the spherical coordinate system.

Parameters:

• radius (ndarray, double) – The radius for each point

• elevation (ndarray, double) – The elevation angle in radians

• azimuth (ndarray, double) – The azimuth angle in radians

property latitude

The latitude angle as used in geospatial coordinates.

property longitude

The longitude angle as used in geospatial coordinates.

merge(other)

Merge another coordinates objects into this object.

property n_points

Return number of points stored in the object

property radius

The radius for each point.

property spherical

Spherical coordinates of all points.

to_pyfar()

Export to a pyfar Coordinates object.

Returns:

The equivalent pyfar class object.

Return type:

pf.Coordinates

property x

The x-axis coordinates for each point.

property y

The y-axis coordinate for each point.

property z

The z-axis coordinate for each point.

class spharpy.samplings.SamplingSphere(x=None, y=None, z=None, n_max=None, weights=None)

Bases: Coordinates

Class for samplings on a sphere

Methods:

__init__([x, y, z, n_max, weights])	Init for sampling class
from_array(values[, n_max, weights, ...])	Create a Coordinates class object from a set of points given as numpy array
from_cartesian(x, y, z[, n_max, weights])	Create a Coordinates class object from a set of points in the Cartesian coordinate system.
from_coordinates(coords[, n_max, weights])	Generate a spherical sampling object from a coordinates object
from_pyfar(coords)	Create a spharpy SamplingSphere object from pyfar Coordinates.
from_spherical(radius, elevation, azimuth[, ...])	Create a Coordinates class object from a set of points in the spherical coordinate system.
to_pyfar()	Export to a pyfar Coordinates object.

Attributes:

n_max	Spherical harmonic order.
weights	Sampling weights for numeric integration.

__init__(x=None, y=None, z=None, n_max=None, weights=None)

Init for sampling class

classmethod from_array(values, n_max=None, weights=None, coordinate_system='cartesian')

Create a Coordinates class object from a set of points given as numpy array

Parameters:

• values (double, ndarray) – Array with shape Nx3 where N is the number of points.

• coordinate_system (string) – Coordinate convention of the given values. Can be Cartesian or spherical coordinates.

classmethod from_cartesian(x, y, z, n_max=None, weights=None)

Create a Coordinates class object from a set of points in the Cartesian coordinate system.

Parameters:

• x (ndarray, double) – x-coordinate

• y (ndarray, double) – y-coordinate

• z (ndarray, double) – z-coordinate

classmethod from_coordinates(coords, n_max=None, weights=None)

Generate a spherical sampling object from a coordinates object

Parameters:

coords (Coordinates) – Coordinate object

Returns:

sampling – Sampling on a sphere

Return type:

SamplingSphere

classmethod from_pyfar(coords)

Create a spharpy SamplingSphere object from pyfar Coordinates.

Parameters:

coords (pf.Coordinates) – A set of coordinates.

Returns:

The same set of coordinates.

Return type:

SamplingSphere

classmethod from_spherical(radius, elevation, azimuth, n_max=None, weights=None)

Create a Coordinates class object from a set of points in the spherical coordinate system.

Parameters:

• radius (ndarray, double) – The radius for each point

• elevation (ndarray, double) – The elevation angle in radians

• azimuth (ndarray, double) – The azimuth angle in radians

property n_max

Spherical harmonic order.

to_pyfar()

Export to a pyfar Coordinates object.

Returns:

The equivalent pyfar class object.

Return type:

pf.Coordinates

property weights

Sampling weights for numeric integration.

spharpy.samplings.calculate_sampling_weights(sampling, round_decimals=12)

Calculate the sampling weights for numeric integration.

Parameters:

• sampling (SamplingSphere) – Sampling points on a sphere

• round_decimals (int, optional) –

• apply (boolean, optional) – Whether or not to store the weights into the class object

Returns:

weigths – Sampling weights

Return type:

ndarray, float

spharpy.samplings.cart2latlon(x, y, z)

Transforms from Cartesian coordinates to Geocentric coordinates

\[ \begin{align}\begin{aligned}h = \sqrt{x^2 + y^2 + z^2},\\\theta = \pi/2 - \arccos(\frac{z}{r}),\\\phi = \arctan(\frac{y}{x})\\-\pi/2 < \theta < \pi/2,\\-\pi < \phi < \pi\end{aligned}\end{align} \]

where \(h\) is the heigth, \(\theta\) is the latitude angle and \(\phi\) is the longitude angle

Parameters:

• x (ndarray, number) – x-axis coordinates

• y (ndarray, number) – y-axis coordinates

• z (ndarray, number) – z-axis coordinates

Returns:

• height (ndarray, number) – The radius is rendered as height information

• latitude (ndarray, number) – Geocentric latitude angle

• longitude (ndarray, number) – Geocentric longitude angle

spharpy.samplings.cart2sph(x, y, z)

Transforms from Cartesian to spherical coordinates. Spherical coordinates follow the common convention in Physics/Mathematics Theta denotes the elevation angle with theta = 0 at the north pole and theta = pi at the south pole. Phi is the azimuth angle counting from phi = 0 at the x-axis in positive direction (counter clockwise rotation).

\[ \begin{align}\begin{aligned}r = \sqrt{x^2 + y^2 + z^2},\\\theta = \arccos(\frac{z}{r}),\\\phi = \arctan(\frac{y}{x})\\0 < \theta < \pi,\\0 < \phi < 2 \pi\end{aligned}\end{align} \]

Notes

To ensure proper handling of the radiant for the azimuth angle, the arctan2 implementatition from numpy is used here.

Parameters:

• x (ndarray, number) –

• y (ndarray, number) –

• z (ndarray, number) –

Returns:

• r (ndarray, number)

• theta (ndarray, number)

• phi (ndarray, number)

spharpy.samplings.cube_equidistant(n_points)

Create a cuboid sampling with equidistant spacings in x, y, and z. The cube will have dimensions 1 x 1 x 1

Parameters:

n_points (int, tuple) – Number of points in the sampling. If a single value is given, the number of sampling positions will be the same in every axis. If a tuple is given, the number of points will be set as (n_x, n_y, n_z)

Returns:

sampling – Sampling positions as Coordinate object

Return type:

Coordinates

spharpy.samplings.dodecahedron()

Generate a sampling based on the center points of the twelve dodecahedron faces.

Returns:

• rad (ndarray) – Radius of the sampling points

• theta (ndarray) – Elevation angle in the range [0, pi]

• phi (ndarray) – Azimuth angle in the range [0, 2 pi]

Returns:

sampling – SamplingSphere object containing all sampling points

Return type:

SamplingSphere

spharpy.samplings.eigenmike_em32()

Microphone positions of the Eigenmike em32 by mhacoustics according to the Eigenstudio user manual on the homepage [6].

References

[6] (1,2)

Eigenstudio User Manual, https://mhacoustics.com/download

Returns:

sampling – SamplingSphere object containing all sampling points

Return type:

SamplingSphere

spharpy.samplings.equalarea(n_max, condition_num=2.5, n_points=None)

Sampling based on partitioning into faces with equal area [9].

Parameters:

• n_max (int) – Spherical harmonic order

• condition_num (double) – Desired maximum condition number of the spherical harmonic basis matrix

• n_points (int, optional) – Number of points to start the condition number optimization. If set to None n_points will be (n_max+1)**2

Returns:

sampling – SamplingSphere object containing all sampling points

Return type:

SamplingSphere

References

[9] (1,2)

P. Leopardi, “A partition of the unit sphere into regions of equal area and small diameter,” Electronic Transactions on Numerical Analysis, vol. 25, no. 12, pp. 309–327, 2006.

spharpy.samplings.equiangular(n_max)

Generate an equiangular sampling of the sphere.

Paramters

n_maxinteger

Spherical harmonic order of the sampling

returns:

sampling – SamplingSphere object containing all sampling points

rtype:

SamplingSphere

spharpy.samplings.gaussian(n_max)

Generate sampling of the sphere based on the Gaussian quadrature.

Paramters

n_maxinteger

Spherical harmonic order of the sampling

returns:

sampling – SamplingSphere object containing all sampling points

rtype:

SamplingSphere

spharpy.samplings.hyperinterpolation(n_max)

Gives the points of a Hyperinterpolation sampling grid after Sloan and Womersley [1].

Notes

This implementation uses precalculated sets of points which are downloaded from Womersley’s homepage [2].

References

[1] (1,2)

I. H. Sloan and R. S. Womersley, “Extremal Systems of Points and Numerical Integration on the Sphere,” Advances in Computational Mathematics, vol. 21, no. 1/2, pp. 107–125, 2004.

[2]

http://web.maths.unsw.edu.au/~rsw/Sphere/Extremal/New/index.html

Parameters:

n_max (integer) – Spherical harmonic order of the sampling

Returns:

sampling – SamplingSphere object containing all sampling points

Return type:

SamplingSphere

spharpy.samplings.icosahedron()

Generate a sampling based on the center points of the twenty icosahedron faces.

Returns:

sampling – SamplingSphere object containing all sampling points

Return type:

SamplingSphere

spharpy.samplings.icosahedron_ke4()

Microphone positions of the KE4 spherical microphone array. The microphone marked as “1” defines the positive x-axis.

Returns:

sampling – SamplingSphere object containing all sampling points

Return type:

SamplingSphere

spharpy.samplings.interior_stabilization_points(kr_max, resolution_factor=1)

Find points inside the interior domain of an open spherical microphone array that stabilize the array array response at the eigenfrequencies of the array. The algorithm is based on [7] and implemented following the Matlab code provided by Gilles Chardon on his homepage at [8]. The stabilization points are independent of the sampling of the sphere and can therefore be combined with arbitrary spherical samplings.

Parameters:

• kr_max (float) – The maximum kr value to be considered. This will define the upper frequency limit of the array.

• resolution_factor (int) – Factor to increase the spatial resolution of the grid used to estimate the stabilization points.

Returns:

sampling_interior – Coordinates of the stabilization points

Return type:

Coordinates

References

[7]

G. Chardon, W. Kreuzer, und M. Noisternig, “Design of spatial microphone arrays for sound field interpolation”, IEEE Journal of Selected Topics in Signal Processing

[8]

https://gilleschardon.fr/jstsp_array/

spharpy.samplings.latlon2cart(height, latitude, longitude)

Transforms from Geocentric coordinates to Cartesian coordinates

\[ \begin{align}\begin{aligned}x = h \cos(\theta) \cos(\phi),\\y = h \cos(\theta) \sin(\phi),\\z = h \sin(\theta)\\-\pi/2 < \theta < \pi/2,\\-\pi < \phi < \pi\end{aligned}\end{align} \]

where \(h\) is the heigth, \(\theta\) is the latitude angle and \(\phi\) is the longitude angle

Parameters:

• height (ndarray, number) – The radius is rendered as height information

• latitude (ndarray, number) – Geocentric latitude angle

• longitude (ndarray, number) – Geocentric longitude angle

Returns:

• x (ndarray, number) – x-axis coordinates

• y (ndarray, number) – y-axis coordinates

• z (ndarray, number) – z-axis coordinates

spharpy.samplings.sph2cart(r, theta, phi)

Transforms from spherical to Cartesian coordinates. Spherical coordinates follow the common convention in Physics/Mathematics Theta denotes the elevation angle with theta = 0 at the north pole and theta = pi at the south pole. Phi is the azimuth angle counting from phi = 0 at the x-axis in positive direction (counter clockwise rotation).

\[ \begin{align}\begin{aligned}x = r \sin(\theta) \cos(\phi),\\y = r \sin(\theta) \sin(\phi),\\z = r \cos(\theta)\end{aligned}\end{align} \]

Parameters:

• r (ndarray, number) –

• theta (ndarray, number) –

• phi (ndarray, number) –

Returns:

• x (ndarray, number)

• y (ndarray, number)

• z (ndarray, number)

spharpy.samplings.spherical_t_design(n_max, criterion='const_energy')

Return the sampling positions for a spherical t-design [3] . For a spherical harmonic order N, a t-Design of degree :math: t=2N for constant energy or :math: t=2N+1 additionally ensuring a constant angular spread of energy is required [4]. For a given degree t

\[L = \lceil \frac{(t+1)^2}{2} \rceil+1,\]

points will be generated, except for t = 3, 5, 7, 9, 11, 13, and 15. T-designs allow for a inverse spherical harmonic transform matrix calculated as :math: D = frac{4pi}{L} mathbf{Y}^mathrm{H}.

Parameters:

• degree (integer) – T-design degree

• criterion ('const_energy', 'const_angular_spread') – Design criterion ensuring only a constant energy or additionally constant angular spread of energy

Returns:

sampling – SamplingSphere object containing all sampling points

Return type:

SamplingSphere

Notes

This function downloads a pre-calculated set of points from Rob Womersley’s homepage [5] .

References

[3] (1,2)

C. An, X. Chen, I. H. Sloan, and R. S. Womersley, “Well Conditioned Spherical Designs for Integration and Interpolation on the Two-Sphere,” SIAM Journal on Numerical Analysis, vol. 48, no. 6, pp. 2135–2157, Jan. 2010.

[4]

F. Zotter, M. Frank, and A. Sontacchi, “The Virtual T-Design Ambisonics-Rig Using VBAP,” in Proceedings on the Congress on Sound and Vibration, 2010.

[5]

http://web.maths.unsw.edu.au/~rsw/Sphere/EffSphDes/sf.html

spharpy.samplings.spherical_voronoi(sampling, round_decimals=13, center=0.0)

Calculate a Voronoi diagram on the sphere for the given samplings points.

Parameters:

• sampling (SamplingSphere) – Sampling points on a sphere

• round_decimals (int) – Number of decimals to be rounded to.

• center (double) – Center point of the voronoi diagram.

Returns:

voronoi – Spherical voronoi diagram as implemented in scipy.

Return type:

SphericalVoronoi

spharpy.samplings.spiral_points(n_max, condition_num=2.5, n_points=None)

Sampling based on a spiral distribution of points on a sphere [10].

Parameters:

• n_max (int) – Spherical harmonic order

• condition_num (double) – Desired maximum condition number of the spherical harmonic basis matrix

• n_points (int, optional) – Number of points to start the condition number optimization. If set to None n_points will be (n_max+1)**2

Returns:

sampling – SamplingSphere object containing all sampling points

Return type:

SamplingSphere

References

[10] (1,2)

E. a. Rakhmanov, E. B. Saff, and Y. M. Zhou, “Minimal Discrete Energy on the Sphere,” Mathematical Research Letters, vol. 1, no. 6, pp. 647–662, 1994.