iipsrv - IIPImage Image Server

NAME DESCRIPTION SYNOPSIS FILES OPTIONS EXAMPLES PROTOCOLS AND API’S IMAGE PATHS SEE ALSO AUTHORS

IIPImage is an advanced high-performance feature-rich multi-protocol image server for web-based streamed viewing and zooming of ultra high-resolution images. It is designed to be fast and bandwidth-efficient with low processor and memory requirements. The system can comfortably handle gigapixel size images as well as advanced image features such as 8, 16 and 32 bit depths, CIELAB colorimetric images and scientific imagery such as multispectral images. Source images can be either TIFF (tiled multi-resolution pyramid), JPEG or JPEG2000.

The image server can also dynamically export images in JPEG, PNG, WebP, AVIF and TIFF format and perform basic image processing, such as contrast adjustment, gamma control, conversion from color to greyscale, color twist, region extraction and arbitrary rescaling. The server can also export spectral point or profile data from multispectral data and apply color maps or perform hillshading rendering.

SYNOPSIS

Command line use:

iipsrv.fcgi --bind host : port

FILES

iipsrv.fcgi main executable

iipsrv.log log file: usually in /var/log/ or /tmp/

OPTIONS

There are several parameters that can be supplied to iipsrv.fcgi These should be set via the appropriate web server configuration directives if running via Apache or Lighttpd. See EXAMPLES for details of web server configuations. Alternatively these parameters can be set via environment settings if running directly from the command line or from spawn-fcgi.
LOGFILE

The log file the module will (attempt) to write to. Make sure the iipsrv server process has write access to this directory. Version 1.1 and later of iipsrv also supports logging to syslog if "syslog" is given as the value.

VERBOSITY

The level of logging. 0 means no logging, 1 is minimal logging, 2 lots of debugging stuff and 3 even more debugging stuff and 4 a very large amount indeed. Logging is only enabled if LOGFILE has also been defined.

TIFF_COMPRESSION

The default compression encoder for TIFF output. 0 = None, 1 = LZW, 2 = Deflate, 3 = JPEG, 4 = WebP, 5 = ZStandard. The default is 2 (Deflate).

TIFF_QUALITY

The default quality factor for compression when the client does not specify one. When using JPEG or WebP, value should be 0-100. For Deflate 1-9. For ZStandard 1-19. The default is 1.

JPEG_QUALITY

The default JPEG quality factor for compression when the client does not specify one. The value should be between 1 (highest level of compression) and 100 (highest image quality). The default is 75.

PNG_QUALITY

The default PNG quality factor for compression when the client does not specify one. The value should be between 1 (faster but lowest level of compression) and 9 (slower but highest level of compression). The default is 1.

WEBP_QUALITY

The default WebP quality factor for compression when the client does not specify one. The value should be between 0 (highest level of compression) and 100 (highest image quality). A value of -1 can be used to specify lossless encoding. The default is 50.

AVIF_QUALITY

The default AVIF quality factor for compression when the client does not specify one. The value should be between 0 (highest level of compression) and 100 (highest image quality). A value of -1 can be used to specify lossless encoding. The default is 50.

AVIF_CODEC

The AVIF codec to use for encoding. Integer value. Set 0 for automatic codec selection, 1 for aom, 2 for rav1e, 3 for svt. Default is 0 (automatic codec selection)

MAX_IMAGE_CACHE_SIZE

Max image cache size to be held in RAM in MB. This is a cache of the compressed image tiles requested by the client. The default is 10MB.

MAX_IMAGE_METADATA_CACHE_SIZE

Max number of items in metadata cache size. This is a cache of key image metadata (dimensions, tile size, bit depth ...) from an image file. The cache avoids the need to read image file header for each request. Default is 1000. If set to -1, the cache size is unlimited.

FILESYSTEM_PREFIX

This is a prefix automatically added by the server to the beginning of each file system path. This can be useful for security reasons to limit access to certain sub-directories. For example, with a prefix of "/home/images/" set on the server, a request by a client for "image.tif" will point to the path "/home/images/image.tif". Any reverse directory path component such as ../ is also filtered out. No default value.

FILESYSTEM_SUFFIX

This is a suffix added to the end of each file system path. It can be combined with FILESYSTEM_PREFIX. It is not used in combination with FILENAME_PATTERN. If e.g. this is set to ".tif", an image URL such as "/UUID" will look for "${FILESYSTEM_PREFIX}/UUID.tif". In the IIIF info.json document, the image @id will be set without the ".tif" suffix.

MAX_CVT

The maximum permitted image pixel size returned by the CVT command in conjunction with WID or HEI or RGN. The default is 5000. This prevents huge requests from overloading the server

ALLOW_UPSCALING

Determines whether an image may be rendered at a size greater than that of the source image. A value of 0 will prevent upscaling. The default is 1 (upscaling is allowed).

MAX_LAYERS

The maximum number of quality layers to decode for image that support progressive quality encoding, such as JPEG2000. Ignored for other file formats. By default half of the available layers are decoded. If set to -1, all the available layers will be decoded.

WATERMARK

TIFF image to use as watermark file. This image should be not be bigger the tile size used for TIFF tiling. If bigger, it will simply be cropped to the tile size. If smaller, the watermark will be positioned randomly within the available space. The image can be either colour or grayscale.

WATERMARK_PROBABILITY

The probability that a particular tile will have a watermark applied to it. 0 means never, 1 means always.

WATERMARK_OPACITY

The opacity (between 0 and 1) applied to the watermark image.

MEMCACHED_SERVERS

A comma-delimitted list of memcached servers with optional port numbers. For example: localhost,192.168.0.1:8888,192.168.0.2.

MEMCACHED_TIMEOUT

Time in seconds that cache remains fresh. Default is 86400 seconds (24 hours).

FILENAME_PATTERN

Pattern that follows the name stem for a panoramic image sequence. eg: "_pyr_" for FZ1_pyr_000_090.tif. In this example, just supply FZ1 to the FIF command. The "000" indicates the vertical angle and "090" the horizontal. This is only relevant to 3D image sequences. The default is "_pyr_".

INTERPOLATION

Interpolation method to use for rescaling when using image export. Integer value. 0 for fastest nearest neighbour interpolation. 1 for bilinear interpolation (better quality but about 2.5x slower). Bilinear by default.

CORS

Cross Origin Resource Sharing setting. Disabled by default. Set to "*" to enable for all domains or specify a single domain. See http://www.w3.org/TR/cors/ for more details on CORS.

BASE_URL

Set a base URL for use in certain protocol requests if web server rewriting has taken place and the public URL is not the same as that supplied to iipsrv

URI_MAP

Set a mapping from a URL prefix to a supported protocol. This enables iipsrv to be able to work without requring full CGI query strings. Map must be of the form "prefix=>protocol" where prefix can be either empty or any string prefix and protocol must be one of IIP,IIIF,DeepZoom, Zoomify. Used, for example, to map requests of the form http://server/iiif/ to the IIIF protocol handler without requiring web server rewriting.

CACHE_CONTROL

Set the HTTP Cache-Control header. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9 for a full list of options. If not set, header defaults to "max-age=86400" (24 hours).

MAX_ICC

Set the maximum ICC profile size in bytes that is allowed to be embedded within an output image. This is set by default to 65535 bytes. If set to -1, no limit is set and all profiles are embedded. If set to 0, no profiles are embedded.

OMP_NUM_THREADS

Set the number of OpenMP threads to be used by the iipsrv image processing routines (See OpenMP specification for details). All available processor threads are used by default.

KAKADU_READMODE

Set the Kakadu JPEG2000 read-mode. 0 for ’fast’ mode with minimal error checking (default), 1 for ’fussy’ mode with no error recovery, 2 for ’resilient’ mode with maximum recovery from codestream errors. See the Kakadu documentation for further details.

CODEC_PASSTHROUGH

Enable pre-encoded tiles to be sent directly to the client without re-encoding or processing if the requested output encoding matches the encoding used within the source image. Enabled only for tile requests that map to a single tile in the source image and that do not specify or require any image processing or manually set the encoding quality level. Only works for TIFF with either JPEG or WebP-encoded tiles. Set to 1 to activate or 0 to disactivate. Default is 1 (activated)

IIIF_VERSION

Set the major IIIF Image API version. Values should be a single digit. For example: 2 for versions 2 or 2.1 etc. 3 for IIIF version 3.x. If not set, defaults to version IIIF 3.x

IIIF_DELIMITER

Set delimiter to enable page or slice selection for a multi-page or image stack for IIIF requests. Delimiter can be a single character or an arbitrary string. Disabled by default.

IIIF_EXTRA_INFO

Add extra arbitrary field to all IIIF info.json files. Must be a string containing a valid JSON key, value line. Key and value quotes should be escaped if necessary and no trailing comma should be added. For example, to add a preferredFormats field: IIIF_EXTRA_INFO=’"preferredFormats": ["webp"]’

IIIF_EXTENSIONS

Enable extra (non-standard) image processing functionality for the ‘quality‘ segment of the IIIF Image API. These allow additional qualities such as ‘negative‘, ‘stretch‘, ‘equalization‘ and ‘log‘ to be used. This is set to 0 by default (disabled). Set to 1 to enable.

Specify a global copyright or rights statement if this is not available in the image metadata itself

EXAMPLES

iipsrv can be automatically started by both Apache and Lighttpd, but not by Nginx or Java Application Servers. See the example configuration in the README or included with your distribution for the appropriate syntax. Note that Apache has two FCGI modules: mod_fastcgi and mod_fcgid which are configured differently.

It is possible to run iipsrv directly as a standalone program. To do this, use the following syntax to bind to a particular port and listen for FCGI (not HTTP) requests. In the following example, iipsrv will bind to port 9000 on the machine’s IP address 192.168.0.1:

% iipsrv.fcgi --bind 192.168.0.1:9000

There is additionally a --backlog parameter that is optional and sets the socket backlog value. The backlog value specifies the number of requests can be queued and, therefore, increases the number of concurrent connections that iipsrv can handle and is set to 2048 by default. For example:

% iipsrv.fcgi --bind 192.168.0.1:9000 --backlog 1024

Note that the backlog parameter must be specified after the bind parameter and argument. Note also that this value may be limited by the operating system. On Linux kernels < 2.4.25 and Mac OS X, the backlog limit is hard-coded to 128, so any value above this will be limited to 128 by the OS. If you do provide a backlog value, verify whether the setting /proc/sys/net/core/somaxconn should be updated.

It is also possible to run iipsrv via the spawn-fcgi program. Set up any parameters via environment variables and run the command as follows to bind, as in the previous example to port 9000 on IP address 192.168.0.1:

% spawn-fcgi -f src/iipsrv.fcgi -a 192.168.0.1 -p 9000

For use in stand alone or spawn-fcgi mode, you will then need to configure your web server (which can be on a different machine) to direct FCGI protocol requests to this IP address and port.

For web servers such as Nginx or Java Application Servers such as Tomcat, JBoss or Jetty, which cannot automatically start FCGI processes, iipsrv will need to be started in stand alone mode or via spawn-fcgi.

PROTOCOLS AND API’S

The IIPImage server supports multiple protocols or API’s: the Internet Imaging Protocol (IIP), the Zoomify API, the DeepZoom API the International Image Interoperability Framework (IIIF) API. Client applications supporting these API’s should be able to use iipsrv as their back-end server. IIP is the most feature rich of the supported protocols and allows access to the more advanced image processing features supported by iipsrv.

IMAGE PATHS

The image paths given to the server must be absolute paths on the server machine (eg. via the FIF variable for the IIP protocol: FIF=/images/test.tif) and not paths relative to the web server document root location. If the FILESYSTEM_PREFIX server directive has been set (see OPTIONS above), then this prefix is automatically pre-pended to all requests to generate the absolute image path. Similarly, if FILESYSTEM_SUFFIX has been set, it will be appended to the path. Make sure that the iipsrv process owner is able to access and read the images.

Note that images do not need to be directly accessible externally by the client via the web server.

AUTHORS

Ruven Pillay <[email protected]>

Updated 2026-06-01 - jenkler.se | uex.se