.. fcmaker documentation master file

.. |DOI_latest| image:: https://zenodo.org/badge/119476467.svg
   :target: https://zenodo.org/badge/latestdoi/119476467
   
.. |ascl| image:: https://img.shields.io/badge/ascl-1806.027-blue.svg?colorB=262255
   :target: http://ascl.net/1806.027

.. |pypi| image:: https://img.shields.io/pypi/v/fcmaker.svg?colorB=<brightgreen>
    :target: https://pypi.python.org/pypi/fcmaker/
    
.. |last-commit| image:: https://img.shields.io/github/last-commit/fpavogt/fcmaker.svg?colorB=e6c000
   :target: https://github.com/fpavogt/fcmaker

.. |issues| image:: https://img.shields.io/github/issues/fpavogt/fcmaker.svg?colorB=b4001e   
   :target: https://github.com/fpavogt/fcmaker/issues

.. |astropy| image:: http://img.shields.io/badge/powered%20by-AstroPy-orange.svg?style=flat
    :target: http://www.astropy.org/
   

.. |stars| image:: https://img.shields.io/github/stars/fpavogt/fcmaker.svg?style=social&label=Stars
   :target: https://github.com/fpavogt/fcmaker/

.. |watch| image:: https://img.shields.io/github/watchers/fpavogt/fcmaker.svg?style=social&label=Watch
   :target: https://github.com/fpavogt/fcmaker/
   
   
.. |github| image:: https://img.shields.io/github/release/fpavogt/fcmaker.svg
   :target: https://github.com/fpavogt/fcmaker/releases   


fcmaker |release| |stars| |watch|  
=================================

|pypi| |DOI_latest| |ascl| |astropy| |last-commit| 


.. figure:: ./examples/fcm_plots/MUSE_WFM-AO_DSS2-Red.png
    :width: 750px
    :align: center
    :alt: fcmaker finding chart example
    
    *Figure 1: a typical MUSE-WFM-AO finding chart generated by fcmaker.*
   

.. note::
   I started developing fcmaker during my ESO Fellowship in late 2017. The code is being 
   shared with the community, in the hope that it can be useful to others. But please note 
   that **fcmaker is not an official tool from the European Southern Observatory (and never 
   will be).**
   
   **As of P103,** ESO implemented a Finding Chart Generation service directly into p2, 
   called `p2fc <https://www.eso.org/sci/observing/phase2/p2intro/p2fcFindingCharts.html>`_. 
   p2fc is `based on a direct fork of fcmaker (v103) 
   <https://github.com/fpavogt/fcmaker/issues/13#issuecomment-441762717>`_, but has since 
   gone its own way.  
   
   **As of P104,** a `p2fc <https://www.eso.org/sci/observing/phase2/p2intro/p2fcFindingCharts.html>`_ 
   binding has been added to the `p2api <https://www.eso.org/copdemo/apidoc/>`_ via the 
   ``generateFindingChart()`` function (which includes the option to use custom `FITS` files). 
   This implies that fcmaker has no more `raison d'être`. I have therefore decided 
   **to stop actively maintaining fcmaker**. 
   

Instruments and modes implemented
---------------------------------

   * **MUSE**: all modes
   * **HAWKI**: NOAO, TT-free AO, including fast photometry
   * **XSHOOTER**: all modes
   * **ESPRESSO**: all modes
   * targets with proper motions, ephemeris files
   * tutorial OBs on `p2demo <http://www.eso.org/p2demo>`_

.. warning::
   **As of P104, the development of fcmaker has officially stopped!** I may still be 
   pushing updates (see the :ref:`changelog` for details) to meet some of my personal 
   observational needs, but will make no efforts to maintain all of the code 
   functionalities. You have been warned.

Contents
---------
.. toctree::
   :maxdepth: 1
   
   Home <self>
   installation
   running
   troubleshooting
   examples/gallery
   modules/modules
   faq
   changelog
   acknowledge
   Github <https://github.com/fpavogt/fcmaker>
   

fcmaker is a Python3 module that offers a rapid, easy and automated way to generate 
ESO-compliant finding charts for observing blocks (OBs) located on 
`p2 <http://www.eso.org/p2>`_. fcmaker relies on `p2api <https://www.eso.org/copdemo/apidoc/>`_ 
to easily interact with the `p2 <http://www.eso.org/p2>`_ database.

The design of the fcmaker finding charts is driven by their use at the VLT to support 
night time operations. They aim at providing a clear and accurate view of the expected 
execution of an OB, given its parameters **(i.e. without any further manual input)**. Note 
that unlike `p2 <http://www.eso.org/p2>`_, fcmaker does **not** perform any validation 
checks on the OB: it merely prints what they do, be it valid or not. **In essence, fcmaker 
provides the user with the ability to visually check the content of an OB.**   

I expect/hope that fcmaker, despite being fully automated, will do a reasonable job for 
most OBs of the supported instruments and modes. Should you stumble upon a case where
fcmaker utterly fails to do something useful/elegant, `I'd be keen to know about it 
<frederic.vogt@alumni.anu.edu.au>`_.

.. note::

   The *operational spirit* of fcmaker implies that, at times, its finding charts may 
   not be the most ideal to **design and prepare** an OB. 
   
   For example, fcmaker voluntarily does not display the SGS area for MUSE WFM 
   observations. Whereas it may be important at the design phase to ensure that a given
   SGS star can be accessible in all the OB steps, it is irrelevant for the execution
   of the OB itself, and would unnecessarily crowd the fcmaker finding charts.
   
.. warning::
   Never blindly rely on what fcmaker does. If the finding chart generated by 
   fcmaker looks different from what you expected, this means that:
   
   A) there is a real design flaw in your OB, or
   B) there is a yet undiscovered bug in fcmaker.
      
   In those discordant cases, `feedback <frederic.vogt@alumni.anu.edu.au>`_ will be greatly 
   appreciated.

----


Copyright notice:
 
This file is part of the fcmaker Python module.
The fcmaker Python module is free software: you can redistribute it and/or modify it under 
the terms of the GNU General Public License as published by the Free Software Foundation, 
version 3 of the License.
 
The fcmaker Python module is distributed in the hope that it will be useful, but without 
any warranty; without even the implied warranty of merchantability or fitness for a 
particular purpose.  See the GNU General Public License for more details.
 
You should have received a copy of the GNU General Public License along with the fcmaker 
Python module.  If not, see http://www.gnu.org/licenses/ .
 

