Source code for irfpy.mexpvat.frame

''' Frame conversion for MEX.

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

>>> from irfpy.mexpvat import mexspice
>>> mexspice.init()
'''
import numpy as np

import spiceypy as spice

irfpy_framenames = {
    'SC': 'MEX_SC',
    'ASPERA': 'MEX_ASPERA',
    'ELS': 'MEX_ASPERA_ELS',
    'NPI': 'MEX_ASPERA_NPI',
    'IMA': 'MEX_ASPERA_IMAS',   # Note, it is not "MEX_ASPERA_IMA".
    'NPD1': 'MEX_ASPERA_NPD1',
    'NPD2': 'MEX_ASPERA_NPD2',
    'SAF': 'MEX_ASPERA_SAF',    # Note, this is subjected to change.
    'URF': 'MEX_ASPERA_URF',    # Note, this is subjected to change.
}
''' Conversion table of frame names

``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="MEX_SC", toframe="MSO"):
    ''' 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.mexpvat import mexspice
    >>> mexspice.init(level='noatt')
    >>> import datetime
    >>> t = datetime.datetime.now()   # This is just a placeholder, as they are fixed each other.
    >>> matx = convert_matrix(t, fromframe='IMA', toframe='MEX_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')