Skip to content

Installation

Jump to bottom Edit New page
ahankinson edited this page Nov 27, 2012 · 101 revisions

Setup and installation

Here you'll find instructions on how to set up the document viewer on your own server. It can then be easily integrated into an existing website.

This guide will assume that you already have a website set up on a server and that the images you want to display can be stored on a server capable of running IIPImage.

What you'll need

  • IIPImage server installation package
  • Some (probably scanned) images that you want to display using your document viewer
  • The installation package for Diva.js

Setting up the backend

  1. Download the IIPImage server installation package for the operating system the server you have shell access to runs, from the IIPImage website.
  2. Install IIPImage following the instructions from their website. Set it up as a FastCGI module. ** If you wish to serve JPEG2000 images with IIP, it's a bit trickier. You will need to download the pre-compiled IIP binaries from Old Maps Online, since they require the Kakadu library. Alternatively, you can purchase the source code to the Kakadu libraries and compile your own version.
  3. Convert the images of the pages of the document viewer into tiled multi-resolution TIFF format or JPEG2000 (see the next section).

Image Processing

For image formats you have two options: Pyramid TIFF or JPEG2000. We ship Diva with two scripts for processing these files, process.py and process_jp2.py. These can be used on the command line to convert an entire directory of image files into Pyramid TIFF or JPEG2000 files.

If you wish to use other utilities to convert your images, please see our documentation on image processing.

  1. To test your IIPImage server installation, transfer your newly-generated .tif files onto the server running IIPImage, into a directory that is accessible by whatever the server process is running under (www-data for instance). Then try to load each image by doing this:

    http://www.your-domain.com/fcgi-bin/iipsrv.fcgi?FIF=/path/to/images/image.tif&CVT=JPG

    (or how/wherever your IIPImage server process is started) and see if the image is displayed properly.

  2. Now test the PHP script to make sure that it's working. Make sure it has permission to access the image folder. Try to load the relevant data at a given zoom as follows:

    http://www.your-domain.com/divaserve.php?d=image_directory&z=2

Where image_directory is the name of the image directory and the z parameter is the zoom level. Make sure to first configure the image and cache directories at the top of the PHP script ($IMAGE_DIR and $CACHE_DIR). The images are sorted lexicographically (using PHP's built-in glob() function), so if your images have numbers in them it's a good idea to pad the numbers with 0s (e.g., if the first page is named page1.tif and the last is named page2340.tif, then rename page1.tif to page0001.tif, page10.tif to page0010.tif, etc). This is taken care of by the process.py script, using the built-in Python string method zfill().

Configuring the frontend

###The HTML file###

Create an HTML file that will contain the document viewer. For an example, check out example.html in the Diva.js download. The important elements in the head are as follows:

<head>
	<link rel="stylesheet" href="css/diva.css" type="text/css" />
	<link rel="stylesheet" href="css/ui-lightness/jquery-ui-1.8.9.custom.css" type="text/css" />
	<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.5.2/jquery.min.js"></script>
	<script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.8.11/jquery-ui-min.js"></script>
	<script src="js/diva-utils.js"></script>
	<script src="js/diva.js"></script>
	<script>
	$(document).ready(function() {
		$('#diva-wrapper').diva({
			iipServerBaseUrl: "http://www.mydomain.com/fcgi-bin/iipsrv.fcgi?FIF=/path/to/images/image_directory_name",
			backendServer: "http://www.mydomain.com/divaserve.php?d=image_directory_name"
			// Other options can be set here as well
		});
	});
	</script>
</head>

To see the other options that can be set upon instantiation, see the overrideable settings section. Such options include setting a fixed (as opposed to adaptive) interpage padding, enabling the use of the space key to scroll down, and making use of callback functions for document viewer events like jumping to a specific page, zooming in or out, or scrolling.

It is not recommended to use a DOCTYPE of strict for the document, as that causes problem with support for Apple touch devices.

The body element should contain a block-level element, generally a div, with the ID specified above (diva-wrapper in this case, although any unique ID is valid, as long as the same one is used within the script tags above). For instance:

<body>
	<div id="diva-wrapper"></div>
</body>

###The CSS###

The included css file (css/diva.css) provides some basic styling. If you need to change anything, it may be easiest to just edit the file directly. The element IDs of the components are as follows:

  • 1-diva-title for the title of the document (this can be disabled by setting enableAutoTitle to false upon instantiation)
  • 1-diva-fullscreen for the icon in the top left corner to toggle fullscreen mode (this can be disabled by setting enableFullscreen to false)
  • 1-diva-tools for the div containing the zoom slider, the "current page" and the "Go to page" box; if both are disabled, then this div will not appear
    • 1-diva-zoom-slider for the zoom slider (using the jQuery UI) - can be disabled by setting enableZoomSlider to false
    • 1-diva-goto-page for the div containing the "Go to page" box - can be disabled by setting enableGotoPage to false
      • 1-diva-goto-input for the text input box where the page number can be entered
      • 1-diva-goto-submit for the submit button that can be clicked to go to a specific page
    • 1-diva-current for the page the user is currently viewing - can be disabled by setting enableCurrentPage to false. The current page is given within a span, and the total number of pages within a label
  • 1-diva-outer for the outer element of the document viewer (required for the dragScrollable plugin); you can set the height and width of this element as desired within the CSS file
  • 1-diva-inner for the inner element; its height and width are determined dynamically (based on the dimensions of the images)

Note that if you have multiple document viewers on a single page, then the components of the first document viewer will have their IDs prefixed by 1, the second 2, and so on. If you want to style all instances equally, using the div[id$=diva-something] type of CSS selector, as is done in css/diva.css, might be easiest. You can distinguish between individual instances using the ID of the element each has been created on (in double.html, for instance, the elements would be #diva-one and #diva-two).

Advanced Topics

If you are expecting to serve up many images, we have found that using load balancing across multiple IIP FastCGI instances, along with multiple Memcached stores, dramatically improves the performance of Diva.

Load Balancing

We use the NginX webserver for a front-end to the IIP Image Server. The following is a snippet from an NginX configuration file that load balances across five IIP Image Servers.

upstream iip {
	server 127.0.0.1:9010;
	server 127.0.0.1:9011;
	server 127.0.0.1:9012;
	server 127.0.0.1:9013;
	server 127.0.0.1:9014;
}

server {
       	listen 9000;
	server_name example.com;

	location /fcgi-bin/iipsrv.fcgi {
		fastcgi_pass 	iip;
		fastcgi_param   PATH_INFO $fastcgi_script_name;
                fastcgi_param   REQUEST_METHOD $request_method;
                fastcgi_param   QUERY_STRING $query_string;
                fastcgi_param   CONTENT_TYPE $content_type;
                fastcgi_param   CONTENT_LENGTH $content_length;
	}

}

You would configure this setup by pointing the iipServerBaseUrl to http://example.com:9000/fcgi-bin/iipsrv.fcgi?FIF=/path/to/images/image_directory_name.

Memcached

The 0.9.9 release of the IIP Image Server supports the definition of multiple memcached instances for caching pre-processed images. This dramatically reduces the response time of the tile server, and is especially useful for often-consulted books. Notes on how to set this up are available on the IIP website.

In addition, the divaserve.php script also accepts a memcached server for caching the JSON response to be sent to the browser.

Alternatives

  • What if I want to put the PHP script on a different server?

proxy_pass

  • What if I don't have a website yet but just want to test it out? slash, is there a demo available?

  • What if I want to put two document viewers on the same page?

Check out double.html for an example (the associated css file is css/double.css)

Add a custom footer

Clone this wiki locally