The IIPImage server natively supports several image request protocols or API’s: IIP (The Internet Imaging Protocol), IIIF (The International Image Interoperability Framework), Zoomify and Deepzoom. They can all be used simultaneously on the same server and on any image and allow various different clients to interface simultaneously with IIPImage. IIP is the most feature-rich protocol, which allows both tile-based access as well as the export of resized images or regions. And it also has support for real-time image processing to be carried out. IIIF is a more recent, but widely used standard, which also allows export of both tile and regions, but which has only limited support for image processing. Zoomify and Deepzoom are older formats originally designed for static JPEG tiles and, therefore, give access to tiles only.
Internet Imaging Protocol
The Internet Imaging 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).
A number of extensions have also been implemented to handle image processing and image types such as image sequences, multispectral images and surface elevations data etc.
All requests take the form of a URL with various commands or parameters using standard query string syntax. The main parameters are listed in the following table with the compatibility with the iipsrv version:
| Parameter | Description | Syntax | Server Compatibility |
|---|---|---|---|
| FIF | Full image path. If the FILESYSTEM_PREFIX server parameter has been set, the path is relative to that path. Note that all IIP protocol requests must start with the FIF parameter |
FIF=/path/image.tif | All |
| JTL | Return a tile in JPEG format with index n at resolution level r Note that the JTL parameter must be set after all other parameters |
JTL=r,n | All |
| PTL | Return a tile in PNG format with index n at resolution level r Note that the PTL parameter must be set after all other parameters |
PTL=r,n | 1.2 |
| WTL | Return a tile in WebP format with index n at resolution level r Note that the WTL parameter must be set after all other parameters |
WTL=r,n | 1.2 |
| ATL | Return a tile in AVIF format with index n at resolution level r Note that the AVIF parameter must be set after all other parameters |
ATL=r,n | 1.3 |
| CVT | Export the full image or a region in the specified format (JPEG, PNG, WebP and AVIF currently supported) Note that the CVT parameter must be set after all other parameters |
CVT=jpeg | All |
| WID | Specify width in pixels, w, for exports with CVT request | WID=w | All |
| HEI | Specify height in pixels, h, for exports with CVT requests | HEI=h | All |
| RGN | Define a region of interest starting at relative coordinates x,y with width w and height h. For use with CVT requests. All values should be ratios in the range 0 – 1.0 | RGN=x,y,w,h | All |
| QLT | Set the output compression level, q. Valid ranges are JPEG: 0-100 and for PNG: 0-9 where a higher value means more compression | QLT=q | All |
| CNT | Contrast adjustment: multiplication of pixel values by factor, c. Value should be an integer or float > 0. Histogram equalization and contrast stretching can additionally be requested by specifying EQ (or EQUALIZATION) for histogram equalization and ST (or STRETCH) for contrast stretching |
CNT=c | All EQ: 1.1 ST: 1.1 |
| 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), h and the vertical angle of incidence, v, with 0 representing a horizontal direction and -1 vertically downwards | SHD=h,v | 0.9.7 |
| LYR | The number of quality layers, l, 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. | LYR=l | 0.9.9 |
| ROT | Rotate (and flip) image by given number of degrees, r. Only 90, 180 and 270 supported. 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 | ROT=r | 1.0 |
| GAM | Apply gamma correction, g: each pixel value to the power of g. If g=log or g=logarithm, the logarithm is applied |
GAM=g | 1.0 log: 1.2 |
| CMP | Generate colormap using one of the standard colormap schemes, s: GREY, JET, COLD, HOT, RED, GREEN and BLUE | CMP=s | 1.0 |
| PFL | Export profile in JSON format at resolution r from position x1,y1 to x2, y2. Only horizontal or vertical profiles are currently supported | PFL=r:x1,y1-x2,y2 | 1.0 |
| MINMAX | Define the range of input pixel values to use for a particular channel, c. This scales the pixel values within the given input range to the full output range to provide contrast enhancement for this range. If channel is set to a dash -, then the min and max are applied to all channels. Example: Given a 16 bit monochrome image with difficult to see detail in the dark areas, MINMAX=0:0,4096 can be used to view only those pixels in the 0-4096 range |
MINMAX=c:min,max | 1.0 |
| CTW | Color twist / channel recombination. Recombine the available image channels into a new color image by multiplication through a matrix. Columns are separated by commas and rows are separated by semi-colons. Values can also be negative. Thus, for the 3×3 matrix example provided to the right, the RGB output image will have bands R = R*r1 + G*g1 + B*b1, G = R*r2 + G*g2 + B*b2, B = R*r3 + G*g3 + B*b3. For multi-band images, the row length should correspond to the number of available bands within the image. The number of output bands depends on the number of rows in the matrix. Thus, to output a 1 band greyscale image, specify just a single row. Examples: To perform naive conversion from 3 channel color to 1 channel grayscale: CTW=[0.33,0.33,0.33] To flip the R and B channels and map an RGB image to BGR: CTW=[0,0,1;0,1,0;1,0,0] For a 5-band multispectral image, to show the difference between the 5th and 2nd band (i.e. 5th-2nd) and outputting the result as grayscale: CTW=[0,-1,0,0,1] To create a false-color image from a 4-band RGB-IR image by mapping the G,R,IR channels to the output RGB: CTW=[0,1,0,0;0,0,1,0;0,0,0,1] |
CTW= [r1,g1,b1; r2,g2,b2; r3,g3,b3] |
1.0 |
| INV | Invert image (no argument) | INV | 1.0 |
| COL | Color transformation to output space, c. Valid values are greyscale (GREY or GRAY) or to binary (BINARY). Examples: Convert to greyscale: COL=gray Convert to binary: COL=binary |
COL=c | 1.1 |
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:
http://your.server/fcgi-bin/iipsrv.fcgi?FIF=/path/image.tif&JTL=2,5
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:
=> FIF=/path/image.tif&CNT=1.5&JTL=2,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:
=> FIF=/path/image.tif&WID=400&CVT=jpeg
To request the same 400px image but rotated by 90°:
=> FIF=/path/image.tif&WID=400&ROT=90&CVT=jpeg
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:
=> FIF=/path/test.tif&WID=400&RGN=0.25,0.25,0.5,0.5&CVT=jpeg
Note that the FIF command must always be the first parameter and the JTL, PTL or CVT command must always be the last.
Protocol Extensions
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.
IIIF API
IIIF, The International Image Interoperability Framework, is an API 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.
The basic image API syntax is the following:
{http/https}://{server}{/prefix}/{identifier}/{region}/{size}/{rotation}/{quality}.{format}
The IIPImage server supports all current and previous versions of the API and provides full level 2 conformance.
Full details on IIIF and how to use and configure IIPImage for it can be found here.
Deepzoom and Zoomify APIs
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.
Zoomify
In order to use a Zoomify client with the iipsrv, use a path of the form:
/fcgi-bin/iipsrv.fcgi?Zoomify=/your/image/path.tif
Deepzoom
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):
/fcgi-bin/iipsrv.fcgi?DeepZoom=/your/image/path.tif.dzi
HTTP Request Methods
Web browsers and viewers will usually request images using the standard HTTP GET method. The IIPImage server can handle any HTTP method, but will simply send back an image or data regardless of the method used. In other words, a PUT or DELETE request does not modify the image. One special case, however, is for POST requests for an image region (requests using the IIP CVT command or equivalent IIIF URL). A POST in this case will modify the Content-Disposition type to “attachment” to make the web browser treat the image as a file to be downloaded rather than try to display it.
