iipsrv 1.2 released

Version 1.2 of iipsrv, the IIPImage server, is now officially released and available for download! This is a major new version containing a whole host of new features, major performance enhancements, optimizations, numerous bug-fixes and stability enhancements. Major new features include support for output in PNG and WebP formats, support for TIFF image stacks such as OME-TIFF, support for the new HTJ2K JPEG2000 format, improved IIIF support, new image processing functions and more.

New features include:

• New output formats: PNG (including transparency support) and WebP
• Support for TIFF image stacks
• HTJ2K (High Throughput JPEG2000) support
• Support for microscopy formats, such as OME-TIFF and (partial support) for Aperio SVS files.
• Improved IIIF support with full handling of versions 1,2 and 3 of the IIIF Image API
• New Logarithm and convolution image processing functions
• Improved metadata support
• Improved Windows support
• Performance enhancements

New Output Formats

This version of iipsrv adds output support for both PNG and WebP formats. Transcoding to PNG or WebP is available through both the IIP and IIIF APIs and tiles or regions can be requested in the same way that JPEG images can.

The default quality levels can be set using two new startup parameters: PNG_QUALITY and WEBP_QUALITY. For WebP, this value works in a similar way to JPEG and should be set to an integer between 0 and 100, where 0 is the highest amount of compression and, therefore, the lowest image quality, whereas 100 represents the best image quality, but a much larger file size. By default, this is set to 50.

For PNG, images are lossless and so this parameter does not affect the image quality, but rather the trade-off between compression and speed. The PNG_QUALITY parameter essentially controls the level of Deflate compression and should be set to an integer between 1 and 9, where 1 is the fastest compression (default) and 9 the slowest (and best) compression. The quality parameters for both PNG and WebP can also, as with JPEG, be set on-the-fly when using the IIP API via the QLT parameter.

WebP and PNG are available through both the IIP and IIIF APIs:

Examples

IIP API

To request an image resized to 1000 pixels in width in PNG format, you can use the CVT command when using the IIP API with the following syntax (replace PNG by WebP for WebP format):

http://your.server/fcgi-bin/iipsrv.fcgi?FIF=image.tif&WID=1000&CVT=PNG

To request an individual tile at a particular resolution level in PNG format, you can use the PTL command, which works in the same way as the existing JTL command for JPEG. For example to request the tile with index 7 from resolution 3:

http://your.server/fcgi-bin/iipsrv.fcgi?FIF=image.tif&PTL=3,7

For WebP tiles, the analogous WTL command should be used:

http://your.server/fcgi-bin/iipsrv.fcgi?FIF=image.tif&WTL=3,7

To specify a particular compression quality, the QLT parameter can be used. For example, to resize to WebP format with a width of 750 pixels and compress to a quality level of 10:

http://your.server/fcgi-bin/iipsrv.fcgi?FIF=image.tif&WID=750&QLT=10&CVT=WebP

IIIF API

For IIIF, you simply need to replace the suffix of the request. Thus, to output an image with size 1000px in width in PNG format:

http://your.server/iiif/image.tif/full/1000,/0/default.png

Replace .png by .webp for WebP format.

New Input Formats

TIFF Image Stacks

Single file TIFF image stacks are now supported allowing image cubes to be handled. IIPImage has long had support for image stacks or sequences with images stored in separate files. However, iipsrv now supports stacks in which a whole sequence is stored in a single TIFF file. These TIFF files are essentially multi-page TIFFs with the multi-resolution pyramid levels stored using TIFF SubIFDs rather than as full IFDs as is traditionally the case. This allows an entire sequence of separate images to be stored, each with their own set of independent pyramid resolution levels. This structure is used in microscopy with the OME-TIFF format and can be used to handle other types of multi-modal imaging. For more information, see the blog post OME-TIFF Whole Slide Microscopy.

Access to individual slices within the stack can be made using the existing SDS command. For example to get a 500px overview image of the 6^th image in the stack (index=5) in WebP format:

http://your.server/fcgi-bin/iipsrv.fcgi?FIF=image.tif&SDS=5&WID=500&CVT=WebP

A new stack metadata command has been added to get access to the list of slices. This will return a list of slice names and their scaling factor in JSON format. The name of each slice should be stored in the TIFF DocumentName tag (269) and the scale in the STONITS (Sample value to Nits) tag (37439) tags respectively.

http://your.server/fcgi-bin/iipsrv.fcgi?FIF=image.tif&OBJ=stack

The existing line profile (PFL) and spectral response (SPECTRA) commands work seamlessly with these image stacks and will output quantitative spectral or profile data adjusted using any scaling factors associated with each slice.

Aperio SVS

This release also adds partial support for Aperio SVS microscopy files. These are essentially tiled multi-resolution TIFF files, but with each sub-resolution being a factor of 4 smaller and with the IFD sequence interspersed with thumbnail and other images. You can see iipsrv serving an SVS file in this demo. However, many SVS files contain non-standard TIFF features, such as JPEG2000 encoded images, which are not support by libtiff and, therefore, not supported by iipsrv.

High Throughput JPEG2000: HTJ2K

High Throughput JPEG2000 (HTJ2K) is a recent extension (Part 15) to the JPEG2000 format standard, which improves both encoding and decoding performance by using a faster block decoder. HTJ2K aims to improve the encoding and decoding throughput while maintaining compatibility with the original JPEG 2000 format. To achieve this increase in speed, it sacrifices the ability to use quality layers within JPEG2000 and also results in a slightly larger file size than when using standard JPEG2000.

IIPImage supports HTJ2K images in .jph format as long as a recent version of Kakadu (8.3 or higher) or OpenJPEG (2.5 or higher) is used. If debugging is enabled within KakaduImage or OpenJPEGImage classes, iipsrv will log any HTJ2K images.

Decoding speeds when using HTJ2K are almost twice as fast for lossy and ~30% faster for losslessly encoded JPEG2000. More details can be found in this presentation carried out for the IIIF consortium looking at HTJ2K performance and in the article Evaluating HTJ2K as a Drop-In Replacement for JPEG2000 with IIIF published in the journal Code4Lib.

IIIF

The IIPImage server fully supports all existing versions of the IIIF Image API (1, 2 and 3) and now provides maximum level 2 compliance for each. There are also a number of improvements and bug fixes to the IIIF code.

The default IIIF Image API version for iipsrv can be set using the IIIF_VERSION server directive, which is set to 3 for this release.  However, to handle environments where multiple IIIF API versions need to be handled simultaneously, iipsrv can now use HTTP content negotiation in order to determine which API version to use. See the iipsrv IIIF content negotiation documentation for more details.

Improved Windows Support

The build procedures for Windows have been completely updated and new Visual Studio build files are available with dependencies now handled by vcpkg. Vcpkg automates the building and installation of open source library dependencies and, therefore, significantly facilitates building iipsrv on Windows. In addition, continuous integration is now also carried out using Azure pipelines for every commit pushed to the iipsrv source repository on Github to ensure on-going compatibility with Windows.

Image Processing

This version introduces two new image processing functions: logarithm and image convolution. The log transform can be applied by setting the existing gamma (GAM) command to LOG (or LOGARITHM): GAM=log. The transform is essentially out = scale * log( 1 + in ) where scale is 1.0 / log( max + 1.0 ).

Convolution can also now be applied on-the-fly to images using the new CNV command. A matrix (kernel) can be supplied in the form [ a1,a2,a3; b1,b2,b3; c1,c2,c3 ] where a1, a2 and a3 are elements from the top row of the matrix, b1, b2 and b3 from the 2nd row and c1, c2 and c3 are from the 3rd row. Elements within a row are separated by commas and rows are separated by semi-colons. Matrices must be square and of odd dimension and up to a maximum of 5×5 elements in size.

For example, to apply the sharpening convolution matrix show on the left to image image.tif and output the result with a width of 500px in PNG format:

http://your.server/fcgi-bin/iipsrv.fcgi?FIF=image.tif&CNV=[0,-1,0;-1,5,-1;0,-1,0]&WID=500&CVT=PNG

A number of pre-defined matrices are available, which can be set without the need to manually specifiy the individual matrix elements. These are: sobel, prewitt, scharr, laplace, gaussian, sharpen and emboss and can be used using the syntax: CNV=emboss. The above sharpening convolution can, therefore, be re-written in a simpler form:

http://your.server/fcgi-bin/iipsrv.fcgi?FIF=image.tif&CNV=sharpen&WID=500&CVT=PNG

Metadata

XMP metadata was already supported when using TIFF and this release adds support for embedding XMP when using a JPEG2000 source and Kakadu. As before, XMP metadata is automatically added to all exported images, apart from individual tiles requested by pan and zoom viewers, where file size is a key consideration and where such metadata can be larger in size than the tile data itself.

Resolution (DPI) information is also now included in the image for all output formats if included in the source image. This information is scaled appropriately depending on the requested output size. This information is also now included in the IIIF info.json manifest using the physical dimensions extension. For the IIP API, a new DPI request has been added to be able to obtain this information:

http://your.server/fcgi-bin/iipsrv.fcgi?FIF=image.tif&OBJ=DPI

Production Stability

The IIPImage server is regularly used in heavy-load production environments and has a track record for stability and performance. Version 1.2 has undergone thorough and extensive bug and load testing and is the most stable version of iipsrv yet to be released. Furthermore, code analysis from the static analysis tool, Coverity Scan has once again certified iipsrv to be defect free with 0.00 code defects

Download

The iipsrv source code and binary releases are now available from the download section.

Linux users running Debian, Ubuntu, or Fedora will be able to use the default package manager to install or update iipsrv once the packages have been updated.

Source code: iipsrv-1.2.tar.bz2

Mac OS X binaries: iipsrv-1.2-OSX.zip

Windows binaries (64 bit): iipsrv-1.2-win64.zip

Windows binaries (32 bit): iipsrv-1.2-win32.zip

Solaris 11.4 binaries: iipsrv-1.2-solaris11.tar.gz

Special thanks to all the many people who contributed code, bug fixes or who helped to test the server for this release