SamplingSphere#

The SamplingSphere class inherits from the pyfar.classes.coordinates class, which supports various coordinate systems and the conversion between them. SamplingSphere is designed to represent a set of points on a sphere.

Therefore, all points must have the same radius within an absolute tolerance, defined by radius_tolerance. If the weights are not None, their sum must equal the integral over the unit sphere, which is \(4\pi\).

The property quadrature is relevant for spherical harmonic processing. It specifies if the points form a quadrature rule, which requires valid weights, that the maximum spherical harmonic order of the sampling grid n_max is specified, and the inner product of the weighted spherical harmonics matrix \(\mathrm{Y}\) yields the identity matrix \(\mathrm{Y}^\mathrm{T} \text{diag}\{w\}\mathrm{Y}=\mathrm{I}\), with the weights vector \(w\). The sampling is considered a valid quadrature if the maximum absolute deviation of \(\mathrm{Y}^\mathrm{T} \text{diag}\{w\}\mathrm{Y}\) from \(I\) is smaller than the specified quadrature_tolerance.

It also adds the additional property:

n_max: the maximum spherical harmonic order of the sampling grid.

Note that the spharpy.samplings module provides a set of predefined spherical sampling grids, which can be used to create a spharpy.SamplingSphere object.

class spharpy.SamplingSphere(x=None, y=None, z=None, n_max=None, weights: array = None, comment: str = '', radius_tolerance=1e-06, quadrature_tolerance=1e-10)[source]#

Class for samplings on a sphere.

Attributes:

`azimuth`	Counter clock-wise angle in the x-y plane of the right handed Cartesian coordinate system in radians.
`cartesian`	Returns `x`, `y`, `z`.
`cdim`	Return channel dimension.
`colatitude`	Angle in the x-z plane of the right handed Cartesian coordinate system in radians.
`comment`	Get comment.
`cshape`	Return channel shape.
`csize`	Return channel size.
`cylindrical`	Cylindrical coordinates.
`elevation`	Angle in the x-z plane of the right handed Cartesian coordinate system in radians.
`frontal`	Angle in the y-z plane of the right handed Cartesian coordinate system in radians.
`lateral`	Counter clock-wise angle in the x-y plane of the right handed Cartesian coordinate system in radians.
`n_max`	Get or set the spherical harmonic order.
`polar`	Angle in the x-z plane of the right handed Cartesian coordinate system in radians.
`quadrature`	Get the quadrature flag.
`quadrature_tolerance`	Get or set the quadrature tolerance.
`radius`	Distance to the origin of the right handed Cartesian coordinate system in meters (\(0\) < radius < \(\infty\)).
`radius_tolerance`	Get or set the radius tolerance in meter.
`rho`	Radial distance to the the z-axis of the right handed Cartesian coordinate system (\(0\) < rho < \(\infty\)).
`spherical_colatitude`	Spherical coordinates according to the top pole colatitude coordinate system.
`spherical_elevation`	Spherical coordinates according to the top pole elevation coordinate system.
`spherical_front`	Spherical coordinates according to the frontal pole coordinate system.
`spherical_side`	Spherical coordinates according to the side pole coordinate system.
`upper`	Angle in the x-z plane of the right handed Cartesian coordinate system in radians.
`weights`	The area/quadrature weights of the sampling.
`x`	X coordinate of a right handed Cartesian coordinate system in meters (\(-\infty\) < x < \(\infty\)).
`y`	Y coordinate of a right handed Cartesian coordinate system in meters (\(-\infty\) < y < \(\infty\)).
`z`	Z coordinate of a right handed Cartesian coordinate system in meters (\(-\infty\) < z < \(\infty\)).

Methods:

`copy`()	Return a deep copy of the Coordinates object.
`find_nearest`(find[, k, distance_measure, ...])	Find the k nearest coordinates points.
`find_within`(find[, distance, ...])	Find coordinates within a certain distance to the query points.
`from_cartesian`(x, y, z[, n_max, weights, ...])	Create a SamplingSphere class object from a set of points on a sphere.
`from_coordinates`(coordinates[, n_max, ...])	Convert Coordinates class object to SamplingSphere class object.
`from_cylindrical`(azimuth, z, rho[, n_max, ...])	Create a SamplingSphere class object from a set of points on a sphere.
`from_spherical_colatitude`(azimuth, ...[, ...])	Create a SamplingSphere class object from a set of points on a sphere.
`from_spherical_elevation`(azimuth, elevation, ...)	Create a SamplingSphere class object from a set of points on a sphere.
`from_spherical_front`(frontal, upper, radius)	Create a SamplingSphere class object from a set of points on a sphere.
`from_spherical_side`(lateral, polar, radius)	Create a SamplingSphere class object from a set of points on a sphere.
`rotate`(rotation[, value, degrees, inverse])	Rotate points stored in the object around the origin of coordinates.
`show`([mask])	Show a scatter plot of the coordinate points.

property azimuth#: Counter clock-wise angle in the x-y plane of the right handed Cartesian coordinate system in radians. \(0\) radians are defined in positive x-direction, \(\pi/2\) radians in positive y-direction and so on (\(-\infty\) < azimuth < \(\infty\), \(2\pi\)-cyclic).

property cartesian#: Returns x, y, z. Right handed cartesian coordinate system. See see Coordinate Systems and Coordinates for more information.

property cdim#

Return channel dimension.

The channel dimension gives the number of dimensions of the coordinate points excluding the last dimension.

property colatitude#: Angle in the x-z plane of the right handed Cartesian coordinate system in radians. \(0\) radians colatitude are defined in positive z-direction, \(\pi/2\) radians in positive x-direction, and \(\pi\) in negative z-direction (\(0\leq\) colatitude \(\leq\pi\)). The colatitude is a variation of the elevation angle.

property comment#: Get comment.

copy()#: Return a deep copy of the Coordinates object.

property cshape#

Return channel shape.

The channel shape gives the shape of the coordinate points excluding the last dimension, which is always 3.

property csize#

Return channel size.

The channel size gives the number of points stored in the coordinates object.

property cylindrical#: Cylindrical coordinates. Returns azimuth, z, rho. See see Coordinate Systems and Coordinates for more information.

property elevation#: Angle in the x-z plane of the right handed Cartesian coordinate system in radians. \(0\) radians elevation are defined in positive x-direction, \(\pi/2\) radians in positive z-direction, and \(-\pi/2\) in negative z-direction (\(-\pi/2\leq\) elevation \(\leq\pi/2\)). The elevation is a variation of the colatitude.

find_nearest(find, k=1, distance_measure='euclidean', radius_tol=None)#

Find the k nearest coordinates points.

Parameters:

find (pf.Coordinates) – Coordinates to which the nearest neighbors are searched.
k (int, optional) – Number of points to return. k must be > 0. The default is 1.
distance_measure (string, optional) –

'euclidean'
distance is determined by the euclidean distance. This is default.

'spherical_radians'
distance is determined by the great-circle distance expressed in radians.

'spherical_meter'
distance is determined by the great-circle distance expressed in meters.
radius_tol (float, None) – For all spherical distance measures, the coordinates must be on a sphere, so the radius must be constant. This parameter defines the maximum allowed difference within the radii. Note that increasing the tolerance decreases the accuracy of the search. The default None uses a tolerance of two times the decimal resolution, which is determined from the data type of the coordinate points using numpy.finfo.

Returns:

index (tuple of arrays) – Indices of the neighbors. Arrays of shape (k, find.cshape) if k>1 else (find.cshape, ).
distance (numpy array of floats) – Distance between the points, after the given distance_measure. It’s of shape (k, find.cshape).

Notes

This is a wrapper for scipy.spatial.cKDTree.

Examples

Find frontal point from a spherical coordinate system

>>> import pyfar as pf
>>> import numpy as np
>>> coords = pf.Coordinates.from_spherical_elevation(
>>>     np.arange(0, 360, 10)*np.pi/180, 0, 1)
>>> to_find = pf.Coordinates(1, 0, 0)
>>> index, distance = coords.find_nearest(to_find)
>>> ax = coords.show(index)
>>> distance
0.0

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

Find multidimensional points in multidimensional coordinates with k=1

>>> import pyfar as pf
>>> import numpy as np
>>> coords = pf.Coordinates(np.arange(9).reshape((3, 3)), 0, 1)
>>> to_find = pf.Coordinates(
>>>     np.array([[0, 1], [2, 3]]), 0, 1)
>>> i, d = coords.find_nearest(to_find)
>>> coords[i] == find
True
>>> i
(array([[0, 0],
        [0, 1]], dtype=int64),
 array([[0, 1],
        [2, 0]], dtype=int64))
>>> d
array([[0., 0.],
       [0., 0.]])

Find multidimensional points in multidimensional coordinates with k=3

>>> import pyfar as pf
>>> import numpy as np
>>> coords = pf.Coordinates(np.arange(9).reshape((3, 3)), 0, 1)
>>> find = pf.Coordinates(
>>>     np.array([[0, 1], [2, 3]]), 0, 1)
>>> i, d = coords.find_nearest(find, 3)
>>> # the k-th dimension is at the end
>>> i[0].shape
(3, 2, 2)
>>> # now just access the k=0 dimension
>>> coords[i][0].cartesian
array([[[0., 0., 1.],
        [1., 0., 1.]],
       [[2., 0., 1.],
        [3., 0., 1.]]])

find_within(find, distance=0.0, distance_measure='euclidean', atol=None, return_sorted=True, radius_tol=None)#

Find coordinates within a certain distance to the query points.

Parameters:

find (pf.Coordinates) – Coordinates to which the nearest neighbors are searched.
distance (number, optional) – Maximum allowed distance to the given points find. Distance must be >= 0. For just exact matches use 0. The default is 0.
distance_measure (string, optional) –

'euclidean'
distance is determined by the euclidean distance. This is default.

'spherical_radians'
distance is determined by the great-circle distance expressed in radians.

'spherical_meter'
distance is determined by the great-circle distance expressed in meters.
atol (float, None) – Absolute tolerance for distance. The default None uses a tolerance of two times the decimal resolution, which is determined from the data type of the coordinate points using numpy.finfo.
return_sorted (bool, optional) – Sorts returned indices if True and does not sort them if False. The default is True.
radius_tol (float, None) – For all spherical distance measures, the coordinates must be on a sphere, so the radius must be constant. This parameter defines the maximum allowed difference within the radii. Note that increasing the tolerance decreases the accuracy of the search, i.e., points that are within the search distance might not be found or points outside the search distance may be returned. The default None uses a tolerance of two times the decimal resolution, which is determined from the data type of the coordinate points using numpy.finfo.

Returns:

index – Indices of the containing coordinates. Arrays of shape (find.cshape).

Return type:

tuple of array

Notes

This is a wrapper for scipy.spatial.cKDTree. Compared to previous implementations, it supports self.ndim>1 as well.

Examples

Find all point with 0.2 m distance from the frontal point

>>> import pyfar as pf
>>> import numpy as np
>>> coords = pf.Coordinates.from_spherical_elevation(
>>>     np.arange(0, 360, 5)*np.pi/180, 0, 1)
>>> find = pf.Coordinates(.2, 0, 0)
>>> index = coords.find_within(find, 1)
>>> coords.show(index)

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

Find all point with 1m distance from two points

>>> import pyfar as pf
>>> coords = pf.Coordinates(np.arange(6), 0, 0)
>>> find = pf.Coordinates([2, 3], 0, 0)
>>> index = coords.find_within(find, 1)
>>> coords.show(index[0])

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

classmethod from_cartesian(x, y, z, n_max=None, weights: array = None, comment: str = '', radius_tolerance: float = 1e-06, quadrature_tolerance: float = 1e-10)[source]#

Create a SamplingSphere class object from a set of points on a sphere.

See pyfar.classes.coordinates for more information.

Parameters:

x (ndarray, number) – X coordinate of a right handed Cartesian coordinate system in meters (-infty < x < infty).
y (ndarray, number) – Y coordinate of a right handed Cartesian coordinate system in meters (-infty < y < infty).
z (ndarray, number) – Z coordinate of a right handed Cartesian coordinate system in meters (-infty < z < infty).
n_max (int, optional) – Maximum spherical harmonic order of the sampling grid. The default is None.
weights (array like, number, optional) – Weighting factors for coordinate points. Their sum must equal to the integral over the unit sphere, which is \(4\pi\). The shape of the array must match the shape of the individual coordinate arrays. The default is None, which means that no weights are used.
comment (str, optional) – Comment about the stored coordinate points. The default is "", which initializes an empty string.
radius_tolerance (float, optional) – All points that are stored in a SamplingSphere must have the same radius and an error is raised if the maximum deviation from the mean radius exceeds this tolerance. The default of 1e-6 meter is intended to allow for some numerical inaccuracy.
quadrature_tolerance (float, optional) – Tolerance for testing whether the provided sampling grid is a valid quadrature. The sampling is considered a valid quadrature if the maximum absolute deviation of the inner product of the weighted spherical harmonics matrix from the identity matrix is smaller than the specified tolerance. The default is 1e-10.

Examples

Create a SamplingSphere object

>>> import spharpy
>>> sampling = spharpy.SamplingSphere.from_cartesian(0, 0, 1)

or the same using

>>> import spharpy
>>> sampling = spharpy.SamplingSphere(0, 0, 1)

classmethod from_coordinates(coordinates, n_max=None, radius_tolerance: float = 1e-06, quadrature_tolerance: float = 1e-10)[source]#

Convert Coordinates class object to SamplingSphere class object.

Parameters:

coordinates (pyfar.Coordinates) – Coordinates to be converted.
n_max (int, optional) – Maximum spherical harmonic order of the sampling grid. The default is None.
radius_tolerance (float, optional) – All points that are stored in a SamplingSphere must have the same radius and an error is raised if the maximum deviation from the mean radius exceeds this tolerance. The default of 1e-6 meter is intended to allow for some numerical inaccuracy.
quadrature_tolerance (float, optional) – Tolerance for testing whether the provided sampling grid is a valid quadrature. The sampling is considered a valid quadrature if the maximum absolute deviation of the inner product of the weighted spherical harmonics matrix from the identity matrix is smaller than the specified tolerance. The default is 1e-10.

classmethod from_cylindrical(azimuth, z, rho, n_max=None, weights: array = None, comment: str = '', radius_tolerance: float = 1e-06, quadrature_tolerance: float = 1e-10)[source]#

Create a SamplingSphere class object from a set of points on a sphere.

See pyfar.classes.coordinates for more information.

Parameters:

azimuth (ndarray, double) – Angle in radiant of rotation from the x-y-plane facing towards positive x direction. Used for spherical and cylindrical coordinate systems.
z (ndarray, double) – The z coordinate
rho (ndarray, double) – Distance to origin for each point in the x-y-plane. Used for cylindrical coordinate systems.
n_max (int, optional) – Maximum spherical harmonic order of the sampling grid. The default is None.
weights (array like, number, optional) – Weighting factors for coordinate points. Their sum must equal to the integral over the unit sphere, which is \(4\pi\). The shape of the array must match the shape of the individual coordinate arrays. The default is None, which means that no weights are used.
comment (str, optional) – Comment about the stored coordinate points. The default is "", which initializes an empty string.
radius_tolerance (float, optional) – All points that are stored in a SamplingSphere must have the same radius and an error is raised if the maximum deviation from the mean radius exceeds this tolerance. The default of 1e-6 meter is intended to allow for some numerical inaccuracy.
quadrature_tolerance (float, optional) – Tolerance for testing whether the provided sampling grid is a valid quadrature. The sampling is considered a valid quadrature if the maximum absolute deviation of the inner product of the weighted spherical harmonics matrix from the identity matrix is smaller than the specified tolerance. The default is 1e-10.

Examples

Create a SamplingSphere object

>>> import spharpy
>>> sampling = spharpy.SamplingSphere.from_cylindrical(
...     0, 0, 1, sh_order=1)

classmethod from_spherical_colatitude(azimuth, colatitude, radius, n_max=None, weights: array = None, comment: str = '', radius_tolerance: float = 1e-06, quadrature_tolerance: float = 1e-10)[source]#

Create a SamplingSphere class object from a set of points on a sphere.

See pyfar.classes.coordinates for more information.

Parameters:

azimuth (ndarray, double) – Angle in radiant of rotation from the x-y-plane facing towards positive x direction. Used for spherical and cylindrical coordinate systems.
colatitude (ndarray, double) – Angle in radiant with respect to polar axis (z-axis). Used for spherical coordinate systems.
radius (ndarray, double) – Distance to origin for each point. Used for spherical coordinate systems.
n_max (int, optional) – Maximum spherical harmonic order of the sampling grid. The default is None.
weights (array like, number, optional) – Weighting factors for coordinate points. Their sum must equal to the integral over the unit sphere, which is \(4\pi\). The shape of the array must match the shape of the individual coordinate arrays. The default is None, which means that no weights are used.
comment (str, optional) – Comment about the stored coordinate points. The default is "", which initializes an empty string.
radius_tolerance (float, optional) – All points that are stored in a SamplingSphere must have the same radius and an error is raised if the maximum deviation from the mean radius exceeds this tolerance. The default of 1e-6 meter is intended to allow for some numerical inaccuracy.
quadrature_tolerance (float, optional) – Tolerance for testing whether the provided sampling grid is a valid quadrature. The sampling is considered a valid quadrature if the maximum absolute deviation of the inner product of the weighted spherical harmonics matrix from the identity matrix is smaller than the specified tolerance. The default is 1e-10.

Examples

Create a SamplingSphere object

>>> import spharpy
>>> sampling = spharpy.SamplingSphere.from_spherical_colatitude(
...     0, 0, 1)

classmethod from_spherical_elevation(azimuth, elevation, radius, n_max=None, weights: array = None, comment: str = '', radius_tolerance: float = 1e-06, quadrature_tolerance: float = 1e-10)[source]#

Create a SamplingSphere class object from a set of points on a sphere.

See pyfar.classes.coordinates for more information.

Parameters:

azimuth (ndarray, double) – Angle in radiant of rotation from the x-y-plane facing towards positive x direction. Used for spherical and cylindrical coordinate systems.
elevation (ndarray, double) – Angle in radiant with respect to horizontal plane (x-z-plane). Used for spherical coordinate systems.
radius (ndarray, double) – Distance to origin for each point. Used for spherical coordinate systems.
n_max (int, optional) – Maximum spherical harmonic order of the sampling grid. The default is None.
weights (array like, float, None, optional) – Weighting factors for coordinate points. Their sum must equal to the integral over the unit sphere, which is \(4\pi\). The shape of the array must match the shape of the individual coordinate arrays. The default is None, which means that no weights are used.
comment (str, optional) – Comment about the stored coordinate points. The default is "", which initializes an empty string.
radius_tolerance (float, optional) – All points that are stored in a SamplingSphere must have the same radius and an error is raised if the maximum deviation from the mean radius exceeds this tolerance. The default of 1e-6 meter is intended to allow for some numerical inaccuracy.
quadrature_tolerance (float, optional) – Tolerance for testing whether the provided sampling grid is a valid quadrature. The sampling is considered a valid quadrature if the maximum absolute deviation of the inner product of the weighted spherical harmonics matrix from the identity matrix is smaller than the specified tolerance. The default is 1e-10.

Examples

Create a SamplingSphere object

>>> import spharpy
>>> sampling = spharpy.SamplingSphere.from_spherical_elevation(0, 0, 1)

classmethod from_spherical_front(frontal, upper, radius, n_max=None, weights: array = None, comment: str = '', radius_tolerance: float = 1e-06, quadrature_tolerance: float = 1e-10)[source]#

Create a SamplingSphere class object from a set of points on a sphere.

See pyfar.classes.coordinates for more information.

Parameters:

frontal (ndarray, double) – Angle in radiant of rotation from the y-z-plane facing towards positive y direction. Used for spherical coordinate systems.
upper (ndarray, double) – Angle in radiant with respect to polar axis (x-axis). Used for spherical coordinate systems.
radius (ndarray, double) – Distance to origin for each point. Used for spherical coordinate systems.
n_max (int, optional) – Maximum spherical harmonic order of the sampling grid. The default is None.
weights (array like, number, optional) – Weighting factors for coordinate points. Their sum must equal to the integral over the unit sphere, which is \(4\pi\). The shape of the array must match the shape of the individual coordinate arrays. The default is None, which means that no weights are used.
comment (str, optional) – Comment about the stored coordinate points. The default is "", which initializes an empty string.
radius_tolerance (float, optional) – All points that are stored in a SamplingSphere must have the same radius and an error is raised if the maximum deviation from the mean radius exceeds this tolerance. The default of 1e-6 meter is intended to allow for some numerical inaccuracy.
quadrature_tolerance (float, optional) – Tolerance for testing whether the provided sampling grid is a valid quadrature. The sampling is considered a valid quadrature if the maximum absolute deviation of the inner product of the weighted spherical harmonics matrix from the identity matrix is smaller than the specified tolerance. The default is 1e-10.

Examples

Create a SamplingSphere object

>>> import spharpy
>>> sampling = spharpy.SamplingSphere.from_spherical_front(0, 0, 1)

classmethod from_spherical_side(lateral, polar, radius, n_max=None, weights: array = None, comment: str = '', radius_tolerance: float = 1e-06, quadrature_tolerance: float = 1e-10)[source]#

Create a SamplingSphere class object from a set of points on a sphere.

See pyfar.classes.coordinates for more information.

Parameters:

lateral (ndarray, double) – Angle in radiant with respect to horizontal plane (x-y-plane). Used for spherical coordinate systems.
polar (ndarray, double) – Angle in radiant of rotation from the x-z-plane facing towards positive x direction. Used for spherical coordinate systems.
radius (ndarray, double) – Distance to origin for each point. Used for spherical coordinate systems.
n_max (int, optional) – Maximum spherical harmonic order of the sampling grid. The default is None.
weights (array like, number, optional) – Weighting factors for coordinate points. Their sum must equal to the integral over the unit sphere, which is \(4\pi\). The shape of the array must match the shape of the individual coordinate arrays. The default is None, which means that no weights are used.
comment (str, optional) – Comment about the stored coordinate points. The default is "", which initializes an empty string.
radius_tolerance (float, optional) – All points that are stored in a SamplingSphere must have the same radius and an error is raised if the maximum deviation from the mean radius exceeds this tolerance. The default of 1e-6 meter is intended to allow for some numerical inaccuracy.
quadrature_tolerance (float, optional) – Tolerance for testing whether the provided sampling grid is a valid quadrature. The sampling is considered a valid quadrature if the maximum absolute deviation of the inner product of the weighted spherical harmonics matrix from the identity matrix is smaller than the specified tolerance. The default is 1e-10.

Examples

Create a SamplingSphere object

>>> import spharpy
>>> sampling = spharpy.SamplingSphere.from_spherical_side(0, 0, 1)

property frontal#: Angle in the y-z plane of the right handed Cartesian coordinate system in radians. \(0\) radians frontal angle are defined in positive y-direction, \(\pi/2\) radians in positive z-direction, \(\pi\) in negative y-direction and so on (\(-\infty\) < frontal < \(\infty\), \(2\pi\)-cyclic).

property lateral#: Counter clock-wise angle in the x-y plane of the right handed Cartesian coordinate system in radians. \(0\) radians are defined in positive x-direction, \(\pi/2\) radians in positive y-direction and \(-\pi/2\) in negative y-direction (\(-\pi/2\leq\) lateral \(\leq\pi/2\)).

property n_max#: Get or set the spherical harmonic order.

property polar#: Angle in the x-z plane of the right handed Cartesian coordinate system in radians. \(0\) radians polar angle are defined in positive x-direction, \(\pi/2\) radians in positive z-direction, \(\pi\) in negative x-direction and so on (\(-\infty\) < polar < \(\infty\), \(2\pi\)-cyclic).

property quadrature#: Get the quadrature flag.

property quadrature_tolerance#: Get or set the quadrature tolerance.

property radius#: Distance to the origin of the right handed Cartesian coordinate system in meters (\(0\) < radius < \(\infty\)).

property radius_tolerance#: Get or set the radius tolerance in meter.

property rho#: Radial distance to the the z-axis of the right handed Cartesian coordinate system (\(0\) < rho < \(\infty\)).

rotate(rotation: str, value=None, degrees=True, inverse=False)#

Rotate points stored in the object around the origin of coordinates.

This is a wrapper for scipy.spatial.transform.Rotation (see this class for more detailed information).

Parameters:

rotation (str) –

'quat'
Rotation given by quaternions.

'matrix'
Rotation given by matrixes.

'rotvec'
Rotation using rotation vectors.

'xyz'
Rotation using euler angles. Up to three letters. E.g., 'x' will rotate about the x-axis only, while 'xz' will rotate about the x-axis and then about the z-axis. Use lower letters for extrinsic rotations (rotations about the axes of the original coordinate system xyz, which remains motionless) and upper letters for intrinsic rotations (rotations about the axes of the rotating coordinate system XYZ, solidary with the moving body, which changes its orientation after each elemental rotation).
value (number, array like) – Amount of rotation in the format specified by rotation (see above).
degrees (bool, optional) – Pass angles in degrees if using 'rotvec' or euler angles ('xyz'). The default is True. Use False to pass angles in radians.
inverse (bool, optional) – Apply inverse rotation. The default is False.

Notes

Points are converted to the cartesian right handed coordinate system for the rotation.

Examples

Get a coordinates object

>>> import pyfar as pf
>>> coords = pf.Coordinates(np.arange(-5, 5), 0, 0)

Rotate 45 degrees about the y-axis using

quaternions

>>> coordinates.rotate('quat', [0 , 0.38268343, 0 , 0.92387953])

a rotation matrix

>>> coordinates.rotate('matrix',
...    [[ 0.70710678,  0 ,  0.70710678],
...     [ 0         ,  1 ,  0.        ],
...     [-0.70710678,  0 ,  0.70710678]])

a rotation vector

>>> coordinates.rotate('rotvec', [0, 45, 0])

euler angles

>>> coordinates.rotate('XYZ', [0, 45, 0])

To see the result of the rotation use

>>> coordinates.show()

show(mask=None, **kwargs)#

Show a scatter plot of the coordinate points.

Parameters:

mask (boolean numpy array, None, optional) – Mask or indexes to highlight. Highlight points in red if mask==True. The default is None, which plots all points in the same color.
kwargs (optional) – Keyword arguments are passed to matplotlib.pyplot.scatter. If a mask is provided and the key c is contained in kwargs, it will be overwritten.

Returns:

ax – The axis used for the plot.

Return type:

Axes3D

property spherical_colatitude#: Spherical coordinates according to the top pole colatitude coordinate system. Returns azimuth, colatitude, radius. See see Coordinate Systems and Coordinates for more information.

property spherical_elevation#: Spherical coordinates according to the top pole elevation coordinate system. azimuth, elevation, radius. See see Coordinate Systems and Coordinates for more information.

property spherical_front#: Spherical coordinates according to the frontal pole coordinate system. Returns frontal, upper, radius. See see Coordinate Systems and Coordinates for more information.

property spherical_side#: Spherical coordinates according to the side pole coordinate system. Returns lateral, polar, radius. See see Coordinate Systems and Coordinates for more information.

property upper#: Angle in the x-z plane of the right handed Cartesian coordinate system in radians. \(0\) radians upper angle are defined in positive x-direction, \(\pi/2\) radians in positive z-direction, and \(\pi\) in negative x-direction (\(0\leq\) upper \(\leq\pi\)).

property weights#: The area/quadrature weights of the sampling. Their sum must equal to \(4\pi\).

property x#: X coordinate of a right handed Cartesian coordinate system in meters (\(-\infty\) < x < \(\infty\)).

property y#: Y coordinate of a right handed Cartesian coordinate system in meters (\(-\infty\) < y < \(\infty\)).

property z#: Z coordinate of a right handed Cartesian coordinate system in meters (\(-\infty\) < z < \(\infty\)).