# 2.8.28 sph2cart

## Brief Information

Convert spherical coordinates to Cartesian

Minimum Origin Version Required:9.1 SR0

## Command Line Usage

 1. sph2cart format:=virmat iw:=[Book1]Sheet1! omx:=<new>!<new> omy:=<same>!<new> omz:=<same>!<new>;//Convert the virtual matrix data in Book1 Sheet1 and output the three matrix objects for X Y Z to the same matrix sheet. 

2. sph2cart ir:=[Book1]Sheet1!(A,B,C)[1:3] unit:=1 oz:=<new>!(<new>,<new>,<new>);//Convert the XYZ worksheet column data and output the resulting XYZ data to a new worksheet as XYZ columns. 

3. sph2cart format:=mats ima:=[MBook1]MSheet1!1 ime:=[MBook2]MSheet1!1 imr:=[MBook3]MSheet1!1;//Convert three matrix objects in different matrix books and output three matrix books for converted X, Y and Z data. 

## Variables

Display
Name
Variable
Name
I/O
and
Type
Default
Value
Description
Data Format format

Input

int

0
Specify the input data format. The input is presumed to use a spherical coordinate system.

Option list:

• xyz:XYZ{0}
Specify input data format as three columns in worksheet with plot designations of XYZ.
• virmat:Virtual matrix{1}
Specify input data format as virtual matrix.
• mat:Matrix object{2}
Specify input data format as one matrix object.
• mats:Three matrices in a layer{3}
Specify input data format as three matrix objects. The three matrix objects need to have the same dimensions.
Input ir

Input

XYZRange

<active>
This variable is only valid when the format variable is set to xyz. It is used to specify the input XYZ data range.
Azimuth ima

Input

MatrixObject

<active>
This variable is only valid when the format variable is set to mats. It is used to specify the input matrix object for Azimuth data.
Elevation ime

Input

MatrixObject

<active>
This variable is only valid when the format variable is set to mats. It is used to specify the input matrix object for Elevation data.

Input

MatrixObject

<active>
This variable is valid when the format variable is set to mat or mats. If the format was mat, this variable specifies the input matrix object. If the format was mats, it then specifies the input matrix object for the Radius data.
Input iw

Input

Worksheet

<active>
This variable is only valid when the format variable is set to virmat. It is used to specify the worksheet range of the virtual matrix.
Angle Data angle

Input

int

0
This variable is only valid when the format variable is set to virmat or mat. It specifies how the Azimuth and Elevation values are considered to be arranged in the source data.

Option list:

• 0:Azimuth Across Columns
If the format is virmat, use a row as Azimuth values and the first data column as Elevation values. The row for Azimuth value can be specified by the Azimuth Values in variable.
If the format is mat, use the X values of the matrix as Azimuth values, and Y values as Elevation values.
• 1:Elevation Across Columns
If the format is virmat, use a row as Elevation values and the first data column as Azimuth values. The row for Elevation value can be specified by the Elevation Values in variable.
If the format is mat, use the X values of the matrix as Elevation values, and Y values as Azimuth values.
Azimuth Values in alabel

Input

int

0
This variable is only valid when the angle variable is set to 0(Azimuth Across Columns). It specifies the data source of Azimuth values.

Option list:

• first:First Data Row{0}
Use the first data row in input worksheet as Azimuth values.
• second:Column Label{1}
Use the values in a column label row as Azimuth values. The column label row can be specified by the param variable.
Elevation Values in elabel

Input

int

0

This variable is only valid when the angle variable is set to 1(Elevation Across Columns). It specifies the data source of Elevation values.

Option list:

• first:First Data Row{0}
Use the first data row in input worksheet as Elevation values.
• second:Column Label{1}
Use the values in a column label row as Elevation values. The column label row can be specified by the param variable.
Column Label param

Input

int

0
This variable is only valid when the alabel or elabel variable is set to second or 1 (Column Label). It specifies the column label row to be used as Azimuth or Elevation data.

Option list:

• longname:Long Name{0}
Use the values in Long Name row as Azimuth/Elevation data.
• units:Units{1}
Use the values in Units row as Azimuth/Elevation data.
Use the values in Comments row as Azimuth/Elevation data.
Angular Unit unit

Input

int

0
This variable specifies the Azimuth unit for input data.

Option list:

The input data is expressed in Radians.
• 1:Degree
The input data is expressed in Degrees.
X omx

Output

MatrixObject

<new>
This variable is valid when the format variable is NOT set to XYZ. It specifies where to output the converted X value. The converted X value will be the Z value in this output matrix object.
Y omy

Output

MatrixObject

<new>
This variable is valid when the format variable is NOT set to XYZ. It specifies where to output the converted Y value. The converted Y value will be the Z value in this output matrix object.
Z omz

Output

MatrixObject

<new>
This variable is valid when the format variable is NOT set to XYZ. It specifies where to output the converted Z value. The converted Z value will be the Z value in this output matrix object.
Output oz

Output

XYZRange

<new>
This variable is only valid when the format variable is set to XYZ. It specifies the worksheet range to output the converted XYZ data.

## Description

This tool is used to convert data in spherical coordinates to Cartesian coordinates. The input data can be XYZ worksheet columns, a virtual matrix, one matrix object, or three matrix objects with the same dimensions.

You can run the following command in the Script Window or Command Window to bring up the GUI dialog box for this tool:

sph2cart -d;

## Algorithm

The spherical coordinates are defined by $\left (r, \theta, \phi \right )$, in which $r$ is the radius (the distance between the origin and the data point), $\phi$ is the elevation (the angular displacement of the data point from the XY plane, expressed in Radians) and $\theta$ is the azimuth (the angular displacement of the data point from the X axis in the positive direction, i.e. X > 0, expressed in Radians). The image below illustrates how each of the three variables is defined:

The source data for azimuth, elevation and radius vary by input data format:

Input Data Format Azimuth Elevation Radius
XYZ X column Y column Z column
Virtual Matrix/One Matrix Object X value of the virtual matrix/matrix object Y value of the virtual matrix/matrix object Z value of the virtual matrix/matrix object
Three Matrix Objects Z value in the matrix object which is selected for Azimuth Z value in the matrix object which is selected for Elevation Z value in the matrix object which is selected for Radius

Input data are converted from spherical coordinates to Cartesian coordinates, using the following:

$x = r \ast cos\left ( \phi \right ) \ast cos \left ( \theta \right );$

$y = r \ast cos\left ( \phi \right ) \ast sin \left ( \theta \right );$

$z = r \ast sin\left ( \phi \right )$