***************************************************
Welcome in the GuitAstro module documentation
***************************************************

1. What is GuitAstro ?
**********************

GuitAstro is a Python module that provides classes and methods
to write scripts for astronomical observations. GuitAstro wraps 
the classical astronomical Python modules (AstroPy, etc.) and
adds functionalities.

GuitAstro is inspired by the software AudeLA written from 1999 
by astronomers of the Toulouse region (France).

Why the name GuitAstro?
	* Official version: **G**\eneral **U**\se of **I**\nstruments and **T**\elescopes in **ASTRO**\nomy.
	* Legendary version: **GUIT**\ alens **ASTRO**\ nomy

.. figure:: doc_images/guitastro_logo.png
	:height: 128px
	:align: center

	GuitAstro Logo.

2. Download Guitastro
*********************

The source code of Guitastro is available using `Git <https://git-scm.com/>`_.
Windows users can install `Tortoige Git <https://tortoisegit.org/>`_ which is user friendly.

You can get Guitastro anywhere in your computer. The examples of this guide consider
to place Guitastro in the folder Documents of your user. If the user is xxx
for linux you have to install guitastro in the folder /home/xxx/Documents. For
Windows users it corresponds to C:\\Users\\xxx\\Documents

Clone the code from the Git repository `https://gitlab.irap.omp.eu/guitastrolib/guitastro.git <https://gitlab.irap.omp.eu/guitastrolib/guitastro.git>`_.

For Linux users, the following git clone command will copy 
all the files of the Guitastro code in the current directory:

.. code-block:: bash

	cd ~/Documents
	git config --global http.sslVerify false	
	git clone https://gitlab.irap.omp.eu/guitastrolib/guitastro.git
	
For Windows users using Tortoise, open a file explorer (Win+E),
create and select a folder where the code will be downloaded.
The contextual menu of the file explorer allows to "Git Clone".
A window opens. Fill the URL entry by 
https://gitlab.irap.omp.eu/guitastrolib/guitastro.git 
and the Directory entry by C:\\Users\\xxx\\Documents\\guitastro. 
Push OK.

For Windows users, if you prefer to use the command line instead of
Tortoise, open a Powershell with Win+R (Open: powershell) and put:

.. code-block:: bash

	cd C:\Users\xxx\Documents
	git config --global http.sslVerify false
	git clone https://gitlab.irap.omp.eu/guitastrolib/guitastro.git

3. Python installation
***********************

There two main ways to install Python:

* **Using default Python installation**. Not recommanded.

.. toctree:: 
   :maxdepth: 3

   python_default

* **Using Anaconda and virtual environments**. Recommanded.

.. toctree:: 
   :maxdepth: 3

   python_anaconda

4. Install Guitastro
*********************

There two main ways to install GuitAstro:

* **Record GuitAstro as a module using setup.py**. This method is good to use GuitAstro but is not adapted to develop GuitAstro.

.. toctree:: 
   :maxdepth: 3

   install_for_use

* **Only apply requirements**. This method is good for developers of Guitastro code but is less convenient to import Guitastro.

.. toctree:: 
   :maxdepth: 3

   install_for_dev
	
5. External resources
*********************

5.1. Resources for Linux
========================

To use Ima.calibwcs you have to install `ASTAP and its quad files <https://www.hnsky.org/astap.htm>`_.
Download the astap_amd64.deb and:

.. code-block:: bash

	sudo apt-get install ./astap_amd64.deb

To use Ima.calibwcs() you have to install `Astrometry.net and its quad index files <https://astrometry.net/use.html>`_:

.. code-block:: bash

	sudo apt install astrometry.net
	sudo apt install astrometry-data-tycho2 
	sudo apt install astrometry-data-2mass

The executable is /usr/bin/solve-field. The default directory where you have to place the index files
is /usr/share/astrometry. However, if you prefer to install the index folders (4100, 4200, 5200) in
another directory, you must change the following line in the configuration
file /etc/astrometry.cfg (sudo):

.. code-block:: bash

    add_path /usr/share/astrometry

For example:

.. code-block:: bash

    add_path /home/myself/astrometry.net

Check solve-field is working before using Ima.calibwcs():

WCS calibration in total blind:

.. code-block:: bash

	cd ~/Documents
	solve-field --crpix-center --overwrite guitastro/tests/data/m57.fits

WCS calibration in case you know approximate coordinates:

.. code-block:: bash

	cd ~/Documents
	solve-field --ra 180 --dec 0 --radius 3 --crpix-center --overwrite guitastro/tests/data/m57.fits

WCS calibration if you know approximate spatial sampling:

.. code-block:: bash

	cd ~/Documents
    solve-field --scale-units arcsecperpix --scale-low 3.5 --scale-high 3.7 --crpix-center --overwrite guitastro/tests/data/m57.fits

5.2. Resources for Windows
==========================

To use Ima.calibwcs you have to install `ASTAP and its quad files <https://www.hnsky.org/astap.htm>`_.


6. Some very simple tests
*************************

.. toctree:: 
   :maxdepth: 3

   guitastro_simple_examples

7. Example collection
*********************

.. toctree:: 
   :maxdepth: 3

   guitastro_examples

8. User guide to program with guitastro Python classes
*******************************************************

Describe how to instanciate guitastro classes to use them in a personal Python code. 

.. toctree:: 
   :maxdepth: 3

   using_guitastro_classes

9. Driving devices with guitastro
*********************************

.. toctree:: 
   :maxdepth: 3

   device_definition

10. Class and method documentation
***********************************

For developers of Python code of GuitAstro:

.. toctree:: 
   :maxdepth: 3

   generate_documentation
	
The classes of GuitAstro.
	 
.. toctree:: 
   :maxdepth: 3

   autodoc_guitastro