pyfar.samplings#

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

Warning

This module will be deprecated in pyfar v0.8.0 in favor of spharpy.samplings.

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)[source]#

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)[source]#

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()[source]#

Return a copy of the Voronoi object.

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

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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

pyfar.samplings.sph_equiangular(n_points=None, sh_order=None, radius=1.0)[source]#

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

pyfar.samplings.sph_extremal(n_points=None, sh_order=None, radius=1.0)[source]#

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

pyfar.samplings.sph_fliege(n_points=None, sh_order=None, radius=1.0)[source]#

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

pyfar.samplings.sph_gaussian(n_points=None, sh_order=None, radius=1.0)[source]#

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

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)[source]#

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 which 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

pyfar.samplings.sph_icosahedron(radius=1.0)[source]#

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)[source]#

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

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

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