# 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:

 Coordinates([points_1, points_2, points_3, ...]) Container class for storing, converting, rotating, querying, and plotting 3D coordinate systems.

Functions:

 cart2cyl(x, y, z) Transforms from Cartesian to cylindrical coordinates. cart2sph(x, y, z) Transforms from Cartesian to spherical coordinates. cyl2cart(azimuth, height, radius) Transforms from cylindrical to Cartesian coordinates. sph2cart(azimuth, colatitude, radius) 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. 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:

 cdim Return channel dimension. comment Get comment. cshape Return channel shape. csize Return channel size. sh_order Get the maximum spherical harmonic order. weights 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

sph, top_elev

azimuth

elevation

sph, side

lateral

polar

sph, front

phi

theta

cyl, top

azimuth

z

>>> 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') for domain = '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.

copy()[source]

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.

find_nearest_cart(points_1, points_2, points_3, distance, domain='cart', convention='right', unit='met', show=False, atol=1e-15)[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 1e-15.

Returns:

• index (numpy array of ints) – The locations of the neighbors in the getter methods (e.g., get_cart). Dimension as in find_nearest_k. Missing neighbors are indicated with csize. Also see Notes below.

• mask (boolean numpy array) – mask that contains True at the positions of the selected points and False otherwise. Mask is of shape cshape.

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

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 with csize. Also see Notes below.

• mask (boolean numpy array) – mask that contains True at the positions of the selected points and False otherwise. Mask is of shape cshape.

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

find_nearest_sph(points_1, points_2, points_3, distance, domain='sph', convention='top_colat', unit='rad', show=False, atol=1e-15)[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 1e-15.

Returns:

• index (numpy array of ints) – The locations of the neighbors in the getter methods (e.g., get_cart). Dimension as in find_nearest_k. Missing neighbors are indicated with csize. Also see Notes below.

• mask (boolean numpy array) – mask that contains True at the positions of the selected points and False otherwise. Mask is of shape cshape.

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 to cKDTree. The index that is returned refers to the reshaped coordinate points. To access the points for example use

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

find_slice(coordinate: str, unit: str, value, tol=0, show=False, atol=1e-15)[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 [value-tol, value+tol]. The default is 0.

• 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 1e-15.

Returns:

• index (numpy array of ints) – 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)

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

>>> 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, and points[...,2] the points for the third coordinate.

Return type:

numpy array

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

>>> 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, and points[...,2] the points for the third coordinate.

Return type:

numpy array

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

sph, top_elev

azimuth

elevation

sph, side

lateral

polar

sph, front

phi

theta

>>> 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, and points[...,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 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
>>> coordinates = pf.samplings.sph_gaussian(sh_order=3)


Rotate 45 degrees about the y-axis using

1. quaternions

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

1. a rotation matrix

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

1. a rotation vector

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

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

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

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

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

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

sph, top_elev

azimuth

elevation

sph, side

lateral

polar

sph, front

phi

theta

>>> 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 a scatter plot of the coordinate points.

Parameters:
• mask (boolean numpy array, None, optional) – Plot points in red if mask==True. The default is None, 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' or unit='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 x-direction and pi/2 at positive y-direction (counter clockwise rotation). The height is identical to the z-coordinate and the radius is measured orthogonal from the z-axis.

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

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 z-axis and is 0 at the North Pole and pi at the South Pole. The azimuth is 0 at positive x-direction and pi/2 at positive y-direction (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

Notes

To ensure proper handling of the azimuth angle, the arctan2 implementation from numpy is used.

Transforms from cylindrical to Cartesian coordinates.

Cylindrical coordinates follow the convention that the azimuth is 0 at positive x-direction and pi/2 at positive y-direction (counter clockwise rotation). The height is identical to the z-coordinate and the radius is measured orthogonal from the z-axis.

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

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.

Transforms from spherical to Cartesian coordinates.

Spherical coordinates follow the common convention in Physics/Mathematics. The colatitude is measured downwards from the z-axis and is 0 at the North Pole and pi at the South Pole. The azimuth is 0 at positive x-direction and pi/2 at positive y-direction (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