; docformat = 'rst'
;
; NAME: 
;    SSOPOSITIONS
; PURPOSE:
;    Return the celestial position of a Solar System Object 
;
;+
; :Description:
;    Return the celestial position of a Solar System Object
;
;    This function is a simple interface to the ephemcc utility of the
;    Eproc ephemeris generator (IMCCE, Paris Observatory, France). See
;    Eproc documentation for more details:
;    http://vo.imcce.fr/webservices/miriade/?ephemcc
;    If Eproc is installed locally, SSOPOSITIONS uses it, otherwise a
;    request to Eproc webservice Miriade is performed.
;
; :Categories:
;    Coordinates, Ephemeris
;    
; :Params:
;    ID: in, required, type=integer/string
;        Target identifyer ('*', Name, Provisional designation, Number) 
;    EP: in, required, type=double/string
;        The epoch at which the ephemeris should be computed
;
; :Returns: A three-element array containing the positions
;
;
; :Keywords:
;    TYPE: in, optional, type=string, default='aster'
;        Type of target (aster | planet | satel | comet), can be set
;        alternatively with the optional keywords ASTEROID, PLANET,
;        SATELLITE, COMET
;    ASTEROID: in, optional, type=boolean, default=1
;        Set the target type to asteroid  (equiv. to type='aster')
;    PLANET: in, optional, type=boolean, default=0
;        Set the target type to planet    (equiv. to type='planet')
;    SATELLITE: in, optional, type=boolean, default=0
;        Set the target type to satellite (equiv. to type='satel')
;    COMET: in, optional, type=boolean, default=0
;        Set the target type to comet     (equiv. to type='comet')
;    RPLANE: in, optional, type=integer, default=1
;        Reference plane (1:equator, 2: ecliptic)
;    OBSERVER: in, optional, type=integer, default=500
;        The IAU Code or geographic coordinates of the
;        observer's location, can be set alternatively with the
;        optional input keywords
;    GEOCENTRIC: in, optional, type=boolean, default=1
;        Compute ephemeris from the geocentre
;    HELIOCENTRIC: in, optional, type=boolean, default=0
;        Compute ephemeris from the heliocentre
;
; :Examples:
;    Compute the geocentric equatorial position of Ceres at J2000.0
;      IDL> xyz = ssoPositions(1,'2000-01-01T00:00:00.0',type='aster', /geocentric)
;    Compute the heliocentric ecliptic position of Pallas at J2000.0
;      IDL> xyz = ssoPositions('Pallas','2000-01-01T00:00:00.0',type='aster', /heliocentric)
;    Compute the gaia-centric equatorial position of Lutetia at on 2016-01-01T00:00:00.0
;      IDL> xyz = ssoPositions(21,'2016-01-01T00:00:00.0',type='aster', observer='@gaia')
;
; :Uses:
;    date_conv, forprint, voMiriade_callEphemcc
;
; :Author:
;    B.Carry (IMCCE)
;
; :History:
;     Change History::
;        Written in February 2014, B. Carry (IMCCE)
;        2013 Sep. - B.Carry (IMCCE) - I/O homogeneous with Miriade
;            (http://vo.imcce.fr/webservices/miriade/?ephemcc)
;        2015 Feb. - B.Carry (IMCCE) - Replaced dependance on call_ephemcc by voMiriade_callEphemcc
;-
function ssoPositions, ID, ep, type=type, rPlane=rPlane, $
                       planet=planet, asteroid=asteroid, satellite=satellite, comet=comet, $
                       observer=observer, geocentric=geocentric, heliocentric=heliocentric 
  COMPILE_OPT hidden, idl2
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---    I -- Initialization And Input Verification              -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
 ;--I.1-- Analyze the Epoch format and convert in Julian Days if needed  ----------
  dims= size( ep )
  epType = dims[ n_elements(dims)-2 ]

 ;--I.1.1-- Single Epoch Specified
  tInFile = '/tmp/inputDates.jd'
  if dims[0] eq 0 then begin
    if epType eq 7 then epoch = date_conv( ep, 'JULIAN' ) $
                   else epoch = ep
    nbd=0

 ;--I.1.2-- Epoch Array Provided
  endif else begin

   ;--I.1.2/A-- Possible Type Conversion
    nbd = dims[1]
    if epType eq 7 then begin
      epoch = dblarr(nbd)
      for kD=0L, nbd-1 do epoch[kD] = date_conv( ep[kD], 'JULIAN' )
    endif else epoch = ep

   ;--I.1.2/B-- Generate the Date Input File for Eproc
    forprint, epoch, format='(D16.8)', textout=tInFile, /NoComment, /Silent
    epoch = tInFile
  endelse


 ;--I.2-- Reference plane (1: Equatorial, 2: Ecliptic)  ---------------------------
  if not keyword_set( rPlane ) then rPlane='1' $
                               else rPlane=strtrim(string(rPlane,format='(I)'),2)

 ;--I.3-- Observer's Location  ----------------------------------------------------
  if not keyword_set(observer)     and $
     not keyword_set(geocentric)   and $
     not keyword_set(heliocentric) then geocentric=1

  if keyword_set(observer) then $
    if strcmp(observer,'@sun') then heliocentric=1 


 ;--I.4-- Type of Target ----------------------------------------------------------
  if not keyword_set(type) then begin

   ;--I.4.1-- If Nothing Specified -> Target is an asteroid
    if not keyword_set(planet)    AND $
       not keyword_set(satellite) AND $
       not keyword_set(comet)     AND $
       not keyword_set(asteroid)  then asteroid=1

   ;--I.4.2-- Choose from User-supplied Keywords
    if keyword_set(planet)    then type = 'planet'
    if keyword_set(satellite) then type = 'satel'
    if keyword_set(comet)     then type = 'comet'
    if keyword_set(asteroid)  then type = 'aster'

  endif


;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---   II -- Ephemeris Generation       -----------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;

 ;--II.1-- Heliocentric
  now=systime(/JULIAN,/UTC)
  file='/tmp/'+string(now,format='(D16.8)')+'.eph'
  if keyword_set(heliocentric) then $
     eph = voMiriade_callEphemcc( ID, epoch, type=type, dateList=nbd, /helio, /JULIAN, $
                                  tCoor='2', rPlane=rPlane, /web, dump=file )

 ;--II.2-- Geocentric
  if keyword_set(geocentric) then $
     eph = voMiriade_callEphemcc( ID, epoch, type=type, dateList=nbd, /geo, /JULIAN, $
                                  tCoor='2', rPlane=rPlane, /web, dump=file )

 ;--II.3-- Topocentric
  if keyword_set(observer) then $
     eph = voMiriade_callEphemcc( ID, epoch, type=type, dateList=nbd, observer=observer, /JULIAN, $
                                  tCoor='2', rPlane=rPlane, /web, dump=file )

 ;--II.4-- Return
  return, transpose([ [eph.x], [eph.y], [eph.z] ])

end