The IIPImage server natively supports several image request protocols: IIP (Internet Imaging Protocol), IIIF (The International Image Interoperability Framework), Zoomify and Deepzoom. They can all be used on the same server and image and allow various clients to interface simultaneously with IIPImage. IIP is the most feature-rich protocol allowing not only tile-based access, but also the export of resized images or regions, and allows real-time image processing to be carried out. IIIF also allows the export of regions, while Zoomify and Deepzoom give access to tiles only.
Internet Imaging Protocol
The protocol for communication between the client and server is based on the Internet Imaging Protocol. 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||Export the full image or a region (only JPEG format currently supported) [CVT=jpeg]|
|WID||Requested export image width in pixels for CVT requests [WID=w]|
|HEI||Requested export image height in pixels for CVT requests [HEI=h]|
|RGN||Define a region of interest starting at relative coordinates x,y with width w and height h. All values should be in ratios 0-1.0 [RGN=x,y,w,h]|
|CNT||Contrast – multiplication of pixel values by factor [CNT=c]|
|ROT||Rotate (and flip) image by given number of degrees. Only 90, 180 and 270 supported [ROT=r]. If angle is prefixed by an exclamation mark !, the image is flipped horizontally before rotation (ex: ROT=!90). Vertical flipping can be achieved by combining horizontal flipping and 180° rotation. (iipsrv version 1.0 and later)|
|GAM||Apply gamma correction [GAM=g] (iipsrv version 1.0 and later)|
|SHD||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.|
|CMP||Generate colormap using one of the standard colormap schemes (GREY, JET, COLD, HOT, RED, GREEN and BLUE). [CMP=s] (iipsrv version 1.0 and later)|
|PFL||Export profile at resolution r from position x1,y1 to x2, y2. Only horizontal or vertical profiles are currently supported [PFL=r:x1,y1-x2,y2]. (iipsrv version 1.0 and later)|
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 from within an image at a particular size, use the
RGN=left,top,width,height command where the left,top,width and height should be floating point numbers between 0 and 1 indicating the ratios you want. So, if you want to export a 400px wide JPEG and crop to 50% from the center 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.
Beyond the original specification, there are several extensions to the IIP protocol to allow tiles of different sizes to be used, to inform the client what vertical and horizontal sequences of an object exist, to apply dynamic hill-shading to 3D map data and to apply gamma corrections etc:
- 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.
IIIF, The International Image Interoperability Framework, is a protocol for image retrieval created by a community of the world’s leading research libraries and image repositories have embarked on an effort to collaboratively produce an interoperable technology and community framework for image delivery. As of version 1.0, the IIPImage server supports the IIIF 2.0 API (see this blog post for more details).
The basic API syntax is the following:
To obtain cleaner URLs such as
http://your.server/iiif/image.tif/full/400,400/90/default.jpg for your IIIF requests and eliminate the
iipsrv.fcgi?IIIF= use simple URL rewriting in your web server.
Deepzoom and Zoomify Protocols
As of version 0.9.8, the IIPImage server can 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):