pyfar.samplings

Collection of sampling schemes and related functionality. For information on the used coordinate systems refer to the concepts.

Classes:

SphericalVoronoi(sampling[, round_decimals, ...])

Voronoi diagrams on the surface of a sphere.

Functions:

calculate_sph_voronoi_weights(sampling[, ...])	Calculate sampling weights for numeric integration.
cart_equidistant_cube(n_points)	Create a cuboid sampling with equidistant spacings in x, y, and z.
sph_dodecahedron([radius])	Generate a sampling based on the center points of the twelve dodecahedron faces.
sph_equal_angle(delta_angles[, radius])	Generate sampling of the sphere with equally spaced angles.
sph_equal_area(n_points[, radius])	Sampling based on partitioning into faces with equal area.
sph_equiangular([n_points, sh_order, radius])	Generate an equiangular sampling of the sphere.
sph_extremal([n_points, sh_order, radius])	Return a Hyperinterpolation sampling grid.
sph_fliege([n_points, sh_order, radius])	Return Fliege-Maier spherical sampling grid.
sph_gaussian([n_points, sh_order, radius])	Generate sampling of the sphere based on the Gaussian quadrature.
sph_great_circle([elevation, gcd, radius, ...])	Spherical sampling grid according to the great circle distance criterion.
sph_icosahedron([radius])	Generate a sampling from the center points of the twenty icosahedron faces.
sph_lebedev([n_points, sh_order, radius])	Return Lebedev spherical sampling grid.
sph_t_design([degree, sh_order, criterion, ...])	Return spherical t-design sampling grid.

class pyfar.samplings.SphericalVoronoi(sampling, round_decimals=12, center=0.0)

Bases: SphericalVoronoi

Voronoi diagrams on the surface of a sphere. Note that calculate_sph_voronoi_weights can be used directly, if only the sampling weights are needed.

Methods:

__init__(sampling[, round_decimals, center])	Calculate a Voronoi diagram on the sphere for the given samplings points.
copy()	Return a copy of the Voronoi object.

__init__(sampling, round_decimals=12, center=0.0)

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

This function will be deprecated in pyfar 0.8.0 in favor of spharpy.samplings.spherical_voronoi.

Parameters:

• sampling (Coordinates) – Spherical sampling.

• round_decimals (int) – Number of decimals to be rounded for checking for equal radius. The default is 12.

• center (double) – Center point of the voronoi diagram. The default is 0.

Returns:

voronoi – Spherical voronoi diagram as implemented in scipy.spatial.

Return type:

SphericalVoronoi

See also

calculate_sph_voronoi_weights

copy()

Return a copy of the Voronoi object.

pyfar.samplings.calculate_sph_voronoi_weights(sampling, normalize=True, center=[0, 0, 0], round_decimals=12)

Calculate sampling weights for numeric integration.

This function will be deprecated in pyfar 0.8.0 in favor of spharpy.samplings.calculate_sampling_weights.

Uses the class method calculate_areas from SphericalVoronoi to calculate the weights. It requires a spherical sampling grid with a single radius and uses scipy.spatial.SphericalVoronoi in the background.

Parameters:

• sampling (Coordinates) – Sampling points on a sphere, i.e., all points must have the same radius.

• normalize (boolean, optional) – Normalize the samplings weights to sum(weights)=1. Otherwise the weights sum to \(4 \pi r^2\). The default is True.

• center (list) – Center of the spherical sampling grid. The default is [0, 0, 0].

• round_decimals (int, optional) – Round to round_decimals digits to check for equal radius. The default is 12.

Returns:

weigths – Sampling weights of size samplings.csize.

Return type:

ndarray, double

pyfar.samplings.cart_equidistant_cube(n_points)

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

This function will be deprecated in pyfar 0.8.0 in favor of spharpy.samplings.cube_equidistant.

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. Does not contain sampling weights.

Return type:

Coordinates

pyfar.samplings.sph_dodecahedron(radius=1.0)

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

This function will be deprecated in pyfar 0.8.0 in favor of spharpy.samplings.dodecahedron.

Parameters:

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

Returns:

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

Return type:

Coordinates

pyfar.samplings.sph_equal_angle(delta_angles, radius=1.0)

Generate sampling of the sphere with equally spaced angles.

This function will be deprecated in pyfar 0.8.0 in favor of spharpy.samplings.equal_angle.

This sampling contain points at the North and South Pole. See sph_equiangular, sph_gaussian, and sph_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_sph_voronoi_weights.

Return type:

Coordinates

pyfar.samplings.sph_equal_area(n_points, radius=1.0)

Sampling based on partitioning into faces with equal area.

This function will be deprecated in pyfar 0.8.0 in favor of spharpy.samplings.equal_area.

For detailed information, see [1].

Parameters:

• n_points (int) – Number of points corresponding to the number of partitions of the sphere.

• 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_sph_voronoi_weights.

Return type:

Coordinates

References

[1]

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.

pyfar.samplings.sph_equiangular(n_points=None, sh_order=None, radius=1.0)

Generate an equiangular sampling of the sphere.

This function will be deprecated in pyfar 0.8.0 in favor of spharpy.samplings.equiangular.

For detailed information, see [2], Chapter 3.2. This sampling does not contain points at the North and South Pole and is typically used for spherical harmonics processing. See sph_equal_angle and sph_great_circle for samplings containing points at the poles.

Parameters:

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

• sh_order (int) – Maximum applicable spherical harmonic order. If this is provided, ‘n_points’ is set to 2 * sh_order + 1. Either n_points or sh_order 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:

Coordinates

References

[2]

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

pyfar.samplings.sph_extremal(n_points=None, sh_order=None, radius=1.0)

Return a Hyperinterpolation sampling grid.

This function will be deprecated in pyfar 0.8.0 in favor of spharpy.samplings.hyperinterpolation.

After Sloan and Womersley [3]. The samplings are available for 1 <= sh_order <= 200 (n_points = (sh_order + 1)^2).

Parameters:

• n_points (int) – Number of sampling points in the grid. Related to the spherical harmonic order by n_points = (sh_order + 1)**2. Either n_points or sh_order must be provided. The default is None.

• sh_order (int) – Maximum applicable spherical harmonic order. Related to the number of points by sh_order = np.sqrt(n_points) - 1. Either n_points or sh_order must be provided. The default is None.

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

Returns:

sampling – Sampling positions including sampling weights.

Return type:

Coordinates

Notes

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

References

[3]

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.

[4]

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

pyfar.samplings.sph_fliege(n_points=None, sh_order=None, radius=1.0)

Return Fliege-Maier spherical sampling grid.

This function will be deprecated in pyfar 0.8.0 in favor of spharpy.samplings.fliege.

For detailed information, see [5]. Call sph_fliege for a list of possible values for n_points and sh_order.

Parameters:

• n_points (int, optional) – Number of sampling points in the grid. Related to the spherical harmonic order by n_points = (sh_order + 1)**2. Either n_points or sh_order must be provided. The default is None.

• sh_order (int, optional) – Maximum applicable spherical harmonic order. Related to the number of points by sh_order = np.sqrt(n_points) - 1. Either n_points or sh_order must be provided. The default is None.

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

Returns:

sampling – Sampling positions including sampling weights.

Return type:

Coordinates

Notes

This implementation uses pre-calculated points from the SOFiA toolbox [6]. Possible combinations of n_points and sh_order are:

n_points	sh_order
4	1
9	2
16	3
25	4
36	5
49	6
64	7
81	8
100	9
121	10
144	11
169	12
196	13
225	14
256	15
289	16
324	17
361	18
400	19
441	20
484	21
529	22
576	23
625	24
676	25
729	26
784	27
841	28
900	29

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

pyfar.samplings.sph_gaussian(n_points=None, sh_order=None, radius=1.0)

Generate sampling of the sphere based on the Gaussian quadrature.

This function will be deprecated in pyfar 0.8.0 in favor of spharpy.samplings.gaussian.

For detailed information, see [7] (Section 3.3). This sampling does not contain points at the North and South Pole and is typically used for spherical harmonics processing. See sph_equal_angle and sph_great_circle for samplings containing points at the poles.

Parameters:

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

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

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

Returns:

sampling – Sampling positions including sampling weights.

Return type:

Coordinates

References

[7]

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

pyfar.samplings.sph_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.

This function will be deprecated in pyfar 0.8.0 in favor of spharpy.samplings.great_circle.

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

Return type:

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.

pyfar.samplings.sph_icosahedron(radius=1.0)

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

This function will be deprecated in pyfar 0.8.0 in favor of spharpy.samplings.icosahedron.

Parameters:

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

Returns:

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

Return type:

Coordinates

pyfar.samplings.sph_lebedev(n_points=None, sh_order=None, radius=1.0)

Return Lebedev spherical sampling grid.

This function will be deprecated in pyfar 0.8.0 in favor of spharpy.samplings.lebedev.

For detailed information, see [9]. For a list of available values for n_points and sh_order call lebedev.

Parameters:

• n_points (int, optional) – Number of sampling points in the grid. Related to the spherical harmonic order by n_points = (sh_order + 1)**2. Either n_points or sh_order must be provided. The default is None.

• sh_order (int, optional) – Maximum applicable spherical harmonic order. Related to the number of points by sh_order = np.sqrt(n_points) - 1. Either n_points or sh_order must be provided. The default is None.

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

Returns:

sampling – Sampling positions including sampling weights.

Return type:

Coordinates

Notes

This is a Python port of the Matlab Code written by Rob Parrish [10].

References

[9]

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.

[10]

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

pyfar.samplings.sph_t_design(degree=None, sh_order=None, criterion='const_energy', radius=1.0)

Return spherical t-design sampling grid.

This function will be deprecated in pyfar 0.8.0 in favor of spharpy.samplings.spherical_t_design.

For detailed information, see [11]. 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 [12]. 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:

• degree (int) – T-design degree between 1 and 180. Either degree or sh_order must be provided. The default is None.

• sh_order (int) – Maximum applicable spherical harmonic order. Related to the degree by degree = 2 * sh_order (const_energy) and degree = 2 * sh_order + 1 (const_angular_spread). Either degree or sh_order must be provided. The default is None.

• 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_sph_voronoi_weights.

Return type:

Coordinates

Notes

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

References

[11]

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.

[12]

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.

[13]

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