cart2sph

Transform Cartesian coordinates to spherical

Syntax

[azimuth,elevation,r] = cart2sph(x,y,z)

Description

[azimuth,elevation,r] = cart2sph(x,y,z) transforms corresponding elements of the Cartesian coordinate arrays x, y, and z to spherical coordinates azimuth, elevation, and r.

Examples

Cartesian to Spherical Coordinates

Convert the Cartesian coordinates defined by corresponding entries in the matrices x, y, and z to spherical coordinates az, el, and r. These points correspond to the eight vertices of a cube.

x = [1 1 1 1; -1 -1 -1 -1]

x = 2×4

     1     1     1     1
    -1    -1    -1    -1

y = [1 1 -1 -1; 1 1 -1 -1]

y = 2×4

     1     1    -1    -1
     1     1    -1    -1

z = [1 -1 1 -1; 1 -1 1 -1]

z = 2×4

     1    -1     1    -1
     1    -1     1    -1

[az,el,r] = cart2sph(x,y,z)

az = 2×4

    0.7854    0.7854   -0.7854   -0.7854
    2.3562    2.3562   -2.3562   -2.3562

el = 2×4

    0.6155   -0.6155    0.6155   -0.6155
    0.6155   -0.6155    0.6155   -0.6155

r = 2×4

    1.7321    1.7321    1.7321    1.7321
    1.7321    1.7321    1.7321    1.7321

Input Arguments

x,y,z — Cartesian coordinates

scalars | vectors | matrices | multidimensional arrays

Cartesian coordinates, specified as scalars, vectors, matrices, or multidimensional arrays. x, y, and z must be the same size, or have sizes that are compatible (for example, x is an M-by-N matrix, y is a scalar, and z is a scalar or 1-by-N row vector). For more information, see Compatible Array Sizes for Basic Operations.

Data Types: single | double

Output Arguments

azimuth — Azimuth angle

array

Azimuth angle, returned as an array. azimuth is the counterclockwise angle in the x-y plane measured in radians from the positive x-axis. The value of the angle is in the range [-pi pi].

elevation — Elevation angle

array

Elevation angle, returned as an array. elevation is the elevation angle in radians from the x-y plane. The value of the angle is in the range [-pi/2, pi/2].

r — Radius

array

Radius, returned as an array. r is the distance from the origin to a point. The length units of r are arbitrary, matching the units of the input arrays x, y, and z.

Algorithms

The mapping from three-dimensional Cartesian coordinates to spherical coordinates is

azimuth = atan2(y,x)
elevation = atan2(z,sqrt(x.^2 + y.^2))
r = sqrt(x.^2 + y.^2 + z.^2)

The notation for spherical coordinates is not standard. For the cart2sph function, elevation is measured from the x-y plane. Notice that if elevation = 0, the point is in the x-y plane. If elevation = pi/2, then the point is on the positive z-axis.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The cart2sph function fully supports tall arrays. For more information, see Tall Arrays.

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• If you use cart2sph with single type and double type operands, the generated code might not produce the same result as MATLAB^®. See Binary Element-Wise Operations with Single and Double Operands (MATLAB Coder).

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The cart2sph function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a