geom3d: update doc for spherical <-> cartesian coordinates conversion…

… functions
mattools · Jun 3, 2021 · 973fe2f · 973fe2f
1 parent 559a6f1
commit 973fe2f
Show file tree

Hide file tree

Showing 6 changed files with 70 additions and 33 deletions.
diff --git a/matGeom/geom3d/cart2sph2.m b/matGeom/geom3d/cart2sph2.m
@@ -1,5 +1,5 @@
 function varargout = cart2sph2(varargin)
-%CART2SPH2 Convert cartesian coordinates to spherical coordinates.
+%CART2SPH2 Convert cartesian coordinates to spherical coordinates.
 %
 %   [THETA PHI RHO] = cart2sph2([X Y Z])
 %   [THETA PHI RHO] = cart2sph2(X, Y, Z)
@@ -19,7 +19,7 @@
 %   cart2sph2([0 0 1])  returns [0 0 1];
 %
 %   See also:
-%   angles3d, sph2cart2, cart2sph, cart2sph2d
+%     angles3d, sph2cart2, cart2sph, cart2sph2d
 %
 
 %   ---------
@@ -33,18 +33,22 @@
 %   03/11/2006: change convention for angle : uses order [THETA PHI RHO]
 %   27/06/2007: manage 2 output arguments
 
-if length(varargin)==1
-    var = varargin{1};
-elseif length(varargin)==3
-    var = [varargin{1} varargin{2} varargin{3}];
+% parse input angles based on input argument number
+if length(varargin) == 1
+    xyz = varargin{1};
+elseif length(varargin) == 3
+    xyz = [varargin{1} varargin{2} varargin{3}];
 end
 
-if size(var, 2)==2
-    var(:,3)=1;
+% ensure z coordinate is specified
+if size(xyz, 2) == 2
+    xyz(:,3) = 1;
 end
 
-[p, t, r] = cart2sph(var(:,1), var(:,2), var(:,3));
+% convert to spherical coordinates
+[p, t, r] = cart2sph(xyz(:,1), xyz(:,2), xyz(:,3));
 
+% format output arguments
 if nargout == 1 || nargout == 0
     varargout{1} = [pi/2-t p r];
 elseif nargout==2

diff --git a/matGeom/geom3d/cart2sph2d.m b/matGeom/geom3d/cart2sph2d.m
@@ -1,5 +1,5 @@
 function varargout = cart2sph2d(x, y, z)
-%CART2SPH2D Convert cartesian coordinates to spherical coordinates in degrees.
+%CART2SPH2D Convert cartesian coordinates to spherical coordinates in degrees.
 %
 %   [THETA PHI RHO] = cart2sph2d([X Y Z])
 %   [THETA PHI RHO] = cart2sph2d(X, Y, Z)
@@ -26,13 +26,18 @@
 %     ans =
 %       0    0    1
 %
+%     % check consistency with sph2cart2d
+%     sph2cart2d(cart2sph2d(30, 40, 5))
+%     ans =
+%         30.0000   40.0000    5.0000
 %
 %   See also:
-%   angles3d, sph2cart2d, cart2sph, cart2sph2
+%     angles3d, sph2cart2d, cart2sph, cart2sph2
 %
+
 % ------
 % Author: David Legland
-% e-mail: david.legland@grignon.inra.fr
+% e-mail: david.legland@inrae.fr
 % Created: 2011-06-29,    using Matlab 7.9.0.529 (R2009b)
 % Copyright 2011 INRA - Cepia Software Platform.
 
@@ -49,10 +54,6 @@
 theta   = 90 - atan2(z, hxy) * 180 / pi;
 phi     = atan2(y, x) * 180 / pi;
 
-% % convert to degrees and theta to colatitude
-% theta   = 90 - rad2deg(theta);
-% phi     = rad2deg(phi);
-
 % format output
 if nargout <= 1
     varargout{1} = [theta phi rho];

diff --git a/matGeom/geom3d/sph2cart2.m b/matGeom/geom3d/sph2cart2.m
@@ -2,11 +2,11 @@
 %SPH2CART2 Convert spherical coordinates to cartesian coordinates.
 %
 %   C = SPH2CART2(S)
-%   C = SPH2CART2(THETA, PHI)       (assume rho = 1)
+%   C = SPH2CART2(THETA, PHI)       (assuming rho = 1)
 %   C = SPH2CART2(THETA, PHI, RHO)   
 %   [X, Y, Z] = SPH2CART2(THETA, PHI, RHO);
 %
-%   S = [phi theta rho] (spherical coordinate).
+%   S = [theta phi rho] (spherical coordinate).
 %   C = [X Y Z]  (cartesian coordinate)
 %
 %   The following convention is used:
@@ -18,13 +18,29 @@
 %   Discussion on choice for convention can be found at:
 %   http://www.physics.oregonstate.edu/bridge/papers/spherical.pdf
 %
+%   Example
+%     xyz = sph2cart2(pi/2, 0, 10)
+%     xyz =
+%        10.0000         0    0.0000
+%
+%     xyz = sph2cart2(pi/2, pi/2, 10)
+%     xyz =
+%         0.0000   10.0000    0.0000
+%
+%     % check consistency with cart2sph2
+%     sph2cart2(cart2sph2(0.7, 0.8, 5))
+%     ans =
+%         0.7000    0.8000    5.0000
+%
 %   See also:
-%   angles3d, cart2sph2, sph2cart, sph2cart2d
+%     angles3d, cart2sph2, sph2cart, sph2cart2d, eulerAnglesToRotation3d
 %
-%   ---------
-%   author : David Legland 
-%   INRA - TPV URPOI - BIA IMASTE
-%   created the 18/02/2005.
+
+% ------
+% Author: David Legland
+% e-mail: david.legland@inrae.fr
+% INRAE - BIA Research Unit - BIBS Platform (Nantes)
+% created the 18/02/2005.
 %
 
 %   HISTORY
@@ -53,6 +69,7 @@
 y  = rz  .* sin(phi);
 z  = rho .* cos(theta);
 
+% format output
 if nargout <= 1
     varargout{1} = [x, y, z];
 else

diff --git a/matGeom/geom3d/sph2cart2d.m b/matGeom/geom3d/sph2cart2d.m
@@ -1,12 +1,12 @@
 function varargout = sph2cart2d(theta, phi, rho)
-%SPH2CART2D Convert spherical coordinates to cartesian coordinates in degrees.
+%SPH2CART2D Convert spherical coordinates to cartesian coordinates in degrees.
 %
-%   C = SPH2CART2(THETA, PHI, RHO)
-%   C = SPH2CART2(THETA, PHI)       (assume rho = 1)
-%   C = SPH2CART2(S)
-%   [X, Y, Z] = SPH2CART2(THETA, PHI, RHO);
+%   C = SPH2CART2D(THETA, PHI, RHO)
+%   C = SPH2CART2D(THETA, PHI)       (assume rho = 1)
+%   C = SPH2CART2D(S)
+%   [X, Y, Z] = SPH2CART2D(THETA, PHI, RHO);
 %
-%   S = [phi theta rho] (spherical coordinate).
+%   S = [theta phi rho] (spherical coordinate).
 %   C = [X Y Z]  (cartesian coordinate)
 %
 %   The following convention is used:
@@ -18,12 +18,27 @@
 %   Discussion on choice for convention can be found at:
 %   http://www.physics.oregonstate.edu/bridge/papers/spherical.pdf
 %
+%   Example
+%     xyz = sph2cart2d(90, 0, 10)
+%     xyz =
+%        10    0    0
+%
+%     xyz = sph2cart2d(90, 90, 10)
+%     xyz =
+%         0   10    0
+%
+%     % check consistency with cart2sph2d
+%     cart2sph2d(sph2cart2d(30, 40, 5))
+%     ans =
+%        30.0000   40.0000    5.0000
+%
 %   See also:
-%   angles3d, cart2sph2d, sph2cart2
+%     angles3d, cart2sph2d, sph2cart2, eulerAnglesToRotation3d
 %
+
 % ------
 % Author: David Legland
-% e-mail: david.legland@grignon.inra.fr
+% e-mail: david.legland@inrae.fr
 % Created: 2011-06-29,    using Matlab 7.9.0.529 (R2009b)
 % Copyright 2011 INRA - Cepia Software Platform.
 

diff --git a/tests/geom3d/test_cart2sph2.m b/tests/geom3d/test_cart2sph2.m
@@ -11,7 +11,7 @@
 %
 % ------
 % Author: David Legland
-% e-mail: david.legland@grignon.inra.fr
+% e-mail: david.legland@inrae.fr
 % Created: 2011-06-29,    using Matlab 7.9.0.529 (R2009b)
 % Copyright 2011 INRA - Cepia Software Platform.
 

diff --git a/tests/geom3d/test_sph2cart2.m b/tests/geom3d/test_sph2cart2.m
@@ -11,7 +11,7 @@
 %
 % ------
 % Author: David Legland
-% e-mail: david.legland@grignon.inra.fr
+% e-mail: david.legland@inrae.fr
 % Created: 2011-06-29,    using Matlab 7.9.0.529 (R2009b)
 % Copyright 2011 INRA - Cepia Software Platform.