Source code for irfpy.joee.frame0

r''' JoEE and S/C frame conversions

Draft version of frame conversions.
See also :ref:`definition_of_frame_joee` for definition.
Brief summary is here.

*Angles to JoEE frame*

|theta| is defined by the angle from y=z plane.
|phi| is defined from z axis and -y axis is 90.

Therefore, the conversion to vector of JoEE frame is

.. math::

    x = \sin\theta  \\
    y = -\cos\theta \times \sin\phi  \\
    z = \cos\theta \times \cos\phi

*JoEE frame and JUICE frame*

The JUICE frame (sometimes called PEP frame or NSC frame) and
the JoEE frame conversion is defined as a simple matrix,
as the same way as JNA0.
See also :mod:`irfpy.jna.frame0`.

There are two following functions, but they are just aliases
from JNA-SC conversion in :mod:`irfpy.jna.frame0`.

.. autofunction:: joee2nsc
.. autofunction:: nsc2joee
'''

import numpy as np

from irfpy.jna.frame0 import jna2nsc as joee2nsc
from irfpy.jna.frame0 import nsc2jna as nsc2joee


def joee2angles(vec):
    r''' Convert from vector to JoEE angles.

    Angles ar in degrees. :math:`\theta` and :math:`\phi`.

    (Below test "+1-1" is just to change -0. to 0. so no meaning.)

    >>> print(joee2angles([0, 0, 2]) + 1 - 1)
    [ 0.  0.]

    >>> print(joee2angles([3, 0, 0]) + 1 - 1)
    [ 90.   0.]

    >>> print(joee2angles([[3, -2, 0, 0, 0], [0, 0, -1.45, 3, 0], [0, 0, 0, 0, -1]]) + 1 - 1)
    [[  90.  -90.    0.    0.    0.]
     [   0.    0.   90.  -90. -180.]]
    '''
    veclen = np.sqrt((np.array(vec) ** 2).sum(0))  # Now, scalar or (N,)
    vu = vec / veclen   # Now, (3,) or (3, N)

    t = np.arcsin(vu[0])
    p = np.arctan2(-vu[1], vu[2])

    return np.array([np.rad2deg(t), np.rad2deg(p)])



def angles2joee(theta, phi):
    r''' From (arrays of) theta and phi, vector(s) in JoEE is returned.

    x = \sin\theta
    y = -\cos\theta \times \sin\phi
    z = \cos\theta \times \cos\phi

    (Below the test include +1-1 just to change -0.0 to 0.0)

    >>> print(angles2joee(0, 0) + 1 - 1)
    [ 0.  0.  1.]
    >>> print(angles2joee(90, 0) + 1 - 1)
    [ 1.  0.  0.]
    >>> print(angles2joee(-90, 0) + 1 - 1)
    [-1.  0.  0.]
    >>> print(angles2joee(0, 90) + 1 - 1)
    [ 0. -1.  0.]
    >>> print(angles2joee(0, -90) + 1 - 1)
    [ 0.  1.  0.]
    >>> print(np.round(angles2joee(0, 180), 3) + 1 - 1)
    [ 0.  0. -1.]
    '''
    th = np.array(theta) * np.pi / 180.
    ph = np.array(phi) * np.pi / 180.

    return np.array([np.sin(th), np.cos(th) * np.sin(-ph), np.cos(th) * np.cos(ph)])

import unittest
import doctest


def doctests():
    return unittest.TestSuite((
        doctest.DocTestSuite(),
        ))
if __name__ == '__main__':
    unittest.main(defaultTest='doctests')