forked from klokantech/iiifserver
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
executable file
·370 lines (270 loc) · 12.5 KB
/
README
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
-----------------------------------------------------------------------
IIPImage - High Resolution Streaming Imaging Server
-----------------------------------------------------------------------
ABOUT:
-----
IIPImage is an advanced high-performance feature-rich imaging 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 both 8 and 16 bit depths, 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
* 16 bit image support
* CIELAB support with automatic CIELAB->sRGB colour space conversion
* JPEG2000 support
* Supports Zoomify and DeepZoom protocols
* 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)
MyServer (http://www.myserverproject.net)
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>.
eg.
./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 number of quality layers to decode for image that support
progressive quality encoding, such as JPEG2000. Ignored for other file
formats. The default is 1.
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 relevent 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.
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
Order allow,deny
Allow from all
</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
Order allow,deny
Allow from all
# 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"
)
))
)
--------------------------------------------------------------------
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).
Command Line:
-------------
It is also possible to start iipsrv on the command line. 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. Your web server should, therefore, be configured to use this socket.
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.sf.net for further details
---------------------------------------------------------------------------
(c) 2000-2011 Ruven Pillay <[email protected]>