Source code for irfpy.vexpvat.frame

''' Frame conversion module for VEX using SPICE.

High level fuctions for VEX frame conversion.
It uses SPICE in its low-level functions, so that you may need to
furnsh :mod:`irfpy.vexpvat.vexspice` before using.

>>> from irfpy.vexpvat import vexspice
>>> vexspice.init()
'''
import numpy as np

import spiceypy as spice

irfpy_framenames = {
    'SC': 'VEX_SPACECRAFT',
    'ASPERA': 'VEX_ASPERA4',
    'ELS': 'VEX_ASPERA4_ELS',
    'NPI': 'VEX_ASPERA4_NPI',
    'IMA': 'VEX_ASPERA4_IMAS',   # Note, it is not "MEX_ASPERA_IMA".
    'NPD1': 'VEX_ASPERA4_NPD1',
    'NPD2': 'VEX_ASPERA4_NPD2',
#    'SAF': 'VEX_ASPERA_SAF',    # Note, this is subjected to change.
#    'URF': 'VEX_ASPERA_URF',    # Note, this is subjected to change.
}
''' Conversion table of frame names

.. TODO::

    Please define the names coherently as MEX.

``irfpy`` users can use the customized frame name above.
The defined name overwrite the spice name in the functions
of this module.

.. note::

    The use of the name convection is limited inside this module.
    These names does *not* register to SPICE.

'''

def spicename(origname):
    ''' Return the SPICE name

    Convert the origname to spicename.
    Name conversion using :attr:`irfpy_framenames` table, and
    if no entry originame is returned as is.
    '''
    if origname in irfpy_framenames:
        return irfpy_framenames[origname]
    else:
        return origname


def convert_matrix(t, fromframe="VEX_SC", toframe="VSO"):
    ''' Return conversion matrix as a numpy array.

    :param t: ``datatime.datetime`` object specifying time.
    :returns: Numpy array of the conversion matrix.  ``numpy.pxform`` is used.

    Conversion between IMA frame and SC frame is

    >>> from irfpy.vexpvat import vexspice
    >>> vexspice.init()
    >>> import datetime
    >>> t = datetime.datetime.now()   # This is just a placeholder, as they are fixed each other.
    >>> matx = convert_matrix(t, fromframe='IMA', toframe='VEX_SPACECRAFT')
    >>> from irfpy.util.with_context import printoptions
    >>> with printoptions(suppress=True, precision=3):  # Note: -0. should be the same as 0., but...
    ...     print(matx)
    [[ 1. -0. -0.]
     [ 0.  0.  1.]
     [-0. -1.  0.]]

    '''
    frame0 = spicename(fromframe)
    frame1 = spicename(toframe)

    et0 = spice.str2et(t.strftime('%FT%T.%f'))
    return np.array(spice.pxform(frame0, frame1, et0))


import unittest
import doctest


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