spharpy.samplings

Spherical samplings.

Functions:

calculate_sampling_weights(sampling[, ...])	Calculate the sampling weights for numeric integration.
dodecahedron([radius])	Generate a sampling based on the center points of the twelve dodecahedron faces.
eigenmike_em32()	Microphone positions of the Eigenmike em32 by mhacoustics.
eigenmike_em64()	Microphone positions of the Eigenmike em64 by mhacoustics.
equal_angle(delta_angles[, radius])	Generate sampling of the sphere with equally spaced angles.
equal_area(n_max[, condition_num, n_points])	Sampling based on partitioning into faces with equal area.
equiangular([n_max, n_points, radius])	Generate an equiangular sampling of the sphere.
equidistant_cuboid(n_points[, flatten_output])	Create a cubic sampling with equidistant spacings in x, y, and z.
fliege(n_max[, radius])	Return Fliege-Maier spherical sampling grid.
gaussian(n_max[, radius])	Generate sampling of the sphere based on the Gaussian quadrature.
great_circle([elevation, gcd, radius, ...])	Spherical sampling grid according to the great circle distance criterion.
hyperinterpolation(n_max[, radius])	Return a Hyperinterpolation sampling grid.
icosahedron([radius])	Generate a sampling from the center points of the twenty icosahedron faces.
icosahedron_ke4()	Microphone positions of IHTA's KE4 spherical microphone array.
interior_stabilization_points(kr_max[, ...])	Find stabilization points inside for an open spherical microphone array.
lebedev([n_max, radius])	Return Lebedev spherical sampling grid.
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.
t_design(n_max[, criterion, radius])	Return spherical t-design sampling grid.

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) – Decimal precision used for sampling.radius. All radii must be identical to compute the sampling weights. This can be used to ignore numerical noise on the radii. The default is 12.

Returns:

weigths – Sampling weights

Return type:

ndarray, float

spharpy.samplings.dodecahedron(radius=1.0)

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

Parameters:

radius (number, optional) – Radius of the sampling grid. The default is 1.

Returns:

sampling – Sampling positions. Sampling weights can be obtained from calculate_sampling_weights.

Return type:

spharpy.SamplingSphere

Examples

>>> import spharpy
>>> coords = spharpy.samplings.dodecahedron()
>>> spharpy.plot.scatter(coords)

(Source code, png, hires.png, pdf)

spharpy.samplings.eigenmike_em32()

Microphone positions of the Eigenmike em32 by mhacoustics.

The data are according to the Eigenstudio user manual on the homepage [1].

Returns:

sampling – SamplingSphere object containing all sampling points

Return type:

spharpy.SamplingSphere

References

[1]

Eigenstudio User Manual, https://eigenmike.com/sites/default/files/documentation-2023-10/EigenStudio%20User%20Manual%20R02D.pdf

Examples

>>> import spharpy
>>> coords = spharpy.samplings.eigenmike_em32()
>>> spharpy.plot.scatter(coords)

(Source code, png, hires.png, pdf)

spharpy.samplings.eigenmike_em64()

Microphone positions of the Eigenmike em64 by mhacoustics.

The data are according to the Eigenmike user manual on the homepage [2].

Returns:

sampling – SamplingSphere object containing all sampling points

Return type:

SamplingSphere

References

[2]

Eigenmike em64 Getting Started Guide, https://eigenmike.com/sites/default/files/documentation-2024-09/getting%20started%20Guide%20to%20em64%20and%20ES3%20R01H.pdf

Examples

>>> import spharpy
>>> coords = spharpy.samplings.eigenmike_em64()
>>> spharpy.plot.scatter(coords)

(Source code, png, hires.png, pdf)

spharpy.samplings.equal_angle(delta_angles, radius=1.0)

Generate sampling of the sphere with equally spaced angles.

This sampling contain points at the North and South Pole. See equiangular, gaussian, and great_circle for samplings that do not contain points at the poles.

Parameters:

• delta_angles (tuple, number) – Tuple that gives the angular spacing in azimuth and colatitude in degrees. If a number is provided, the same spacing is applied in both dimensions.

• radius (number, optional) – Radius of the sampling grid. The default is 1.

Returns:

sampling – Sampling positions. Sampling weights can be obtained from calculate_sampling_weights.

Return type:

pyfar.Coordinates

Examples

>>> import spharpy
>>> coords = spharpy.samplings.equal_angle(delta_angles=45)
>>> spharpy.plot.scatter(coords)

(Source code, png, hires.png, pdf)

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

Sampling based on partitioning into faces with equal area.

The implementation is based on [3] and Leopardi’s MATLAB implementation.

Parameters:

• n_max (int) – Spherical harmonic order

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

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

Returns:

sampling – SamplingSphere object containing all sampling points

Return type:

spharpy.SamplingSphere

References

[3]

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.

Examples

>>> import spharpy
>>> coords = spharpy.samplings.equal_area(n_max=3)
>>> spharpy.plot.scatter(coords)

(Source code, png, hires.png, pdf)

spharpy.samplings.equiangular(n_max=None, n_points=None, radius=1.0)

Generate an equiangular sampling of the sphere.

For detailed information, see [4], Chapter 3.2. This is a quadrature sampling with the sum of the sampling weights in sampling.weights being \(4\pi\) if the number of rings is even and the number of points in azimuth and elevation are equal. This condition is always fulfilled if the number of points is chosen through n_max. This sampling does not contain points at the North and South Pole and is typically used for spherical harmonics processing. See equal_angle and great_circle for samplings containing points at the poles.

Parameters:

• n_max (int) – Maximum applicable spherical harmonic order. If this is provided, ‘n_points’ is set to 2 * n_max + 1. Either n_points or n_max must be provided. The default is None.

• n_points (int, tuple of two ints) – Number of sampling points in azimuth and elevation. Either n_points or n_max must be provided. The default is None.

• radius (number, optional) – Radius of the sampling grid. The default is 1.

Returns:

sampling – Sampling positions including sampling weights.

Return type:

spharpy.SamplingSphere

References

[4]

B. Rafaely, Fundamentals of spherical array processing, 1st ed. Berlin, Heidelberg, Germany: Springer, 2015.

Examples

>>> import spharpy
>>> coords = spharpy.samplings.equiangular(n_max=3)
>>> spharpy.plot.scatter(coords)

(Source code, png, hires.png, pdf)

spharpy.samplings.equidistant_cuboid(n_points, flatten_output=True)

Create a cubic sampling with equidistant spacings in x, y, and z.

The cuboid spans from -1 m to 1 m along each axis and is centered at the origin.

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

• flatten_output (bool, optional) – Whether to flatten the output Coordinates object or not. The default is False.

Returns:

sampling – Sampling positions as Coordinate object with cshape (n_x, n_y, n_z) if flatten_output is False, otherwise with cshape (n_x*n_y*n_z, ). Does not contain sampling weights.

Return type:

pyfar.Coordinates

Examples

>>> import spharpy
>>> coords = spharpy.samplings.equidistant_cuboid(3)
>>> spharpy.plot.scatter(coords)

(Source code, png, hires.png, pdf)

spharpy.samplings.fliege(n_max, radius=1.0)

Return Fliege-Maier spherical sampling grid.

For detailed information, see [5].

Note

This is intended to be a quadrature sampling with positive sampling weights summing to \(4\pi\). For unknown reasons, this is not the case for orders 10, 12, 18, 20, 24, 26, 27, and 29. For this reason, the respective weights are not returned regardless of the order.

Parameters:

• n_max (int) – Maximum applicable spherical harmonic order. It must be between 1 and 29.

• radius (number, optional) – Radius of the sampling grid in meters. The default is 1.

Returns:

sampling – (n_max + 1)**2 sampling positions without sampling weights (see note above).

Return type:

spharpy.SamplingSphere

Notes

This implementation uses pre-calculated points from the SOFiA toolbox [6].

References

[5]

J. Fliege and U. Maier, “The distribution of points on the sphere and corresponding cubature formulae,” IMA J. Numerical Analysis, Vol. 19, pp. 317-334, Apr. 1999, doi: 10.1093/imanum/19.2.317.

[6]

https://audiogroup.web.th-koeln.de/SOFiA_wiki/DOWNLOAD.html

Examples

>>> import spharpy
>>> coords = spharpy.samplings.fliege(n_max=3)
>>> spharpy.plot.scatter(coords)

(Source code, png, hires.png, pdf)

spharpy.samplings.gaussian(n_max, radius=1.0)

Generate sampling of the sphere based on the Gaussian quadrature.

For detailed information, see [7] (Section 3.3). This is a quadrature sampling with the sum of the sampling weights in sampling.weights being \(4\pi\). This sampling does not contain points at the North and South Pole and is typically used for spherical harmonics processing. See equal_angle and great_circle for samplings containing points at the poles.

Parameters:

• n_max (int) – Maximum applicable spherical harmonic order. Results in 2 * (n_max + 1) in azimuth and n_max + 1 points in elevation.

• radius (number, optional) – Radius of the sampling grid in meters. The default is 1.

Returns:

sampling – Sampling positions including sampling weights.

Return type:

spharpy.SamplingSphere

References

[7]

B. Rafaely, Fundamentals of spherical array processing, 1st ed. Berlin, Heidelberg, Germany: Springer, 2015.

Examples

>>> import spharpy
>>> coords = spharpy.samplings.gaussian(n_max=3)
>>> spharpy.plot.scatter(coords)

(Source code, png, hires.png, pdf)

spharpy.samplings.great_circle(elevation=array([-90., -80., -70., -60., -50., -40., -30., -20., -10., 0., 10., 20., 30., 40., 50., 60., 70., 80., 90.]), gcd=10, radius=1, azimuth_res=1, match=360)

Spherical sampling grid according to the great circle distance criterion.

Sampling grid where neighboring points of the same elevation have approx. the same great circle distance across elevations [8].

Parameters:

• elevation (array like, optional) – Contains the elevation from wich the sampling grid is generated, with \(-90^\circ\leq elevation \leq 90^\circ\) (\(90^\circ\): North Pole, \(-90^\circ\): South Pole). The default is np.linspace(-90, 90, 19).

• gcd (number, optional) – Desired great circle distance (GCD). Note that the actual GCD of the sampling grid is equal or smaller then the desired GCD and that the GCD may vary across elevations. The default is 10.

• radius (number, optional) – Radius of the sampling grid in meters. The default is 1.

• azimuth_res (number, optional) – Minimum resolution of the azimuth angle in degree. The default is 1.

• match (number, optional) – Forces azimuth entries to appear with a period of match degrees. E.g., if match=90, the grid includes the azimuth angles 0, 90, 180, and 270 degrees. The default is 360.

Returns:

sampling – Sampling positions. Sampling weights can be obtained from calculate_sampling_weights.

Return type:

pyfar.Coordinates

References

[8]

B. P. Bovbjerg, F. Christensen, P. Minnaar, and X. Chen, “Measuring the head-related transfer functions of an artificial head with a high directional resolution,” 109th AES Convention, Los Angeles, USA, Sep. 2000.

Examples

>>> import spharpy
>>> coords = spharpy.samplings.great_circle()
>>> spharpy.plot.scatter(coords)

(Source code, png, hires.png, pdf)

spharpy.samplings.hyperinterpolation(n_max, radius=1.0)

Return a Hyperinterpolation sampling grid.

After Sloan and Womersley [9]. The samplings are available for spherical harmonics orders \(1 \leq n_\text{max} \leq 200\). The number of points in the sampling grid equals \((n_\text{max} + 1)^2\).

Parameters:

• n_max (int) – Maximum applicable spherical harmonic order. It must be between 1 and 200.

• radius (number, optional) – Radius of the sampling grid in meters. The default is 1.

Returns:

sampling – Sampling positions including sampling weights, with (n_max + 1)**2 points.

Return type:

spharpy.SamplingSphere

Notes

This implementation uses precalculated sets of points from [10]. The data up to n_max = 20 are loaded the first time this function is called. The remaining data is loaded upon request.

References

[9]

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.

[10]

https://web.maths.unsw.edu.au/~rsw/Sphere/MaxDet/

Examples

>>> import spharpy
>>> coords = spharpy.samplings.hyperinterpolation(n_max=3)
>>> spharpy.plot.scatter(coords)

(Source code, png, hires.png, pdf)

spharpy.samplings.icosahedron(radius=1.0)

Generate a sampling from the center points of the twenty icosahedron faces.

Parameters:

radius (number, optional) – Radius of the sampling grid. The default is 1.

Returns:

sampling – Sampling positions. Sampling weights can be obtained from calculate_sampling_weights.

Return type:

spharpy.SamplingSphere

Examples

>>> import spharpy
>>> coords = spharpy.samplings.icosahedron()
>>> spharpy.plot.scatter(coords)

(Source code, png, hires.png, pdf)

spharpy.samplings.icosahedron_ke4()

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

Returns:

sampling – SamplingSphere object containing all sampling points

Return type:

spharpy.SamplingSphere

Examples

>>> import spharpy
>>> coords = spharpy.samplings.icosahedron_ke4()
>>> spharpy.plot.scatter(coords)

(Source code, png, hires.png, pdf)

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

Find stabilization points inside for an open spherical microphone array. The interior points stabilize the array response at the eigenfrequencies of the array. The algorithm is based on [11] and implemented following the Matlab code provided by Gilles Chardon on his homepage at [12]. 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. Default is 1.

Returns:

sampling_interior – Coordinates of the stabilization points

Return type:

Coordinates

References

[11]

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

[12]

https://gilleschardon.fr/jstsp_array/

spharpy.samplings.lebedev(n_max=None, radius=1.0)

Return Lebedev spherical sampling grid.

For the Lebedev grid [13], the number of points \(Q\) can be approximated by the spherical harmonic order \(N\) (parameter n_max)

\(Q \approx 1.3 \, (N+1)^2\)

For a list of available orders n_max and the exact number of points call lebedev without any arguments. This will print available orders and number of points to the console.

Note

This is intended to be a quadrature sampling with positive sampling weights summing to \(4\pi\). For unknown reasons, this is not the case in the original sources [14] and the Matlab code [15] on which this Python version is based for orders 6, 12, and 13. For this reason, the respective weights are not returned regardless of the order.

Parameters:

• n_max (int, optional) – Maximum applicable spherical harmonic order between 1 and 65. Because not all orders are available, the default None prints possible orders to the console.

• radius (number, optional) – Radius of the sampling grid in meters. The default is 1.

Returns:

sampling – Sampling positions without sampling weights (see note above).

Return type:

spharpy.SamplingSphere

References

[13]

V.I. Lebedev, and D.N. Laikov “A quadrature formula for the sphere of the 131st algebraic order of accuracy” Doklady Mathematics, Vol. 59, No. 3, 1999, pp. 477-481.

[14]

https://people.sc.fsu.edu/~jburkardt/datasets/sphere_lebedev_rule/sphere_lebedev_rule.html

[15]

https://de.mathworks.com/matlabcentral/fileexchange/27097-getlebedevsphere

Examples

>>> import spharpy
>>> coords = spharpy.samplings.lebedev(n_max=3)
>>> spharpy.plot.scatter(coords)

(Source code, png, hires.png, pdf)

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. Default is 13.

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

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.

The implementation is based on [16].

Parameters:

• n_max (int) – Spherical harmonic order

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

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

Returns:

sampling – SamplingSphere object containing all sampling points

Return type:

spharpy.SamplingSphere

References

[16]

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.

Examples

>>> import spharpy
>>> coords = spharpy.samplings.spiral_points(n_max=3)
>>> spharpy.plot.scatter(coords)

(Source code, png, hires.png, pdf)

spharpy.samplings.t_design(n_max, criterion='const_energy', radius=1.0)

Return spherical t-design sampling grid.

For detailed information, see [17]. For a spherical harmonic order \(n_{sh}\), a t-Design of degree \(t=2n_{sh}\) for constant energy or \(t=2n_{sh}+1\) additionally ensuring a constant angular spread of energy is required [18]. 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 an inverse spherical harmonic transform matrix calculated as \(D = \frac{4\pi}{L} \mathbf{Y}^\mathrm{H}\) with \(\mathbf{Y}^\mathrm{H}\) being the hermitian transpose of the spherical harmonics matrix.

Parameters:

• n_max (int) – Maximum applicable spherical harmonic order. Related to the degree by degree = 2 * n_max (const_energy) and degree = 2 * n_max + 1 (const_angular_spread). Must be between 1 and 90 for const_energy and between 1 and 89 for const_angular_spread.

• criterion (const_energy, const_angular_spread) – Design criterion ensuring only a constant energy or additionally constant angular spread of energy. The default is const_energy.

• radius (number, optional) – Radius of the sampling grid in meters. The default is 1.

Returns:

sampling – Sampling positions. Sampling weights can be obtained from calculate_sampling_weights.

Return type:

spharpy.SamplingSphere

Notes

This function downloads a pre-calculated set of points from [19] . The data up to degree = 20 are loaded the first time this function is called. The remaining data is loaded upon request.

References

[17]

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.

[18]

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.

[19]

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

Examples

>>> import spharpy
>>> coords = spharpy.samplings.t_design(n_max=3)
>>> spharpy.plot.scatter(coords)

(Source code, png, hires.png, pdf)