home.md

@@ -10,19 +10,135 @@ the particle velocity.
 
 ![screenshot](/uploads/98c17929e4429634ce520500484d7787/screenshot.png)
 
+## Install
+
+TODO: Construct \*.whl and conda package, upload to mfix.netl.doe.gov/dist
+
 ## Dependencies
 
 The following dependencies need to be satisfied:
 
-- `python` (2 ro 3)
-- `opencv` (2+)
+- `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)
 
 These dependencies can be easily meet by downloading and installing
-[Anaconda][1].
+[Anaconda][1]. 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:
+
+```shell
+conda install opencv numpy qtpy scipy pyqt psutil matplotlib
+```
+
+## Getting Started
+
+To start the application from the source directory, open a console on linux and
+mac or the `Anaconda prompt` on windows and enter the following command from the
+top-level of the source directory (where this README.md file is):
+
+```shell
+python -m tracker
+```
+
+There are a number of command line options that can be passed to the
+application. For a list of all the options, pass a `-h` when starting:
+
+```shell
+python -m tracker -h
+```
+
+## No GUI
+
+The application can be run in a "no gui" mode by passing a `*.trak` file and the
+`--nogui` or `-ng` flag. This will not run the Qt based GUI. The application
+will open the passes `*.trak` file and processing the entire media (video,
+image, synthetic) as specified in the `*.trak` file:
+
+```shell
+python -m tracker examples/50_synthetic_hough_circles.trak --nogui
+```
+
+Multiple `*.trak` files can be processed at the same time by using wild cards
+when specifing the `*.trak` file. For example, process all the included examples
+with:
+
+```shell
+python -m tracker examples/*.trak --nogui
+```
+
+## Code Structure
+
+Most of the files in this repository support the GUI with `app.py` being the
+main entry point. Both the GUI and command line interface (`no_app.py`) are
+started there. The basic image processing pipeline is achieved over three main
+files:
+
+  - videos and images are read with methods in `media_reader.py`
+  - images are processes with the functions in `process_image.py`
+  - particles are tracked using functions in `track.py`
+
+A collection of workers in `workers.py` perform the multithreading or
+multiprocessing of the GUI and video or image processing. Note: multiprocessing
+is not support on windows.
+
+Synthetic data is created with the routines in `synthetic_images.py` and
+supporting functions in `particle_generators.py`.
+
+Some common support functions are contained in the following files:
+
+  - `constants.py` holds various "global" constants
+  - `stats.py` contains methods for calculating and saving statics from the
+    tracks
+  - `tools.py` contains common functions, mainly supporting the GUI.
+
+The rest of the files support the GUI:
+
+  - `app.py` is the main entry point and GUI code
+  - `image_viewer.py` is the image viewer widget that shows the images and draws
+    the tracks, etc.
+  - `main_menu.py` is the code for the main menu (save, load, examples, info,
+    help, etc.)
+  - `tone_curve.py` is the tone curve widget
+  - `widget_map.py` contains the dictionary that relates the GUI widgets to
+    variables. This is what is saved and is available to the processing
+    functions
+  - `widgets.py` contains custom widgets used throughout the GUI
+
+The `*.ui` files stored under `uifiles/` are xml files created with Qt's
+designer. This is where the majority of the widgets are defined and placed
+in the GUI.
+
+
+## Tests
+
+There are a collection of unit tests located under the `tests` directory. These
+tests are run using the `pytest` library which can be installed using conda:
+
+```shell
+conda install pytest pytest-cov
+```
+
+These tests can be run by executing the following command in a console on linux
+and mac or the `Anaconda prompt` on windows in the top level directory:
+
+```shell
+pytest
+```
+
+A coverage report can be generated with the following command
 
+```shell
+pytest --cov=tracker
+```
 
 [1]: http://continuum.io/downloads
\ No newline at end of file