1IIPSRV(8)                   System Manager's Manual                  IIPSRV(8)
2
3
4

NAME

6       IIPSRV - IIPImage Image Server
7
8

DESCRIPTION

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
19       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
26

SYNOPSIS

28       Command line use:
29
30       iipsrv.fcgi --bind host : port
31
32
33

FILES

35       iipsrv.fcgi main executable
36
37       iipsrv.log log file: usually in /var/log/ or /tmp/
38
39
40

OPTIONS

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
49
50       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
57       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
63       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
69       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
74       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
83       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
88       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
93       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
100       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
107       WATERMARK_PROBABILITY
108              The probability that a particular tile  will  have  a  watermark
109              applied to it. 0 means never, 1 means always.
110
111       WATERMARK_OPACITY
112              The opacity (between 0 and 1) applied to the watermark image.
113
114       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
118       MEMCACHED_TIMEOUT
119              Time in seconds that cache remains fresh. Default is 86400  sec‐
120              onds (24 hours).
121
122       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
129       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
135       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
139       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
144       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
153       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
159       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
164       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
169       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
176
177

EXAMPLES

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
185       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
190       % iipsrv.fcgi --bind 192.168.0.1:9000
191
192       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
198       % iipsrv.fcgi --bind 192.168.0.1:9000 --backlog 1024
199
200       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
207
208       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
213       % spawn-fcgi -f src/iipsrv.fcgi -a 192.168.0.1 -p 9000
214
215       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
219       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
223
224

PROTOCOLS

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
233
234
235

IMAGE PATHS

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
245       Note  that  images  do not need to be directly accessible externally by
246       the client via the web server.
247
248
249

SEE ALSO

251       IIPImage website: https://iipimage.sourceforge.io
252
253

AUTHORS

255       Ruven Pillay <ruven@users.sourceforge.net>
256
257
258
259
260Ruven Pillay                       June 2019                         IIPSRV(8)
Impressum