Mercurial > hg > digilib
changeset 1273:30ec52034355
added some forgotten docs.
| author | robcast |
|---|---|
| date | Fri, 31 Jan 2014 12:26:08 +0100 |
| parents | d0c99b2d7234 |
| children | 8f8dff61535a |
| files | doc/src/site/markdown/digilib-short.md doc/src/site/markdown/install-digilib.md doc/src/site/markdown/scaler-api.md doc/src/site/resources/images/digilib-short-1.png doc/src/site/resources/images/digilib-short-2.png |
| diffstat | 5 files changed, 283 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/src/site/markdown/digilib-short.md Fri Jan 31 12:26:08 2014 +0100 @@ -0,0 +1,97 @@ +# A short introduction to digilib + +## digilib -- how does it work? + +The image server digilib is a state-less web-based client-server +application for interactive viewing and manipulation of images. + +## Frontend and Scaler server + +digilib consists mainly of two parts, the image server component proper, +called "Scaler" and a client-side part that runs in the users web +browser. + + + +The users browser sends an HTTP request for a certain (zoomed, scaled, +rotated) image to the Scaler server and the server returns the image +data as HTTP response. + +To complete the schematics of figure 1 we must also take into account +that the client-side part consisting of HTML and Javascript code has +also been requested and loaded from a frontend-web server into the users +browser. + + + +To date there are several frontend implementations for digilib like the +current "jquery" version that only requires static HTML and Javascript and the +older "greyskin" version (grey buttons, implemented in JSP) that come with +the default [digilib distribution][1] or the "[Zogilib][2]" frontend version +implemented in ZOPE. + +The frontend-server and the Scaler-server do not have to run +on the same machine and often there are several frontends that use the +same Scaler server. + +### Request formats + +The format of the HTTP requests for the frontend and the +Scaler server can be completely different. The HTML and Javascript code +of the frontend just has to generate the correct request for the Scaler +to produce the desired image. Most of the current frontend implementations +share some or all of the parameters with the Scaler API. + +### Scaler + +The [Scaler API](scaler-api.html) is documented on the digilib.berlios.de +pages. Here is a minimal version: + +The Scaler servlet takes parameters in the HTTP request format: +`Scaler/request\_path/?param1=value1¶m2=value2&...` Unknown parameters +will be silently ignored. + +Recognised parameters: + +- `request_path` path to file or directory. +- `fn` path to file or directory. This path will be added to the + `request_path` behind the servlet name. Either parameter can be + empty. All paths are relative to the configured base directory + (digilib-config parameter `basedir-list`). +- `pn` page number. Index into the (alphabetically sorted) + directory given by the path. Starts with 1. Ignored if the path + points to a file. Default: 1. +- `dw` destination image width (pixels). If omitted the image is + scaled to fit `dh.` +- `dh` destination image height (pixels). If omitted the image + is scaled to fit `dw`. +- `wx` relative x offset of the image area to be sent (0 <= + `wx` <= 1). Default: 0. +- `wy` relative y offset of the image area to be sent (0 <= + `wy` <= 1). Default: 0. +- `ww` relative width of the image area to be sent (0 <= `ww` + <= 1). Default: 1. +- `wh` relative height of the image area to be sent (0 <= `wh` + <= 1). Default: 1. +- The image to be loaded can be specified by the `request_path` + (deprecated) or the `fn` (preferred) parameter and the optional + index `pn` + - if `fn` points to a directory then the file with the index `pn` + (in alphabetical order according to ASCII) will be loaded + - if `fn` points to a file (with or without extension) then this + file will be loaded + +The image will be scaled equally in horizontal and vertical direction +such that the resulting image does not exceed the rectangle [`dw`,`dh`]. +If only either height or width is given the image is scaled to match +only the given parameter. The size of the resulting image in the other +parameter is determined by the aspect ratio of the image. + +An example for a Scaler URL is: +`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` +such a URL can be used as src attribute to an img element in the +frontend HTML. + +[1]: http://hg.berlios.de/repos/digilib/file/default/webapp/src/main/webapp + +[2]: http://itgroup.mpiwg-berlin.mpg.de/cgi-bin/cvsweb.cgi/zogiLib/
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/src/site/markdown/install-digilib.md Fri Jan 31 12:26:08 2014 +0100 @@ -0,0 +1,74 @@ +# Installing digilib + +To run digilib you need: + +* [Java](http://www.java.com/) (1.6 or higher) +* a Servlet Container like [Tomcat](http://tomcat.apache.org/) (version 7 or +higher) or [Jetty](http://www.eclipse.org/jetty/) (version 8 or higher) +* the digilib web application as a WAR file or application directory + +## Run the Servlet Container + +Install and run the Servlet Container of your choice: +[Tomcat](http://tomcat.apache.org/tomcat-7.0-doc/setup.html) or +[Jetty](http://wiki.eclipse.org/Jetty/Howto/Run_Jetty). + +When it runs you should be able to access the start page on +<http://localhost:8080/> + +## Install a digilib WAR file + +1. Download a digilib WAR file of a recent digilib release from the +BerliOS [Download page](http://developer.berlios.de/project/showfiles.php?group_id=251) +or the latest digilib build from the +[daily build page](http://digilib.berlios.de/downloads/daily-build/). +2. Rename the WAR file to `digilib.war`. +3. Deploy the WAR file, i.e. drop it into the `webapps` directory of your +Servlet Container. +4. Restart your Servlet Container (this may not be necessary). +5. Access your digilib instance at <http://localhost:8080/digilib/digilib.html>. + +You will now be able to see the sample images provided with the digilib +installation. + +If you want to use digilib to show your own images you have to change the +configuration file [digilib-config.xml](digilib-config.html) **inside** the +web application. This is hard to do with a WAR file so its better to +deploy digilib as a web application directory. + +## Install digilib as a web application directory + +Unpack the WAR file into a directory called `digilib` using +an unzip tool or the `jar -xf` Java command. + +Alternatively you can look into the `webapps` directory of your Servlet +Container (when its not running) to see if it created an unpacked web +application directory called `digilib`. + +Alternatively you can build your own version of digilib as documented +[here](build-maven.html). + +Then: + +1. Make sure that your Servlet Container is not running and remove any +`digilib.war` files from the `webapps` directory. +2. Copy your `digilib` directory into the `webapps` directory of the +Servlet Container. +3. Edit the `digilib-config.xml` file in the `WEB-INF` subdirectory of the +`digilib` directory and adjust the `basedir-list` parameter to point to +the directory with your image files [according to the +documentation](digilib-config.html). If there is no file `digilib-config.xml` +you can either create a new file or rename the sample file +`digilib-config.xml.template` to `digilib-config.xml` and edit it. +4. Start your Servlet Container. +5. Access your digilib instance at <http://localhost:8080/digilib/digilib.html> + +You can now view your own images in digilib by providing the directory and file +name as the `fn` parameter to `digilib.html`, e.g. if your file is called +`flower.jpg` and it is in a subdirectory of the base directory called +`digilib-test` you can now access the URL + +<http://localhost:8080/digilib/digilib.html?fn=digilib-test/flower> + +Read more about the layout of image files and directories +[here](image-directories.html).
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/src/site/markdown/scaler-api.md Fri Jan 31 12:26:08 2014 +0100 @@ -0,0 +1,112 @@ +# The digilib Scaler API + +The Scaler servlet takes parameters in the HTTP request format: + + Scaler/request_path/?param1=value1¶m2=value2&... + +Unknown parameters will be silently ignored. + +Recognised parameters (as of Version 2.2.2, for the most recent list of +parameters +[use the source](http://hg.berlios.de/repos/digilib/file/default/servlet/src/main/java/digilib/conf/DigilibServletRequest.java) +): + +- `request_path`: path to file or directory. +- `fn`: path to file or directory. This path will be added to the + `request_path` behind the servlet name. Either parameter can be + empty. All paths are relative to the configured base directory + (digilib-config parameter `basedir-list`). +- `pn`: page number. Index into the (alphabetically sorted) + directory given by the path. Starts with 1. Ignored if the path + points to a file. Default: 1. +- `dw`: destination image width (pixels). If omitted the image is + scaled to fit `dh.` +- `dh`: destination image height (pixels). If omitted the image + is scaled to fit `dw`. +- `wx`: relative x offset of the image area to be sent (0 <= + `wx` <= 1). Default: 0. +- `wy`: relative y offset of the image area to be sent (0 <= + `wy` <= 1). Default: 0. +- `ww`: relative width of the image area to be sent (0 <= `ww` + <= 1). Default: 1. +- `wh`: relative height of the image area to be sent (0 <= `wh` + <= 1). Default: 1. +- `ws`: additional scaling factor. The resulting image will have + the size \[`ws`\*`dw` x `ws`\*`dh`\]. Default: 1. +- `cont`: change contrast of the image. Negative values reduce + contrast, positive values enhance contrast. Pixel value is + multiplied by 2^`cont`. Default: 0 +- `brgt`: change brightness of image. Negative value reduces + brightness, positive value enhances brightness. The value `brgt` is + added to the pixel value. Default: 0 +- `rot`: rotate image. Rotation angle is given in degrees. + Default: 0 +- `rgbm`: modify colour by multiplication. The contrast of the + red green and blue components of the image can be reduced or + enhanced similar to the `cont` parameter. The factors for red, green + and blue are separated by slashes (e.g. `0.86/0/-0.5`). + Default: `0/0/0` +- `rgba`: modify colour by addition. The brightness of the red + green and blue components of the image can be reduced or enhanced + similar to the `brgt` parameter. The factors for red, green and blue + are separated by slashes (e.g. `100/0/25`). Default: `0/0/0` +- `ddpi`: resolution of client display for `osize` mode. Either + `ddpi` or `ddpix` and `ddpiy` must be set to use `osize` mode. +- `ddpix`: resolution of client display in x direction for + `osize` mode. +- `ddpiy`: resolution of client display in y direction for + `osize` mode. +- `scale`: absolute scale factor applied to the highest resolution image + for `ascale` mode. +- `colop`: additional color operation. One of "GRAYSCALE" (produces grayscale + image), "NTSC\_GRAY" (uses NTSC formula to produce grayscale image), + "INVERT" (inverts colors), "MAP\_GRAY\_BGR" (produces false-color image). +- `mo`: list flags for the mode of operation separated by comma ",". + - `fit`: always scale the image to fit \[`dw` x `dh`\] (default). + - `clip`: send the file in its original resolution, cropped + to fit \[`dw` x `dh`\]. + - `osize`: scale to original size based on image + resolution (from the image metadata) and display resolution + (from parameter ddpi). Fails if either resolution is unknown. + - `ascale`: scale the highest resolution image by an absolute + factor given by the `scale` parameter. + - `file`: send the file as-is (may be very large and all + sorts of image types!). If configuration doesn't allow sending + files (`sendfile-allowed=false`) revert to `clip`. + - `rawfile`: send the file as-is with a mime-type of + "application/octet-stream" so it can be downloaded with the + browser. + - `errtxt`: send error response as plain text. + - `errimg`: send error response as image (default). + - `errcode`: send error response as HTTP status code. + - `q0`-`q2`: quality of interpolation in scaling (q0: + worst, default). + - `lores`: try to use scaled image (default) + - `hires`: always use the highest resolution image. + - If the image is zoomed (`ww`, `wh` \< 1) the use of the scaled + image files depends on the requested resolution. + - `vmir`: mirror image vertically. + - `hmir`: mirror image horizontally. + - `jpg`: the resulting image is always sent as JPEG + (otherwise TIFF and PNG images are sent as PNG). + - `png`: the resulting image is always sent as PNG + (otherwise JPEG and J2K images are sent as JPEG). + +The image to be loaded can be specified by the `request_path` +(deprecated) or the `fn` parameter (preferred) and the optional +index `pn`: + +- if `fn` points to a directory then the file with the index `pn` + (in alphabetical order according to ASCII) will be loaded +- if `fn` points to a file (with or without extension) then this + file will be loaded + +Find more information on the directory layout [here](image-directories.html). + +The image will always be scaled equally in horizontal and vertical direction, +preserving the aspect ratio, +such that the resulting image does not exceed the rectangle \[`dw` x `dh`\]. + +If only either height or width is given the image is scaled to match +only the given dimension. The size of the resulting image in the other +dimension is determined by the aspect ratio of the image.