IIPImage - High Resolution Streaming Image Server

ABOUT

IIPImage is an advanced high-performance feature-rich image server system 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 bits per channel, CIELAB colorimetric images and scientific imagery such as multispectral images, image sequences and 3D surface topologies.

FEATURES

Fast lightweight C++ FastCGI server
High performance with inbuilt configurable cache
Support for extremely large images: tera-pixel and multi gigapixel support
TIFF, JPEG2000 and JPEG input support
JPEG, PNG, WebP, AVIF and TIFF output support: export of whole or regions of images at any size
Supports IIP, Zoomify, DeepZoom and IIIF API's
1, 2, 4, 6, 8, 10, 12, 14, 16 and 32 bit input image support including 32 bit floating point support
CIELAB support with automatic CIELAB->sRGB color space conversion
Multispectral and hyperspectral image support
Support for XMP metadata and ICC profiles
Image stacks and image sequence support
Dynamic hillshading of 3D surface topologies
Dynamic watermarking
Memcached support

LICENCE

iipsrv is released under the GNU General Public License (GPL). See the copyright notice COPYING in this directory for licensing details or go to http://www.gnu.org/licenses/gpl.html for more details.

BUILDING

Building iipsrv requires a C++ compiler and several development libraries.

Dependencies

Required Libraries:

libtiff development files
libjpeg compatible JPEG development files such as libjpeg or libjpeg-turbo
libfcgi - the latest version of the FCGI development library is bundled with the iipsrv distribution. If no system FCGI library is detected, the bundled version will be used. See fcgi/COPYING.FCGI for licensing information for these libraries.

Optional Libraries:

Kakadu for JPEG2000 input support. Note, however, that this is not open source and you will need to purchase a license for the source code. In order to use, first build the Kakadu SDK as per the instructions supplied with the SDK. Then, supply the following parameters to the ./configure command: --with-kakadu=/path/to/kakadu/distribution
OpenJPEG for JPEG2000 input support. OpenJPEG will be disabled if Kakadu support has been enabled. Use the --with-openjpeg=<path> configure option if this library is installed in a non-standard location
libpng for PNG output support
libwebp for WebP output support
libavif for AVIF output support
libmemcached for Memcached, a high-performance, distributed memory object caching system. If enabled, IIPImage will cache results using this distributed cache, giving IIPImage added speed and scalability

Building on UNIX / Linux / Mac OSX

On UNIX, Linux and Mac OS X based systems, iipsrv can be built using the standard autoconf configure / make build process.

First download iipsrv, then unpack it and change your working directory to be the iipsrv source code location. For example:

tar jxvf iipsrv-<version>.tar.bz2
cd iipsrv-<version>

If you are building from a git clone rather than from a release package, you must first generate the configure script and autoconf build environment using the provided autogen.sh script. This step is not necessary for release versions.

./autogen.sh

Now run the configure script:

./configure

Optional libraries are activated by default if found by configure. To manually disable, use the --disable-<option> flag. For example --disable-openjpeg will disable OpenJPEG support.

To see the full list of available configuration options:

./configure --help

Now compile using make:

make

The resulting executable is iipsrv.fcgi in the src/ sub-directory.

It's possible to perform an optional run-time test of the compiled iipsrv executable using make:

make check

To install iipsrv to a system folder:

make install

This will install iipsrv (note without the .fcgi suffix) in the system sbin directory for use, for example, with a service script. By default, this is /usr/local/sbin/iipsrv. Use configure's --prefix parameter to change the destination directory. For example, to install in /usr/sbin/

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

Building on Windows

For building on Windows, Visual Studio build files are available in the windows/ sub-directory. These use vcpkg for dependency management.

To install all required and optional dependencies using vcpkg:

.\vcpkg.exe install tiff openjpeg fastcgi libpng libwebp libavif[aom] --triplet x64-windows

Make these available to Visual Studio:

.\vcpkg.exe integrate install

Now open the provided iipsrv project with Visual Studio and build. See https://iipimage.sourceforge.io/documentation/server/windows for full details.

DEVELOPMENT DOCUMENTATION

Detailed class descriptions (generated using doxygen) are available in the doc sub-directory. To (re)-generate the HTML documentation:

doxygen doc/doxygen-html.conf

RUNNING IIPSRV

The IIPImage server can be started in a number of ways.

Directly on the command line or through an FCGI process manager such as spawn-fcgi
Through a Linux/UNIX system startup service, such as an init.d script, systemd or supervisor service
Started and managed by the web server itself (only Apache and Lighttpd can start iipsrv)

Both the command line / process manager and system startup script options will start an iipsrv process, which will listen on the specified port or socket for FCGI requests. iipsrv currently does not handle HTTP requests and so, you will need an FCGI-aware web server front-end in order to handle HTTP and communicate using FCGI to iipsrv.

Most HTTP web servers are FCGI-compatible and are able to connect to a running iipsrv instance. The following web servers have been successfully tested with iipsrv:

Apache
Lighttpd
IIS
NginX
MyServer
Java Application Servers (Tomcat, JBoss)

Apache, Lighttpd and IIS can additionally start and manage the iipsrv process.

Starting iipsrv on the Command Line

iipsrv can be started directly on the command line using the --bind parameter in order to listen on the specified port or socket. For example:

export VERBOSITY=5
iipsrv.fcgi --bind 0.0.0.0:9000

where the argument given to bind is the socket on which to listen to FCGI requests. The socket can be a network (IP address and port) or UNIX file socket. Note that configuration parameters need to be exported as environment variables. See the CONFIGURATION section for more details.

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.

iipsrv can also be started using lighttpd's spawn-fcgi. The process can be bound to an IP address and port for backend load-balancing configurations and multiple processes can be forked. For example:

spawn-fcgi -f iipsrv.fcgi -a 0.0.0.0 -p 9000

Starting iipsrv using an Init Script or Service

OpenRC and Systemd scripts and configuration files for Linux are provided in the script/ sub-directory. To use these, copy and rename the iipsrv.fcgi executable to just iipsrv and place in /usr/sbin/. See the accompanying README files for more details.

Starting and Managing iipsrv through a Web Server

Apache and Lighttpd are able to start and manage the iipsrv process themselves. First install the iipsrv.fcgi executable in a suitable location. For example: /var/www/fcgi-bin/iipsrv.fcgi.

Apache

There are 2 Apache modules available that are able to sta

Iipsrv

Install / Use

README