pyLICORS was built and is maintained in `Python <http://www.python.org>`_ 2.7. 
As far as I am aware it does not use any particular 2.7 feature of 
Python so pyLICORS should also work with other versions 
(at least 2.5+ should not pose problems; but: 
`Python 2 or 3 <http://wiki.python.org/moin/Python2orPython3>`_ and 
`What's new in Python 3 
<http://docs.python.org/release/3.0.1/whatsnew/3.0.html>`_). 

If you follow the instructions below and get **all** third-party 
extension/libraries (both Python and C/C++) to work properly, then 
chances are high it will work also on your Python version.

.. _installation: 

**********************
One-line installation
**********************

Open the command line and run

> pip install pyLICORS

or 

> easy_install pyLICORS


************
Dependencies 
************

.. note:: 

  From experience during the devolopment the most difficult 
  part was to get the Python wrappers for OpenCV to work properly. 
  
  OpenCV has a built in Python wrapper ``cv``, which can be imported using
  ``import cv``. However, the ``pyopencv`` wrapper using the Boost libraries which are
  3-4 times faster on a Windows machine.
  
  Although several third-party wrappers for OpenCV exist (e.g. `ctypes-opencv 
  <https://code.google.com/p/ctypes-opencv/>`_ or `Swig Python Interface from OpenCV
  <http://opencv.willowgarage.com/wiki/SwigPythonInterface>`_), I could only successfully 
  use `pyopencv <https://code.google.com/p/pyopencv/>`_ in Windows.
    
  If you can successfully call the OpenCV Kmeans++ from Python with 
  another wrapper I would appreciate instructions (and a simple demo script) so I can
  include it another wrapper as an option in future relaeses.
  
Required 
========

The most important non-Python software to install are: 

* `OpenCV library <http://opencv.willowgarage.com/wiki/>`_ (version 2.2 [#version22]_ ): collection of powerful and
  **fast** computer vision algorithms. **Absolutely necessary** to perform 
  fast `Kmeans++ <https://en.wikipedia.org/wiki/K-means%2B%2B>`_ (`original paper on kmeans++ <https://www.stanford.edu/~darthur/kMeansPlusPlus.pdf>`_).
  
* `FFmpeg <http://ffmpeg.org/>`_: cross-platform solution to record, convert and stream audio and video. 
  This library is used to write the results of the analysis back to a video file.

* `OpenGL <http://www.opengl.org/>`_: OpenGL for video writing/reading.

* `Boost <http://www.boost.org/>`_: free peer-reviewed portable C++ source libraries. Necessary for pyopencv.

Before installing pyLICORS the following Python packages **must** be installed and run successfully
(installing in this order will avoid dependency problems between libraries): 

* `numpy and scipy <http://numpy.scipy.org/>`_: libraries for scientific computing. 

* `matplotlib <http://matplotlib.sourceforge.net/>`_: plotting library

* `pyopengl <http://pyopengl.sourceforge.net/>`_: Python wrapper for OpenGL. Used for visvis.

* `pyopencv <https://code.google.com/p/pyopencv/>`_: Python wrapper for the OpenCV library 

* `visvis <https://code.google.com/p/visvis/>`_: Video processing module for python. 
  Necessary to read and access videos frame-by-frame. Requires pyopengl and OpenGL.

* `PyTables <http://www.pytables.org/moin>`_: Data storage in HDF5 files with a convenient Python wrapper. 

* `psutil <https://code.google.com/p/psutil/>`_: interface for retrieving information on all running processes and system utilization (CPU, disk, memory, network).

* `PIL <http://www.pythonware.com/products/pil/>`_: another plotting library

.. note::
   If you know another library for Kmeans that can be used from Python and is *faster than OpenCV Kmeans*, please let me know.
  
Optional 
======== 

Recommended packages for better visualization/individual checks of the analysis are: 

* `nibabel <http://nipy.sourceforge.net/nibabel/>`_: read and write access to some common medical and neuroimaging file formats

* `ViTables <http://vitables.org/>`_: GUI for browsing and editing files in PyTables' HDF5 and standard hdf5 formats. 

* `sklearn <http://scikit-learn.org/stable/>`_: powerful machine learning library with a huge selection of methods. In particular, if you can't get
  the OpenCV library to work, then you can use the Kmeans algorithm in sklearn. However, this will be much slower and can only be used for
  small data projects.

* `munkres <http://pypi.python.org/pypi/munkres/>`_: implementation of the Munkres algorithm (also called the Hungarian algorithm or the Kuhn-Munkres algorithm), 
  useful for solving the Assignment Problem.

* `VirtualDub <http://www.virtualdub.org>`_: An excellent program (at least on Windows) to view videos frame by frame (and do 
  almost any other imaginable video processing).

.. note::
  These packages are optional; they are **not necessary** for the core functionality
  of pyLICORS.   
         
.. [#version22] I use version 2.2. As long as you successfully 
   set up a Python wrapper with the OpenCV library
   the actual version should not matter (probably it should at least be 2.2+).
   
.. [#ffmpeg_wrapper] If you are aware of a Python wrapper for ffmpeg that 
   works nicely to read frames of videos
   and write video data from ``numpy.arrays`` please let me know.
   
.. [#virtualdub] An excellent program (at least on Windows) to view videos frame by frame (and do 
   almost any other imaginable video processing) is `VirtualDub <http://www.virtualdub.org/>`_.
   
.. [#system_call] In particular, it uses ``subprocess.Popen(cmd, shell=True, stdout=subprocess.PIPE)``, 
   where ``cmd`` is a particular ffmpeg command to produce useful videos from a sequence of images.