iipsrv 1.3

Ruven

Version 1.3 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 and numerous bug-fixes. This is a fast, stable and production-ready release.

New features include:

JPEG Input Support

Until now only TIFF and JPEG2000 have been supported as input image formats by the IIPImage server. The JPEG format has always been supported, but only as an output format. However, from version 1.3 of iipsrv, it is now possible to use JPEG directly as an input format without the need to first transcode the image to TIFF or JPEG2000.

JPEG is, however, not an ideal format for use with an image server. Unlike formats such as TIFF and JPEG2000, JPEG does not support efficient random-access through tiling nor does it support multi-resolution encoding. Decoding, therefore, will necessarily be much slower than for TIFF or JPEG2000, especially for large images. Nevertheless, for small or even medium sized images, this performance penalty can often be acceptable as it allows JPEG to be used directly without the need to first transcode to a more optimized format.

The implementation fully handles all baseline JPEG images and, in addition, supports ICC, XMP as well as EXIF metadata. Progressive JPEG images, however, should be avoided as they contain multiple scans making them particularly slow to decode.

New Output Formats

This version of iipsrv adds support for both AVIF and TIFF output. Transcoding to AVIF or TIFF is available through both the IIP and IIIF APIs and tiles or regions can be requested in the same way that the existing output formats, JPEG, PNG or WebP can. For IIP requests new tile commands ATL and TTL have been introduced that work in exactly the same way as JTL for JPEG tile output.

For example, to resize a TIFF image test.tif to 500px in width and converted to AVIF format using the IIP API:

https://your.host/fcgi-bin/iipsrv.fcgi?FIF=test.tif&WID=500&CVT=avif

The equivalent request using the IIIF API:

https://your.host/iiif/test.tif/full/500,/0/default.avif

The default quality levels can be set using two new startup parameters: AVIF_QUALITY and TIFF_QUALITY. For AVIF, this value works in a similar way to JPEG and WebP 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 AVIF. iipsrv uses the libavif library for AVIF transcoding and this library supports several backend codecs. The AVIF_CODEC parameter can be used to select the specific default codec to use. Values should be an integer with 0 = auto, 1 = aom, 2 = rav1e, 3 = SVT-AV1. This is set to 0 by default.

For TIFF output, a new TIFF_COMPRESSION startup parameter allows the default compression / encoding of the image to be set. This should be set to an integer where 0 = None, 1 = LZW, 2 = Deflate, 3 = JPEG, 4 = WebP, 5 = ZStandard. The TIFF_QUALITY parameter sets the default compression level for compression schemes that support variable levels. The range of accepted values depends on the compression scheme chosen. For Deflate, this ranges from 1-9, for JPEG and WebP 1-100 and for ZStandard 1-23.

For IIP requests, the encoding quality can also be controlled on-the-fly via the QLT URL parameter. For TIFF, both the encoding and compression can be specified through this parameter. For example to export an image, test.tif in TIFF format resized to a width of 500px with ZStandard encoding and a compression level of 12:

https://your.host/fcgi-bin/iipsrv.fcgi?FIF=test.tif&WID=500&QLT=zstd:12&CVT=tiff

Low Latency Pass-Through Mode

This release introduces a new highly efficient low-latency “pass-through” mode. Previous versions of iipsrv (and most other image servers) first decode an image region when a request is made and then process and re-encode that data to the requested output format. This is  necessary if any modification or image processing needs to be carried out on the image data. These can include geometric transformations such as rotation or resizing or pixel-wise transformation for contrast adjustment, gamma control or if the source image is in a different bit depth to the output data. For example downsampling from 16 bit per pixel to 8 bit per pixel etc. However, in many cases where the image data is simply to be viewed as-is, this slow decode-reencode cycle is entirely unnecessary. A very common usage scenario for iipsrv is as a back-end server to a pan-and-zoom viewer. In such a use case, image tiles are requested which require no resizing or other processing.

This new functionality, therefore, allows encoded image tile data to be sent without the need for any encode-decode cycle when no modification of the image data is required. This provides a fast highly efficient path that allows iipsrv to function as a fully dynamic image server, yet with almost the speed and efficiency of static image tiles. This functionality works only for TIFF input images and exploits the fact that tiled multi-resolution pyramid TIFF contains independent tiles that can be individually encoded using browser-native image formats, such as JPEG and WebP.

If a request is made for an image region that exactly coincides with an existing tile within the TIFF multi-resolution pyramid structure and if the requested output format and compression also perfectly match that in the source image, then the tile is simply extracted as-is with almost zero overhead. This functionality is available when using TIFF with JPEG or WebP compression. Such images can be generated using, for example Vips:

vips tiffsave --tile-width 256 --tile-height 256 --pyramid --compression webp --Q 75 input.tif output.tif

The compressed tiles within a TIFF do not contain metadata (XMP or EXIF) or an ICC profile, as these are stored only once within the top-level TIFF metadata. Thus, If metadata or an ICC profile exists, these are efficiently injected into the output bitstream without modification of the image data itself. This makes such image requests flexible, yet extremely efficient.

This new functionality can be controlled via the new CODEC_PASSTHROUGH startup parameter, which accepts the integer values 0 or 1, where 0 = disabled and 1 = enabled.  This is enabled by default.

IIIF Enhancements

IIIFThis version has improved IIIF support with the introduction of several new features.

info.json

The new IIIF_EXTRA_INFO startup parameter allows arbitrary extra fields to be added to the info.json for an image. Note that quotes need to be properly escaped for the final JSON to be valid and that no trailing comma should be added. For example, to inject a preferredFormats field into the info.json for every image:

export IIIF_EXTRA_INFO='"preferredFormats": [ "webp", "avif" ]'

Multi-page images

The ability to request specific pages within a multi-page TIFF image (TIFFs must be encoded using sub-IFDs) through IIIF is now possible by using a delimiter after the file name part of the URL syntax.  The startup parameter IIIF_DELIMITER allows a character (or string) to be defined for this delimiter. For example, if we set IIIF_DELIMITER to a semi-colon:

IIIF_DELIMITER=";"

then it’s possible to request the 4th page (index starts at 0) from the image test.tif like so:

https://your.host/test.tif;4/full/500,/0/default.jpg

Image processing extensions

This version also introduces access through IIIF to some of the existing image processing functionality available within iipsrv. The ability to perform contrast stretching, histogram equalization, inversion (image negative) and a log transform have until now only been available using the IIP API. However, these features can now be accessed when using IIIF via several non-standard extensions to the IIIF API. The qualities part of the IIIF API already allows images to be converted to grayscale or bitonal. These IIPImage extensions add stretch for contrast stretching, equalization for histogram equalization, negative for inversion and log for the application of a logarithm transform.

For example, the following will render the input image test.tif to an output with a height of 400px, flipped horizontally and converted to a negative in WebP format

https://your.host/test.tif/full/,400/!0/negative.webp

Note that this feature is disabled by default and must be explicitly enabled by setting the startup parameter IIIF_EXTENSIONS to 1.

Metadata

This release supports the inclusion of EXIF data in JPEG, PNG, WebP and AVIF output. Currently this is only available when using JPEG input images and is not yet available for TIFF. The JPEG2000 format does not, in any case, support EXIF directly, but EXIF can be encoded within an XMP block and XMP is fully supported by iipsrv for all image types.

This release also introduces a new COPYRIGHT startup parameter. Copyright or rights information is already taken from any source image metadata and re-injected into the output image format metadata (for formats that support this). This information is also included for IIIF in the IIIF info.json metadata. This new startup parameter extends this and allows a default rights or copyright statement to be set for images that do not have individual copyright metadata within the image itself. This can be set with, for example:

export COPYRIGHT="Copyright IIPImage 2025"

Build and Packaging Improvements

The build configuration has been improved with a view to facilitating things for downstream distribution package managers. A new make check command tests whether the compiled iipsrv executable is able to run and make install now installs a binary iipsrv into the system’s sbin directory (usually /usr/sbin/). Therefore, to fully compile, check and install iipsrv (with no .fcgi suffix) into /usr/sbin/ use:

./configure --prefix=/usr
make
make check
sudo make install

Systemd and OpenRC init scripts and default configuration are also now provided in the scripts directory.

This allows iipsrv to be started through a standard systemd service command:

systemctl start iipsrv

Or through an OpenRC init service:

/etc/init.d/iipsrv start

See READMEs for SystemD and OpenRC for more details on how to install, configure use these.

Debugging

Improved debugging is now possible for developers wishing to test iipsrv. Add the --enable-debug-mode flag during compilation to enable:

./configure --enable-debug-mode
make

You can then start the iipsrv binary on the command line, then type in individual requests or use redirection to send an entire list of URLs with the output saved in the file iipsrv.debug:

src/iipsrv.fcgi < request_list.txt

Production Stability

The IIPImage server is regularly used in heavy-load production environments and has a track record for stability and performance. As with previous versions, version 1.3 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 Alpine Linux will be able to use the default package manager to install or update iipsrv once the packages have been updated.

Source code: iipsrv-1.3.tar.bz2

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

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

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

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