; docformat = 'rst'
;
; NAME:
;    SPH2CART
; PURPOSE:
;    Convert spherical coordinates into cartesian coordinates
;
;+
; :Description:
;    SPH2CART converts polar/spherical coordinates into 2-D or 3-D
;    cartesian coordinates 
;
; :Categories:
;    Coordinates, Convertion
;    
; :Params:
;    C1: in, required, type=float
;        Polar/Spherical coordinates. C1 can be a Nx[1,2,3] array, if Nx1
;        then C1 contains only the first coordinate ("R"), if Nx2, C1
;        contains the two first coordinates ("R,Theta"), if Nx3 then C1
;        contains the 3-D coordinates ("R,Theta,Phi")
;    C2: in, optional, type=float
;        Polar/Spherical second coordinate ("Theta")
;    C3: in, optional, type=float
;        Spherical third coordinate  ("Phi")
;
; :Returns: The input coordinates converted in 2-D or 3-D cartesian
;
; :Examples:
;    Compute the cartesian coordinates of the point [r,t,p] = [1.73205, 45.0000, 35.2644]
;      IDL> print, sph2carT(1.73205, 45.0000, 35.2644 )     
;           0.999999     0.999999      1.00000
;
; :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 SPH2CART, 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 -  CART =  SPH2CART( C1, [C2, C3] )'
    return, -1
 endif

 ;--I.2-- Decode Input Variables into R,Theta,Phi Coordinates
  dims=size(C1)
  if keyword_set(C2) then begin
    r=c1
    theta=c2
    if keyword_set(C3) then phi=c3
     
  endif else begin

    if dims(0) eq 1 then begin
      r=c1(0)
      theta=c1(1)
      if dims(1) eq 3 then phi=c1(2)
    endif else begin
      r=c1(0,*)
      theta=c1(1,*)
      if dims(1) eq 3 then phi=c1(2,*)
    endelse

  endelse

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

    x = reform( r * cos( theta ) )
    y = reform( r * sin( theta ) )
    coord = transpose([ [x], [y] ])

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

    x = reform( r * cos( theta ) * cos( phi ) )
    y = reform( r * sin( theta ) * cos( phi ) )
    z = reform( r * sin( phi ) )
    coord = transpose([ [x], [y], [z] ])

  endelse

 ;--IV-- Return Cartesian Coordinates  -------------------------------------------------
  return, coord

end