glymur/docs/source/introduction.rst

=========================================
glymur: a Python interface for JPEG 2000
=========================================

**glymur** contains a Python interface to the OpenJPEG library
which allows linux and mac users to read and write JPEG 2000 files.  For more
information about OpenJPEG, please consult http://www.openjpeg.org.  glymur
should be considered to be alpha-quality software.

glymur tries to support reading and writing of JP2 and J2C files.  Writing
J2C/JP2 files is currently limited to images that can fit in memory, however.
Of particular focus is metadata retrieval, such as XMP packets.

There is some very limited support for reading JPX
metadata.  For instance, **asoc** and **labl** boxes are recognized, so GMLJP2
metadata can be retrieved from such JPX files.

------------
Requirements
------------
glymur works on Python 2.7 and 3.3.  Python 3.3 is strongly recommended.

OpenJPEG
========
OpenJPEG must be built as a shared library.  In addition, you
currently must compile OpenJPEG from the developmental source that
you can retrieve via subversion.  As of this time of writing, svn 
revision 2345 works.  In addition, you should also retrieve their test data, as
you will need it when running glymur's test suite.

Earlier versions of OpenJPEG through the 2.0 official release are not supported.

Be sure to have the following ports/RPMs/debs installed.

    * gcc
    * gcc-c++
    * cmake
    
You should build OpenJPEG with testing turned on.  Consult the OpenJPEG 
documentation on how to do this.  If you use linux, make sure that you 
have the following development packages installed

    * zlib-devel
    * png-devel
    * libtiff-devel
    * lcms2-devel

OS
==

Mac OS X
--------
All the necessary packages are available to use glymur with Python 3.3 via
MacPorts.  A minimal set of ports includes

      * python33
      * py33-numpy
      * py33-distribute

To run all the testing, one of the following combinations of ports must
additionally be installed:

      * py33-scikit-image and either py33-Pillow or freeimage
      * py33-matplotlib and py33-Pillow

Linux
-----

Fedora 18
'''''''''
Fedora 18 ships with Python 3.3, so all the necessary RPMs are available to 
meet the minimal set of requirements.

      * python3 
      * python3-numpy
      * python3-setuptools
      * python3-matplotlib (for running tests)
      * python3-matplotlib-tk (or whichever matplotlib backend you prefer)

A few tests still will not run, however, unless one of the following
combinations of RPMs / Python packages is installed.

      * scikit-image and either Pillow or freeimage
      * matplotlib and Pillow

The 2nd route is probably the easiest, so go ahead and install Pillow
via pip since Pillow is not yet available in Fedora 18 default
repositories::

    $ yum install python3-devel       # pip needs this in order to compile Pillow
    $ yum install python3-pip
    $ pip-python3 install Pillow --user
    $ export PYTHONPATH=$HOME/.local/lib/python3.3/site-packages:$PYTHONPATH

Fedora 17
'''''''''
Fedora 17 ships with Python 3.2 and 2.7, so these steps detail working with 
2.7.  

Required RPMs include::

      * python
      * python-mock
      * python-pip
      * python-setuptools
      * numpy

In addition, you must install contextlib2 via pip.

A few tests still will not run, however, unless one of the following 
combinations of RPMs / Python packages is installed.

      * scikit-image and either Pillow or freeimage
      * matplotlib and Pillow

scikit-image is not available in the Fedora 17 default repositories, but 
it may be installed via pip::

    $ yum install Cython       # pip needs this in order to compile scikit-image
    $ yum install python-devel # pip needs this in order to compile scikit-image
    $ yum install freeimage    # scikit-image uses this as a backend
    $ yum install scipy        # needed by scikit-image
    $ pip-python install scikit-image --user
    $ pip-python install contextlib2 --user
    $ export PYTHONPATH=$HOME/.local/lib/python2.7/site-packages:$PYTHONPATH

Windows
-------
Not currently supported.

------------------------------------
Installation, Testing, Configuration
------------------------------------

From this point forward, python3 will be referred to as just "python".

Installation
============

In addition to merely installing glymur, you should adjust your **$PATH**
environment variable in order to be able to use the **jp2dump** script from
the unix command line.

::

    $ python setup.py install --prefix=/install/path
    $ export PYTHONPATH=/install/path/lib/python3.3/site-packages
    $ export PATH=/install/path/bin:$PATH


Configuration
=============
glymur uses ctypes (for the moment) to access the openjp2 library, and
because ctypes access libraries in a platform-dependent manner, it is 
recommended that you create a configuration file to help glymur properly find
the openjp2 library.  You may create the configuration file as follows::

    $ mkdir ~/.glymur
    $ cd ~/.glymur
    $ cat > glymurrc << EOF
    > [library]
    > openjp2: /opt/openjp2-svn/lib/libopenjp2.so
    > EOF

That assumes, of course, that you've installed OpenJPEG into /opt/openjp2-svn.


Testing
=======
In order to run all of the test suite, you will first need the OpenJPEG test
data that you previously retrieved.
Then you should set the **OPJ_DATA_ROOT** environment variable to
point to this directory, e.g.::

    $ cd /somewhere/outside/the/glymur/unpacking/directory
    $ svn co http://openjpeg.googlecode.com/svn/data
    $ export OPJ_DATA_ROOT=`pwd`/data

The test suite may then be run with::

    $ cd /back/to/glymur/unpacking/directory
    $ python -m unittest discover

At the moment, the development version of the library prints quite a few 
warnings to stderr, which you may ignore.  There are also more skipped tests
on Python 2.7 than on Python 3.3.  The important thing will be whether
or not any test errors are reported at the end.