Install Guide
=============

Register
--------

Tracker is an open-source particle tracking application and is free to download
and use. A one-time no-cost registration is required prior to downloading the
software. To register, go to https://mfix.netl.doe.gov/register and submit your
account information. Your application will be manually reviewed and
accepted, so please allow for 2-3 business days for your registration to be
processed. You will receive a confirmation email when you can login.

OS Support
----------

Tracker is a pure python library. As a result, all operating systems that
python and the dependencies can be installed on will run Tracker. Development
and testing is performed on the following operating systems:

- Linux
    - Ubuntu
    - CentOS
- macOS (latest)
- Windows
    - Windows 7
    - Windows 10

Installation
------------

.. _install_conda_cmd:

Using conda
+++++++++++

The easiest and recommended way to install Tracker and the dependencies is
through the Anaconda Distribution. Download and install Miniconda_ or Anaconda_.

Once Miniconda_ or Anaconda_ are installed:

- Browse to the `Tracker Download Page`_
- Copy the conda install command. The conda command will look similar to this,
  but with your own individual username and hexadecimal token::

   conda install Tracker -c https://usr:token@mfix.netl.doe.gov/dist

- Paste the conda install command into your Linux or Mac terminal, or into your
  `Anaconda Prompt` on Windows and Execute the install command.

.. Note::
  On Windows, to open the `Anaconda Prompt`, go to the start menu and search For
  Anaconda Prompt. The `Anaconda Prompt` sets up the correct environment, adding
  `conda` and other commands.

The installation will download other dependencies and Tracker. The process
will take a few minutes to complete. Once completed, the application can be
started by entering the following command into your Linux or Mac terminal, or
into your `Anaconda Prompt` on Windows::

  tracker


From source
+++++++++++

If you already have a python environment setup without using Miniconda_ or
Anaconda_, Tracker can be installed from source:

- Browse to the `Tracker Download Page`_
- Download the tarball, extract, and go into the top level source directory::

   tar xf Tracker-*.tar.gz
   cd Tracker

- install Tracker with::

   python setup.py install

Please see the dependencies listed below. Once completed and the dependencies
are met, the application can be started by using the following command::

     tracker

.. Note::
  To build the local documentation, the following libraries are required:
  - sphinx
  - sphinx_rtd_theme

Dependencies
------------

If installed using the :ref:`install_conda_cmd` above, you can skip this part as
the dependencies have already been installed.

The following dependencies need to be satisfied:

- `python` >= 3
- `opencv` >= 2
- `Qt` >= 5
- a Qt wrapper (`PyQt4`, `PyQt5`, or `pyside`)
- `qtpy`
- `numpy`
- `scipy`
- `matplotlib`

Optional dependencies are:

- `psutil` (allows for ram and cpu monitoring)
- `pandas` (write HDF5 files)

These dependencies can be easily meet by downloading and installing
Anaconda_. Once Anaconda is installed, install the required modules by
opening a console on linux and mac or the `Anaconda prompt` on windows and
executing the following command:

.. code:: shell

  conda install opencv numpy qtpy scipy pyqt psutil matplotlib


Update
------

To update Tracker, follow the above install instructions

Uninstall
---------

If installed with conda, uninstall by running the following command::

  conda uninstall tracker

If installed from source, uninstall by running::

  pip uninstall tracker


.. _Anaconda: http://continuum.io/downloads
.. _Miniconda: https://conda.io/miniconda.html
.. _`Tracker Download Page`: https://mfix.netl.doe.gov/mfix/download-tracker