IIPSRV - IIPImage Image Server
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) or JPEG2000
The image server can also dynamically export images in JPEG 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.
Command line use:
iipsrv.fcgi --bind host
log file: usually in /var/log/
There are several parameters that can be supplied to iipsrv.fcgi
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.
- The log file the module will (attempt) to write to. If no
value is given, no log will be written. Make sure the server process has
write access to this directory. Paths with spaces in them may not work
- 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.
- 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.
- Max image cache size to be held in RAM in MB. This is a
cache of the compressed JPEG image tiles requested by the client. The
default is 5MB.
- 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.
- 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
- 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.
- 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.
- The probability that a particilar tile will have a
watermark applied to it. 0 means never, 1 means always.
- The opacity (between 0 and 1) applied to the watermark
- A comma-delimitted list of memcached servers with optional
port numbers. For example: localhost,192.168.0.1:8888,192.168.0.2.
- Time in seconds that cache remains fresh. Default is 86400
seconds (24 hours).
- 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_".
- 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.
- 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
- 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"
will 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
You may also wish to run iipsrv
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
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
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 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
webserver on the same machine or another 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
need to be started in stand alone mode or via spawn-fcgi.
The IIPImage server supports the Internet Imaging Protocol (IIP)
protocol, the DeepZoom
and the International Image
Interoperability Framework (IIIF)
protocols. Client applications
supporting these protocols should be able to use iipsrv
back-end server. IIP
is the most feature rich of the 4 protocols and
allows access to the more advanced imaging server features.
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
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. Make sure that the server process owner is able to access and read
Note that images do not
need to be directly accessible externally by the
client via the web server.
IIPImage website: http://iipimage.sourceforge.net
Ruven Pillay <firstname.lastname@example.org>