Prime Visualisation
===================

A program  which  can  be  used to  create,  view  and  save  various  graphical
representations of prime numbers and prime number related data classifications.

Developed using the 2.7.9 implementation of the CPython (standard) interpreter.


Running the Program
-------------------

If  all the  dependencies are  present and  have the correct  version installed,
simply run the program from the base directory with the following command:

    python main.py


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

* Python v2.7.9
  - https://www.python.org/
* Numpy v1.9.2
  - http://www.numpy.org/
* Pillow v2.8.1
  - http://pillow.readthedocs.org/
* PyQt4 v4.11.3
  - http://pyqt.sourceforge.net/Docs/PyQt4/installation.html
* Nose v1.3.4
  - https://nose.readthedocs.org/en/latest/
* Vispy v0.3.0
  - http://vispy.readthedocs.org/en/v0.3.0/
  - N.B. The  current development  version is v0.4.0.  This  is  not   backwards
         compatible so please ensure v0.3.0 is installed --- this is the current
         release present on `pip' as of 07 May 2015.
  - v0.3.0 Source found here: https://github.com/vispy/vispy/releases/tag/v0.3.0
* PyOpenGL v3.1.0
  - http://pyopengl.sourceforge.net/documentation/installation.html

N.B. It's probably  best to  read  the  documentation on  how to install them at
the urls above.


Structure of the Project
------------------------

All source code is found  within the `primes' directory. Different functionality
in the program has been split up into multiple packages:

* Generator
    - Classes which  generate the  datasets used  by the program  along with the
      data itself.
    - There is 1  generator to a  dataset. These  unique generators  all inherit
      from the Generator class found within primes/generator/generator.py
    - Generators themselves have no individual packages, instead residing in the
      generator directory with unique (and identifiable) names.
    - The generators  write cache files to a  subdirectory of a matching name in
      the primes/generator/data/ directory.

* Visualisation
    - Classes which  generate the actual visualisations which will  be displayed
      in the user interface.
    - Each visualisation inherits from the Generic class found within generic.py
      at primes/visualisation/generic.py.
    - gl_base.py: Implements an  extension of Vispy's Canvas class which is used
      in  most  of  the  visualisations  to  generate interactive,  OpenGL based
      layouts.
    - Each  subdirectory in  the visualisation  package  contains  one  or  more
      modules for creating unique visualisations. There is no  naming convention
      present  and no  limit on the  number  of helper files (see  the wireframe
      package)  however the module from  which the  Ui  class  has a handle MUST
      implement one of either the to_image() or to_gl() functions. These are the
      functions which are called from the Ui which generate the visualisation at
      run time.

* Ui
    - Classes which pertain to the user interface.
    - gui.py: The implementation and core functionality of the user interface.
    - tabbed_window.py: The auto-generated code from Qt Designer which initiates
      all Ui components.
    - form_handler.py: Classes  which  perform the task of  auto  loading unique
      forms corresponding to each visualisation when the user changes the layout
      in the `layout' drop box within the Ui.
    - The forms  directory contains a number of subdirectories which each relate
      to an individual visualisation.  These are the functions and classes which
      are called  from  the  form handler  module in  order  to create a dynamic
      interface.

* Utils
    - A package containing a collection of miscellaneous  modules and  functions
      used in various places within the program.

* Tmp
    - Used  to store temporary  images, namely the images which are generated by
      the program when a user wishes to save (export) a visualisation.

* Tests
    - A collection of unit tests for various parts of the program.
    - To run the tests, navigate to primes/tests/ and run the following command:

            nosetests

    - Note that  the file `1.dat' should be present in the data  subdirectory of
      the test directory in order for the tests to pass.

* Ui Files
    - A collection of .ui files which have been created from layouts designed in
      the  Qt Designer  program.  These are converted  to Python code using  the
      py2uic4 program (provided by PyQt).