Mercurial > hg > digilib

comparison doc/src/site/markdown/image-directories.md @ 1216:bd7dfa8b164e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
author robcast
date Fri, 06 Sep 2013 10:25:05 +0200
parents
children aa09153a2b13
comparison
equal deleted inserted replaced
1215:68625b3c5341 1216:bd7dfa8b164e
1 # Directory layout for images
2
3 In digilib all images are identified by the `fn` and (optional) `pn` parameters.
4 The value for `fn` can be a directory path or a directory path and a filename,
5 separated by slashes, e.g. "`fn=books/book1/page0002`".
6
7 If `fn` is a directory path without filename `pn` is the index number of the
8 image files in this directory in alphabetical order, e.g.
9 "`fn=books/book1&pn=2`". The default for `pn` is 1 i.e. the first image.
10
11 If `fn` ends in a filename `pn` is ignored. File extensions are also ignored,
12 i.e. "`books/book1/page0002`" and "`books/book1/page0002.tif`" identify the same
13 image. It is recommended to omit the file extension.
14
15 The directory path in `fn` is relative to the base directory in the `basedir-list`
16 parameter of the `digilib-config.xml` file, e.g. if
17
18 <parameter name="basedir-list" value="/docuserver/images" />
19
20 and
21
22 fn=books/book1/page0002
23
24 then digilib will try to load the file
25
26 /docuserver/images/books/book1/page0002.tif
27
28 (automatically finding the right file extension)
29
30
31 ## Prescaled images
32
33 You can provide any number of scaled-down versions of your images that
34 digilib can use when a smaller version of an image is requested. Since less data
35 has to be read and processed this can speed up digilib's performance considerably.
36
37 The actual process is that the client requests a certain target size,
38 digilib scans all available scaled-down versions of the same image, selects the
39 smallest image that is larger than the requested size and scales it down to the
40 requested size.
41
42 There is another optimization in digilib: if the requested image is *exactly*
43 the same size and type as the pre-scaled image then the pre-scaled image is sent
44 unmodified to the client which is a lot faster. So it makes sense to produce
45 thumbnails of exactly 90 pixel width when they are used in an HTML page where
46 all images are 90 pixel wide.
47
48 The scaled-down versions of the image have to have the same file name as
49 the original hi-res file. They can have a different type and extension (e.g.
50 `img002.jpg` for `img002.TIFF`)
51
52 The scaled down images have to have the same directory path (the part that
53 shows up in digilib's "fn" parameter) as the hi-res file wile the first part of each
54 directory tree is configured by the `basedir-list` parameter in
55 `digilib-config.xml`.
56
57 The sequence of directories in `basedir-list` is from high-res to low-res.
58 Images must be present in the hires directory but they need not be present in
59 all lower-res directories.
60
61 e.g. if digilib-config.xml contains
62
63 <parameter name="basedir-list" value="/images:/scaled:/thumb" />
64
65 and a user requests the image `books/book1/page0002` digilib looks for
66
67 1. `/thumb/books/book1/page0002.jpg`
68 2. `/scaled/books/book1/page002.jpg`
69 3. `/images/books/book1/page002.tif`
70
71 (automatically finding the right file extension)
72 and uses the first image that is bigger than or equal to the requested size.
73
74 For batch-prescaling our images we use a script called "scale-o-mat" that uses a
75 lot of freely available imaging libraries (ImageMagick, libtiff, netpbm) and is
76 available in our public CVS [[1]](http://itgroup.mpiwg-berlin.mpg.de/cgi-bin/cvsweb.cgi/scaleomat/).
77 The script is given a
78 hi-res base directory, a destination base directory, a destination size and a
79 starting directory. It then processes all files in the starting directory and
80 all its subdirectories and creates scaled images in corresponding directories
81 under the destination base directory.
82
83 We currently use prescaled thumbnails of 100 pixels and images for browser
84 display of 1500 pixels. Remember that the prescaled image has to be larger (or
85 the same size) than the requested image size!