; docformat = 'rst'
;
; NAME: 
;    readSpin
; PURPOSE:
;    Read a spin parameter file in DAMIT format into a structure.
;+
; :Description:
;    Read a spin parameter file in DAMIT format into a structure.
;
; :Categories:
;    Disk I/O, Shape Models
;
; :Params:
;    file: in, required, type=string
;        The path to the file containing the spin parameters
;
; :Keywords:
;    empty: in, optional, type=boolean, default=0
;      If set, returns an empty spin structure
;
; :Returns: Upon success, a structure containing the spin parameters. Fields are::
;       .LON  : ECJ2000 longitude of the spin axis
;       .LAT  : ECJ2000 latitude of the spin axis
;       .PH   : Sidereal rotation period (hour)
;       .PD   : Sidereal rotation period (day)
;       .JD0  : Reference epoch (JD)
;       .PHI0 : Rotation phase reference (deg)
;       .PHASE: Phase function parameters (3 elements)
;       .LSL  : Ratio Lambert to Lommel-Seelinger in light-scattering rendering
;    If the reading fails, it returns an error code::
;      1 : Syntax error
;      2 : File cannot be read
;      3 : Erroneous file format
;
; :Examples:
;    Read a spin file and print the value of the rotation period in hours::
;      IDL> spin = readSpin('myfile')
;      IDL> print, spin.ph
;
; :Uses:
;
; :Author:
;    B.Carry (OCA)
;
; :History:
;    Change History::
;      Original Version written in 2011, B. Carry (ESA)
;      2013 Nov. - B.Carry (IMCCE) - Model structure modified
;      2014 Jun. - B.Carry (IMCCE) - Correct Bug arising from different number of lines
;      2015 Sep. - B.Carry (OCA)   - Close the file at the end - Avoid bug on # of logical units
;      2017 Feb. - B.Carry (OCA)   - Added idl2 && Implemented phase function
;      2017 July - B.Carry (OCA)   - Added test on I/O, bullet-proofed spin file & empty keyword
;      2018 June - B.Carry (OCA)   - Corrected float->double in jd0
;-
function readSpin, file, empty=empty
  COMPILE_OPT hidden, idl2
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---    I -- Initialization And Input Verification              -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;

 ;--I.1-- Definition of the Spin Structure  ----------------------------------------------------
  spin =  {lon:0., lat:0., ph:0., pd:0., jd0:0.d, phi0:0., $
           phase:[0., 0., 0.], p1:0., p2:0., p3:0., lsl:0.}


 ;--I.2-- Return Empty Structure if Required  --------------------------------------------------
  if keyword_set(empty) then return, spin


 ;--I.3-- Validation of Input Syntax  ----------------------------------------------------------
  if not keyword_set(file) then begin
    message, 'syntax: spinStructure = readSpin(file)'
    return, 1
  endif


 ;--I.4-- Test if Input File can be Read  ------------------------------------------------------
  if not file_test(file) then begin
    message, 'ERROR: readSpin cannot read the input file: '+strTrim(file,2)
    return, 2
  endif


 ;--I.5-- Default Phase Function Parameters  ---------------------------------------------------
  defPhase = [0.5, 0.1, -0.5]


;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---   II -- Read the Spin Parameter File                       -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;

 ;--II.1-- Open the File  ----------------------------------------------------------------------
  openR, idIn, file, /Get_Lun
  line=''

 ;--II.2-- Spin Coordinates & Period  ----------------------------------------------------------
 ;--II.2.1-- Read Current Line
  readf, idIn, line
  split = strSplit( line, ' ', /Extract, count=nbParam )

 ;--II.2.2-- Fill Structure with Appropriate Information
  if nbParam eq 3 then begin
    spin.lon = float(split[0])
    spin.lat = float(split[1])
    spin.ph  = float(split[2])
    spin.pd  = spin.ph/24.

 ;--II.2.3-- Deal with Exception
  endif else begin
    message, 'ERROR: readSpin detected an erroneous format for the spin file '+strTrim(file,2)
    return, 3
  endelse


 ;--II.3-- Reference Epoch and Angle  ----------------------------------------------------------
 ;--II.3.1-- Read Current Line
  readf, idIn, line
  split = strSplit( line, ' ', /Extract, count=nbParam )

 ;--II.3.2-- Fill Structure with Appropriate Information
  if nbParam eq 2 then begin
    spin.jd0  = double(split[0])
    spin.phi0 = float(split[1])

 ;--II.3.3-- Deal with Exception
  endif else begin
    message, 'ERROR: readSpin detected an erroneous format for the spin file '+strTrim(file,2)
    return, 3
  endelse



 ;--II.4-- Phase Function Parameters  ----------------------------------------------------------
 ;--II.4.1-- Read Current Line
  readf, idIn, line
  split = strSplit( line, ' ', /Extract, count=nbParam )

 ;--II.4.2-- Fill Structure with Appropriate Information
  case nbParam of

   ;--II.4.2/A-- No Phase Function Specified
    1: begin
      spin.lsl   = float(split[0])
      spin.p1    = defPhase[0]
      spin.p2    = defPhase[1]
      spin.p3    = defPhase[2]
      spin.phase = [spin.p1, spin.p2, spin.p3]
    end

   ;--II.4.2/B-- LSL and Phase Function Specified 
    5: begin
      spin.lsl   = float(split[0])
      spin.p1    = float(split[1])
      spin.p2    = float(split[2])
      spin.p3    = float(split[3])
      spin.phase = [spin.p1, spin.p2, spin.p3]
    end
  
   ;--II.4.3/C-- Phase Function Specified then LSL Coefficients
    3: begin
      spin.p1    = float(split[0])
      spin.p2    = float(split[1])
      spin.p3    = float(split[2])
      spin.phase = [spin.p1, spin.p2, spin.p3]

      readf, idIn, line
      split = strsplit( line, ' ', /EXTRACT )
      spin.lsl = float(split[0])
    end

   ;--II.4.4/D-- No idea of what is that format
    4: begin
      spin.lsl   = float(split[0])
      spin.p1    = float(split[1])
      spin.p2    = float(split[2])
      spin.p3    = float(split[3])
      spin.phase = [spin.p1, spin.p2, spin.p3]
    end

 ;--II.4.3-- Deal with Exception
    else: begin
      message, 'ERROR: readSpin detected an erroneous format for the spin file '+strTrim(file,2)
      return, 3
    end
  endcase


;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---  III -- Close the File and Return Values                   -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
 ;--III.1-- Close the File  --------------------------------------------------------------------
  free_lun, idIn

 ;--III.2-- Return Spin Structure  -------------------------------------------------------------
  return, spin

end