.. _frame_conversion:

=============================
How to convert between frames
=============================

.. todo::

        Write sample codes.

``pyana`` supports the frame (coordinate system) conversion.
Most of the conversion is based on the pre-calculated data file.

Defined coordinate systems are:

- CENA sensor frame (angle-wise)
- CENA sensor frame (vector-wise)
- SWIM sensor frame
- Spacecraft frame
- LSE frame
- ME frame (a selenological coordinate system)


CENA sensor frames
==================

The CENA sensor frames are fixed coordinate system to the CENA sensor.
Fields of view angle is fixed in these coordinate systems.
See detailed definition in :mod:`pyana.cena.fov` and :ref:`CENA calibration report issue 1 rev 1 <cenacalrep>`.

Getting FoV is in :mod:`pyana.cena.fov`.  The module also support the conversion between
the angle-wise definition and the vector-wise definition.

The each viewing angle information of CENA sensor is mainly defined in the angle-wise CENA sensor frame.
This is useful especially to consider the calibration results or sensor property.
For example, you may know the FWHM of the response of CENA in this frame intuitively.

Indeed, the conversion with spacecraft frame is also fixed, and thus, the conversions are straightforward.
However, you can use :mod:`pyana.cena.frames` module to conduct the conversion.


SWIM sensor frames
==================

This is also fixed frame compared to the spacecraft.
Low-level module :mod:`pyana.swim.SwimFov` and higher-level module :mod:`pyana.swim.swim_fov` provide the conversion.

(TBW)


Spacecraft frame
================
Spacecraft frame is defined by the mission team. CENA and SWIM frames are fixed to the spacecraft frame.

LSE frame
=========
LSE (Lunar-Solar Ecliptic) frame is one of the most common frame for plasma physics.
Sometimes it is called SSE frame.  You may imagine GSE frame (Geo- brabra) for comparison.
Indeed the differences are quite small.

LSE frame is time depended compared with spacecraft coordinate system.

Conversion from SC to LSE can be conducted using :mod:`pyana.cy1orb.pvat2` high-level module.
The module provides a function :func:`pyana.cy1orb.pvat2.getlsevec` that converts a vector in SC frame
to the corresponding vector in LSE.

Inverse function, :func:`pyana.cy1orb.pvat2.getscvec` is implemented in version 1.15.

(TBW about low-level functions)


ME frame
========
ME (Mean-earth) frame is the frame fixed on the lunar surface.
This is time-variant compared with LSE frame.
The conversion between can be done using high-level functions in :mod:`lseme` module.


Summary
=======

The following diagram may help.

::

        CENA (angle)    <---(pyana.cena.fov)--->    CENA (vector)
                                                           ^
                                                           |
                                                  (pyana.cena.frames)
                                                           |
                                                           v
                                                          S/C   <---(pyana.swim.SwimFov)--->   SWIM
                                                           ^
                                                           |
                                            (pyana.cy1orb.pvat2.getlsevec)
                                                           |
                                                           v
                                                          LSE
                                                           ^
                                                           |
                                                  (pyana.cy1orb.lseme)
                                                           |
                                                           v
                                                          ME