Skip to content

Installation

Jump to bottom Edit New page
ahankinson edited this page Jun 6, 2011 · 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 the website. Set it up as a FastCGI module.

  3. Convert the images of the pages of the document viewer into tiled multi-resolution tiff format. This can be most easily done from the command line, using the process.py script provided in the Diva.js installation package. If you want to write your own script to do this, or want to do it manually, you can use the convert command provided by the ImageMagick software suite. For example, to convert a JPEG image named test.jpg into .tif format, you might use the following command:

    convert test.jpg -define tiff:tile-geometry=256x256 -compress jpeg 'ptif:1.tif'

    Note that while the output file (1.tif in this case) must have a .tif or .ptif extension, the rest of the filename can be whatever you wish. For more, see the ImageMagick manual (link?) The VIPS image processing suite can also be used, either using the VIPS GUI or the command line. Using the same example as above, you might run the following command:

    vips im_vips2tiff test.jpg 1.tif:jpeg:75,tile:256x256,pyramid

    where jpeg:75 is the level of compression (other options include none and deflate, but jpeg is recommended as deflate might not work with the Python Imaging Library and none results in uncompressed images. For more, see the VIPS manual (link?).

  4. 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.

  5. 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). Also include instructions on memcaching.

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