Mercurial > hg > digilib

annotate doc/src/site/markdown/iiif-api.md @ 1685:b234dd84320d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
cleanup
author Robert Casties <casties@mpiwg-berlin.mpg.de>
date Mon, 26 Mar 2018 16:12:41 +0200
parents cd45d49f438d
children e46756f0d661
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.