User interface
==============

FPlane retrieval
****************

To retrieve the current fplane file call::

    get_fplane.sh

this retrieves the actual fplane file and saves it as
``fplaneYYYMMDD.txt``

To retrieve it and write to a different filename e.g. ``fplane.txt``
call::

    get_fplane.sh -o fplane.txt

To retrieve the fplane file for a different date e.g. ``20180715`` call::

    get_fplane.sh 20180715

this retrieves the actual fplane file and saves it as
``fplane20180715.txt``
The server also accepts other date formats including
``YYYYMMDDTHH:MM:SS`` so you can directly use the DATE-OBS from a fits
header. In this case the default filename is
``fplaneYYYYMMDDTHH:MM:SS.txt``

By default the script retrieves an fplane file like the one stored in
virus_config. If you want just a short version (only active virus
units, no LRS, no HRS) call::

    get_fplane.sh -s

To retrieve (of available) exact IFU positions call::

    get_fplane.sh -p


Access from python
------------------

This code snippet will retrieve an fplane file and writes it to filename.

datestr can be a fits datestr, something of the form YYYYMMDD (or some
other formats). If you give it in the form YYYYMMDD it will retrieve
the fplane file for midnight of night starting on datestr. If you
leave the datestr empty, it will retrieve it for the “now” timestamp. 

With actpos=True it retrieves the latest set of exact ifu positions
for that date (These are usually valid since the last IFU updates).

full=True retrieves a complete fplane file with all entries and the
not used commented out, with full=False, it retrieves a file with only
the lines for the active VIRUS IFUs (No commented IFUS, no LRS, no
HRS, no HPF).

The code as is should work with Python2 and 3.

.. code-block:: python

    try:
        # Python 3
        from urllib.request import urlopen
        from urllib.error import HTTPError
    except ImportError:
        # Python 2
        from urllib2 import urlopen, HTTPError
    
    
    def get_fplane(filename, datestr='', actpos=False, full=True):
    
        url = 'https://luna.mpe.mpg.de/fplane/' + datestr
    
        if actpos:
            url += '?actual_pos=1'
        else:
            url += '?actual_pos=0'
    
        if full:
            url += '&full_fplane=1'
        else:
            url += '&full_fplane=0'
    
        try:
            resp = urlopen(url)
        except HTTPError as e:
            raise Exception(' Failed to retrieve fplane file, server '
                            'responded with %d %s' % (e.getcode(), e.reason))
    
        with open(filename, 'w') as f:
            f.write(resp.read().decode())


  
FPlane update
*************

To update the fplane data in the database a script is supplied that
should be run on a daily basis as a cron job at HET, updating the
database from the TCS information