Internet Imaging Protocol
The protocol for communication between the client and server is based on the Internet Imaging Protocol (though the server also supports the Deepzoom and Zoomify protocols – see below for more details). This protocol was initially developed by the now defunct DIG (Digital Imaging Group) consortium to allow high resolution images to be easily streamed over the internet. The protocol is a simple RESTful-like request-reponse protocol allowing access to individual tiles, processing commands, image views or image metadata. It is designed around tiled multi-resolution formats such as TIFF or JPEG2000 and enables flexible URL-based access to both tiles and image regions.
Using this protocol allows the IIPImage server and clients to inter-operate with other IIP-based client-server systems. The IIPImage server supports the main subset of the full protocol (version 1.0.5) and, in addition, several extensions to handle complex image types such as 3D object sequences, multispectral images and surface elevations etc.
The main commands are:
|FIF||Image path [FIF=/path/image.tif]|
|JTL||Return a tile in JPEG format with index n at resolution level r [JTL=r,n]|
|CVT||Return the full image or a region (in JPEG format only) [CVT=jpeg]|
|WID||Requested image width for CVT requests [WID=w]|
|HEI||Requested image height for CVT requests [HEI=h]|
|RGN||Define a region of interest starting at relative coordinates x,y with width w and height h [RGN=x,y,w,h]|
|CNT||Contrast – multiplication of pixel values by factor [CNT=c]|
|ROT||Rotate image by given number of degrees. Only 90, 180 and 270 supported [ROT=r]|
|GAM||Apply gamma correction [GAM=g]|
All requests take the general URL form:
<http/https>://<server address>/<iipsrv.fcgi>?<IIP Commands>
The first IIP command must specify the image path and several IIP command – value pairs can be chained together using the separator & in the following way:
=> FIF=<image path>&<command>=<value>&<command>=<value>
A typical full request is of the form:
where FIF is the path to the image on the server and JTL is the request for a single JPEG compressed tile, specifically tile 5 from resolution number 2.
To request the same tile, but with a contrast factor of 1.5:
To request an export in JPEG format at a particular width, use the CVT=jpeg command together with WID=width. Thus to request a 400px wide version of image.tif:
To request the same 400px image but rotated by 90°:
To request the export of a region at a particular size within an image, use the
RGN=left,top,width,height command where the left,top,width and height are defined as floating point numbers between 0 and 1. So, if you want the image to be the middle 50% of the image, use:
Note that the FIF command must always be the first parameter and the JTL or CVT command must always be the last.
There are several extensions to the IIP protocol to allow tiles of different sizes to be used and to inform the client what vertical and horizontal sequences of an object exist.
- Tile-size: The horizontal and vertical size of the image tiles. eg. “64 64″. The IIP specification limits the tiles to 64×64 pixels. However, the IIPImage server and client are able to handle tiles of any size.
- Horizontal-views: A list of space-separated horizontal angles (degrees) available. eg. “0 90 180 270″. If there is only a single image, zero is returned.
- Vertical-views: A list of space-separated vertical angles (degrees) available. The angles are defined from the vertical plane, so a view from directly below the image is zero, directly facing the object is 90 and from directly overhead 180. eg. “0 90 180″. If there is only a single image, 90 is returned.
- SHD: (iipsrv version 0.9.7 and later) Simulated hill-shading for image normal data. The argument is the angle of incidence of the light source in the horizontal plane (from 12 o’clock) comma-separated with the vertical angle of incidence with 0 representing a horizontal direction and -1 vertically downwards.
- LYR: (iipsrv version 0.9.9 and later) The number of quality layers in an image to decode. This is for file types that can contain multiple quality layers, such as JPEG2000. For example, a request for LYR=3 will decode only the first 3 quality layers present in the image. The number of layers decoded will be limited to a maximum given by the MAX_LAYERS environment variable if this has been set in the server configuration. This can be useful to either limit the quality of the images users may see or to speed up decoding by only decoding the faster lower quality layers.
- GAM: (iipsrv version 1.0 and later) The gamma to apply to the image.
Deepzoom and Zoomify Protocols
As of version 0.9.8, the IIPImage server can now serve images using either the Deepzoom or Zoomify protocols, thereby allowing the use of these clients while maintaining the benefits of having a full imaging server with single TIFF or JPEG2000 files.
In order to use a Zoomify client with the iipsrv, use a path of the form:
And for Deepzoom (you must add a .dzi suffix to the end of your TIFF or JPEG2000 file path – do not change the name of the TIFF file itself):