Conversion

The ear.core.objectbased.conversion module contains functionality to convert AudioBlockFormatObjects objects between polar and Cartesian coordinate conventions, according to section 10 of BS.2127-0.

Conversion functions in this module are not straightforward coordinate conversions, they instead try to minimise the difference in behaviour between the polar and Cartesian rendering paths.

Conversion can not account for all differences between the two rendering paths, and while conversion of position coordinates is invertible, conversion of extent parameters is not, except in simple cases. Because of these limitations, conversion should be used as part of production processes, where the results can be monitored and adjusted.

audioBlockFormat Conversion Functions

These conversions apply conversion to AudioBlockFormatObjects objects, returning a new copy:

ear.core.objectbased.conversion.to_polar(block_format)

Convert a block format to use polar coordinates according to ITU-R BS.2127-0 section 10.

The cartesian flag will be set to match the coordinates used.

The position, width, height and depth will be converted; the rest of the parameters will be unmodified.

Parameters

block_format (ear.fileio.adm.elements.AudioBlockFormatObjects) –

Return type

ear.fileio.adm.elements.AudioBlockFormatObjects

ear.core.objectbased.conversion.to_cartesian(block_format)

Convert a block format to use Cartesian coordinates according to ITU-R BS.2127-0 section 10.

The cartesian flag will be set to match the coordinates used.

The position, width, height and depth will be converted; the rest of the parameters will be unmodified.

Parameters

block_format (ear.fileio.adm.elements.AudioBlockFormatObjects) –

Return type

ear.fileio.adm.elements.AudioBlockFormatObjects

Low-Level Conversion Functions

These functions operate on the individual parameters, and may be useful for testing:

ear.core.objectbased.conversion.point_polar_to_cart(az, el, d)

Convert a position from polar to Cartesian according to ITU-R BS.2127-0 section 10.

Parameters
Returns

converted Cartesian position

Return type

np.ndarray of shape (3,)

ear.core.objectbased.conversion.point_cart_to_polar(x, y, z)

Convert a position from Cartesian to polar according to ITU-R BS.2127-0 section 10.

Parameters

  • x (float) – X coordinate

  • y (float) – Y coordinate

  • z (float) – Z coordinate

Returns

converted azimuth, elevation and distance

Return type

(float, float, float)

ear.core.objectbased.conversion.extent_polar_to_cart(az, el, dist, width, height, depth)

Convert a position and extent parameters from polar to Cartesian according to ITU-R BS.2127-0 section 10.

Parameters

  • az (float) – azimuth

  • el (float) – elevation

  • dist (float) – distance

  • width (float) – width parameter

  • height (float) – height parameter

  • depth (float) – depth parameter

Returns

converted X, Y, Z, width (X size), depth (Y size) and height (Z size)

Return type

(float, float, float, float, float, float)

ear.core.objectbased.conversion.extent_cart_to_polar(x, y, z, xs, ys, zs)

Convert a position and extent parameters from Cartesian to polar according to ITU-R BS.2127-0 section 10.

Parameters

  • x (float) – X coordinate

  • y (float) – Y coordinate

  • z (float) – Z coordinate

  • xs (float) – width (X size)

  • ys (float) – depth (Y size)

  • zs (float) – height (Z size)

Returns

converted azimuth, elevation, distance, width, height and depth

Return type

(float, float, float, float, float, float)