cart2sphvec

Convert vector from cartesian representation to spherical representation

Syntax

vs = cart2sphvec(vr,az,el)

Description

vs = cart2sphvec(vr,az,el) converts the components of a vector or set of vectors, vr, from their representation in a local cartesian coordinate system to a spherical basis representation contained in vs. A spherical basis representation is the set of components of a vector projected into a basis given by $$({\widehat{e}}_{az},{\widehat{e}}_{el},{\widehat{e}}_R)$$. The orientation of a spherical basis depends upon its location on the sphere as determined by azimuth, az, and elevation, el. See Spherical basis representation of vectors (Phased Array System Toolbox).

Each column of vs is a vector in the spherical basis. The third dimension of vs can correspond to different spherical bases if az and el.

Examples

Spherical Representation of Unit Z-Vector

Start with a vector in Cartesian coordinates pointing along the z-direction and located at 45° azimuth, 45° elevation. Compute its components with respect to the spherical basis at that point.

vr = [0;0;1];
vs = cart2sphvec(vr,45,45)

vs = 3×1

         0
    0.7071
    0.7071

Spherical Representations of Vectors at Two Points

Start with a two vectors in Cartesian coordinates, one pointing along the z-direction and the other pointing in the y-direction.

Load the vector pairs into two different pages. The pages correspond to points (az=20,el=2) and (az=90,el=35). Compute the components of these vectors with respect to the spherical bases at these points.

az = [20 90];
el = [2 35];

Set up page 1 with two vectors.

vr1 = [0 0 1];
vr2 = [0 1 0];
vr = [vr1' vr2']

vr = 3×2

    0    0
    0    1
    1    0

Put the same vectors into page 2.

vr(:,:,2) = vr

vr = 
vr(:,:,1) =

     0     0
     0     1
     1     0


vr(:,:,2) =

     0     0
     0     1
     1     0

Compute the spherical representations.

vs = cart2sphvec(vr,az,el)

vs = 
vs(:,:,1) =

         0    0.9397
    0.9994   -0.0119
    0.0349    0.3418


vs(:,:,2) =

         0         0
    0.8192   -0.5736
    0.5736    0.8192

Input Arguments

vr — Vector in cartesian basis representation

real-valued 3-by-N matrix | real-valued 3-by-N-by-M MATLAB^® array

Vectors in a cartesian basis representation, specified as a real-valued 3-by-N matrix or a real-valued 3-by-N-by-M MATLAB array. N is the number of vectors to convert.

• If vr is a 3-by-N matrix, each column represents a vector in one spherical basis defined by a scalar az and el arguments.

• If vr is a 3-by-N-by-M MATLAB array, each column each column represents a vector in a cartesian basis. Each column of vr contains the three components of a vector in the right-handed cartesian basis. Each page of vr corresponds to different spherical bases. Both the az and el input arguments must be length-M row vectors. Each entry in the az and el vectors corresponds to a page in vr. The m^-th page of vr is converted using the m^-th values of az and el.

Example: [4.0;-3.5;6.3]

Data Types: single | double

az — Azimuth angle

scalar | real-valued M-by-1 vector

Azimuth angle, specified as a scalar or real-valued M-by-1 vector in the closed range [–180,180]. M is the number of azimuth angles and must match the size of el. To define the azimuth angle of a point on a sphere, construct a vector from the origin to the point. The azimuth angle is the angle in the xy-plane from the positive x-axis to the vector's orthogonal projection into the xy-plane. As examples, 0° azimuth angle and 0° elevation angle specify a point on the x-axis while an azimuth angle of –90° and an elevation angle of 0° specify a point on the y-axis. Angle units are in degrees.

Example: [10,45]

Data Types: single | double

el — Elevation angle

scalar | real-valued M-by-1 vector

Elevation angle specified as a scalar or real-valued M-by-1 vector in the closed range [–90,90]. M is the number of elevation angles and must match the size of az. To define the elevation angle of a point on the sphere, construct a vector from the origin to the point. The elevation angle is the angle from vector's orthogonal projection into the xy-plane to the vector itself. As examples, 0° elevation angle defines the equator of the sphere and ±90° elevation define the north and south poles, respectively. Angle units are in degrees.

Example: [2,-3]

Data Types: single | double

Output Arguments

vs — Spherical basis representation of input vectors

real-valued 3-by-N matrix | real-valued 3-by-N-M MATLAB array

Spherical basis representation of output vectors, returned as a real-valued 3-by-N matrix or real-valued MATLAB array. vs has the same size as vr. Each column of vs contains the three components of the vector in a right-handed $$({\widehat{e}}_{az},{\widehat{e}}_{el},{\widehat{e}}_R)$$ basis.

More About

Spherical basis representation of vectors

Spherical basis vectors are a local set of basis vectors which point along the radial and angular directions at any point in space.

The spherical basis is a set of three mutually orthogonal unit vectors $$({\widehat{e}}_{az},{\widehat{e}}_{el},{\widehat{e}}_R)$$ defined at a point on the sphere. The first unit vector points along lines of azimuth at constant radius and elevation. The second points along the lines of elevation at constant azimuth and radius. Both are tangent to the surface of the sphere. The third unit vector points radially outward.

The orientation of the basis changes from point to point on the sphere but is independent of R so as you move out along the radius, the basis orientation stays the same. The following figure illustrates the orientation of the spherical basis vectors as a function of azimuth and elevation:

For any point on the sphere specified by az and el, the basis vectors are given by:

$$\begin{array}{ll}{\widehat{e}}_{az}\hfill & =-\sin (az)\widehat{i}+\cos (az)\widehat{j}\hfill \\ {\widehat{e}}_{el}\hfill & =-\sin (el)\cos (az)\widehat{i}-\sin (el)\sin (az)\widehat{j}+\cos (el)\widehat{k}\hfill \\ {\widehat{e}}_R\hfill & =\cos (el)\cos (az)\widehat{i}+\cos (el)\sin (az)\widehat{j}+\sin (el)\widehat{k}\text{.}\hfill \end{array}$$

Any vector can be written in terms of components in this basis as $$v=v_{az}{\widehat{e}}_{az}+v_{el}{\widehat{e}}_{el}+v_R{\widehat{e}}_R$$. The transformations between spherical basis components and Cartesian components take the form

$$\left[\begin{array}{c}{v}_x\\ v_y\\ v_z\end{array}\right]=\left[\begin{array}{ccc}-\sin (az)& -\sin (el)\cos (az)& \cos (el)\cos (az)\\ \cos (az)& -\sin (el)\sin (az)& \cos (el)\sin (az)\\ 0& \cos (el)& \sin (el)\end{array}\right]\left[\begin{array}{c}{v}_{az}\\ v_{el}\\ v_R\end{array}\right]$$

.

and

$$\left[\begin{array}{c}{v}_{az}\\ v_{el}\\ v_R\end{array}\right]=\left[\begin{array}{ccc}-\sin (az)& \cos (az)& 0\\ -\sin (el)\cos (az)& -\sin (el)\sin (az)& \cos (el)\\ \cos (el)\cos (az)& \cos (el)\sin (az)& \sin (el)\end{array}\right]\left[\begin{array}{c}{v}_x\\ v_y\\ v_z\end{array}\right]$$.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

Does not support variable-size inputs.

Version History

Introduced in R2020a

R2026a: Multiple spherical coordinate systems

The version accepts vector inputs to support multiple spherical coordinate systems.