; docformat = 'rst'
;
; NAME: 
;    euclidReadRS
; PURPOSE:
;    Read a Euclid Reference Survey file and store it in structure
;+
; :Description:
;    Read a Euclid Reference Survey file and store it in structure
;
; :Categories:
;
; :Returns: A structure with the reference survey
;
; :Params:
;    file: in, required, type=string
;        The path to the survey file
;
; :Keywords:
;
; :Examples:
;    Read the wide survey
;      IDL> rs = euclidReadRS( 'wide.csv' )
;
; :Uses:
;    readcol
;
; :Author:
;    B.Carry (OCA)
;
; :History:
;    Change History::
;      Written at some point in 2016, B. Carry (OCA)
;      2017 May - B. Carry (OCA) - idl2 added, code commented
;-
function euclidReadRS, file
  compile_opt hidden, idl2
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---    I -- Initialization And Input Verification              -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
 ;--I.1-- Syntax  ------------------------------------------------------------------------------;
  if not keyword_set(file) then begin
    message, /ioError, 'syntax: rs = euclidReadRS( file )'
    return, -1
  endif

 ;--I.2-- File Accessibility  ------------------------------------------------------------------;
  if not file_test(file, /read) then begin
    message, 'Cannot read the Euclid Survey file: '+strTrim(file,2)
    return, -2
  endif


;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---   II -- Read and Organize the Survey in Structure          -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
 ;--II.1-- Read the File  ----------------------------------------------------------------------;
  readcol, file, delimiter=',', /Silent, $
           Id,patchId,fieldId,ditherId,$
           Type,MJD2000,UTC,lon,lat,Phi,$
           Qx,Qy,Qz,Qw,Dur,Slew,SPAA,SAA,$
           Alpha,Beta,Slew2,xJump,dX,dY,dZ, $
           format='(I,I,I,I,'+$
                    'A,D,A,F,F,F,'+$
                    'F,F,F,F,F,F,F,F,'+$
                    'F,F,F,F,F,F,F)'

 ;--II.2-- Convert EC into EQ Coordinates  -----------------------------------------------------;
  wCoord = framecoord_ec2eq( lon, lat )
  RA  = wCoord[*,0]
  DEC = wCoord[*,1]

 ;--II.3-- Create a Structure  -----------------------------------------------------------------;
  survey= {id:Id, $             ;-Pointing id: The unique and correlative Id for a field
           patchId:patchId, $   ;-Patch id: The associated patch Id
           fieldId:fieldId, $   ;-Field Id
           ditherId:ditherId,$  ;-Dither id
           type:Type, $         ;-The observation type: WIDE, CAL, DEEP
           mjd2000:MJD2000, $   ;-Modified Julian Date from 2000.0 at the start of observation
           utc:UTC, $           ;-Civil time
           lon:lon, $           ;-Ecliptic longitude
           lat:lat, $           ;-Ecliptic latitude
           ra:ra, $             ;-Equatorial Right Ascension  [computed]
           dec:dec, $           ;-Equatorial Declination      [computed]
           phi:Phi, $           ;-Orientation: FOV orientation in Ecliptic coordinates
           qx:Qx, $             ;-The satellite attitude Quaternion in ecliptic coordinates.
           qy:Qy, $             ;-The Euclid convention
           qz:Qz, $             ;-    Z:Boresight
           qw:Qw, $             ;-    X: Solar Panels
           dur:Dur, $           ;-Observation duration in seconds
           slew:Slew, $         ;-Observation slew (before observation) in seconds
           SPAA:SPAA, $         ;-Solar Panel Aspect Angle 
           SAA:SAA, $           ;-Solar Aspect Angle (SAA)
           alpha:Alpha, $       ;-Solar Alpha angle
           beta:Beta, $         ;-Solar Beta angle
           slew2:Slew2, $       ;-Step in degrees
           xJump:xJump, $       ;-XJump in degrees
           dX:dX, $             ;-X-rotation in degrees
           dY:dY, $             ;-Y-rotation in degrees
           dZ:dZ}               ;-Z-rotation in degrees

 ;--II.4-- Return the Structure  ---------------------------------------------------------------;
  return, survey

end