# HG changeset patch
# User robcast
# Date 1391167568 -3600
# Node ID 30ec520343551fdbb470ea8a9bc4d2e9fa984ef1
# Parent d0c99b2d72349393c8dd0563818fcdd9aece9f12
added some forgotten docs.
diff -r d0c99b2d7234 -r 30ec52034355 doc/src/site/markdown/digilib-short.md
--- /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/
diff -r d0c99b2d7234 -r 30ec52034355 doc/src/site/markdown/install-digilib.md
--- /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
+
+
+## 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 .
+
+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
+
+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
+
+
+
+Read more about the layout of image files and directories
+[here](image-directories.html).
diff -r d0c99b2d7234 -r 30ec52034355 doc/src/site/markdown/scaler-api.md
--- /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.
diff -r d0c99b2d7234 -r 30ec52034355 doc/src/site/resources/images/digilib-short-1.png
Binary file doc/src/site/resources/images/digilib-short-1.png has changed
diff -r d0c99b2d7234 -r 30ec52034355 doc/src/site/resources/images/digilib-short-2.png
Binary file doc/src/site/resources/images/digilib-short-2.png has changed