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)

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:

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)

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') 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()

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)

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)

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

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)

(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=1e-15)

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)

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

find_slice(coordinate: str, unit: str, value, tol=0, show=False, atol=1e-15)

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

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

Return type:

numpy array

get_cyl(convention='top', unit='rad', convert=False)

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

Return type:

numpy array

get_sph(convention='top_colat', unit='rad', convert=False)

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

Return type:

numpy array

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

2. a rotation matrix

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

3. a rotation vector

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

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

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

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

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)

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)

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)

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

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

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

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

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

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

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

• radius (numpy array, number) – radii

Returns:

• x (numpy array, number) – x values

• y (numpy array, number) – y values

• z (numpy array, number) – z vales