; docformat = 'rst'
;
; NAME:
;    getCameraJitter
; PURPOSE:
;    Retrieve the camera jitter from FITS header
;
;+
; :Description:
;    Retrieve the camera jitter from FITS header
;
;    The jitter is expressed as a vector from the reference of the
;    frame to the target. I.e., if the target was set primarily on the
;    reference pixel, the jitter correspond to the displacement on the
;    detector plane.
;
; :Categories:
;    FITS, Camera
;
; :Returns: The camera jitter in pixel or arcseconds.
;
; :Params:
;    head: in, required, type=string
;        A FITS header from the telescope
;    tel: in, optional, type=string
;        The ID of the telescope (from getTelescopeID)
;    cam: in, optional, type=string
;        The ID of the camera (from getCameraID)
;
; :Keywords:
;    ref: in, optional, type=string
;        The FITS header for a reference frame from the telescope
;        (needed for Keck/NIRC2)
;    PIXEL: in, optional, type=boolean, default=1
;        Provides the jitter in pixels along x,y
;    RADEC: in, optional, type=boolean, default=0
;        Provides the jitter in arcsec along RA/DEC
;
; :Uses:
;    sxpar(), getTelescopeID(), getCameraID()
;
; :Author:
;    B.Carry (OCA)
;
; :History:
;    Change History::
;      Written in March 2014, B. Carry (IMCCE)
;      2014-Dec: B.Carry (IMCCE) - Gem-N/NIRI Added
;      2015-Apr: B.Carry (IMCCE) - Keyword ref Added (Keck/NIRC2)
;      2015 Nov - B.Carry (OCA) - Added compile option idl2 -- Added SPHERE/IRDIS 
;      2019 Jan - B.Carry (OCA) - Adapted to new getCameraPixel
;      2019 Jun - B.Carry (OCA) - Added Keck/NIRSPEC
;      2022 Nov - B.Carry (OCA) - Added CFHT/PUEO
;      2023 Dec.: B.Carry (OCA) - Added LBTO
;      2024 Mar.: B.Carry (OCA) - Added VLT/ERIS/NIX
;-
function getCameraJitter, head, tel, cam, ref=ref, PIXEL=PIXEL, RADEC=RADEC
  COMPILE_OPT hidden, idl2
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---    I -- Initialization And Input Verification              -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
 ;--I.1-- Input Syntax Verification  ----------------------------------------------------
  if N_PARAMS() lt 1 then begin
    message, /IOERROR, 'Syntax : ID = getCameraJitter(HEAD, [telID, camID])'
    return, -1
  endif

 ;--I.2-- Set Output Dimensions (pixel or arcsec)  --------------------------------------
  if not keyword_set(pixel) and not keyword_set(radec) then pixel=1

 ;--I.3-- Telescope and Camera ID  ------------------------------------------------------
  if not keyword_set(tel) then tel=getTelescopeID(head)
  if not keyword_set(cam) then cam=getCameraID(head)


;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---   II -- Header Parsing and Pole Angle Computation          -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
  case tel of

    ;--II.1-- ESO-VLT Telescopes  ---------------------------------------------------------------
    'ESO-VLT': begin
       case cam of

        ;--II.1.1-- NACO  -------------------------------------------------------------------------
         'NACO': begin
            if keyword_set(pixel) then jitter = [lxpar(head,'HIERARCH ESO SEQ CUMOFFSETX'),$
                                                 lxpar(head,'HIERARCH ESO SEQ CUMOFFSETY')]
            if keyword_set(radec) then jitter = [lxpar(head,'HIERARCH ESO SEQ CUMOFFSETA'),$
                                                 lxpar(head,'HIERARCH ESO SEQ CUMOFFSETD')]
         end

        ;--II.1.2-- SPHERE/IRDIS ------------------------------------------------------------------
         'SPHERE/IRDIS': begin
            if keyword_set(pixel) then jitter = [lxpar(head,'HIERARCH ESO INS1 DITH POSX'),$
                                                 lxpar(head,'HIERARCH ESO INS1 DITH POSY')]
            if keyword_set(radec) then begin
              jitter = [lxpar(head,'HIERARCH ESO INS1 DITH POSX'),$
                        lxpar(head,'HIERARCH ESO INS1 DITH POSY')]
              scale = getCameraPixel(head, telID, camID)
              PA = getCameraPA( head, telID, camID )
              vec=[ [jitter,0],[jitter,0]]
              
              t3d, /reset
              t3d, rotate=[0,0,PA/!DTOR]
              jitter = vert_t3d(vec)
              jitter=[-jitter[0,0], jitter[1,0]]
              
              jitter /= scale.resol
            endif

         end

        ;--II.1.3-- ISAAC  ------------------------------------------------------------------------
         'ISAAC': begin
            if keyword_set(pixel) then jitter = [lxpar(head,'HIERARCH ESO SEQ CUMOFFSETX'),$
                                                 lxpar(head,'HIERARCH ESO SEQ CUMOFFSETY')]
            if keyword_set(radec) then begin
              jitter = [lxpar(head,'HIERARCH ESO SEQ CUMOFFSETA'),$
                        lxpar(head,'HIERARCH ESO SEQ CUMOFFSETD')]
              scale = getCameraPixel(head, telID, camID)
              PA = getCameraPA( head, telID, camID )
              vec=[ [jitter,0],[jitter,0]]
             
              t3d, /reset
              t3d, rotate=[0,0,PA/!DTOR]
              jitter = vert_t3d(vec)
              jitter=[-jitter[0,0], jitter[1,0]]
              
              jitter /= scale.resol
            endif
         end

        ;--II.1.4-- ERIS/NIX  ---------------------------------------------------------------------
         'ERIS/NIX': begin
            if keyword_set(pixel) then jitter = [lxpar(head,'HIERARCH ESO OCS CUMOFFS X'),$
                                                 lxpar(head,'HIERARCH ESO OCS CUMOFFS Y')]
            if keyword_set(radec) then jitter = [lxpar(head,'HIERARCH ESO OCS CUMOFFS RA'),$
                                                 lxpar(head,'HIERARCH ESO OCS CUMOFFS DEC')]
         end


        ;--II.1.x-- Unknown  ----------------------------------------------------------------------
         else: begin
           message, 'getCameraJitter: ESO Camera not known'
           return, -1
         end
       endcase
     end


    ;--II.2-- ESO-LSO Telescopes  ---------------------------------------------------------------
    'ESO-LSO': begin
       case cam of

        ;--II.2.1-- EFOSC  ------------------------------------------------------------------------
         'EFOSC': begin
           message, 'getCameraJitter: EFOSC to be coded!!!'
           return, -1
         end

        ;--II.2.x-- Unknown  ----------------------------------------------------------------------
         else: begin
           message, 'getCameraJitter: ESO Camera not known'
           return, -1
         end
       endcase
     end


    ;--II.3-- Keck Observatory  -------------------------------------------------------------
    'KeckII': begin
       case cam of

        ;--II.3.1-- NIRC2  ------------------------------------------------------------------------
         'NIRC2':  begin 

          ;--II.3.1/A-- No Reference Provided: Use Keck Keyword
           if not keyword_set(ref) then begin
             jitter = [ sxpar(head,'RAOFF') , sxpar(head,'DECOFF')  ]* 3600.
          ;--II.3.1/B-- Reference Provided: Compute Offset Manually
           endif else begin 
             refPos = [ sxpar(ref, 'RA') , sxpar(ref, 'DEC')  ]
             curPos = [ sxpar(head,'RA') , sxpar(head,'DEC')  ]
             jitter = -(curPos-refPos )* 3600.
           endelse

          ;--II.3.1/C-- Convert in Pixel if Requested
           if keyword_set(pixel) then begin
             scale = getCameraPixel(head, telID, camID)
             PA = getCameraPA( head, telID, camID )
             vec=[ [jitter,0],[jitter,0]]
             
             t3d, /reset
             t3d, rotate=[0,0,PA/!DTOR]
             jitter = vert_t3d(vec)
             jitter=[-jitter[0,0], jitter[1,0]]

             jitter /= scale.resol
           endif


         end

        ;--II.3.1-- NIRC2  ------------------------------------------------------------------------
         'NIRSPEC':  begin 
            jitter=[0.,0.]
         end

        ;--II.3.x-- Unknown  ----------------------------------------------------------------------
         else: begin
           message, 'getCameraJitter: Keck Camera not known'
           return, -1
         end
       endcase
     end


    ;--II.4-- Gemini Observatory  -----------------------------------------------------------
    'Gem-N': begin
       case cam of

        ;--II.4.1-- NIRI  -------------------------------------------------------------------------
         'NIRI':  begin 
            if keyword_set(radec) then jitter = [sxpar(head,'RAOFFSET'),sxpar(head,'DECOFFSE')]
            if keyword_set(pixel) then begin
              jitter = [sxpar(head,'XOFFSET'), -sxpar(head,'YOFFSET')]
              scale = getCameraPixel(head, telID, camID)
              jitter /= scale.resol
            endif
          end

        ;--II.4.2-- Hokupaa  ----------------------------------------------------------------------
         'Hokupaa':  jitter =[0,0]

        ;--II.4.x-- Unknown  ----------------------------------------------------------------------
         else: begin
           message, 'getCameraJitter: Gemini Camera not known'
           return, -1
         end
       endcase
     end

    ;--II.5-- Haute-Provence Observatory  ---------------------------------------------------
    'OHP-120': begin
       case cam of

        ;--II.5.1-- Andor iKon 2k2k  --------------------------------------------------------------
         'iKon-2k':  jitter=[0,0]

        ;--II.4.x-- Unknown  ----------------------------------------------------------------------
         else: begin
           message, 'getCameraJitter: OHP/T120 Camera not known'
           return, -1
         end
       endcase
    end

    ;--II.6-- CFHT  -------------------------------------------------------------------------
    'CFHT': begin
       case cam of

        ;--II.6.1-- PUEO  -------------------------------------------------------------------------
         'PUEO':  jitter=[0,0]

        ;--II.4.x-- Unknown  ----------------------------------------------------------------------
         else: begin
           message, 'getCameraJitter: CFHT Camera not known'
           return, -1
         end
       endcase
    end

 
    ;--II.7-- LBTO  -------------------------------------------------------------------------
    'LBTO': begin
       case cam of

        ;--II.7.1-- PISCES  -----------------------------------------------------------------------
         'PISCES':  jitter=[ sxpar(head,'ABSOFFRA') , sxpar(head,'ABSOFFDE')  ]

        ;--II.4.x-- Unknown  ----------------------------------------------------------------------
         else: begin
           message, 'getCameraJitter: LBTO Camera not known'
           return, -1
         end
       endcase
    end

    ;--II.x-- Unknown  ------------------------------------------------------------------------
     else: begin
       message, 'getCameraJitter: Telescope not known'
       return, -1
     end
  endcase

 ;----- Return Camera X/Y Jitter  -------------------------------------------------------
  return, jitter
end