Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update documentation #7

Merged
merged 22 commits into from
Oct 20, 2023
Merged

Update documentation #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
f53796b
First pass at updating documentation
hadro Aug 15, 2023
231b188
Revise documentation
hadro Aug 25, 2023
8c67a13
Update documentation
hadro Sep 29, 2023
b4cd238
Update CSS
hadro Sep 29, 2023
14fe5b8
More work on documentation
hadro Sep 29, 2023
351a655
Try adding helper
hadro Oct 5, 2023
6c55382
Tweak docs
hadro Oct 5, 2023
4d48747
Try again
hadro Oct 5, 2023
f69f67f
Update documentation
hadro Oct 5, 2023
7917a62
Fix typo
hadro Oct 5, 2023
943ece8
Making Sara's documentation edits
hadro Oct 5, 2023
209996c
Add appendix
hadro Oct 5, 2023
6f5aa16
Fix typo
hadro Oct 5, 2023
c8e90a9
More Sara tweaks
hadro Oct 6, 2023
47f4588
Fix docs typos
hadro Oct 6, 2023
47f16af
Merge branch 'main' into update-docs
hadro Oct 20, 2023
dd25374
Add comment about ID plus image filename
hadro Oct 20, 2023
a323cc1
Cleanup template
hadro Oct 20, 2023
bab15c2
Add note about helper pages; fixes #36
hadro Oct 20, 2023
ea17e7a
Add helper notes
hadro Oct 20, 2023
145df6e
clean up templates
hadro Oct 20, 2023
13a56f6
Add clover and mirador
hadro Oct 20, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 15 additions & 4 deletions iiify/static/styles/docs.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ a {
}

p {
font-size: .85em;
font-size: 1em;
line-height: 1.5em;
color: #444;
}
Expand All @@ -44,7 +44,7 @@ code {
border-radius: 3px;
display: block;
font-family: Consolas, 'Liberation Mono', Courier, monospace;
font-size: .75em;
font-size: 1em;
color: #fff;
}

Expand All @@ -71,7 +71,7 @@ h2 a {

h3 {
color: #444;
font-size: 1em;
font-size: 1.2em;
}

#container {
Expand Down Expand Up @@ -153,7 +153,7 @@ h3 {
border: 1px solid #ddd;
border-radius: 3px;
font-family: Consolas, 'Liberation Mono', Courier, monospace;
font-size: .75em;
font-size: 1em;
}

.warning {
Expand All @@ -163,4 +163,15 @@ h3 {

h2.pagetitle {
margin-bottom: 10px;
}

thead {
font-size: 1.2em;
font-weight: bold;
}
table {
padding: 2em 0 2em 0;
}
table td {
padding: 0 1em 0 1em;
}
51 changes: 51 additions & 0 deletions iiify/templates/docs/appendix.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
<article id="resources" class="hiddenz">
<h1 id="appendix">Appendix</h1>

<section>
<h2><a name="resources-legacy"></a>Getting legacy IIIF Presentation API 2.1 manifests</h2>

<p>To get the older Presentation API 2.1 IIIF manifest, plug in the ID to the following template:</p>
<div class="request">https://iiif.archive.org/iiif/2/<b>:id</b>/manifest.json</div>
</section>

<section>
<h2><a name="resources-listing">Listing all items</a></h2>
<p>
Querying the root of the Internet Archive IIIF API
results in a list of all publicly available items. Some items which are indexed in our search
engine but do have no associated content files will result in an
Internal Server Error. There are also a small number of items returned that do not have material types associated with them that are IIIF compatible. You can confirm whether the resource
actually exists or not by visiting the item's /details page on
archive.org.
</p>

<div class="request">https://iiif.archive.org/iiif</div>

</section>


<section>
<h2><a name="helpers">Helpers for various media types</a></h2>
<p>
To give you a sense of how different media types on the Internet Archive can be used in IIIF viewers, we've created a set of item "helpers" that provide some useful iformation and links.
</p>
<p>The pattern for these helper pages is as follows:</p>
<div class="request">https://iiif.archive.org/iiif/helper/<b>:id</b> </div>

<p>So, for example, the helper page for <a href="https://archive.org/details/img-8664_202009">a single image item</a> with item id <b>img-8664_202009</b> would be the following:</p>
<div class="request">https://iiif.archive.org/iiif/helper/img-8664_202009</div>

<p>The helper page for this <a href="https://archive.org/details/youtube-7w8F2Xi3vFw">movie item</a> with item id <b>youtube-7w8F2Xi3vFw</b> would be the following:</p>
<div class="request">https://iiif.archive.org/iiif/helper/youtube-7w8F2Xi3vFw</div>

<p>Not all media types on the Internet Archive have files that are playable in IIIF viewers, but the helper pages should work for images, texts, audio, and movie items.</p>
<br>
<br>
<br>
<br>



</section>
</article>
</hr>
44 changes: 44 additions & 0 deletions iiify/templates/docs/collections.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
<article id="resources" class="hiddenz">
<h1 id="collections">Collections</h1>

<section>
<h2><a name="resources-collections"></a>Getting IIIF collection manifests</h2>

<p>A group of more than one IIIF manifests is called a collection. On archive.org, a collection is a group of item pages organized under a collections page. For convenience, we've generate a IIIF collection manfiest for all of the collections on the Internet Archive. For more on how Internet Archive collections work, see <a href="https://help.archive.org/help/collections-a-basic-guide/">the "Collections - A Basic Guide"</a>.</p>

<h4>Example</h4>
<p>As with the manifests above, you'll need the Internet Archive identifier for the colllection. Here's an example collection page from the University of Leeds:</p>
<pre><a href="https://archive.org/details/leedsuniversitylibrary">https://archive.org/details/leedsuniversitylibrary</a></pre>

<p>In this case, the id is:</p>
<pre>leedsuniversitylibrary</pre>

<p>To then get the IIIF collection manifest, plug in the ID to the following template:</p>
<div class="request">https://iiif.archive.org/iiif/3/<b>:id</b>/collection.json</div>

<p>For the Leeds example above, the final IIIF collection manifest URL would be:</p>
<div class="request">https://iiif.archive.org/iiif/3/leedsuniversitylibrary/collection.json</div>

<h3>Note about nested collections</h3>
<p>Please note that Internet Archive collections can be arbitrarily nested within other collections. In these cases, the IIIF collection manifest will return a link to one or more IIIF collection manifest(s) in addition to the items nested individually within that Internet Archive collection.</p>

</section>

<section>
<h2><a name="resources-listing">Pagination for large collections</a></h2>
<p>The pattern described above for generating IIIF collection manifests will return the first 1000 items or sub-collections within the collection. In order to get the remaining items for collections larger than that, pagination is required.</p>
<p>This looks like the following:
<div class="request">https://iiif.archive.org/iiif/<b>:id</b>/<b>:page</b>/collection.json</div></p>

<p>For the University of Leeds collection above, there are at the time of this writing 3,775 items in the collection. That means that four collections manifest requests will be required to retrieve all the items and/or sub-collections listed within the collection.</p>

<table>
<thead><td>Collection manifest URL</td><td>Items retrieved</td></thead>
<tr><td>https://iiif.archive.org/iiif/3/leedsuniversitylibrary/collection.json</td><td>0-999</td></tr>
<tr><td>https://iiif.archive.org/iiif/3/leedsuniversitylibrary/2/collection.json</td><td>1000-1999</td></tr>
<tr><td>https://iiif.archive.org/iiif/3/leedsuniversitylibrary/3/collection.json</td><td>2000-2999</td></tr>
<tr><td>https://iiif.archive.org/iiif/3/leedsuniversitylibrary/4/collection.json</td><td>3000-3775</td></tr>
</table>
</section>
</article>
</hr>
25 changes: 11 additions & 14 deletions iiify/templates/docs/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,42 +2,39 @@
<html class="no-js" lang="">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">

<title>IIIF Documentation | Internet Archive</title>
<meta name="description" content="">

<meta name="viewport" content="width=device-width, initial-scale=1">

<link rel="apple-touch-icon" href="apple-touch-icon.png">
<!-- Place favicon.ico in the root directory -->
<link rel="stylesheet" type="text/css" href="{{ request.url_root}}static/styles/docs.css" media="all"/>
<script type="text/javascript" href="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.0.0-alpha1/jquery.min.js"></script>
<script type="text/javascript" href="{{ request.url_root}}static/scripts/docs.js"></script>
</head>
<body>
<!--[if lt IE 8]>
<p class="browserupgrade">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> to improve your experience.</p>
<![endif]-->

<header>
<img class="center" src="{{ request.url_root }}static/images/ia.png"/>
</header>
<div id="container">
<h2 class="pagetitle">IIIF API</h2>
<h2 class="pagetitle">IIIF APIs</h2>
<hr class="pagetop"/>
<main>
{% include 'docs/introduction.html' %}
{% include 'docs/overview.html' %}
{% include 'docs/resources.html' %}
{% include 'docs/items.html' %}
{% include 'docs/collections.html' %}
{% include 'docs/appendix.html' %}

</main>
<nav>
<ol>
<li><a href="#intro">Introduction</a></li>
<li><a href="#overview">Overview</a></li>
<li><a href="#image-api">Image API</a></li>
<li><a href="#presentation-api">Presentation API</a></li>
<li><a href="#resources">Items</a></li>
<li><a href="#resources">Tiles</a></li>
<li><a href="#resources">Viewers</a></li>
<li><a href="#resources">Integrations</a></li>
<li><a target="_blank" href="https://github.com/mekarpeles/iiif.archive.org/issues">Issues</a></li>
<li><a href="#collections">Collections</a></li>
<li><a href="#appendix">Appendix</a></li>
</ol>
</nav>
</div>
Expand Down
100 changes: 11 additions & 89 deletions iiify/templates/docs/introduction.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,107 +1,29 @@
<article id="introduction" class="hiddenz">
<h1>Introduction</h1>
<h1 id="intro">Introduction</h1>

<p><a href="https://iiif.io">IIIF</a> stands for the International Image Interoperability Framework.</p>

<p>
For those newly aquainted with the IIIF specification, this
introduction describes the purpose and applications of
<a href="https://iiif.io">IIIF</a> and the Internet Archive's IIIF
Service.
This introduction describes the way that the IIIF standards have been applied to the Internet Archive's services.
</p>

<ol type="i" class="toc">
<li><a href="">What is IIIF?</a></li>
<li><a href="">Importance</a></li>
<li><a href="">Deploying a IIIF Service</a></li>
</ol>

<section>
<h2><a name="intro-iiif">What is IIIF?</a></h2>
<p>
<a href="https://iiif.io">IIIF</a> (the "International Image
Interoperability Framework") is a collection of web standards for
manipulating and serving image resources (Image API), as well as
structuring collections of these images (Presentation API).
</p>

<h3>Image API</h3>
<p>
The <a href="http://iiif.io/api/image/2.0/">Image API</a> is an
interface capable of producing and serving arbitrary tiles of
arbitrary regions of an image (like Google Maps). The properties
of these image tiles are specified within a URL, allowing
permenant citation and retrieval at a later time
(see <a href="https://en.wikipedia.org/wiki/Idempotence">idempotence</a>).
The Image API supports and powers other computer applications
(like <a href="https://openseadragon.github.io/">zoomable image
viewers</a>
and <a href="http://universalviewer.azurewebsites.net/">book
readers</a>).
IIIF is a set of open standards for delivering high-quality, attributed digital objects online at scale. It’s also an international community developing and implementing the IIIF APIs in various contexts. IIIF is backed by a consortium of leading cultural institutions. For more details and examples, check out the <a href="https://iiif.io">IIIF website</a>, or the <a href="https://iiif.io/api">full API specifications</a>.
</p>
<p>For a very high-level overview see <a href="https://iiif.io/get-started/how-iiif-works/">"How IIIF Works"</a> published by the IIIF Consortium.</p>

<h3>Presentation API</h3>
<p>
The <a href="http://iiif.io/api/presentation/2.0/">Presentation
API</a> allows institutions to publish and consume metadata about
collections and sequences of image resources, called Manifests. A
Manifest may be composed of resources from any number of different
institutions serving their images in IIIF format.
</p>

<p>
For more information, read about IIIF's
goals <a href="http://universalviewer.azurewebsites.net/">here</a>.
</p>

<h2><a name="intro-importance">Importance</a></h2>
<h2><a name="intro-importance">Why?</a></h2>
<p>
At its essence, the goal of IIIF is interoperability: to make an
institution's image resources available and accessible to web
applications and clients running on other domains.
The goal of IIIF is interoperability: to make an
institution's image and audio/visual openly accessible resources available and easily reusable in a variety of web viewers and players, often open source, without the need for any special plugins or software.
</p>

<p>
The <a href="{{ request.url_root }}">Internet Archive IIIF API
v1</a>
(<a href="https://en.wikipedia.org/wiki/Software_release_life_cycle#Alpha">alpha</a>)
is
a <a href="https://en.wikipedia.org/wiki/Representational_state_transfer">RESTful</a>
<a href="https://en.wikipedia.org/wiki/Web_service">web
service</a> which implements IIIF (Image API &amp; Presentation
API) and provides a mechanism for accessing all of the Archive's
images and books in IIIF format. Every image item in the Archive
now has has a corresponding info.json and every book a
manifest.json. This means, you can seamlessly view any Archive.org
image or book in any interface compatible with IIIF (such as
OpenSeadragon, Mirador, and the Universal Viewer) and also enjoy
the enhancements they provide (annotation, side-by-size viewing,
and loading images from different institutions into the same
space).
</p>
<p>Fore more about how the goals of interoperability fit with the Internet Archive's mission, see our <a href="https://blog.archive.org/2023/09/18/making-iiif-official-at-the-internet-archive/">Making IIIF Official at the Internet Archive</a> announcement.</p>

<p>
The service also provides a mechanism for producing permanantly
citeable image tiles of any arbitrary region of any image or book
found in the Internet Archive.
</p>
</section>

<section>
<h2>Deploying a IIIF Service</h2>
<p>
The Internet Archive IIIF API v1 (alpha) is built using
Python3.4 <a href="https://pypi.python.org/pypi/Flask">Flask</a>
web application framework and
the <a href="https://pypi.python.org/pypi/iiif2">iiif2</a>
library. The source code
for <a href="iiif.archive.org">iiif.archive.org</a> is publicly
available <a href="https://github.com/mekarpeles/iiif.archive.org">here</a>,
as is the source of
the <a href="pypi.python.org/pypi/iiif2">iiif2</a> image
processing
library <a href="https://github.com/mekarpeles/iiif2">here</a>. For
questions on implementing a service,
contact <a href="mailto:support@archive.org">support@archive.org</a>.
</p>
</section>
</article>

<hr/>
60 changes: 60 additions & 0 deletions iiify/templates/docs/items.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
<article id="resources" class="hiddenz">
<h1 id="items">Items</h1>
<p>
<!--
<ol type="i" class="toc">
<li><a href="">Listing Items</a></li>
<li><a href="">Items Types</a></li>
<li><a href="">Viewing Items</a></li>
<li><a href="">Producing Tiles</a></li>
<li><a href="">IIIF Manifests &amp; Metadata</a></li>
</ol> -->



<section>
<h2><a name="resources-types">Item Types</a></h2>
<p>
Items available through the this service include Images, Books,
Audio, and Movie materials. This means any item on archive.org which has a
`mediatype` of `texts`, `image`, `audio`, or `movie`.</p>

<p>For more pointers on how IIIF manifests can be used for different material types, see the Appendix section on <a href="#helpers">Helpers</a>.</p>

<p>There are some edge cases where rare file types are not represented in the IIIF presentation manifest. If you encounter an item where you think this may be the case, <a href="https://github.com/internetarchive/iiif/issues">open an issue on the Github repository</a>.</p>

</section>

<section>
<h2><a id="retrieving-manifests"></a>Retrieving a manifest for an item</h2>

<p>Every Internet Archive item has a "details" page that is the main page for that item.</p>
<p>
The "details" page will have the word "details" in the URL, like in this example:
<pre><a href="https://archive.org/details/img-8664_202009">https://archive.org/details/img-8664_202009</a></pre></p>

<h4>Example</h4>
<p>What you'll need to get the IIIF manifest for any Internet Archive item is the identifier, which is the alphanumeric part of the URL that follows the "/details/" part. </p>

<p>So, from our example just above, the Internet Archive identifier for that item is: <pre>img-8664_202009</pre></p>

<p>To then get the IIIF manifest, plug in the ID to the following template:</p>
<div class="request">https://iiif.archive.org/iiif/3/<b>:id</b>/manifest.json</div>

<p>For the example above, the final IIIF manifest URL would be:</p>
<div class="request">https://iiif.archive.org/iiif/3/img-8664_202009/manifest.json</div>

<h3>Note about IIIF Presentation API versions</h3>
<p>
The pattern above describes the way to return IIIF Presentation API 3.0 manifests, as denoted by the <b>/3/</b> in the URL. </p>
<p>The manifest URL can also be used with the version number removed (<span>https://iiif.archive.org/iiif/<b>:id</b>/manifest.json</span>), though note that with any future updates that URL will always return the most current version of the Presentation API.</p>


<p>The older experimental version of the IIIF APIs for Internet Archive materials hosted on Archivelabs served up IIIF Presentation API version 2.1 manifests; <a href="#appendix">see below for instructions on retrieving a legacy manifests</a>.</p>


</section>


</article>
</hr>
Loading
Loading