annotate doc/src/site/markdown/scaler-api.md @ 1593:4ef25f916df8

cleanup and site doc.
author robcast
date Wed, 08 Feb 2017 20:24:42 +0100
parents 71cd204862d4
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1273
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
1 # The digilib Scaler API
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
2
1291
bd333826fb7a small doc improvements.
robcast
parents: 1279
diff changeset
3 The Scaler servlet takes parameters in the HTTP query string format:
1273
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
4
1291
bd333826fb7a small doc improvements.
robcast
parents: 1279
diff changeset
5 http://host.domain/digilib/Scaler/request_path/?param1=value1&param2=value2&...
1273
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
6
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
7 Unknown parameters will be silently ignored.
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
8
1593
4ef25f916df8 cleanup and site doc.
robcast
parents: 1462
diff changeset
9 Recognised parameters (as of Version 2.5.0, for the most up to date information use the source for
4ef25f916df8 cleanup and site doc.
robcast
parents: 1462
diff changeset
10 [parameters](https://sourceforge.net/p/digilib/code/ci/default/tree/servlet/src/main/java/digilib/conf/DigilibServletRequest.java)
4ef25f916df8 cleanup and site doc.
robcast
parents: 1462
diff changeset
11 and
4ef25f916df8 cleanup and site doc.
robcast
parents: 1462
diff changeset
12 [mode options](https://sourceforge.net/p/digilib/code/ci/default/tree/common/src/main/java/digilib/conf/DigilibOption.java)
1273
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
13 ):
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
14
1291
bd333826fb7a small doc improvements.
robcast
parents: 1279
diff changeset
15 - `request_path`: (optional) path to file or directory.
bd333826fb7a small doc improvements.
robcast
parents: 1279
diff changeset
16 - `fn`: path to file or directory. (This path will be added to
bd333826fb7a small doc improvements.
robcast
parents: 1279
diff changeset
17 `request_path`. Either parameter can be empty.
bd333826fb7a small doc improvements.
robcast
parents: 1279
diff changeset
18 All paths are relative to the configured base directory
bd333826fb7a small doc improvements.
robcast
parents: 1279
diff changeset
19 from the [digilib-config.xml](digilib-config.html) parameter `basedir-list`).
1273
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
20 - `pn`: page number. Index into the (alphabetically sorted)
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
21 directory given by the path. Starts with 1. Ignored if the path
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
22 points to a file. Default: 1.
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
23 - `dw`: destination image width (pixels). If omitted the image is
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
24 scaled to fit `dh.`
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
25 - `dh`: destination image height (pixels). If omitted the image
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
26 is scaled to fit `dw`.
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
27 - `wx`: relative x offset of the image area to be sent (0 <=
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
28 `wx` <= 1). Default: 0.
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
29 - `wy`: relative y offset of the image area to be sent (0 <=
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
30 `wy` <= 1). Default: 0.
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
31 - `ww`: relative width of the image area to be sent (0 <= `ww`
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
32 <= 1). Default: 1.
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
33 - `wh`: relative height of the image area to be sent (0 <= `wh`
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
34 <= 1). Default: 1.
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
35 - `ws`: additional scaling factor. The resulting image will have
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
36 the size \[`ws`\*`dw` x `ws`\*`dh`\]. Default: 1.
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
37 - `cont`: change contrast of the image. Negative values reduce
1291
bd333826fb7a small doc improvements.
robcast
parents: 1279
diff changeset
38 contrast, positive values enhance contrast. Each pixel value is
1273
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
39 multiplied by 2^`cont`. Default: 0
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
40 - `brgt`: change brightness of image. Negative value reduces
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
41 brightness, positive value enhances brightness. The value `brgt` is
1291
bd333826fb7a small doc improvements.
robcast
parents: 1279
diff changeset
42 added to each pixel value. Default: 0
1273
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
43 - `rot`: rotate image. Rotation angle is given in degrees.
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
44 Default: 0
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
45 - `rgbm`: modify colour by multiplication. The contrast of the
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
46 red green and blue components of the image can be reduced or
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
47 enhanced similar to the `cont` parameter. The factors for red, green
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
48 and blue are separated by slashes (e.g. `0.86/0/-0.5`).
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
49 Default: `0/0/0`
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
50 - `rgba`: modify colour by addition. The brightness of the red
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
51 green and blue components of the image can be reduced or enhanced
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
52 similar to the `brgt` parameter. The factors for red, green and blue
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
53 are separated by slashes (e.g. `100/0/25`). Default: `0/0/0`
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
54 - `ddpi`: resolution of client display for `osize` mode. Either
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
55 `ddpi` or `ddpix` and `ddpiy` must be set to use `osize` mode.
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
56 - `ddpix`: resolution of client display in x direction for
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
57 `osize` mode.
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
58 - `ddpiy`: resolution of client display in y direction for
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
59 `osize` mode.
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
60 - `scale`: absolute scale factor applied to the highest resolution image
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
61 for `ascale` mode.
1462
71cd204862d4 document new parameters.
robcast
parents: 1291
diff changeset
62 - `colop`: color operation. One of
71cd204862d4 document new parameters.
robcast
parents: 1291
diff changeset
63 - `GRAYSCALE` (produces grayscale image)
71cd204862d4 document new parameters.
robcast
parents: 1291
diff changeset
64 - `NTSC_GRAY` (uses NTSC formula to produce grayscale image)
71cd204862d4 document new parameters.
robcast
parents: 1291
diff changeset
65 - `BITONAL` (produces black-and-white image)
71cd204862d4 document new parameters.
robcast
parents: 1291
diff changeset
66 - `INVERT` (inverts colors)
71cd204862d4 document new parameters.
robcast
parents: 1291
diff changeset
67 - `MAP_GRAY_BGR` (produces false-color image mapping brightness values to color scale from blue via green to red).
1593
4ef25f916df8 cleanup and site doc.
robcast
parents: 1462
diff changeset
68 - `mo`: list of options for the mode of operation separated by comma ",".
4ef25f916df8 cleanup and site doc.
robcast
parents: 1462
diff changeset
69 - `fit`: scale the (selected area of the) image proportionally to fit inside [dw x dh], preserving its aspect ratio (default).
4ef25f916df8 cleanup and site doc.
robcast
parents: 1462
diff changeset
70 - `squeeze`: scale the (selected area of the) image to fill [dw x dh], changing its aspect ratio (since v2.3.3).
4ef25f916df8 cleanup and site doc.
robcast
parents: 1462
diff changeset
71 - `crop`: scale the (selected area of the) image proportionally to fill [dw x dh] with the shorter side, cropping the longer side (since v2.5).
4ef25f916df8 cleanup and site doc.
robcast
parents: 1462
diff changeset
72 - `fill`: scale the (selected area of the) image proportionally to fill [dw x dh] with the longer side, filling out the image on the shorter side if possible (since v2.3.3).
1462
71cd204862d4 document new parameters.
robcast
parents: 1291
diff changeset
73 - `clip`: send the file in the highest resolution, cropped
1273
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
74 to fit \[`dw` x `dh`\].
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
75 - `osize`: scale to original size based on image
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
76 resolution (from the image metadata) and display resolution
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
77 (from parameter ddpi). Fails if either resolution is unknown.
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
78 - `ascale`: scale the highest resolution image by an absolute
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
79 factor given by the `scale` parameter.
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
80 - `file`: send the file as-is (may be very large and all
1291
bd333826fb7a small doc improvements.
robcast
parents: 1279
diff changeset
81 sorts of image types!). If the configuration doesn't allow sending
1273
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
82 files (`sendfile-allowed=false`) revert to `clip`.
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
83 - `rawfile`: send the file as-is with a mime-type of
1291
bd333826fb7a small doc improvements.
robcast
parents: 1279
diff changeset
84 "application/octet-stream" so the browser presents a download dialog.
1273
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
85 - `errtxt`: send error response as plain text.
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
86 - `errimg`: send error response as image (default).
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
87 - `errcode`: send error response as HTTP status code.
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
88 - `q0`-`q2`: quality of interpolation in scaling (q0:
1291
bd333826fb7a small doc improvements.
robcast
parents: 1279
diff changeset
89 worst, q2 best).
bd333826fb7a small doc improvements.
robcast
parents: 1279
diff changeset
90 - `hires`: only use the highest resolution image.
1462
71cd204862d4 document new parameters.
robcast
parents: 1291
diff changeset
91 - `autores`: use the pre-scaled image that is bigger than the requested size (default).
71cd204862d4 document new parameters.
robcast
parents: 1291
diff changeset
92 - `lores`: prefer the next-smaller pre-scaled image.
1273
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
93 - `vmir`: mirror image vertically.
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
94 - `hmir`: mirror image horizontally.
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
95 - `jpg`: the resulting image is always sent as JPEG
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
96 (otherwise TIFF and PNG images are sent as PNG).
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
97 - `png`: the resulting image is always sent as PNG
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
98 (otherwise JPEG and J2K images are sent as JPEG).
1462
71cd204862d4 document new parameters.
robcast
parents: 1291
diff changeset
99 - `pxarea`: interpret `wx`, `wy`, `ww`, `wh` as pixel coordinates on the highest resolution image.
1273
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
100
1291
bd333826fb7a small doc improvements.
robcast
parents: 1279
diff changeset
101 The image to be loaded is specified by the `request_path`
bd333826fb7a small doc improvements.
robcast
parents: 1279
diff changeset
102 (deprecated) and/or the `fn` parameter (preferred) and the optional
1273
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
103 index `pn`:
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
104
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
105 - if `fn` points to a directory then the file with the index `pn`
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
106 (in alphabetical order according to ASCII) will be loaded
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
107 - if `fn` points to a file (with or without extension) then this
1291
bd333826fb7a small doc improvements.
robcast
parents: 1279
diff changeset
108 file will be loaded (regardless of `pn`).
1273
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
109
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
110 Find more information on the directory layout [here](image-directories.html).
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
111
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
112 The image will always be scaled equally in horizontal and vertical direction,
1462
71cd204862d4 document new parameters.
robcast
parents: 1291
diff changeset
113 preserving the aspect ratio (except with `mo=squeeze`),
1273
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
114 such that the resulting image does not exceed the rectangle \[`dw` x `dh`\].
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
115
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
116 If only either height or width is given the image is scaled to match
30ec52034355 added some forgotten docs.
robcast
parents:
diff changeset
117 only the given dimension. The size of the resulting image in the other
1462
71cd204862d4 document new parameters.
robcast
parents: 1291
diff changeset
118 dimension is determined by the aspect ratio of the image or the selected area.