; docformat = 'rst'
;
; NAME:
;    CART2SPH
; PURPOSE:
;    Convert cartesian coordinates into spherical coordinates
;
;+
; :Description:
;    CART2SPH converts 2-D or 3-D cartesian coordinates into
;    polar/spherical coordinates 
;
; :Categories:
;    Coordinates, Convertion
;    
; :Params:
;    C1: in, required, type=float
;        Cartesian coordinates. C1 can be a Nx[1,2,3] array, if Nx1
;        then C1 contains only the first coordinate ("X"), if Nx2, C1
;        contains the two first coordinates ("X,Y"), if Nx3 then C1
;        contains the 3-D coordinates
;    C2: in, optional, type=float
;        Cartesian second coordinate ("Y")
;    C3: in, optional, type=float
;        Cartesian third coordinate  ("Z")
;
; :Returns: The input coordinates converted in polar (2-D) or
;        spherical (3-D) (angles in radians)
;
; :Examples:
;    Compute the spherical coordinates of the point [x,y,z] = [1,1,1]::
;      IDL> print, cart2sph( 1,1,1. )
;           1.73205      45.0000      35.2644
;
; :Author:
;    B.Carry (IMCCE)
;
; :History:
;     Change History::
;        Written in February 2009, B. Carry (ESO/LESIA)
;        2013 Sep. - B.Carry (IMCCE) - Code cleaned
;        2013 Nov. - B.Carry (IMCCE) - Allows multi-dimensions C1 
;-
function CART2SPH, C1, C2, C3
  COMPILE_OPT hidden


 ;--I-- Initialization And Input Verification  ----------------------------------------
 ;--I.1-- Check Presence of Arguments
  if N_params() LT 1 then begin
    message, /INFO, ' Syntax -  SPH =  CART2SPH( C1, [C2, C3] )'
    return, -1
 endif


 ;--I.2-- Decode Input Variables into X,Y,Z Coordinates
  dims=size(C1)
  if keyword_set(C2) then begin
    x=c1
    y=c2
    if keyword_set(C3) then z=c3
     
  endif else begin

    if dims(0) eq 1 then begin
      x=c1(0)
      y=c1(1)
      if dims(1) eq 3 then z=c1(2)
    endif else begin
      x=c1(0,*)
      y=c1(1,*)
      if dims(1) eq 3 then z=c1(2,*)
    endelse

  endelse



 ;--II-- Coordinates in 2-D: Polar  ----------------------------------------------------
  if not keyword_set(z) then begin

    radius = reform( sqrt( x^2. + y^2. ) ) 
    theta  = reform( atan( y, x ) )
    coord = transpose([ [radius], [theta] ])

 ;--III-- Coordinates in 3-D: Spherical  ------------------------------------------------
  endif else begin

    radius = reform( sqrt( x^2. + y^2. + z^2. ) )
    theta  = reform( atan( y, x ) )
      phi  = reform( atan( z, sqrt( x^2. + y^2.) ) )
    coord = transpose([ [[radius]], [[theta]], [[phi]]], [2,0,1] ) 

  endelse

 ;--IV-- Return Spherical/Polar Coordinates  --------------------------------------------
  return, reform(coord)

end