; docformat = 'rst'
;
; NAME: 
;    ORIENTMODEL
; PURPOSE:
;    Orient a 3-D shape model on the plane of the sky with observer at +z
;+
; :Description:
;    Orient a 3-D shape model on the plane of the sky with observer at +z
;
; :Categories:
;    Shape Models
;
; :Params:
;    V: in, required, type=fltarr
;        Cartesian coordinates of the N vertex
;    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 December 2013, B. Carry (IMCCE)
;      2014 Apr. - B.Carry (IMCCE) - Header compatible with idlDoc
;      2017 June - B.Carry (OCA) - Idl2 + Input validation added
;-
function orientModel, V, SEP, PA
  COMPILE_OPT hidden, idl2
 ;--I-- Test Presence of Arguments  ---------------------------------------------------
  if N_params() LT 2 then begin
    message, /ioError, 'Syntax -  XYZ = orientModel( V, SEP [, PA] )'
    return, -1
 endif

 ;--II-- Set Default Values  ----------------------------------------------------------
  if not keyword_Set(pa) then pa=0
  sepDefault={lon:0., lat:0.}
  if not keyword_set(sep) then sep=sepDefault else sep = updateStructure(sepDefault,sep)


 ;--III-- 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

 ;--III-- Rotate and Return Input Vector  -----------------------------------------------
  return, vert_t3d(V)

end