1IIPSRV(8) System Manager's Manual IIPSRV(8)
2
6 IIPSRV - IIPImage Image Server
7
10 IIPImage is an advanced high-performance feature-rich multi-protocol
11 image server for web-based streamed viewing and zooming of ultra high-
12 resolution images. It is designed to be fast and bandwidth-efficient
13 with low processor and memory requirements. The system can comfortably
14 handle gigapixel size images as well as advanced image features such as
15 8, 16 and 32 bit depths, CIELAB colorimetric images and scientific
16 imagery such as multispectral images. Source images can be either TIFF
17 (tiled multi-resolution) or JPEG2000 (if enabled).
18 The image server can also dynamically export images in JPEG format and
20 perform basic image processing, such as contrast adjustment, gamma con‐
21 trol, conversion from color to greyscale, color twist, region extrac‐
22 tion and arbitrary rescaling. The server can also export spectral point
23 or profile data from multispectral data and apply color maps or perform
24 hillshading rendering.
25
28 Command line use:
29 iipsrv.fcgi --bind host : port
31
35 iipsrv.fcgi main executable
36 iipsrv.log log file: usually in /var/log/ or /tmp/
38
42 There are several parameters that can be supplied to iipsrv.fcgi These
43 should be set via the appropriate web server configuration directives
44 if running via Apache or Lighttpd. See EXAMPLES for details of web
45 server configuations. Alternatively these parameters can be set via
46 environment settings if running directly from the command line or from
47 spawn-fcgi.
48 LOGFILE
51 The log file the module will (attempt) to write to. If no value
52 is given, no log will be written. Make sure the server process
53 has write access to this directory. Paths with spaces in them
54 may not work correctly. Version 1.1 and later of iipsrv also
55 supports logging to syslog if "syslog" is given as the value.
56 VERBOSITY
58 The level of logging. 0 means no logging, 1 is minimal logging,
59 2 lots of debugging stuff and 3 even more debugging stuff and 4
60 a very large amount indeed. Logging is only enabled if LOGFILE
61 has also been defined.
62 JPEG_QUALITY
64 The default JPEG quality factor for compression when the client
65 does not specify one. The value should be between 1 (highest
66 level of compression) and 100 (highest image quality). The
67 default is 75.
68 MAX_IMAGE_CACHE_SIZE
70 Max image cache size to be held in RAM in MB. This is a cache of
71 the compressed JPEG image tiles requested by the client. The
72 default is 5MB.
73 FILESYSTEM_PREFIX
75 This is a prefix automatically added by the server to the begin‐
76 ning of each file system path. This can be useful for security
77 reasons to limit access to certain sub-directories. For example,
78 with a prefix of "/home/images/" set on the server, a request by
79 a client for "image.tif" will point to the path
80 "/home/images/image.tif". Any reverse directory path component
81 such as ../ is also filtered out. No default value.
82 MAX_CVT
84 The maximum permitted image pixel size returned by the CVT com‐
85 mand in conjunction with WID or HEI or RGN. The default is 5000.
86 This prevents huge requests from overloading the server
87 ALLOW_UPSCALING
89 Determines whether an image may be rendered at a size greater
90 than that of the source image. A value of 0 will prevent upscal‐
91 ing. The default is 1 (upscaling is allowed).
92 MAX_LAYERS
94 The maximum number of quality layers to decode for image that
95 support progressive quality encoding, such as JPEG2000. Ignored
96 for other file formats. By default half of the available layers
97 are decoded. If set to -1, all the available layers will be
98 decoded.
99 WATERMARK
101 TIFF image to use as watermark file. This image should be not be
102 bigger the tile size used for TIFF tiling. If bigger, it will
103 simply be cropped to the tile size. If smaller, the watermark
104 will be positioned randomly within the available space. The
105 image can be either colour or grayscale.
106 WATERMARK_PROBABILITY
108 The probability that a particular tile will have a watermark
109 applied to it. 0 means never, 1 means always.
110 WATERMARK_OPACITY
112 The opacity (between 0 and 1) applied to the watermark image.
113 MEMCACHED_SERVERS
115 A comma-delimitted list of memcached servers with optional port
116 numbers. For example: localhost,192.168.0.1:8888,192.168.0.2.
117 MEMCACHED_TIMEOUT
119 Time in seconds that cache remains fresh. Default is 86400 sec‐
120 onds (24 hours).
121 FILENAME_PATTERN
123 Pattern that follows the name stem for a panoramic image
124 sequence. eg: "_pyr_" for FZ1_pyr_000_090.tif. In this exam‐
125 ple, just supply FZ1 to the FIF command. The "000" indicates the
126 vertical angle and "090" the horizontal. This is only relevant
127 to 3D image sequences. The default is "_pyr_".
128 INTERPOLATION
130 Interpolation method to use for rescaling when using image
131 export. Integer value. 0 for fastest nearest neighbour interpo‐
132 lation. 1 for bilinear interpolation (better quality but about
133 2.5x slower). Bilinear by default.
134 CORS Cross Origin Resource Sharing setting. Disabled by default. Set
136 to "*" to enable for all domains or specify a single domain.
137 See http://www.w3.org/TR/cors/ for more details on CORS.
138 BASE_URL
140 Set a base URL for use in certain protocol requests if web
141 server rewriting has taken place and the public URL is not the
142 same as that supplied to iipsrv
143 URI_MAP
145 Set a mapping from a URL prefix to a supported protocol. This
146 enables iipsrv to be able to work without requring full CGI
147 query strings. Map must be of the form "prefix=>protocol" where
148 prefix can be either empty or any string prefix and protocol
149 must be one of IIP,IIIF,DeepZoom, Zoomify. Used, for example, to
150 map requests of the form http://server/iiif/ to the IIIF proto‐
151 col handler without requiring web server rewriting.
152 CACHE_CONTROL
154 Set the HTTP Cache-Control header. See http://www.w3.org/Proto‐
155 cols/rfc2616/rfc2616-sec14.html#sec14.9 for a full list of
156 options. If not set, header defaults to "max-age=86400" (24
157 hours).
158 EMBED_ICC
160 Set whether the ICC profile is embedded within the output image.
161 0 to strip profile, 1 to embed profile. The default is 1 (embed‐
162 ded profiles).
163 OMP_NUM_THREADS
165 Set the number of OpenMP threads to be used by the iipsrv image
166 processing routines (See OpenMP specification for details). All
167 available processor threads are used by default.
168 KAKADU_READMODE
170 Set the Kakadu JPEG2000 read-mode. 0 for 'fast' mode with mini‐
171 mal error checking (default), 1 for 'fussy' mode with no error
172 recovery, 2 for 'resilient' mode with maximum recovery from
173 codestream errors. See the Kakadu documentation for further
174 details.
175
179 iipsrv will be automatically started by both Apache and Lighttpd. But
180 not by Nginx or Java Application Servers. See the example configura‐
181 tion in the README or included with your distribution for the appropri‐
182 ate syntax. Note that Apache has two FCGI modules: mod_fastcgi and
183 mod_fcgid which are configured differently.
184 You may also wish to run iipsrv as a standalone program. To do this,
186 use the following syntax to bind to a particular port and listen for
187 FCGI (not HTTP) requests. In the following example, iipsrv will bind
188 to port 9000 on the machine's IP address 192.168.0.1:
189 % iipsrv.fcgi --bind 192.168.0.1:9000
191 There is additionally a --backlog parameter that is optional and sets
193 the socket backlog value. The backlog value specifies the number of
194 requests can be queued and, therefore, increases the number of concur‐
195 rent connections that iipsrv can handle and is set to 2048 by default.
196 For example:
197 % iipsrv.fcgi --bind 192.168.0.1:9000 --backlog 1024
199 Note that the backlog parameter must be specified after the bind param‐
201 eter and argument. Note also that this value may be limited by the
202 operating system. On Linux kernels < 2.4.25 and Mac OS X, the backlog
203 limit is hard-coded to 128, so any value above this will be limited to
204 128 by the OS. If you do provide a backlog value, verify whether the
205 setting /proc/sys/net/core/somaxconn should be updated.
206 It is also possible to run iipsrv via the spawn-fcgi program. Set up
209 any parameters via environment variables and run the command as follows
210 to bind, as in the previous example to port 9000 on IP address
211 192.168.0.1:
212 % spawn-fcgi -f src/iipsrv.fcgi -a 192.168.0.1 -p 9000
214 For use in stand alone or spawn-fcgi mode, you will then need to con‐
216 figure your webserver on the same machine or another to direct FCGI
217 protocol requests to this IP address and port.
218 For web servers such as Nginx or Java Application Servers such as Tom‐
220 cat, JBoss or Jetty, which cannot automatically start FCGI processes,
221 iipsrv will need to be started in stand alone mode or via spawn-fcgi.
222
226 The IIPImage server supports the Internet Imaging Protocol (IIP) , the
227 Zoomify protocol, the DeepZoom and the International Image Interoper‐
228 ability Framework (IIIF) protocols. Client applications supporting
229 these protocols should be able to use iipsrv as their back-end server.
230 IIP is the most feature rich of the 4 protocols and allows access to
231 the more advanced imaging server features.
232
237 The image paths given to the server must be absolute paths on the
238 server machine (eg. via the FIF variable for the IIP protocol:
239 FIF=/images/test.tif) and not paths relative to the web server document
240 root location. If the FILESYSTEM_PREFIX server directive has been set
241 (see OPTIONS above), then this prefix is automatically pre-pended to
242 all requests to generate the absolute image path. Make sure that the
243 server process owner is able to access and read the images.
244 Note that images do not need to be directly accessible externally by
246 the client via the web server.
247
251 IIPImage website: https://iipimage.sourceforge.io
252
255 Ruven Pillay <ruven@users.sourceforge.net>
256Ruven Pillay June 2019 IIPSRV(8)