; docformat = 'rst'
;
; NAME: 
;    orientVector
; PURPOSE:
;    Orient a 3-D vector on the plane of the sky with observer at +z
;+
; :Description:
;    Orient a 3-D vector on the plane of the sky with observer at +z
;
; :Categories:
;    Shape Models
;
; :Params:
;    V: in, required, type=fltarr
;        Cartesian coordinates of the vector
;    SEP: in, required, type=structure
;        Longitude and Latitude of the sub-Earth point (deg.)
;    PA: in, required, type=float
;        Angle between celestial north and rotation axis (deg.,
;        positive through East)
;
; :Returns: The cartesian coordinates of the profile on the
;    plane of the sky.
;
; :Uses:
;
; :Author:
;    B.Carry (OCA)
;
; :History:
;    Change History::
;      Original Version written in May 2014, B. Carry (IMCCE)
;-
function orientVector, V, SEP, PA
  COMPILE_OPT hidden, idl2
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---    I -- Initialization And Input Verification              -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;

 ;--I.1-- Test Presence of Arguments  ---------------------------------------------------
  if N_params() LT 3 then begin
    message, /ioError, 'Syntax -  XYZ = orientVector( V, SEP, PA )'
    return, -1
 endif

 ;--I.2-- Test Input Vector  ------------------------------------------------------------
  dimV = size(V)
  case dimV[0] of
   ;-I.2.1-- V = [x,y,z]
    1:
   ;-I.2.2-- V = T([x,y,z])
    2: V = transpose(V)
   ;-I.2.3-- V = Error!
    else: begin
      message, /IOERROR, 'Input vector is not a 3x1 array'
      return, -1
    end
  endcase

 ;--I.3-- Test Validity of SEP Structure  -----------------------------------------------
  tags = tag_names(SEP)
;-TBD orientVector - check that all sep.tags are present  

;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---   II -- Rotation and Exportation                           -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;

 ;--II.1-- Create Rotation Matrix  -------------------------------------------------------
  T3D, /RESET                         ;-                               N
  T3D, rotate=[-90d0  ,   -90d0, 0d0]   ;-Permut Z -> Y -> X (IDL)     E + O
  T3D, rotate=[0d0    ,-sep.lon, 0d0]   ;-SEP_long at image center       S
  T3D, rotate=[sep.lat,     0d0, 0d0]   ;-SEP_lat at image center
  T3D, rotate=[0d0    ,     0d0,  PA]   ;-Pole Angle alignment

 ;--II.2-- Rotate a [3,2] Version of Input Vector  ---------------------------------------
  rotated=vert_t3d( [[V],[V]] )

 ;--II.3-- Return Rotated Vector  --------------------------------------------------------
  return, rotated[*,0]

end