Coordinates¶

Generate, store, and manipulate points in 3D coordinate systems.

The core of this module is the Coordinates class. It can convert between coordinate conventions and rotate, query and plot coordinates points. Functions for converting coordinates not stored in a Coordinates object are available for convenience. However, it is strongly recommended to use the:py:func:Coordinates class for all conversions.

Coordinate systems are defined by their domain (e.g. 'spherical'), convention (e.g. 'top_elev'), and unit (e.g. 'deg'). A complete list and description of supported coordinate systems is given in the image below

and can be obtained by

>>> coords = Coordinates()  # get an empty instance of the class
>>> coords.systems()        # list all systems

A plethora of sampling schemes to generate coordinate objects is contained in 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.
`copy`()	Return a deep copy of the Coordinates object.
`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_nearest_cart`(points_1, points_2, …[, …])	Find coordinates within a certain distance in meters to query points.
`get_nearest_k`(points_1, points_2, points_3)	Find the k nearest coordinates points.
`get_nearest_sph`(points_1, points_2, …[, …])	Find coordinates within certain angular distance to the query points.
`get_slice`(coordinate, unit, value[, tol, …])	Get a slice of the coordinates points.
`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:

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

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

Return type

numpy array

get_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 according to distance (see above). 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

Get frontal points within a distance of 0.5 meters

>>> import pyfar as pf
>>> coords = pf.samplings.sph_lebedev(sh_order=10)
>>> result = coords.get_nearest_cart(1, 0, 0, 0.5, show=True)

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

get_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

distance (numpy array of floats) – The euclidian distances to the nearest neighbors. If the points have the shape tuple, then the distance has the shape tuple+(k,). When k == 1, the last dimension is squeezed. Missing neighbors are indicated with infinite distances.
index (numpy array of ints) – The locations of the neighbors in the getter methods (e.g., self.get_cart). Dimension according to distance (see above). 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

Get frontal point from a spherical coordinate system

>>> import pyfar as pf
>>> coords = pf.samplings.sph_lebedev(sh_order=10)
>>> result = coords.get_nearest_k(1, 0, 0, show=True)

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

get_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 according to distance (see above). 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

Get top points within a distance of 45 degrees

>>> import pyfar as pf
>>> coords = pf.samplings.sph_lebedev(sh_order=10)
>>> result = coords.get_nearest_sph(0, 0, 1, 45, show=True)

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

get_slice(coordinate: str, unit: str, value, tol=0, show=False, atol=1e-15)[source]¶

Get 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

mask – mask that contains True at the positions of the selected points and False otherwise. Mask is of shape self.cshape.

Return type

boolean numpy array

Notes

value must be inside the range of the coordinate (see .systems). However, value +/- tol may exceed the range.

Examples

Get 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.get_slice('elevation', 'deg', 0, 10, show=True)

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

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

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 and black elsewhere. 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.

Returns

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.

$azimuth &= \arctan(\frac{y}{x}), height &= z, radius &= \sqrt{x^2 + y^2},$

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

$azimuth &= \arctan(\frac{y}{x}), colatitude &= \arccos(\frac{z}{r}), radius &= \sqrt{x^2 + y^2 + z^2}$

$0 < azimuth < 2 \pi, 0 < colatitude < \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
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 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.

$x &= radius \cdot \cos(azimuth), y &= radius \cdot \sin(azimuth), z &= height$

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

$x &= radius \cdot \sin(colatitude) \cdot \cos(azimuth), y &= radius \cdot \sin(colatitude) \cdot \sin(azimuth), z &= radius \cdot \cos(colatitude)$

$0 < azimuth < 2 \pi 0 < colatitude < \pi$

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