.. include:: <isonum.txt>

==============================
Introduction and Installation
==============================

:program:`AdNite2` provides libraries and programs for estimating
natural night time illuminances. Artificial illumination is not
covered. The program ships together with a rudimentary sqlite location
database.  :program:`AdNite2` is an acronym for *Admont Nightvision
Tool - Version 2*.

It is loosely based on the open source software project 'adnite' -
http://adnitevision.foehnwall.at.


Programs/Scripts
================

* :program:`adnite2`

* :program:`adnite2-cli`

* :program:`adnite2dbedit`

* :program:`adnite2cratedb`

For a detailed decription see section :ref:`programs`.


Required python3 libraries
==========================

* **Linux operating system**. Tested with

  * Ubuntu 16.04 (Xenial Xerus)

  * Ubuntu 14.04 (Trusty Tahr)

  * Ubuntu 15.04 (Wily Werewolf)

  * Debian 8 (Jessie)

  Probably it will run with Windows\ |reg| after some
  installation and configuartion processes. It has not yet been
  tried.

  Troubles are observed with Debian 9 (Stretch - Testing) because of changing behaviour  

* **Python 3.4** or higher

* python setuptools: https://pypi.python.org/pypi/setuptools to run
  installations.

  * For downloading packages python pip3:
    
    * https://pypi.python.org/pypi/pip,
    
    * https://en.wikipedia.org/wiki/Pip_%28package_manager%29,
      
    * https://wiki.ubuntuusers.de/pip

* Tkinter should be part of any python3 standard installation:

  * https://docs.python.org/3/library/tkinter.html

  The 'tkinter' related libraries ScrolledText, tkFileDialog,
  tkMessageBox are also part of the standard installation.

* PIL/PILLOW (python imaging library with PIL-TK): python-pil and
  python-pil.imagetk:

  * http://pillow.readthedocs.org/en/latest/#pillow

  * For a discussion see
    https://en.wikipedia.org/wiki/Python_Imaging_Library

* numpy: http://www.numpy.org/

* scipy: http://www.scipy.org/

* matplotlib: http://matplotlib.org/

* pyephem: http://rhodesmill.org/pyephem/

* unidecode (for program :program:`adnite2createdb`) :
  https://pypi.python.org/pypi/Unidecode
  
* jinja: http://http://jinja.pocoo.org/ (not yet needed)


Required external programs
==========================

* Web browser, e.g. Firefox: https://www.mozilla.org/en-US/firefox/new/

* Pdf-viewer, e.g. Evince: https://wiki.gnome.org/Apps/Evince

* `reStructuredText <https://en.wikipedia.org/wiki/ReStructuredText>`_
  to html generateror :program:`rst2html` as part of the package
  *python3-docutils* (standard package):
  http://docutils.sourceforge.net/

* `reStructuredText <https://en.wikipedia.org/wiki/ReStructuredText>`_
  to pdf generator: :program:`rst2pdf` as a *python2* (!) program:
  https://pypi.python.org/pypi/rst2pdf

  **rst2pdf needs a python 2.7 environment!**
	   
The utility programs are partly configureable via the text file
:file:`~/.adnite/adnite.cfg`.

All required libraries and programs should be available via the
standard respositories of recent Linux distributions.





Install (only Linux and python >=3.4)
=====================================

1. Unpack source code package:

   ::

       > tar -xvz adnite2-<version>.tar.gz

   wherever you like. You will get a directory *adnite2-<version>*.

3. Enter with

   ::

      > cd adnite2-<version>

2. Run

   Recommended:

   ::

      > sudo python3 setup.py install

   Makes a full installation below :file:`/usr/local` also for the
   libraries

   For a testing environment:

   ::

      > sudo python3 setup.py develop

   Installs the scripts *adnite2*, *adnite2-gui*, *adnite2-cli* and
   *adnite2dbedit* (most likely) into

   ::

      /usr/local/bin

   and installs pointers to the source files you downloaded

.. warning::

   On some platforms there are **troubles for the standard install
   procedure** because of unresolved dependencies.

   Try :code:`> sudo python3 setup.py develop` instead. That always
   seems to work ;)



3. Important:

   Each time the program starts the existance of directory
   :file:`~/.adnite2` is checked. If the directory does not exist the
   configuration directory is copied from a template. In case of
   troubles delete the old configuration directory by

   ::

      > rm -r ~/.adnite2

   and restart the program. Alternatively perform by 'hand':

   ::

      > cd adnite2-<version>
      > cp -r config ~/.adnite2

-------------------------------------------------------------------

**Feedback: adnite(at)foehnwall(dot)at**