How to Use the Image API

Requesting & displaying images using the IIIF Image API

"Resizing" images using IIIF

Without IIIF, resizing an image would require downloading and editing it in a separate software program (e.g. Adobe Photoshop, Canva). However, if IIIF is available and we simply want to display the image on the web, we wouldn't need to create a derivative file. Instead, we can request the size we want using the IIIF Image API, and the image server will respond with the resized image.

The steps for manually requesting a resized image (given the IIIF manifest) are listed below. Although we use Vault as an example, the same instructions will work for any manifest that is backed by a IIIF image server and is level 1 or level 2 compliant (details on levels of Image API compliance).

Go to the object's manifest page (see detailed instructions for finding a Vault manifest). We'll use this Vault manifest as the example for the rest of this tutorial.
Scroll through the manifest until you reach the "canvases" section. From here, you'll need to find the canvas that corresponds to the image you're looking for. Depending on the IIIF viewer you're using, it may be faster to search the canvases by title rather than by counting X no. of images from the start.
From the canvas, follow the manifest down to images, then resource, then service, then the @id attribute. This should look like a URL and contain the unique identifier for this particular image. For our example, this @id is https://vault.library.uvic.ca/images/0a4d3d9f-210a-47be-b89d-a627ea4c570f%252Ffiles%252Fde77c7a9-77fb-4d9e-aa54-87b51b16fd1f. (Note that if you were actually to visit this link in your browser, you would get the info.json response for that image.)

    The manifest continues above...

    canvases": [
        {
        "@type": "sc:Canvas",
        "@id": "https://vault.library.uvic.ca/concern/generic_works/1a597e67-17a8-4c97-9c63-c835a41f5474/manifest/canvas/0a4d3d9f-210a-47be-b89d-a627ea4c570f",
        "label": "20_ORP.021.tif",
        "width": 3184,
        "height": 5232,
        "images": [
            {
                "@type": "oa:Annotation",
                "motivation": "sc:painting",
                "resource": {
                "@type": "dctypes:Image",
                "@id": "https://vault.library.uvic.ca/downloads/0a4d3d9f-210a-47be-b89d-a627ea4c570f",
                "height": 5232,
                "width": 3184,
                "format": "jpg",
                "service": {
                    "@context": "http://iiif.io/api/image/2/context.json",
                    "@id": "https://vault.library.uvic.ca/images/0a4d3d9f-210a-47be-b89d-a627ea4c570f%2Ffiles%2Fde77c7a9-77fb-4d9e-aa54-87b51b16fd1f",
                    "profile": "http://iiif.io/api/image/2/level2.json"

    The manifest continues below...

Paste this @id into our browser (but don't hit Enter or visit the link).
Use the size parameter to change the image's size to what we want. For example, to request the full image at its full/maximum size, we would add "/full/full/0/default.jpg" to the end. So the link to the full image is https://vault.library.uvic.ca/images/0a4d3d9f-210a-47be-b89d-a627ea4c570f%252Ffiles%252Fde77c7a9-77fb-4d9e-aa54-87b51b16fd1f/full/full/0/default.jpg.

As another example, for a thumbnail of the full image that is 150px wide, we would add "/full/150,/0/default.jpg" to the end instead. Some more examples of image requests are below:

Request:
/full/,100/0/default.jpg

The image file that would be returned by the stated request to the Image API. The image is a small thumbnail of an illustrated letter from the William Orpen collection in Vault. — Result: **61px by 100px**

Request:
/full/200,200/0/default.jpg

The image file that would be returned by the stated request to the Image API. Because the width and height in the request do not match the aspect ratio of the original, full image, the result looks squashed vertically. The image is an illustrated letter from the William Orpen collection in Vault. — Result: **200px by 200px**

Request:
/full/!300,600/0/default.jpg

The image file that would be returned by the stated request to the Image API. Since the dimensions are expressed as maximum values (300 pixels by 600 pixels), the image retains its original aspect ratio and fills the indicated space without overflowing. The image is an illustrated letter from the William Orpen collection in Vault. — Result: **300px by 493px**

The official IIIF documentation contains more visual examples of requests and their results.

"Cropping" images using IIIF

To display a specific part or region of an image without IIIF, we would need to download the full image, crop the image manually, and save a new copy. However, if we want to display the image on the web using IIIF, we can use the Image API to request/display a specific region or area of the image, without needing to save the result as a new image or overwriting the original.

As an example, we'll use the following image of Robin Hopper's nickel glaze tests, which is featured in UVic's Spotlight exhibit, University of Victoria Libraries Publication Series.

A series of multi-coloured ceramic tiles laid out in a 5 by 6 grid.

Find the item's manifest page (see detailed instructions for finding a Spotlight manifest).
Follow steps 2-4 for the previous section above to get the @id attribute of the web service. For our example, this @id is https://exhibits.library.uvic.ca/images/14862-24c186a1fac33deb92d0dbed4239cac4.
Use the region parameter to specify the region of the image that you want. For example, we could get the first two rows of tiles by appending the following request to the @id attribute:

An image showing the first two rows of tiles from the grid described in the previous image. — Human translation of the request: "Give me an image that is 600 pixels wide by 400 pixels tall (maximum). It should be an area that is 2176 x 1000 pixels of the original image, counting from the top left corner (0 pixels from the left edge, 0 pixels from the top edge)."

Note that the region is defined in reference to the full image (2176 px wide by 2906 px high), and not in reference to the size of the image that you're ultimately requesting. The max dimensions of the image are defined in the resource section of a manifest, or in the info.json for an image resource. The IIIF documentation contains a more detailed diagram of how the region is calculated.

Here are 3 more examples of image requests that use the region parameter to "crop" a specific tile:

Request:
/1290,2350,400,400
/!200,200/0/default.jpg The result/response to the image request above: a green tile with a bumpy texture, which is part of the tile grid in the original image.

The result/response to the image request above: a green tile with a bumpy texture, which is part of the tile grid in the original image.

Request:
/900,1900,400,400
/!200,200/0/default.jpg The result/response to the image request above: a yellow tile with a fuzzy white pattern. It is part of the tile grid in the original image.

The result/response to the image request above: a yellow tile with a fuzzy white pattern. It is part of the tile grid in the original image.

Request:
/500,1450,400,400
/!200,200/0/default.jpg The result/response to the image request above: a blue tile with a chevron pattern. It is part of the tile grid in the original image. A leaf is etched into the tile's surface.

The result/response to the image request above: a blue tile with a chevron pattern. It is part of the tile grid in the original image. A leaf is etched into the tile's surface.