django-djatokalayers /

Filename Size Date modified Message
15.0 KB
63 B
8.2 KB
1.2 KB


Djatokalayers is a django application for embedding a JPEG 2000 image viewer into your website. The djatokalayers image viewer combines OpenLayers, which provides a Javascript-based viewer interface, with Djatoka, which dynamically serves portions of JPEG 2000 images upon request, obviating the need for creating and maintaining tile cache pyramids.

A template that provides a djatokalayers viewer might look something like this:

{% load djatokalayers %}

    <title>Djatokalayers Viewer</title>
    {% djl_header '' %}
    {% djl_viewer '' %}

That's it. The djl_header template tag provides the OpenLayers javascript, and links to the Djatoka server, while djl_viewer creates the space in the page for the OpenLayers viewer.

Djatokalayers can handle a variety of server setups just by specifying a few configuration variables in your django project's file. It can also create a viewer which allows users to switch between multiple images, and be configured to handle image data stored in any database model.


DjatokaLayers depends on several external pieces. Much of the installation process described below points you toward the resources you need to get the dependencies installed. If you already have everything you need, skip directly to step 5.

  1. Obviously, you need Django. If you don't already have django installed, you probably aren't looking at this software. However, just in case you need them, installation instructions are available on the django project website.

  2. You need the Djatoka JPEG 2000 Image Server. Installation instructions for that are available on the Djatoka SourceForge page.

  3. For the viewer window itself you can download OpenLayers, and save it to a web-accessible location. This is optional. If you don't provide a copy of OpenLayers, djatokalayers will link to the copy hosted on the OpenLayers website.

  4. To make OpenLayers work with Djatoka, you will need Hugh Cayless' OpenLayers OpenURL extension. You will need to save the OpenURL.js file to a web-accessible location.

  5. Finally, you need to install django-djatokalayers itself. It is not yet available in the python package index. In the meantime, you can either install it directly from the mercurial repository using pip, or clone the repository, and install it with the included file.

    To install using pip:

    $ pip install -e hg+

    To install using

    $ hg clone /tmp/django-djatokalayers
    $ cd /tmp/django-djatokalayers
    $ python install

    If the pip or commands fail, you may need to run them as an administrator or superuser. On linux systems, this is usually accomplished by running the command under sudo.

    $ sudo pip install -e hg+
    $ sudo python install

Getting Started

In order to get djatokalayers working, you need to configure your django project to know about your pieces.

  1. As is standard with most django apps, you need to make your project aware of djatokalayers. To do this, add 'djatokalayers' to your INSTALLED_APPS setting.

  2. Then, include 'djatokalayers.urls' in your project's file. A good location for this is at the URL r'^djatokalayers/', but it will work anywhere, as all urls within it are only provided for internal functionality, and will be called as named URLs.

  3. Add custom configuration variables to tell Django how to find and access your Djatoka and OpenLayers installations. These are detailed below in Configuration Variables.

  4. Make Django aware of the djatokalayers context processors. This will allow templates to know about our custom configuration variables through the use of a request context. Though we only need to add djatokalayers.context_processors.djatokalayers_processor, there are a number of default context processors that get deactivated when you add a new context processor. The list of defaults is changing between Django 1.1 and Django 1.2, so check the documentation for updates. (The above link is to the development trunk; make sure you are looking at the template reference for your version of django).

    In Django 1.1, the appropriate setting is:

  5. Load the djatokalayers template tag library near the top of your django template, using the line:

    {% load djatokalayers %}
  6. Import all the needed header pieces using the following line somewhere in the <head> of your HTML template:

    {% djl_header jp2_url %}

    Where jp2_url is the URL of your JPEG 2000 image, which can also be specified as a string. You can also provide a second variable, which specifies the id of the viewer window which will be included below:

    {% djl_header '' 'the_viewer_div' %}
  7. Create the necessary markup for the viewer window itself in the <body> of your HTML template using the following template tag:

    {% djl_viewer '' %}

    The empty first argument is required. Hopefully, I'll find a clean way to change this at some point.

Configuration Variables

Much of the customization for djatokalayers is done by setting a few configuration variables in your file.


A URL pointing to the OpenLayers.js library. If not provided, this defaults to pointing to the public OpenLayers.js library.


A URL pointing to the OpenURL.js file used to add a djatoka image layer to OpenLayers.


A URL pointing to the jquery.js library. If not provided, this defaults to pointing to the public jquery.js library hosted at


A URL pointing to a valid djatoka server that will be managing your images.


The path to djatoka's resolver on the djatoka server. If it is not set, it will default to /adore-djatoka/resolver.



Authentication information to access the djatoka server, if needed. If your Djatoka server is accessible without authentication, you need not specify these settings.

Handling Multiple Images

You can also create a viewer which allows the user to select between a collection of images, by providing a query set as the first argument to djl_viewer:

{% djl_viewer object.image_set.all %}

In the default configuration, this queryset should provide model objects that have a title attribute and a url attribute. If your models are set up differently, just copy djatokalayers/viewer.html to a location where it can override the app-provided template, and, change the part of the template that looks like:

{% for image in image_set %}
    <option value='{{ image.url }}'>{{ image.title }}</title>
{% endfor %}