<commit_before>Loris JPEG 2000 Server
========================

Loris is a lightweight implementation of the 
[International Image Interoperability Framework: Image API 1.0] [1]. More about 
this is discussed under IIIF 1.0 Compliance [link!] below.

Design
------
Loris is designed to stand on the shoulders of giants. Essentially, all it 
does is parse [IIIF URLs] [2] into a set of objects (in the source these are 
the `RegionParameter`, `SizeParameter`, and `RotationParameter` classes) that 
are then used to build utility command lines that are shelled out.

The [Werkzeug Python WSGI Utility Library] [3] handles the URL parsing and 
routing and supplies a few other conveniences.

Deployment
----------
TODO

Tests
-----
Run `./tests.py`.

Source JPEG 2000 Images
-----------------------
TODO - give PUL sample recipes.

Return Formats
--------------
Right now `jpg` and `png` are supported. The latter is underdeveloped and not 
terribly performant, but is in place so that all of the necessary branching in 
the content negotiation and rendering could be put in place and tested.

Resolving Identifiers
---------------------
The method for resolving identifiers to images is about as simple as it could 
be. In a request that looks like this 

    http://example.com/images/some/img/dir/0004/0,0,256,256/full/0/color.jpg

The portion between the path the to service on the host server and the region, 
i.e.:

    http://example.com/images/some/img/dir/0004/0,0,256,256/full/0/color.jpg
                              \_______________/

will be joined to the `src_img_root` property, and have `.jp2` appended. So if

    [directories]
    ...
    src_img_root=/usr/local/share/images

then this file must exist:

    /usr/local/share/images/some/img/dir/0004.jp2 

This can be revised to fit other environments by replacing the 
`Loris#_resolve_identifier(self, ident)` method.

Dependencies
------------
Addition Python libraries:
 * [Werkzeug] [3] ([Installation] [5])

System Utilites
 * `kdu_expand`
 * `convert` (ImageMagick)


Both of the above should be on your PATH and executable from the command line.

Loris was developed on Ubuntu 12.04 with Python 2.7.2 and has only been tested
in that environment.

Logging
-------
Logging is set up in `loris.conf` and is extremely loud by default. Then 
handlers configured near the bottom of that file control the levels and 
directories. The directories must exist and be writable.

The Name
--------
Could stand for __Lightweight Open Repository Image Server__ or not. Thanks to
[shaune](https://github.com/sdellis, '<NAME>') for coming up with it.

IIIF 1.0 Compliance
-------------------<commit_msg>added section aobut configuration;<commit_after>Loris JPEG 2000 Server
========================

Loris is a lightweight implementation of the 
[International Image Interoperability Framework: Image API 1.0] [1]. More about 
this is discussed under IIIF 1.0 Compliance [link!] below.

Design
------
Loris is designed to stand on the shoulders of giants. Essentially, all it 
does is parse [IIIF URLs] [2] into a set of objects (in the source these are 
the `RegionParameter`, `SizeParameter`, and `RotationParameter` classes) that 
are then used to build utility command lines that are shelled out.

The [Werkzeug Python WSGI Utility Library] [3] handles the URL parsing and 
routing and supplies a few other conveniences.

Deployment
----------
TODO

Tests
-----
Run `./tests.py`.

Source JPEG 2000 Images
-----------------------
TODO - give PUL sample recipes.

Return Formats
--------------
Right now `jpg` and `png` are supported. The latter is underdeveloped and not 
terribly performant, but is in place so that all of the necessary branching in 
the content negotiation and rendering could be put in place and tested.

Resolving Identifiers
---------------------
The method for resolving identifiers to images is about as simple as it could 
be. In a request that looks like this 

    http://example.com/images/some/img/dir/0004/0,0,256,256/full/0/color.jpg

The portion between the path the to service on the host server and the region, 
i.e.:

    http://example.com/images/some/img/dir/0004/0,0,256,256/full/0/color.jpg
                              \_______________/

will be joined to the `src_img_root` property, and have `.jp2` appended. So if

    [directories]
    ...
    src_img_root=/usr/local/share/images

then this file must exist:

    /usr/local/share/images/some/img/dir/0004.jp2 

This can be revised to fit other environments by replacing the 
`Loris#_resolve_identifier(self, ident)` method.

Dependencies
------------
Addition Python libraries:
 * [Werkzeug] [3] ([Installation] [5])

System Utilites
 * `kdu_expand`
 * `convert` (ImageMagick)

Both of the above should be on your PATH and executable from the command line. 

Loris was developed on Ubuntu 12.04 with Python 2.7.2 and has only been tested
in that environment.

Configuration
-------------
Please read through `loris.conf`. Properties and options are explained there.

Logging
-------
Logging is set up in `loris.conf` and is extremely loud by default. Then 
handlers configured near the bottom of that file control the levels and 
directories. The directories must exist and be writable.

The Name
--------
Could stand for __Lightweight Open Repository Image Server__ or not. Thanks to
[shaune](https://github.com/sdellis, '<NAME>') for coming up with it.

IIIF 1.0 Compliance
-------------------
{'fraction_non_alphanumeric': 0.12229556288962229, 'fraction_numerical': 0.021268793546021268, 'mean_word_length': 3.0861423220973783, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3327156', 'n_tokens_mistral': 1651, 'n_tokens_neox': 1509, 'n_words': 680}