; docformat = 'rst'
;
; NAME:
;    FRAMECOORD_EQ2EC
; PURPOSE:
;    Convert Equatorial coordinates in Ecliptic coordinates or reverse
;
;+
; :Description:
;    Convert Equatorial coordinates in Ecliptic coordinates or reverse
;
; :Categories:
;    Coordinates, Convertion
;    
; :Params:
;    EQ1: in, required, type=float
;        A two-elements vector with equatorial coordinates (deg). If
;        EQ2 is set, then EQ1 must contain a single element only
;        (right ascencion).
;    EQ2: in, optional, type=float
;        The declination can be alternatively provided here (deg).
;
; :Returns: A two-elements vector with coordinates converted in Ecliptic (deg).
;
; :Keywords:
;    EQ_TO_EC: in, optional, type=boolean, default=1
;        If set, transforms EQuatorial coordinates into ECliptic
;    EC_TO_EQ: in, optional, type=boolean, default=0
;        If set, transforms ECliptic coordinates into EQuatorial
;    VERBOSE: in, optional, type=boolean, default=0
;        If set, prints coordinate in standard output
;
; :Examples:
;    Prints several convertions::
;        IDL> print, framecoord_EQ2EC( 0., 0. )
;        IDL> print, framecoord_EQ2EC( [0., 0.] )
;        IDL> print, framecoord_EQ2EC( [210., +20.] )
;
; :Author:
;    B.Carry (OCA)
;
; :History:
;     Change History::
;        Written in July 2008, B. Carry (ESO/LESIA)
;        2013-Nov. -  B.Carry (IMCCE) - Allows input coords in two variables
;        2015 Oct. -  B.Carry (OCA) - Compile option idl2 added
;        2016 Nov. -  B.Carry (OCA) - Corrected bug on ec2eq conversion!
;        2017 Feb. -  B.Carry (OCA) - Allows arrays as input
;-
function frameCoord_EQ2EC, EQ1, EQ2, EQ_TO_EC=EQ_TO_EC, EC_TO_EQ=EC_TO_EQ, VERBOSE=VERBOSE
  COMPILE_OPT hidden, idl2
 ;--------------------------------------------------------------------------------
 ;--I-- Input verification and Initialization  -----------------------------------
 ;--I.1-- Coordinates Provided in one or two Variables
  if keyword_set(EQ2) then coord=transpose([[EQ1],[EQ2]]) else coord=EQ1

 ;--I.2-- EC->EQ or EQ->EC?
  if not keyword_set(EC_TO_EQ) and not keyword_set(EQ_TO_EC) then EQ_TO_EC=1

 ;--I.3-- Adjust Rotation Sign Following Conversion Choice
  if keyword_Set(EQ_TO_EC) then rotSign = -1.    $
                           else rotSign =  1. 

 ;--I.4-- Angle between Ecliptic and Equatorial
  epsilon = rotSign * (23. + 26./60. + 21.4119/3600. )*!DTOR


 ;--------------------------------------------------------------------------------
 ;--II-- Actual Conversion Computation  ------------------------------------------
 ;--II.1-- Conversion into Cartesian coordinates
  x1 = cos( coord[0,*]*!DTOR )*cos( coord[1,*]*!DTOR )
  y1 = sin( coord[0,*]*!DTOR )*cos( coord[1,*]*!DTOR )
  z1 = sin( coord[1,*]*!DTOR )

 ;--II.2-- Rotation in Cartesian Coordinates
  x2 = x1
  y2 = y1*cos( epsilon ) - z1*sin( epsilon )
  z2 = y1*sin( epsilon ) + z1*cos( epsilon )

 ;--II.3-- Conversion back into Spherical Coordinates
  out1 = atan( y2, x2 )/!DTOR
    out1 += 360.
    out1 = out1 mod 360.
  out2 = asin( z2 ) /!DTOR


 ;--------------------------------------------------------------------------------
 ;--III-- UI - If VERBOSE Specified  ---------------------------------------------
  if keyword_set(verbose) then begin

    if keyword_Set(EQ_TO_EC) then begin
      print, 'EQuatorial: alpha, delta :'+strtrim(string(coord[0], format='(F6.1)'),2)+'   '+$
                                          strtrim(string(coord[1], format='(F6.1)'),2)

      print, 'ECliptic  : lambda, beta :'+strtrim(string(out1, format='(F6.1)'),2)+'   '+$
                                          strtrim(string(out2, format='(F6.1)'),2)
    endif else begin
      print, 'ECliptic  : lambda, beta :'+strtrim(string(coord[0], format='(F6.1)'),2)+'   '+$
                                          strtrim(string(coord[1], format='(F6.1)'),2)
      print, 'EQuatorial: alpha, delta :'+strtrim(string(out1, format='(F6.1)'),2)+'   '+$
                                          strtrim(string(out2, format='(F6.1)'),2)

    endelse
  endif


 ;--------------------------------------------------------------------------------
 ;--IV-- Return the Result of Conversion
  return, reform([[reform(out1)], [reform(out2)]])

end