Mercurial > hg > digilib

annotate doc/src/site/markdown/iiif-api.md @ 1714:d497eb11141c default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
updated travis-ci config for automatic WAR releases.
author Robert Casties <casties@mpiwg-berlin.mpg.de>
date Mon, 18 Feb 2019 20:49:15 +0100
parents e46756f0d661
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1396
7a2de95a7b8e documentation updated with Ubbo's codec tuning tips and IIIF API info.
robcast
parents:
diff changeset
1 # The digilib IIIF API
7a2de95a7b8e documentation updated with Ubbo's codec tuning tips and IIIF API info.
robcast
parents:
diff changeset
2
1635
cd45d49f438d cleanup and add doc about Manifester servlet.
robcast
parents: 1458
diff changeset
3 ## IIIF Image API
cd45d49f438d cleanup and add doc about Manifester servlet.
robcast
parents: 1458
diff changeset
4
1685
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
5 The Scaler servlet provides not only its native [Scaler API](scaler-api.html) but also an API
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
6 compliant to the standards of the International Image Interoperability Framework http://iiif.io.
1396
7a2de95a7b8e documentation updated with Ubbo's codec tuning tips and IIIF API info.
robcast
parents:
diff changeset
7
1685
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
8 As of version 2.3.7 digilib supports the [IIIF Image API version 2](http://iiif.io/api/image/2.1/)
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
9 at [compliance level 2](http://iiif.io/api/image/2.0/compliance.html). You can switch between API
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
10 version 1.1 and 2.0 support with the `iiif-api-version` parameter in [digilib-config](digilib-config.html),
1396
7a2de95a7b8e documentation updated with Ubbo's codec tuning tips and IIIF API info.
robcast
parents:
diff changeset
11
7a2de95a7b8e documentation updated with Ubbo's codec tuning tips and IIIF API info.
robcast
parents:
diff changeset
12 IIIF Image API URLs for an image request have the form:
7a2de95a7b8e documentation updated with Ubbo's codec tuning tips and IIIF API info.
robcast
parents:
diff changeset
13
1452
9429bb9c3a42 more IIIF API support (expose size of prescaled images).
robcast
parents: 1427
diff changeset
14 http[s]://{server}/{digilib-webapp}/Scaler/{iiif-prefix}/{identifier}/{region}/{size}/{rotation}/{quality}.{format}
1396
7a2de95a7b8e documentation updated with Ubbo's codec tuning tips and IIIF API info.
robcast
parents:
diff changeset
15
7a2de95a7b8e documentation updated with Ubbo's codec tuning tips and IIIF API info.
robcast
parents:
diff changeset
16 where `digilib-webapp` is the name of the digilib web application in the servlet container.
7a2de95a7b8e documentation updated with Ubbo's codec tuning tips and IIIF API info.
robcast
parents:
diff changeset
17
1685
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
18 The value of `iiif-prefix` is defined by the `iiif-prefix` parameter in [digilib-config](digilib-config.html).
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
19 The default value is "IIIF".
1396
7a2de95a7b8e documentation updated with Ubbo's codec tuning tips and IIIF API info.
robcast
parents:
diff changeset
20
1685
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
21 The `identifier` part of the URL must not contain slashes. Since the identifier is mapped to the digilib
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
22 fn-parameter, which is a filesystem path that likely contains slashes separating subdirectories, all
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
23 occurrences of a slash have to be replaced by the value of the `iiif-slash-replacement` parameter in
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
24 [digilib-config](digilib-config.html). The default value of the replacement string is "!", so the fn-path
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
25 "books/book1/page0002" becomes the identifier "books!book1!page0002".
1396
7a2de95a7b8e documentation updated with Ubbo's codec tuning tips and IIIF API info.
robcast
parents:
diff changeset
26
1685
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
27 For a definition of the other parameters `region`, `size`, `rotation`, `quality`, and `format` please
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
28 see the [IIIF Image API docs](http://iiif.io/api/image/2.0/).
1396
7a2de95a7b8e documentation updated with Ubbo's codec tuning tips and IIIF API info.
robcast
parents:
diff changeset
29
7a2de95a7b8e documentation updated with Ubbo's codec tuning tips and IIIF API info.
robcast
parents:
diff changeset
30 A IIIF Image API image request URL could look like:
7a2de95a7b8e documentation updated with Ubbo's codec tuning tips and IIIF API info.
robcast
parents:
diff changeset
31
1452
9429bb9c3a42 more IIIF API support (expose size of prescaled images).
robcast
parents: 1427
diff changeset
32 http://www.example.org/digilib/Scaler/IIIF/books!book1!page0002/full/!150,75/0/default.jpg
1396
7a2de95a7b8e documentation updated with Ubbo's codec tuning tips and IIIF API info.
robcast
parents:
diff changeset
33
7a2de95a7b8e documentation updated with Ubbo's codec tuning tips and IIIF API info.
robcast
parents:
diff changeset
34 An info request URL for the same image looks like:
7a2de95a7b8e documentation updated with Ubbo's codec tuning tips and IIIF API info.
robcast
parents:
diff changeset
35
7a2de95a7b8e documentation updated with Ubbo's codec tuning tips and IIIF API info.
robcast
parents:
diff changeset
36 http://www.example.org/digilib/Scaler/IIIF/books!book1!page0002/info.json
1635
cd45d49f438d cleanup and add doc about Manifester servlet.
robcast
parents: 1458
diff changeset
37
cd45d49f438d cleanup and add doc about Manifester servlet.
robcast
parents: 1458
diff changeset
38 ## IIIF Presentation API
cd45d49f438d cleanup and add doc about Manifester servlet.
robcast
parents: 1458
diff changeset
39
1685
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
40 As of version 2.5.3 digilib provides the optional Manifester servlet that generates simple
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
41 [IIIF Presentation API version 2](http://iiif.io/api/presentation/2.1) manifests that can
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
42 be used with any [IIIF viewer](http://iiif.io/apps-demos/#image-viewing-clients) to navigate
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
43 a directory full of images with the functions of a book-reader or light-table.
1635
cd45d49f438d cleanup and add doc about Manifester servlet.
robcast
parents: 1458
diff changeset
44
cd45d49f438d cleanup and add doc about Manifester servlet.
robcast
parents: 1458
diff changeset
45 To build digilib with the Manifester servlet you need to add the `iiif-presentation` profile to your Maven build:
cd45d49f438d cleanup and add doc about Manifester servlet.
robcast
parents: 1458
diff changeset
46
cd45d49f438d cleanup and add doc about Manifester servlet.
robcast
parents: 1458
diff changeset
47 mvn -Piiif-presentation package
cd45d49f438d cleanup and add doc about Manifester servlet.
robcast
parents: 1458
diff changeset
48
cd45d49f438d cleanup and add doc about Manifester servlet.
robcast
parents: 1458
diff changeset
49 (or use the digilib-webapp-X.X.X-srv3p.war file from the website)
cd45d49f438d cleanup and add doc about Manifester servlet.
robcast
parents: 1458
diff changeset
50
cd45d49f438d cleanup and add doc about Manifester servlet.
robcast
parents: 1458
diff changeset
51 The Manifester servlet URLs have the form:
cd45d49f438d cleanup and add doc about Manifester servlet.
robcast
parents: 1458
diff changeset
52
cd45d49f438d cleanup and add doc about Manifester servlet.
robcast
parents: 1458
diff changeset
53 http[s]://{server}/{digilib-webapp}/Manifester/{iiif-prefix}/{identifier}
cd45d49f438d cleanup and add doc about Manifester servlet.
robcast
parents: 1458
diff changeset
54
cd45d49f438d cleanup and add doc about Manifester servlet.
robcast
parents: 1458
diff changeset
55 So you can get a manifest for all images in the directory `/books/book1` with a URL like:
cd45d49f438d cleanup and add doc about Manifester servlet.
robcast
parents: 1458
diff changeset
56
cd45d49f438d cleanup and add doc about Manifester servlet.
robcast
parents: 1458
diff changeset
57 http://www.example.org/digilib/Manifester/IIIF/books!book1
cd45d49f438d cleanup and add doc about Manifester servlet.
robcast
parents: 1458
diff changeset
58
1685
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
59 To try out a viewer on your manifest you can go to the website of the Universal Viewer
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
60 [http://universalviewer.io/](http://universalviewer.io/) and enter the URL of your manifest
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
61 in the "view a manifest" box on the page. This will work even with a local digilib
b234dd84320d cleanup
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1635
diff changeset
62 installation since the Javascript in your Browser reads and interprets the manifest.
1686
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
63
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
64 The minimal information in the manifest can be enhanced with additional metadata or the replaced
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
65 by a custom manifest. If the servlet finds a file with the name
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
66
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
67 manifest.json
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
68
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
69 in a directory then the contents of that file are sent instead of an auto-generated manifest.
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
70 This works also in directories with no images so you could put a file with
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
71 [collection](http://iiif.io/api/presentation/2.1/#collection) information in a higher-level directory.
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
72
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
73 If the servlet finds a file with the name
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
74
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
75 manifest-meta.json
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
76
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
77 in a directory with images then the contents of that file are added to the top-level manifest
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
78 (`@context`, `@type`, `@id`, `sequences` are ignored). You can use this to add real bibliographical
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
79 information to the manifest.
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
80
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
81 The configuration parameter `iiif-manifest-page-label` determines the format of the label of each image:
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
82 `filename` uses the image file name (default, sans extension), `index` uses the index (counting from 1).
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
83
e46756f0d661 Config to select page labels and documentation for Manifester.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1685
diff changeset
84