Dear madam/sir,
I have been struggling with the function (theta,phi,R) = cart2sph(x,y,z) for some time and found out that
the description in the octave manual is not exactly in line with its behaviour.
But I found out that:
In the manual it is told that:
'theta represents the angle relative to the positive x-axis'
The angle relative to the positive x-axis is mathematically defined as the dotproduct of a position
vector r with the unitvector in the x-direction. This is in line with default mathematical representation
of spherical polar coordinates where theta represents the angle between position vector and unitvector z axis.
I assumed from the description in the manual that in Octave unit x took over the role of unit z, which apparently isn't.
Moreover, the angle phi is the elevation angle above the x-y-plane.
However, I found out that the angle theta using cart2sph is defined as the angle of the orthogonal projection
of position vector r onto the xy plane with the unitvector x.
This is in line with the definition of cart2sph in MatLab, where it is explicitly said that
theta represents the azimuth angle and phi the elevation angle.
This is in line with the description in the Octave manual.
It would be nice and less confusing if the words azimuth and elevation were used in this context, if possible with
a small graph.
so, just to verify, the cart2sph ordering is the same as Matlab:
Matlab 2019a:
>> [a b c] = cart2sph(1,2,3)
a =
1.1071
b =
0.9303
c =
3.7417
Octave 5.1.0:
>> [a b c] = cart2sph(1,2,3)
a = 1.1071
b = 0.93027
c = 3.7417
the only compatibility concern i see is that if nargout = 0 or 1, Matlab only gives the first return value [1x1], and Octave gives teh full set as a [1x3] array. This could result in a nonconformance mismatch between transferred code.
I don't see anything in the bug database to capture that, so I filed one here:
I noted the variable usage concern, but the current convention does match matlab behavior. and from the wiki Doug linked:
"
However, some authors (including mathematicians) use φ for inclination (or elevation) and θ for azimuth, which "provides a logical extension of the usual polar coordinates notation".[2] Some authors may also list the azimuth before the inclination (or elevation)"
The only deviation is that elevation is measured from the xy plane and not the z axis, but both matlab and octave specify this usage. But thus even the use of 'elevation' doesn't necessarily clear up any discrepancy.
Without changing too much, would it help to simply add:
"theta describes the angle relative to the positive x-axis measured in the x-y plane"
Otherwise it seems the text accurately describes the usage.