.. _services_tut:

OSIRIS Level 1 Services
************************
The ``osirisl1services.services`` module supplies users with an xarray accessor ``L1Services`` that supplies additional
functionality for the computation of spatial positioning, pointing, and tangent point information through the accessor
name ``l1``.

Pointing
========
The accessor supports computation of instrument lines of sight or both the IR and spectrograph datasets
in both ECEF and ECI coordinates:

* :py:attr:`l1.look_ecef`
* :py:attr:`l1.look_eci`

These pointing vectors are expressed as unit XYZ vectors in an earth centered inertial coordinate system.
For the IR instrument, a look vector is computed for each pixel. For the spectrograph, a single look vector for each
exposure.

Position and Velocity
=====================
The accessor supports the calculation of spacecraft position and velocity in both ECEF and ECI coordinates systems.
This functionality is provided by the functions below and can be applied to the IR and spectrograph datasets:

* :py:attr:`l1.position_ecef`
* :py:attr:`l1.position_eci`
* :py:attr:`l1.velocity_ecef`
* :py:attr:`l1.velocity_eci`

Tangent Points
==============
Using pointing and position methods in conjunction allows us to calculate the location of tangent points for each
saltellite position / look vector pair.
This is accessed via:

* :py:attr:`l1.altitude`
* :py:attr:`l1.latitude`
* :py:attr:`l1.longitude`

As with the pointing, the data is computed for each pixel for IR data and each exposure for spectrograph data.

Solar Angles
============
Additionally, the solar angles relative to the tangent point can be calculated.
This is accessed via:

* :py:attr:`l1.sza`: the solar zenith angle
* :py:attr:`l1.ssa`: the solar scattering angle
* :py:attr:`l1.saa`: the solar azimuth angle
* :py:attr:`l1.satellite_azimuth_angle`: the azimuth angle of the satellite look vector

As with the pointing, the data is computed for each pixel for IR data and each exposure for spectrograph data.

Apparent Solar Time
===================
The apparrent solar angles time is accessed via:

* :py:attr:`l1.apparent_solar_time`

Miscellaneous
=============
Additional methods are available to compute the satellites position and velocity in ECEF and ECI coordinates for an
arbitrary list of mjds rather than for a specific spectrograph scan or IR orbit:

* :py:func:`services.get_odin_position_ecef`
* :py:func:`services.get_odin_position_eci`
* :py:func:`services.get_odin_velocity_ecef`
* :py:func:`services.get_odin_velocity_eci`

The final method within the ``osirisl1services.services`` module is :py:func:`services.get_scans_in_orbit_below_sza`.
As its name suggests, this function takes an orbit number and a value of solar zenith angle as input,
and returns all scans within the specified orbit with solar zenith angles lower than the given angle.