Merge pull request #18 from bodleian/develop

Travis, readthedocs, and change to exiftool

.gitignore

@@ -6,4 +6,5 @@ tests/output
 .cache
 /dist/
 /build/
+_build
 /*.egg-info

.travis.yml

@@ -0,0 +1,27 @@
+language: python
+python:
+  - "2.7"
+  - "3.5"
+  - "3.6"
+cache:
+  - pip: true
+  - apt: true
+addons:
+  apt:
+    sources:
+      - sourceline: 'ppa:ubuntu-toolchain-r/test'
+    packages:
+      - unzip
+      - exiftool
+      - libstdc++6
+install:
+  - wget http://kakadusoftware.com/wp-content/uploads/2014/06/KDU7A2_Demo_Apps_for_Ubuntu-x86-64_170827.zip
+  - unzip KDU7A2_Demo_Apps_for_Ubuntu-x86-64_170827.zip
+  - mv KDU7A2_Demo_Apps_for_Ubuntu-x86-64_170827 /opt/kakadu
+  - PATH=$PATH:/opt/kakadu
+  - LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/kakadu
+  - export PATH
+  - export LD_LIBRARY_PATH
+  - pip install -r requirements.txt
+script:
+  - py.test

AUTHORS

@@ -1,7 +1,7 @@
-Authors of image-processing
+Authors of image-processing:
 
 Primary developer: Mel Mason
 Project manager: Andrew Hankinson
 Digital preservation advice: Edith Halvarsson, James Mooney, and Sarah Mason
 
-This software was developed in Bodleian Digital Libraries Systems and Services at the University of Oxford.
+This software was developed in the Bodleian Digital Libraries Systems and Services department at the University of Oxford.

README.rst

@@ -0,0 +1,90 @@
+Image Processing
+================
+.. inclusion-marker-intro-start
+
+Image-processing is a Python library that converts a source image (TIFF or JPEG) to a JP2 file with a focus on digital preservation and making sure the conversion is reversible.
+
+At the Bodleian we use it to generate the derivative image files we ingest into Digital Bodleian for both delivery and long-term preservation.
+
+
+.. image:: https://travis-ci.org/bodleian/image-processing.svg?branch=master
+    :target: https://travis-ci.org/bodleian/image-processing
+    :alt: Build Status
+.. image:: https://readthedocs.org/projects/image-processing/badge/?version=latest
+    :target: https://image-processing.readthedocs.io/?badge=latest
+    :alt: Documentation Status
+
+Use cases
+---------
+- An all-in-one workflow to go from source file to derivatives including all validation checks. The defaults are tailored to Digital Bodleian preferences, but this is customisable.
+- Individual functions to be called separately from a workflow manager like Goobi.
+- Easy TIFF to JP2 conversion from Python: basic Python wrapper around Kakadu, along with some tested parameter recipes.
+
+
+Installation
+------------
+
+``pip install git+https://github.com/bodleian/image-processing.git``
+
+- Compatible with both Python 2.7 and 3.5+
+
+Dependencies
+~~~~~~~~~~~~
+- `Exiftool`_
+    - ``yum install perl-Image-ExifTool``
+    - ``apt install exiftool``
+- `Kakadu`_
+    - If you want to process compressed TIFFs, compile it with libtiff support. In the makefile ``apps/make/Makefile-<OS>``, add ``-DKDU_INCLUDE_TIFF`` to CFLAGS and ``-ltiff`` to LIBS
+- `Pillow`_ prerequisites before pip install
+    - May need some image packages installed before pip installation (may not need lcms2 depending on which TIFF formats you'll be processing)
+    - ``yum install lcms2 lcms2-devel libtiff libtiff-devel libjpeg libjpeg-devel``
+    - The virtual environment's python binary needs to match the Python.h used by GCC. If necessary, use ``export C_INCLUDE_PATH=/usr/local/include/python2.7/``
+- `Jpylyzer`_ prerequisites before pip install
+    - Needs a relatively recent pip version to install - it fails on 1.4.
+
+.. _Exiftool: http://owl.phy.queensu.ca/~phil/exiftool/
+.. _Kakadu: http://kakadusoftware.com/
+.. _Pillow: http://pillow.readthedocs.io/en/latest/
+.. _Jpylyzer: http://jpylyzer.openpreservation.org/
+
+
+
+Quick start
+-----------
+
+To run a full conversion on a TIFF file, with validation, format checks, XMP extraction and creation of a thumbnail JPEG:
+::
+
+    from image_processing.derivative_files_generator import DerivativeFilesGenerator
+    derivatives_gen = DerivativeFilesGenerator(kakadu_base_path="/opt/kakadu")
+    derivatives_gen.generate_derivatives_from_tiff("input.tif", "output/folder")
+
+
+To access the validation and conversion functions separately so they can be integrated into a workflow system like Goobi:
+::
+
+    from image_processing.derivative_files_generator import DerivativeFilesGenerator
+    from image_processing import kakadu, validation
+    derivatives_gen = DerivativeFilesGenerator(kakadu_base_path="/opt/kakadu",
+                                               kakadu_compress_options=kakadu.DEFAULT_LOSSLESS_COMPRESS_OPTIONS)
+
+    # each of these statements can be run separately, with different instances of DerivativeFilesGenerator
+    validation.check_image_suitable_for_jp2_conversion("input.tif")
+    derivatives_gen.generate_jp2_from_tiff("input.tif", "output.jp2")
+    derivatives_gen.validate_jp2_conversion("input.tif", "output.jp2", check_lossless=True)
+
+To just use Kakadu directly through the wrapper:
+::
+
+    from image_processing import kakadu
+    kdu = kakadu.Kakadu(kakadu_base_path="/opt/kakadu")
+    kdu.kdu_compress("input.tif", "output.jp2", kakadu_options=kakadu.DEFAULT_LOSSLESS_COMPRESS_OPTIONS)
+
+
+.. inclusion-marker-intro-end
+
+More information
+----------------
+
+See our `documentation <https://image-processing.readthedocs.io/>`__
+

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = image_processing
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/code.rst

@@ -0,0 +1,32 @@
+=============
+API Reference
+=============
+
+DerivativeFilesGenerator
+------------------------
+.. automodule:: image_processing.derivative_files_generator
+    :members:
+    :undoc-members:
+    :special-members: __init__
+
+Validation
+----------
+.. automodule:: image_processing.validation
+    :members:
+
+Conversion
+----------
+.. automodule:: image_processing.conversion
+    :members:
+
+Exceptions
+----------
+.. automodule:: image_processing.exceptions
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Kakadu
+------
+.. automodule:: image_processing.kakadu
+    :members: