home | help 
IIPSRV(8)		     System Manager's Manual		       IIPSRV(8)

NAME
     IIPSRV - IIPImage Image Server

DESCRIPTION
     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 proces-
     sor 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  multi-
     spectral images.  Source images can be either TIFF (tiled multi-resolution)
     or JPEG2000 (if enabled).

     The  image  server can also dynamically export images in JPEG, PNG and WebP
     format and perform basic image processing,  such  as  contrast  adjustment,
     gamma  control, conversion from color to greyscale, color twist, region ex-
     traction 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 con-
     figuations.  Alternatively these parameters can be set via environment set-
     tings if running directly from the command line or from spawn-fcgi.

     LOGFILEThe  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 correctly. Version 1.1 and later of iipsrv also  supports  log-
	    ging 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.

     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 (highest level of
	    compression) and 9 (highest image quality).  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).  The default is 50.

     MAX_IMAGE_CACHE_SIZE
	    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.

     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 "im-
	    age.tif" will point to the path "/home/images/image.tif".	Any  re-
	    verse  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" suuffix.

     MAX_CVTThe  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 sup-
	    port progressive quality encoding, such  as  JPEG2000.  Ignored  for
	    other  file formats. By default half of the available layers are de-
	    coded. 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 posi-
	    tioned  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 num-
	    bers. 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). Bi-
	    linear 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_MAPSet  a  mapping  from a URL prefix to a supported protocol. This en-
	    ables 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/Proto-
	    cols/rfc2616/rfc2616-sec14.html#sec14.9  for a full list of options.
	    If not set, header defaults to "max-age=86400" (24 hours).

     EMBED_ICC
	    Set whether the ICC profile is embedded within the output image.   0
	    to	strip  profile,  1  to embed profile. The default is 1 (embedded
	    profiles).

     OMP_NUM_THREADS
	    Set the number of OpenMP threads to be used by the iipsrv image pro-
	    cessing routines (See OpenMP specification for details). All  avail-
	    able 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.

     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

EXAMPLES
     iipsrv  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  con-
     figured differently.

     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 connec-
     tions 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 webserver on the same machine or another to direct FCGI  protocol  re-
     quests 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=/im-
     ages/test.tif) and not paths relative to the web server document root loca-
     tion. 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 server 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.

SEE ALSO
     IIPImage website: https://iipimage.sourceforge.io

AUTHORS
     Ruven Pillay <ruven@users.sourceforge.net>

Ruven Pillay			    May 2023			       IIPSRV(8)
home | help