Version 1.1 of iipsrv, the IIPImage server, is now officially released! 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 decoding JPEG2000 images via the OpenJPEG library, support for several new image processing functions, ICC profile and XMP embedding support, clean URL support and more.
New features include:
- JPEG2000 decoding via the OpenJPEG library
- ICC profile embedding support
- XMP metadata embedding support
- Clean URLs without the need for server-side URL rewriting
- Logging through syslog
- Histogram equalization and contrast stretch
- Conversion to greyscale or bilevel (aka binary or bitonal)
Open Source JPEG2000
iipsrv has supported JPEG2000 through the proprietary Kakadu library since version 0.9.9. A number of performance improvements to OpenJPEG have been made since then, which have made it practical to use OpenJPEG for JPEG2000 decoding and, thereby, providing a fully open-source solution.
OpenJPEG is now detected at build time and integrated if found. It is recommended that version 2.3.0 of OpenJPEG or greater is used as important performance enhancements were made, including especially better sub-tile decoding. Note, however, that despite these improvements, OpenJPEG remains at best around 30% slower than Kakadu and at worse several times that.
A possible alternative to OpenJPEG is Grok, an open source fork of OpenJPEG that is a drop-in replacement for OpenJPEG and which includes additional optimizations.
IIIF – International Image Interoperability Framework
The IIPImage server provides a fast, stable and robust interface to the IIIF image API and is the most widely used image server for use with IIIF. Version 1.1 of the IIPImage server contains a number of IIIF-related improvements and fully supports all versions of the IIIF Image API up to and including the current version, 2.1. iipsrv is fully compliant with the IIIF specification and has 100% validation from the IIIF validator.
Version 3.0 of the IIIF image API is currently under development and there is already support within IIPImage for the new features that will be included in this forthcoming version making future upgrades to the new IIIF image API straightforward.
Image Processing
Several new image processing functions have been added in this release. It is now possible to perform histogram equalization and contrast stretching. Fast and efficient implementations have been added which enable instant histogram equalization or contrast stretching to be performed on gigapixel sized images. The implementations additionally remove outlier pixel values, thereby providing excellent results on even noisy images. This new functionality can be accessed when using IIP protocol requests through the existing contrast parameter, CNT. The CNT parameter usually takes an integer or float value for contrast adjustment, but can now also take the values EQ (or EQUALIZATION) for histogram equalization and ST (or STRETCH) for contrast stretching. Thus, to perform histogram equalization on an image, simply add the parameter CNT=EQ to the tile or region request. For example, to export the entire image shrunk to a width of 500 pixels with histogram equalization
=> FIF=/path/image.tif&CNT=EQ&WID=500&CVT=jpeg
or to export a single tile with contrast stretching and with tile index 23 at resolution 5:
=> FIF=/path/image.tif&CNT=ST&JTL=5,23
There is also now support for conversion to grayscale or to binary (also known as bilevel or bitonal). For binary images, thresholds are calculated using Otsu’s method. This functionality is available for both IIP protocol requests and for IIIF Image API requests. For IIP requests, this can be achieved through the new COL parameter. For example: COL=gray or COL=grey for greyscale and COL=binary to convert to binary. For example:
=> FIF=/path/image.tif&COL=gray&WID=1000&CVT=jpeg
For IIIF, this is accessible through the Image API quality parameter, which means ending the URL with grey.jpg (or gray.jpg) or bitonal.jpg:
For example, to export an image test.tif uncropped, resized to 400×400 pixels, rotated by 90° and converted to bitonal, use the following URI:
=> test.tif/full/400,400/90/bitonal.jpg
Metadata
ICC profiles from the source TIFF or JPEG2000 image are now automatically added to images exported by iipsrv (both tile requests and resized image or region exports). Set the EMBED_ICC server parameter to 0 to disable this.
XMP metadata included in the source image (TIFF only for the moment) is also now automatically added to all exported images. This is with the exception of individual tile requests, where file size is a key consideration and where such metadata can be larger in size than the tile data itself.
Configuration
Clean URLs
APIs such as IIIF are intended to be used as “clean” URLs with no query parameters. Until now, this has required URL rewriting by the front-end web server in order to map a “clean” request to iipsrv’s IIIF handler, which is of the form: iipsrv.fcgi?IIIF=<IIIF request>. However, it’s now possible to forward these requests directly to iipsrv without any URL rewriting by using iipsrv’s new URI_MAP configuration directive. This directive maps a URL prefix to an iipsrv command using the following syntax:
URI_MAP="prefix=>command"
Thus, to map, for example, requests with a prefix /iiif/ to the IIIF handler, simply add the following to your iipsrv configuration:
URI_MAP="iiif=>IIIF"
You then need to configure your front-end web server to send any requests with such a prefix directly to iipsrv. For example with Apache, use the ScriptAlias directive to alias the prefix to your iipsrv.fcgi instance:
ScriptAlias /iiif "/var/www/localhost/fcgi-bin/iipsrv.fcgi"
For Lighttpd:
"/iiif" => (
("host"=>"127.0.0.1", "port"=>9000, "check-local"=>"disable")
)
And for Nginx:
location /iiif {
...
}
This mechanism can also be used for any of the other supported API’s. For IIP API requests, use the command FIF, for Deepzoom Deepzoom and for Zoomify Zoomify. For example to map a URL prefix “images” to the IIP API, add the parameters URI_MAP=”images=>FIF” to your iipsrv configuration.
Logging
It has always been possible for iipsrv to provide logging to a file. It is now also possible to use the standard POSIX syslog logging facility on platforms that support this. The syslog format is widely supported making it possible to use monitoring software such as Grafana or InfluxDB for real-time analytics and monitoring. To enable syslog output, just set the LOGFILE iipsrv server parameter to “syslog”.
Syslog itself is very customizable and can be configured in a number of ways. For example, to re-direct iipsrv messages into a separate log file, put the following into a configuration file in the appropriate location for your syslogger (for example on Ubuntu with rsyslog: /etc/rsyslog.d/20-iipsrv.conf):
$umask 0022
$FileCreateMode 0644
:programname,isequal,"iipsrv" /var/log/iipsrv.log
& stop
Cache Management
Version 1.1 also enables system administrators to empty the internal iipsrv caches without having to stop and restart the server. To do this, use the POSIX signal functionality available on most platforms to send SIGHUP to iipsrv. This can be easily done on the command line on Linux, Mac OS X and Solaris by providing the iipsrv process ID like this:
kill -SIGHUP <process id>
Production Stability
The IIPImage server is regularly used in heavy load production environments and has a track record for stability and performance. Version 1.1 has undergone thorough bug and load testing. 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.1.tar.bz2
Mac OS X binaries: iipsrv-1.1-OSX.zip
Windows binaries: iipsrv-1.1-win32.zip
Solaris 11.4 binaries: iipsrv-1.1-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
