1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460
|
IIPImage - High Resolution Streaming Image Server
=================================================
[![GPLv3 Licensed](https://img.shields.io/badge/license-GPLv3-blue.svg)](https://www.gnu.org/copyleft/gpl.html)
[![Build Status](https://travis-ci.org/ruven/iipsrv.svg)](https://travis-ci.org/ruven/iipsrv)
[![Coverity Scan](https://img.shields.io/coverity/scan/3997.svg)](https://scan.coverity.com/projects/ruven-iipsrv)
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 embeddable FastCGI server module
* High performance with inbuilt configurable cache
* Support for gigapixel images
* Dynamic JPEG export of whole or regions of images at any resolution
* Supports IIP, Zoomify, DeepZoom and IIIF protocols
* 1, 8, 16 and 32 bit image support including 32 bit floating point support
* CIELAB support with automatic CIELAB->sRGB colour space conversion
* JPEG2000 support
* Multispectral image support
* Dynamic watermarking
* Memcached support
* 3D panoramic views
* Dynamic hillshading of 3D surface topologies
* Dynamic decoder module capability
DOCUMENTATION
-------------
Detailed class descriptions (generated using doxygen) are available in the
doc subdirectory
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.
If you use IIPImage on a public site and remove the IIP link logo from the
client, you must provide a link on your site back to the IIPImage site -
http://iipimage.sf.net
This distribution includes version 2.4.0 of the FCGI development libraries.
See COPYING.FCGI for licensing information for these libraries.
REQUIREMENTS
------------
Requirements: libtiff, zlib and the IJG JPEG development libraries.
Optional: libmemcached (for Memcached) and Kakadu (for JPEG2000)
Plus, of course, an fcgi-enabled web server. The server has been successfully
tested on the following servers:
- Apache (http://httpd.apache.org),
- Lighttpd (http://www.lighttpd.net)
- IIS (http://www.iis.net)
- NginX (http://www.nginx.org)
- MyServer (http://www.myserverproject.net)
- Java Application Servers (Tomcat, JBoss)
Example server configurations are shown below.
BUILDING
--------
The standard autoconf build process should work fine. If you want to allow
dynamic loading of 3rd party image decoders, use the configure option
--enable-modules. There is a version of the FCGI development library included
in this distribution. The configure script will use this bundled version
unless it detects one already installed. Alternatively, you may specify the
path using --with-fcgi-incl=<path> and --with-fcgi-lib=<path>.
If this is an SVN or Git development version, first generate the autoconfigure
environment using autogen.sh:
./autogen.sh
Otherwise for release versions, use configure directly:
./configure
make
OPTIONAL LIBRARIES: MEMCACHED
-----------------------------
IIPImage is able to use Memcached (http://www.memcached.org), a high-performance,
distributed memory object caching system. If enabled, IIPImage will cache
results using Memcached, giving IIPImage added speed and scalability. To use
this, you will need to install the library (and development files) of
libmemcached (http://libmemcached.org). This will be automatically detected
during the build process.
OPTIONAL LIBRARIES: KAKADU
--------------------------
IIPImage is able to decode JPEG2000 images via the Kakadu SDK
(http://www.kakadusoftware.com). This is, however, not open source and 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, the
following parameters to the ./configure command
--with-kakadu=/path/to/kakadu/distribution
INSTALLATION
------------
Simply copy the executable called iipsrv.fcgi in the src subdirectory into
the web server fcgi directory. If one does not exist, simply create one, called,
for example, fcgi-bin. The web server will need to be configured to use this
executable.
CONFIGURATION
-------------
There are several startup variables that can be passed to the server.
They are all optional.
LOGFILE: the server will log its output to the file specified, if it can.
VERBOSITY: 0 means no logging, 1 is minimal logging, 2 lots of debugging stuff,
3 even more debugging stuff and 10 a very large amount indeed ;-)
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 10MB.
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 "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.
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.
MAX_CVT: Limits the maximum image dimensions in pixels (the WID or HEI
commands) allowable for dynamic JPEG export via the CVT command. This
prevents huge requests from overloading the server. The default is 5000.
MAX_LAYERS: The maximum number of quality layers to decode for images that support
progressive quality encoding, such as JPEG2000. Ignored for other file
formats. If not set, half of the available quality layers will be decoded by default.
If set to -1, all the available layers will be decoded by default.
FILENAME_PATTERN: Pattern that follows the name stem for a 3D or multispectral
sequence. eg: "_pyr_" for FZ1_pyr_000_090.tif. The default is "_pyr_". This is
only relevant to 3D image sequences.
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 positioned
randomly within the available space. The image can be either colour or
grayscale.
WATERMARK_PROBABILITY: The probability that a particilar 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 numbers. 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).
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). Bilinear 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.
CACHE_CONTROL: 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" (24 hours).
DECODER_MODULES: Comma separated list of external modules for decoding
other image formats. This is only necessary if you have activated
--enable-modules for ./configure and written your own image format
handler(s).
IMAGE PATHS
-----------
The images paths given to the server via the FIF variable must be
absolute paths on the server machine (eg. FIF=/images/test.tif)
and not paths relative to the web server document root location.
Images do not, therefore, need to be directly accessible by the
client via the web server. Make sure the server process owner is
able to access and read the images!
EXAMPLE SERVER CONFIGURATIONS
-----------------------------
### Apache and mod_fastcgi
httpd.conf example extract:
```
--------------------------------------------------------------------
# Create a directory for the iipsrv binary
ScriptAlias /fcgi-bin/ "/usr/local/httpd/fcgi-bin/"
# Set the options on that directory
<Directory "/usr/local/httpd/fcgi-bin">
AllowOverride None
Options None
# Syntax for access is different in Apache 2.4 - uncomment appropriate version
# Apache 2.2
# Order allow,deny
# Allow from all
# Apache 2.4
Require all granted
</Directory>
# Set the module handler
AddHandler fastcgi-script fcg fcgi fpl
# Initialise some variables for the FCGI server
FastCgiServer /usr/local/httpd/fcgi-bin/iipsrv.fcgi \
-initial-env LOGFILE=/tmp/iipsrv.log \
-initial-env VERBOSITY=2 \
-initial-env MAX_IMAGE_CACHE_SIZE=10 \
-initial-env FILENAME_PATTERN=_pyr_ \
-initial-env JPEG_QUALITY=50 \
-initial-env MAX_CVT=3000
--------------------------------------------------------------------
```
### Apache and mod_fcgid
mod_fcgid is a binary compatible replacement for mod_fastcgi. It works in the
same way, but is configured differently. Load the module like this:
LoadModule fcgid_module /path/to/apachemodules/mod_fcgid.so
Here is an example configuration. Note that mod_fcgid does not have a
FastCgiServer directive and there is no need to explicitly start the server:
```
-------------------------------------------------------------------
# Create a directory for the iipsrv binary
ScriptAlias /fcgi-bin/ "/var/www/localhost/fcgi-bin/"
# Set the options on that directory
<Directory "/var/www/localhost/fcgi-bin/">
AllowOverride None
Options None
# Syntax for access is different in Apache 2.4 - uncomment appropriate version
# Apache 2.2
# Order allow,deny
# Allow from all
# Apache 2.4
Require all granted
# Set the module handler
AddHandler fcgid-script .fcgi
</Directory>
# Set our environment variables for the IIP server
FcgidInitialEnv VERBOSITY "5"
FcgidInitialEnv LOGFILE "/tmp/iipsrv.log"
FcgidInitialEnv MAX_IMAGE_CACHE_SIZE "10"
FcgidInitialEnv JPEG_QUALITY "50"
FcgidInitialEnv MAX_CVT "3000"
# Define the idle timeout as unlimited and the number of
# processes we want
FcgidIdleTimeout 0
FcgidMaxProcessesPerClass 1
-------------------------------------------------------------------
```
Note that on CentOS, FcgidIPCDir is configured by default to
/var/log/httpd/fcgidsock, which may not be writable by Apache. If this is the case,
specify another location for FcgidIPCDir, which is writable, such as /tmp/fcgidsock
### Lighttpd
lighttpd.conf example extract:
```
--------------------------------------------------------------------
fastcgi.server = ( "/fcgi-bin/iipsrv.fcgi" =>
(( "host" => "127.0.0.1",
"port" => 9000,
"check-local" => "disable",
"min-procs" => 1,
"max-procs" => 1,
"bin-path" => "/var/www/localhost/fcgi-bin/iipsrv.fcgi",
"bin-environment" => (
"LOGFILE" => "/tmp/iipsrv.log",
"VERBOSITY" => "5",
"MAX_IMAGE_CACHE_SIZE" => "10",
"FILENAME_PATTERN" => "_pyr_",
"JPEG_QUALITY" => "50",
"MAX_CVT" => "3000"
)
))
)
--------------------------------------------------------------------
```
### NginX
iipsrv can also be used with NginX. The one drawback with regards to iipsrv is that it cannot automatically spawn FCGI processes, so you will need to use
nginx together with spawn-fcgi or start iipsrv from the command line.
To set up nginx with iipsrv add a directive such as this to your nginx configuration, which will forward requests to /fcgi-bin/iipsrv.fcgi to a
running iipsrv process on port 9000.
```
location /fcgi-bin/iipsrv.fcgi {
fastcgi_pass localhost:9000;
fastcgi_param PATH_INFO $fastcgi_script_name;
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param QUERY_STRING $query_string;
fastcgi_param CONTENT_TYPE $content_type;
fastcgi_param CONTENT_LENGTH $content_length;
fastcgi_param SERVER_PROTOCOL $server_protocol;
fastcgi_param REQUEST_URI $request_uri;
fastcgi_param HTTPS $https if_not_empty;
}
```
Nginx can also handle load balancing to multiple iipsrv instances, which can be hosted on the same machine on multiple ports or on different hosts.
For a multiple host configuration, declare the load balancing like this:
```
upstream iip {
server 192.168.0.1:9000;
server 192.168.0.2:9000;
server 192.168.0.3:9000;
server 192.168.0.4:9000;
}
```
and change the fastcgi_pass parameter in the above location configuration to point to this instead of a fixed address:
fastcgi_pass iip;
### spawn-fcgi
iipsrv can also be used with lighttpd's spawn-fcgi without the need for a
full web server. Simply spawn the iipsrv process on the command line. The
process can be bound to an IP address and port for backend load-balancing
configurations. For example:
spawn-fcgi -f src/iipsrv.fcgi -a 192.168.0.1 -p 9000
### MyServer:
Simply run the MyServer configuration and in the MIME section, choose the .fcgi extension
and select:
```
--------------------------------------------------------------------
MIME Type: application octet-stream
Action: Execute self contained FastCGI
Manager: NONE
--------------------------------------------------------------------
```
### Java Application Servers (Tomcat, Jetty, JBoss etc)
IIPImage can also be used with Java Application Servers such as Apache Tomcat, JBoss and Jetty. Simply add
the JFastCGI jar file to your webapp and add the following to your web.xml configuration file in order to
re-route FCGI requests to the IIPImage server on the specified port.
```
<!-- Gateway Servlet to IIPImage FCGI server -->
<servlet>
<servlet-name>fcgi</servlet-name>
<servlet-class>net.jr.fastcgi.FastCGIServlet</servlet-class>
<init-param>>
<param-name>server-address</param-name>
<param-value>127.0.0.1:6667</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>fcgi</servlet-name>
<url-pattern>/cgi-bin/iipsrv.fcgi</url-pattern>
</servlet-mapping>
```
You then need to start an instance of the server on the requested port (6667 in this example) using
spawn-cgi (see spawn-cgi section above) or on the command line (see below).
### Command Line
It is also possible to start iipsrv directly on the command line using the --bind parameter.
For example:
iipsrv.fcgi --bind 192.168.0.1:9000
where the argument given to bind is the socket on which to listen to FCGI
requests. Note that these are *not* HTTP requests and iipsrv will still require a web server front-end.
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.
Your web server should, therefore, be configured to use this address for FastCGI.
For example with lighttpd:
fastcgi.server = (
"/fcgi-bin/iipsrv.fcgi" => (
("host"=>"192.168.0.1", "port"=>9000, "check-local"=>"disable")
)
)
------------------------------------------------------------------------------------
Please refer to the project site http://iipimage.sourceforge.net for further details
------------------------------------------------------------------------------------
(c) 2000-2016 Ruven Pillay <ruven@users.sourceforge.net>
|