Coordinates¶
The following documents the pyfar coordinates class and functions for
coordinate conversion. More background information is given in
coordinates concepts
.
Available sampling schemes are listed at samplings
.
Classes:

Container class for storing, converting, rotating, querying, and plotting 3D coordinate systems. 
Functions:

Transforms from Cartesian to cylindrical coordinates. 

Transforms from Cartesian to spherical coordinates. 

Transforms from cylindrical to Cartesian coordinates. 

Transforms from spherical to Cartesian coordinates. 
 class pyfar.classes.coordinates.Coordinates(points_1=None, points_2=None, points_3=None, domain='cart', convention=None, unit=None, weights=None, sh_order=None, comment=None)[source]¶
Bases:
object
Container class for storing, converting, rotating, querying, and plotting 3D coordinate systems.
Methods:
__init__
([points_1, points_2, points_3, ...])Create
Coordinates
object with or without coordinate points.copy
()Return a deep copy of the Coordinates object.
find_nearest_cart
(points_1, points_2, ...[, ...])Find coordinates within a certain distance in meters to query points.
find_nearest_k
(points_1, points_2, points_3)Find the k nearest coordinates points.
find_nearest_sph
(points_1, points_2, ...[, ...])Find coordinates within certain angular distance to the query points.
find_slice
(coordinate, unit, value[, tol, ...])Find a slice of the coordinates points.
get_cart
([convention, unit, convert])Get coordinate points in cartesian coordinate systems.
get_cyl
([convention, unit, convert])Get coordinate points in cylindircal coordinate system.
get_sph
([convention, unit, convert])Get coordinate points in spherical coordinate systems.
rotate
(rotation[, value, degrees, inverse])Rotate points stored in the object around the origin of coordinates.
set_cart
(points_1, points_2, points_3[, ...])Enter coordinate points in cartesian coordinate systems.
set_cyl
(points_1, points_2, points_3[, ...])Enter coordinate points in cylindrical coordinate systems.
set_sph
(points_1, points_2, points_3[, ...])Enter coordinate points in spherical coordinate systems.
show
([mask])Show a scatter plot of the coordinate points.
systems
([show, brief])Print coordinate systems and their description on the console.
Attributes:
Return channel dimension.
Get comment.
Return channel shape.
Return channel size.
Get the maximum spherical harmonic order.
Get sampling weights.
 __init__(points_1=None, points_2=None, points_3=None, domain='cart', convention=None, unit=None, weights=None, sh_order=None, comment=None)[source]¶
Create
Coordinates
object with or without coordinate points.The points that enter the Coordinates object are defined by the domain, convention, and unit as illustrated in the
coordinates concepts
:domain, convention
points_1
points_2
points_3
unit
cart, right
x
y
z
met
sph, top_colat
azimuth
colatitude
radius
rad, deg
sph, top_elev
azimuth
elevation
radius
rad, deg
sph, side
lateral
polar
radius
rad, deg
sph, front
phi
theta
radius
rad, deg
cyl, top
azimuth
z
radius_z
rad, deg
For more information run
>>> coords = Coordinates() >>> coords.systems()
 Parameters:
points_1 (array like, number) – points for the first coordinate
points_2 (array like, number) – points for the second coordinate
points_3 (array like, number) – points for the third coordinate
domain (string) –
domain of the coordinate system
'cart'
Cartesian
'sph'
Spherical
'cyl'
Cylindrical
The default is
'cart'
.convention (string) – coordinate convention (see above) The default is
'right'
if domain is'cart'
,'top_colat'
if domain is'sph'
, and'top'
if domain is'cyl'
.unit (string) – unit of the coordinate system. By default the first available unit is used, which is meters (
'met'
) fordomain = 'cart'
and radians ('rad'
) in all other cases (See above).weights (array like, number, optional) – sampling weights for the coordinate points. Must have same size as the points points, i.e., if points have five entries, the weights must also have five entries. The default is
None
.sh_order (int, optional) – maximum spherical harmonic order of the sampling grid. The default is
None
.comment (str, optional) – comment about the stored coordinate points. The default is
None
.
 property cdim¶
Return channel dimension.
The channel dimension gives the number of dimensions of the coordinate points excluding the last dimension.
 property comment¶
Get comment.
 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.
 find_nearest_cart(points_1, points_2, points_3, distance, domain='cart', convention='right', unit='met', show=False, atol=1e15)[source]¶
Find coordinates within a certain distance in meters to query points.
 Parameters:
points_i (array like, number) – first, second and third coordinate of the points to which the nearest neighbors are searched.
distance (number) – Euclidean distance in meters in which the nearest points are searched. Must be >= 0.
domain (string, optional) – domain of the points. The default is
'cart'
.convention (string, optional) – convention of points. The default is
'right'
.unit (string, optional) – unit of the points. The default is
'met'
for meters.show (bool, optional) – show a plot of the coordinate points. The default is
False
.atol (float, optional) – a tolerance that is added to distance. The default is`` 1e15``.
 Returns:
index (numpy array of ints) – The locations of the neighbors in the getter methods (e.g.,
get_cart
). Dimension as infind_nearest_k
. Missing neighbors are indicated withcsize
. Also see Notes below.mask (boolean numpy array) – mask that contains
True
at the positions of the selected points andFalse
otherwise. Mask is of shapecshape
.
Notes
numpy.spatial.cKDTree
is used for the search, which requires an (N, 3) array. The coordinate points in self are thus reshaped to (csize, 3) before they are passed tocKDTree
. The index that is returned refers to the reshaped coordinate points. To access the points for example use>>> points_reshaped = self.get_cart().reshape((self.csize, 3)) >>> points_reshaped[index]
Examples
Find frontal points within a distance of 0.5 meters
>>> import pyfar as pf >>> coords = pf.samplings.sph_lebedev(sh_order=10) >>> result = coords.find_nearest_cart(1, 0, 0, 0.5, show=True)
(
Source code
,png
,hires.png
,pdf
)
 find_nearest_k(points_1, points_2, points_3, k=1, domain='cart', convention='right', unit='met', show=False)[source]¶
Find the k nearest coordinates points.
 Parameters:
points_i (array like, number) – first, second and third coordinate of the points to which the nearest neighbors are searched.
k (int, optional) – Number of points to return. k must be > 0. The default is
1
.domain (string, optional) – domain of the points. The default is
'cart'
.convention (string, optional) – convention of points. The default is
'right'
.unit (string, optional) – unit of the points. The default is
'met'
for meters.show (bool, optional) – show a plot of the coordinate points. The default is
False
.
 Returns:
index (numpy array of ints) – The locations of the neighbors in the getter methods (e.g.,
self.get_cart
). Dimension according to distance (see below). Missing neighbors are indicated withcsize
. Also see Notes below.mask (boolean numpy array) – mask that contains
True
at the positions of the selected points andFalse
otherwise. Mask is of shapecshape
.
Notes
numpy.spatial.cKDTree
is used for the search, which requires an (N, 3) array. The coordinate points in self are thus reshaped to (csize, 3) before they are passed tocKDTree
. The index that is returned refers to the reshaped coordinate points. To access the points for example use>>> points_reshaped = self.get_cart().reshape((self.csize, 3)) >>> points_reshaped[index]
Examples
Find frontal point from a spherical coordinate system
>>> import pyfar as pf >>> coords = pf.samplings.sph_lebedev(sh_order=10) >>> result = coords.find_nearest_k(1, 0, 0, show=True)
(
Source code
,png
,hires.png
,pdf
)
 find_nearest_sph(points_1, points_2, points_3, distance, domain='sph', convention='top_colat', unit='rad', show=False, atol=1e15)[source]¶
Find coordinates within certain angular distance to the query points.
 Parameters:
points_i (array like, number) – first, second and third coordinate of the points to which the nearest neighbors are searched.
distance (number) – Great circle distance in degrees in which the nearest points are searched. Must be >= 0 and <= 180.
domain (string, optional) – domain of the input points. The default is
'sph'
.convention (string, optional) – convention of the input points. The default is
'top_colat'
.unit (string, optional) – unit of the input points. The default is
'rad'
.show (bool, optional) – show a plot of the coordinate points. The default is
False
.atol (float, optional) – a tolerance that is added to distance. The default is
1e15
.
 Returns:
index (numpy array of ints) – The locations of the neighbors in the getter methods (e.g.,
get_cart
). Dimension as infind_nearest_k
. Missing neighbors are indicated withcsize
. Also see Notes below.mask (boolean numpy array) – mask that contains
True
at the positions of the selected points andFalse
otherwise. Mask is of shapecshape
.
Notes
numpy.spatial.cKDTree
is used for the search, which requires an (N, 3) array. The coordinate points in self are thus reshaped to (csize, 3) before they are passed tocKDTree
. The index that is returned refers to the reshaped coordinate points. To access the points for example usepoints_reshaped = points.get_sph().reshape((points.csize, 3))
points_reshaped[index]
Examples
Find top points within a distance of 45 degrees
>>> import pyfar as pf >>> coords = pf.samplings.sph_lebedev(sh_order=10) >>> result = coords.find_nearest_sph(0, 0, 1, 45, show=True)
(
Source code
,png
,hires.png
,pdf
)
 find_slice(coordinate: str, unit: str, value, tol=0, show=False, atol=1e15)[source]¶
Find a slice of the coordinates points.
 Parameters:
coordinate (str) – coordinate for slicing.
unit (str) – unit in which the value is passed
value (number) – value of the coordinate around which the points are sliced.
tol (number, optional) – tolerance for slicing. Points are sliced within the range
[valuetol, value+tol]
. The default is0
.show (bool, optional) – show a plot of the coordinate points. The default is
False
.atol (number, optional) – a tolerance that is added to tol. The default is
1e15
.
 Returns:
index (tuple of numpy arrays) – The indices of the selected points as a tuple of arrays. The length of the tuple matches
cdim
. The length of each array matches the number of selected points.mask (boolean numpy array) – mask that contains True at the positions of the selected points and False otherwise. Mask is of shape self.cshape.
Notes
value must be inside the range of the coordinate (see
.systems
). However, value +/ tol may exceed the range.Examples
Find horizontal slice of spherical coordinate system within a ring of +/ 10 degrees
>>> import pyfar as pf >>> coords = pf.samplings.sph_lebedev(sh_order=10) >>> result = coords.find_slice('elevation', 'deg', 0, 5, show=True)
(
Source code
,png
,hires.png
,pdf
)
 get_cart(convention='right', unit='met', convert=False)[source]¶
Get coordinate points in cartesian coordinate systems.
The points that are returned are defined by the domain, convention, and unit:
domain, convention
p[…,1]
p[…,1]
p[…,1]
units
cart, right
x
y
z
met
For more information run
>>> coords = Coordinates() >>> coords.systems()
 Parameters:
convention (string, optional) – convention in which the coordinate points are stored. The default is
'right'
.unit (string, optional) – unit in which the coordinate points are stored. The default is
'met'
.convert (boolean, optional) – if True, the internal representation of the samplings points will be converted to the queried coordinate system. The default is
False
, i.e., the internal presentation remains as it is.
 Returns:
points – coordinate points.
points[...,0]
holds the points for the first coordinate,points[...,1]
the points for the second, andpoints[...,2]
the points for the third coordinate. Return type:
numpy array
 get_cyl(convention='top', unit='rad', convert=False)[source]¶
Get coordinate points in cylindircal coordinate system.
The points that are returned are defined by the domain, convention, and unit:
domain, convention
p[…,1]
p[…,1]
p[…,1]
units
cyl, top
azimuth
z
radius_z
rad, deg
For more information run
>>> coords = Coordinates() >>> coords.systems()
 Parameters:
convention (string, optional) – convention in which the coordinate points are stored. The default is
'right'
.unit (string, optional) – unit in which the coordinate points are stored. The default is
'met'
.convert (boolean, optional) – if True, the internal representation of the samplings points will be converted to the queried coordinate system. The default is False, i.e., the internal presentation remains as it is.
 Returns:
points – coordinate points.
points[...,0]
holds the points for the first coordinate,points[...,1]
the points for the second, andpoints[...,2]
the points for the third coordinate. Return type:
numpy array
 get_sph(convention='top_colat', unit='rad', convert=False)[source]¶
Get coordinate points in spherical coordinate systems.
The points that are returned are defined by the domain, convention, and unit:
domain, convention
p[…,1]
p[…,1]
p[…,1]
units
sph, top_colat
azimuth
colatitude
radius
rad, deg
sph, top_elev
azimuth
elevation
radius
rad, deg
sph, side
lateral
polar
radius
rad, deg
sph, front
phi
theta
radius
rad, deg
For more information run
>>> coords = Coordinates() >>> coords.systems()
 Parameters:
convention (string, optional) – convention in which the coordinate points are stored. The default is
'top_colat'
.unit (string, optional) – unit in which the coordinate points are stored. The default is
'rad'
.convert (boolean, optional) – if True, the internal representation of the samplings points will be converted to the queried coordinate system. The default is
False
, i.e., the internal presentation remains as it is.
 Returns:
points – coordinate points.
points[...,0]
holds the points for the first coordinate,points[...,1]
the points for the second, andpoints[...,2]
the points for the third coordinate. Return type:
numpy array
 rotate(rotation: str, value=None, degrees=True, inverse=False)[source]¶
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 xaxis only, while'xz'
will rotate about the xaxis and then about the zaxis. 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 isTrue
. 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 >>> coordinates = pf.samplings.sph_gaussian(sh_order=3)
Rotate 45 degrees about the yaxis 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()
 set_cart(points_1, points_2, points_3, convention='right', unit='met')[source]¶
Enter coordinate points in cartesian coordinate systems.
The points that enter the Coordinates object are defined by the domain, convention, and unit
domain, convention
points_1
points_2
points_3
unit
cart, right
x
y
z
met
For more information run
>>> coords = Coordinates() >>> coords.systems()
 Parameters:
points_i (array like, number) – points for the first, second, and third coordinate
convention (string, optional) – convention in which the coordinate points are stored. The default is
'right'
.unit (string, optional) – unit in which the coordinate points are stored. The default is
'met'
for meters.
 set_cyl(points_1, points_2, points_3, convention='top', unit='rad')[source]¶
Enter coordinate points in cylindrical coordinate systems.
The points that enter the Coordinates object are defined by the domain, convention, and unit
domain, convention
points_1
points_2
points_3
unit
cyl, top
azimuth
z
radius_z
rad, deg
For more information run
>>> coords = Coordinates() >>> coords.systems()
 Parameters:
points_i (array like, number) – points for the first, second, and third coordinate
convention (string, optional) – convention in which the coordinate points are stored. The default is
'top'
.unit (string, optional) – unit in which the coordinate points are stored. The default is
'rad'
.
 set_sph(points_1, points_2, points_3, convention='top_colat', unit='rad')[source]¶
Enter coordinate points in spherical coordinate systems.
The points that enter the Coordinates object are defined by the domain, convention, and unit
domain, convention
points_1
points_2
points_3
unit
sph, top_colat
azimuth
colatitude
radius
rad, deg
sph, top_elev
azimuth
elevation
radius
rad, deg
sph, side
lateral
polar
radius
rad, deg
sph, front
phi
theta
radius
rad, deg
For more information run
>>> coords = Coordinates() >>> coords.systems()
 Parameters:
points_i (array like, number) – points for the first, second, and third coordinate
convention (string, optional) – convention in which the coordinate points are stored. The default is
'top_colat'
.unit (string, optional) – unit in which the coordinate points are stored. The default is
'rad'
.
 property sh_order¶
Get the maximum spherical harmonic order.
 show(mask=None, **kwargs)[source]¶
Show a scatter plot of the coordinate points.
 Parameters:
mask (boolean numpy array, None, optional) – Plot points in red if
mask==True
. The default isNone
, which the same color for all points.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:
matplotlib.axes._subplots.Axes3DSubplot
 systems(show='all', brief=False)[source]¶
Print coordinate systems and their description on the console.
Note
All coordinate systems are described with respect to the right handed cartesian system (
domain='cart'
,convention='right'
). Distances are always specified in meters, while angles can be radians or degrees (unit='rad'
orunit='deg'
). Parameters:
show (string, optional) –
'current'
to list the current corrdinate system or'all'
to list all coordinate systems. The default is'all'
.brief (boolean, optional) – Will only list the domains, conventions and units if True. The default is
False
.
 Return type:
Prints to console.
 property weights¶
Get sampling weights.
 pyfar.classes.coordinates.cart2cyl(x, y, z)[source]¶
Transforms from Cartesian to cylindrical coordinates.
Cylindrical coordinates follow the convention that the azimuth is 0 at positive xdirection and pi/2 at positive ydirection (counter clockwise rotation). The height is identical to the zcoordinate and the radius is measured orthogonal from the zaxis.
Cartesian coordinates follow the right hand rule.
\[ \begin{align}\begin{aligned}azimuth &= \arctan(\frac{y}{x}),\\height &= z,\\radius &= \sqrt{x^2 + y^2},\end{aligned}\end{align} \]\[0 < azimuth < 2 \pi\] Parameters:
x (numpy array, number) – x values
y (numpy array, number) – y values
z (numpy array, number) – z values
 Returns:
azimuth (numpy array, number) – azimuth values
height (numpy array, number) – height values
radius (numpy array, number) – radii
Notes
To ensure proper handling of the azimuth angle, the
arctan2
implementation from numpy is used.
 pyfar.classes.coordinates.cart2sph(x, y, z)[source]¶
Transforms from Cartesian to spherical coordinates.
Spherical coordinates follow the common convention in Physics/Mathematics. The colatitude is measured downwards from the zaxis and is 0 at the North Pole and pi at the South Pole. The azimuth is 0 at positive xdirection and pi/2 at positive ydirection (counter clockwise rotation).
Cartesian coordinates follow the right hand rule.
\[ \begin{align}\begin{aligned}azimuth &= \arctan(\frac{y}{x}),\\colatitude &= \arccos(\frac{z}{r}),\\radius &= \sqrt{x^2 + y^2 + z^2}\end{aligned}\end{align} \]\[ \begin{align}\begin{aligned}0 < azimuth < 2 \pi,\\0 < colatitude < \pi\end{aligned}\end{align} \] Parameters:
x (numpy array, number) – x values
y (numpy array, number) – y values
z (numpy array, number) – z values
 Returns:
azimuth (numpy array, number) – azimuth values
colatitude (numpy array, number) – colatitude values
radius (numpy array, number) – radii
Notes
To ensure proper handling of the azimuth angle, the
arctan2
implementation from numpy is used.
 pyfar.classes.coordinates.cyl2cart(azimuth, height, radius)[source]¶
Transforms from cylindrical to Cartesian coordinates.
Cylindrical coordinates follow the convention that the azimuth is 0 at positive xdirection and pi/2 at positive ydirection (counter clockwise rotation). The height is identical to the zcoordinate and the radius is measured orthogonal from the zaxis.
Cartesian coordinates follow the right hand rule.
\[ \begin{align}\begin{aligned}x &= radius \cdot \cos(azimuth),\\y &= radius \cdot \sin(azimuth),\\z &= height\end{aligned}\end{align} \]\[0 < azimuth < 2 \pi\] Parameters:
azimuth (numpy array, number) – azimuth values
height (numpy array, number) – height values
radius (numpy array, number) – radii
 Returns:
x (numpy array, number) – x values
y (numpy array, number) – y values
z (numpy array, number) – z values
Notes
To ensure proper handling of the azimuth angle, the
arctan2
implementation from numpy is used.
 pyfar.classes.coordinates.sph2cart(azimuth, colatitude, radius)[source]¶
Transforms from spherical to Cartesian coordinates.
Spherical coordinates follow the common convention in Physics/Mathematics. The colatitude is measured downwards from the zaxis and is 0 at the North Pole and pi at the South Pole. The azimuth is 0 at positive xdirection and pi/2 at positive ydirection (counter clockwise rotation).
Cartesian coordinates follow the right hand rule.
\[ \begin{align}\begin{aligned}x &= radius \cdot \sin(colatitude) \cdot \cos(azimuth),\\y &= radius \cdot \sin(colatitude) \cdot \sin(azimuth),\\z &= radius \cdot \cos(colatitude)\end{aligned}\end{align} \]\[ \begin{align}\begin{aligned}0 < azimuth < 2 \pi\\0 < colatitude < \pi\end{aligned}\end{align} \] Parameters:
azimuth (numpy array, number) – azimuth values
colatitude (numpy array, number) – colatitude values
radius (numpy array, number) – radii
 Returns:
x (numpy array, number) – x values
y (numpy array, number) – y values
z (numpy array, number) – z vales