Mercurial > hg > digilib

comparison doc/src/site/markdown/digilib-short.md @ 1273:30ec52034355

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
added some forgotten docs.
author robcast
date Fri, 31 Jan 2014 12:26:08 +0100
parents
children 828b6c8b1b19
comparison
equal deleted inserted replaced
1272:d0c99b2d7234 1273:30ec52034355
1 # A short introduction to digilib
2
3 ## digilib -- how does it work?
4
5 The image server digilib is a state-less web-based client-server
6 application for interactive viewing and manipulation of images.
7
8 ## Frontend and Scaler server
9
10 digilib consists mainly of two parts, the image server component proper,
11 called "Scaler" and a client-side part that runs in the users web
12 browser.
13
14 ![digilib client and Scaler server](images/digilib-short-1.png)
15
16 The users browser sends an HTTP request for a certain (zoomed, scaled,
17 rotated) image to the Scaler server and the server returns the image
18 data as HTTP response.
19
20 To complete the schematics of figure 1 we must also take into account
21 that the client-side part consisting of HTML and Javascript code has
22 also been requested and loaded from a frontend-web server into the users
23 browser.
24
25 ![digilib client with frontend and Scaler server](images/digilib-short-2.png)
26
27 To date there are several frontend implementations for digilib like the
28 current "jquery" version that only requires static HTML and Javascript and the
29 older "greyskin" version (grey buttons, implemented in JSP) that come with
30 the default [digilib distribution][1] or the "[Zogilib][2]" frontend version
31 implemented in ZOPE.
32
33 The frontend-server and the Scaler-server do not have to run
34 on the same machine and often there are several frontends that use the
35 same Scaler server.
36
37 ### Request formats
38
39 The format of the HTTP requests for the frontend and the
40 Scaler server can be completely different. The HTML and Javascript code
41 of the frontend just has to generate the correct request for the Scaler
42 to produce the desired image. Most of the current frontend implementations
43 share some or all of the parameters with the Scaler API.
44
45 ### Scaler
46
47 The [Scaler API](scaler-api.html) is documented on the digilib.berlios.de
48 pages. Here is a minimal version:
49
50 The Scaler servlet takes parameters in the HTTP request format:
51 `Scaler/request\_path/?param1=value1&param2=value2&...` Unknown parameters
52 will be silently ignored.
53
54 Recognised parameters:
55
56 - `request_path` path to file or directory.
57 - `fn` path to file or directory. This path will be added to the
58 `request_path` behind the servlet name. Either parameter can be
59 empty. All paths are relative to the configured base directory
60 (digilib-config parameter `basedir-list`).
61 - `pn` page number. Index into the (alphabetically sorted)
62 directory given by the path. Starts with 1. Ignored if the path
63 points to a file. Default: 1.
64 - `dw` destination image width (pixels). If omitted the image is
65 scaled to fit `dh.`
66 - `dh` destination image height (pixels). If omitted the image
67 is scaled to fit `dw`.
68 - `wx` relative x offset of the image area to be sent (0 <=
69 `wx` <= 1). Default: 0.
70 - `wy` relative y offset of the image area to be sent (0 <=
71 `wy` <= 1). Default: 0.
72 - `ww` relative width of the image area to be sent (0 <= `ww`
73 <= 1). Default: 1.
74 - `wh` relative height of the image area to be sent (0 <= `wh`
75 <= 1). Default: 1.
76 - The image to be loaded can be specified by the `request_path`
77 (deprecated) or the `fn` (preferred) parameter and the optional
78 index `pn`
79 - if `fn` points to a directory then the file with the index `pn`
80 (in alphabetical order according to ASCII) will be loaded
81 - if `fn` points to a file (with or without extension) then this
82 file will be loaded
83
84 The image will be scaled equally in horizontal and vertical direction
85 such that the resulting image does not exceed the rectangle [`dw`,`dh`].
86 If only either height or width is given the image is scaled to match
87 only the given parameter. The size of the resulting image in the other
88 parameter is determined by the aspect ratio of the image.
89
90 An example for a Scaler URL is:
91 `http://digilib.mpiwg-berlin.mpg.de/digitallibrary/servlet/Scaler?fn=experimental/digilib-test/images&wh=0.1712&ww=0.1282&wy=0.1681&wx=0.6895&dw=862&dh=904`
92 such a URL can be used as src attribute to an img element in the
93 frontend HTML.
94
95 [1]: http://hg.berlios.de/repos/digilib/file/default/webapp/src/main/webapp
96
97 [2]: http://itgroup.mpiwg-berlin.mpg.de/cgi-bin/cvsweb.cgi/zogiLib/