.. _tinstallation:

Installation
============

Python
______

.. note::

	download and install anaconda3 from https://www.anaconda.com/download/

Python is an application to run python scripts. It includes a *Python Standard Library* with many modules (mathematical tools, file and directory access, etc.). The Python Standard Library can be extended by a wide range of free available packages offered by third parts. A package bundles all files used in a module, including, apart of python files  and where applicable, example data, libraries (.dll, .so), etc. Modules are python files and packages. Python distributions add selected free available packages to Python (including its standard library). 

We recommend to install *anaconda*, a distribution including python and over 1000 packages. Check whether your computer has a 32 or 64-bit processor. Donwload anaconda's latest Python 3 version from https://www.anaconda.com/download/ and install it. Use the default installation options. After finishing the installation, you should find a folder *anaconda3* in your home directory (typically /home/MYNAME/anaconda3 in linux or C:/users/MYNAME/Anaconda3 in windows).

Third part packages not included in Anaconda can be additionally installed using the commands *pip* or *conda*. Both are package management systems used to install and manage software packages. 

pip
^^^

PIP is a package manager to install, update, and uninstall packages. Your computer may have different python installations: anaconda3, anaconda2, native python (linux, mac), python inside some software (ArcGIS, QGIS, etc.), etc. Each of them has probably its own pip. Be sure you are installing girs on anaconda3 by using the right pip, in our case ~/anaconda3/bin/pip. You can check in a terminal:

.. code-block:: console

	> pip -version


.. image:: images/pip.png
   :width: 600




Installing gdal
_______________

.. note::

	| python 3: conda install gdal  
	| python 2 for linux & mac: conda install gdal  
	| python 2 for windows: https://www.lfd.uci.edu/~gohlke/pythonlibs/#gdal


*girs* uses, among others, the gdal library. Depending on the operating system (windows, linux, mac) and on the python distribution, GDAL'S installation can be tricky. Therefore, I recommend installing and testing gdal before installing girs.  

Windows: 

	* start the conda prompt
	* install gdal

Linux & Mac OS:
 
	* start a terminal
	* install gdal

.. image:: images/conda_gdal.png
   :width: 600

.. code-block:: console

	> conda install gdal

*conda* will inform which packages will be new installed, updated or downgraded.

gdal for windows and python 2.7
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Eventually you will face problems installing gdal for windows unter python 2.7. Even if gdal was succesfully installed with conda, it may  fail the test *from osgeo import gdal, ogr, osr* as described in Chapter :ref:`testing_gdal`. In this case, first uninstall gdal:

.. code-block:: console

	> conda uninstall gdal

Then download and install the last gdal version from https://www.lfd.uci.edu/~gohlke/pythonlibs/#gdal. Currently they are:

	- GDAL‑2.2.4‑cp27‑cp27m‑win32.whl: for 32-bits CPU
	- GDAL‑2.2.4‑cp27‑cp27m‑win_amd64.whl: for 64-bits CPU

Check your pip (see below)

.. code-block:: console

	> pip --version

Install the wheel, for example for a 64-bit computer:


.. code-block:: console

	> pip install ~/Downloads/GDAL‑2.2.4‑cp27‑cp27m‑win_amd64.whl

Test gdal with python using *from osgeo import gdal, ogr, osr* as described above.

.. _testing_gdal:

Testing gdal
^^^^^^^^^^^^

Start python in the same terminal and insert:

.. code-block:: console

	> python
	>>> from osgeo import gdal, ogr, osr
	
If there is no error, gdal was succesfully installed.

.. image:: images/gdaltest.png
   :width: 600


Installing girs
_______________

.. note::

	pip install girs


girs is currently only available using pip. 

Using pip:

.. code:: console

	> pip install girs
	
pip in a virtual environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you face problems to install gdal in the virtual environment in linux:

.. code:: console

	> sudo apt-get install libgdal-dev
	> sudo apt-get install gdal-bin
	> pip install GDAL==$(gdal-config --version) --global-option=build_ext --global-option="-I/usr/include/gdal"

For windows you can install a wheel from https://www.lfd.uci.edu/~gohlke/pythonlibs/#gdal as described above.

Installing dependencies
_______________________

All dependencies should be automatically installed. Known issues are known for gdal, as described above. The dependencies are:

	- future
	- gdal
	- numpy
	- scipy
	- pandas
	- matplotlib

Testing the installation
________________________

To check whether dependencies are correctly installed:

.. code:: python

	import girs
	girs.check_packages()