more_fun_with_iiif.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# More fun with IIIF\n",
    "\n",
    "[IIIF](https://iiif.io/) (the International Image Interoperability Framework) has defined a set of standards for publishing and using image collections. The State Library of Victoria makes many of its images available from an IIIF-compliant server. This means you can access and manipulate the images in standard ways set out by the [IIIF Image API](https://iiif.io/api/image/2.1/). This notebook demonstrates some of the possibilities.\n",
    "\n",
    "There are more details about the [default image](http://handle.slv.vic.gov.au/10381/25896) used in this notebook on the SLV site. If you would like to try these examples with another image, just go to the image in the SLV viewer. Underneath the image, you'll see a box like this. Select the IIIF tab, copy the url, then paste it in the cell below.\n",
    "\n",
    "![IIIF link box in image viewer](images/iiif-link.png)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Replace with another IIIF link if you want!\n",
    "manifest_url = 'https://rosetta.slv.vic.gov.au/delivery/iiif/presentation/2.1/IE1164978/manifest'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-warning\">\n",
    "<p>If you haven't used one of these notebooks before, they're basically web pages in which you can write, edit, and run live code. They're meant to encourage experimentation, so don't feel nervous. Just try running a few cells and see what happens!</p>\n",
    "\n",
    "<p>\n",
    "    Some tips:\n",
    "    <ul>\n",
    "        <li>Code cells have boxes around them.</li>\n",
    "        <li>To run a code cell click on the cell and then hit <b>Shift+Enter</b>. The <b>Shift+Enter</b> combo will also move you to the next cell, so it's a quick way to work through the notebook.</li>\n",
    "        <li>While a cell is running a <b>*</b> appears in the square brackets next to the cell. Once the cell has finished running the asterix will be replaced with a number.</li>\n",
    "        <li>In most cases you'll want to start from the top of notebook and work your way down running each cell in turn. Later cells might depend on the results of earlier ones.</li>\n",
    "        <li>To edit a code cell, just click on it and type stuff. Remember to run the cell once you've finished editing.</li>\n",
    "    </ul>\n",
    "</p>\n",
    "\n",
    "<p><b>Is this thing on?</b> If you can't edit or run any of the code cells, you might be viewing a static (read only) version of this notebook. Click here to <a href=\"https://mybinder.org/v2/gh/GLAM-Workbench/state-library-victoria/master?urlpath=lab/tree/more_fun_with_iiif.ipynb\">load a <b>live</b> version</a> running on Binder.</p>\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Important note\n",
    "\n",
    "In order to access an image from the SLV's IIIF server, you need to have set a cookie in your browser by loading the IIIF manifest (that's the link provided by the image viewer). That's fine if you're just playing around in your browser, although it means you can't share a link to a derivative image, or embed it in another page. It also means that if you're building some sort of processing pipeline, you need to create a session to store the cookie value in and load the manifest to set the cookie, before requesting any images. This notebook uses `requests.Session()` to handle this.\n",
    "\n",
    "If they want people to make full use of their IIIF service, the SLV should really change this."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setting things up"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests\n",
    "import re\n",
    "import ipywidgets as widgets\n",
    "from pathlib import Path\n",
    "from IPython.display import display, HTML"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "def get_image_ids(manifest):\n",
    "    '''\n",
    "    Extract a list of image @ids from an IIIF manifest\n",
    "    '''\n",
    "    image_ids = []\n",
    "    # There can be multiple images in a record\n",
    "    # So we loop through the canvases to get each one.\n",
    "    for canvas in manifest['sequences'][0]['canvases']:\n",
    "        image_ids.append(canvas['images'][0]['resource']['service']['@id'])\n",
    "    return image_ids\n",
    "\n",
    "def display_image(image_url, feature):\n",
    "    '''\n",
    "    Download and display the requested derivative image\n",
    "    '''\n",
    "    # Get the pid from the link\n",
    "    pid = re.search(r'\\/IE(\\d+):', image_url).group(1)\n",
    "    # Construct a filename\n",
    "    filename = Path(f'images/slv-{pid}-{feature}.jpg')\n",
    "    # Download and save the image\n",
    "    response = s.get(image_url)\n",
    "    filename.write_bytes(response.content)\n",
    "    # Display the image\n",
    "    display(HTML(f'<a href=\"{filename}\"><img src=\"{filename}\"></a>'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Create a default session to use for image requests, and load the manifest to set the required cookie."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "https://rosetta.slv.vic.gov.au:443/cantaloupe/iiif/2/IE1164978:FL15631103.tif\n"
     ]
    }
   ],
   "source": [
    "# Here we're creating a session and loading the manifest to set the cookie we'll need to access images\n",
    "# All the requests below will use this session\n",
    "s = requests.Session()\n",
    "response = s.get(manifest_url)\n",
    "manifest = response.json()\n",
    "# Get the id of the first image in the manifest\n",
    "# We'll use this id in the examples\n",
    "image_id = get_image_ids(manifest)[0]\n",
    "print(image_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## IIIF image parameters"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A request for an image from an IIIF-compliant server includes the following parameters: **region**, **size**, **rotation**, **quality**, and **format**. The [downloading images notebook](download_image_from_iiif.ipynb) let you select the size and format, but here we'll explore the options in more depth.\n",
    "\n",
    "The parameters are supplied in the url you use to request an image. Here's a IIIF url with the default parameters.\n",
    "\n",
    "```\n",
    "https://rosetta.slv.vic.gov.au:443/cantaloupe/iiif/2/IE1164978:FL15631103.tif/full/max/0/default.jpg\n",
    "```\n",
    "\n",
    "Let's break it down:\n",
    "\n",
    "*  `full` – supply the complete image (not cropped or sliced)\n",
    "* `max` – supply the image at its largest possible size\n",
    "* `0` – supply the image with a rotation of 0 degrees\n",
    "* `default` – supply the image in its current quality (no colour changes)\n",
    "* `jpg` – supply the image in JPEG format\n",
    "\n",
    "All of these can be changed.\n",
    "\n",
    "Note that the transformations are applied in the order they're supplied in the url. So if you specify a region and a size, the region will be selected from the full image and then resized."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<a href=\"images/slv-1164978-full.jpg\"><img src=\"images/slv-1164978-full.jpg\"></a>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# For easy display we're asking for a maximum width of 300 pixels\n",
    "image_url = f'{image_id}/full/300,/0/default.jpg'\n",
    "display_image(image_url, 'full')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Select a region\n",
    "\n",
    "We can ask for just part of the image to be returned.\n",
    "\n",
    "If we want a square, centered image, we can just use the `square` value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<a href=\"images/slv-1164978-square.jpg\"><img src=\"images/slv-1164978-square.jpg\"></a>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# For easy display we're asking for a maximum width of 300 pixels\n",
    "image_url = f'{image_id}/square/300,/0/default.jpg'\n",
    "display_image(image_url, 'square')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For more control, we can specify a region using coordinates. Let's ask for the top left corner of the image.\n",
    "\n",
    "Here we specify the `x` and `y` coordinates of the top left-hand corner of our selection, followed by the required `width` and `height`. So to get a 1000 x 200 pixel slice, starting at the top left of the image, we want `0,0,1000,200`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<a href=\"images/slv-1164978-region.jpg\"><img src=\"images/slv-1164978-region.jpg\"></a>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "image_url = f'{image_id}/0,0,1000,200/max/0/default.jpg'\n",
    "display_image(image_url, 'region')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the manifest includes the full image dimensions, so you could retrieve and use them in your selections.\n",
    "\n",
    "We can also specify a region using percentages rather than pixel numbers. So if we want the centre of the image we could try `pct:46,46,8,8`, which will select a region that's 8% of the width and height of the original, starting at a point that's 46% of the distance from the top and left."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<a href=\"images/slv-1164978-region-pct.jpg\"><img src=\"images/slv-1164978-region-pct.jpg\"></a>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "image_url = f'{image_id}/pct:46,46,8,8/max/0/default.jpg'\n",
    "display_image(image_url, 'region-pct')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Specify a size\n",
    "\n",
    "We've already seen this in action. Just specify a width, a height, or both (in pixels). If you supply both, the aspect ratio will probably get screwed up. You can prevent this by adding a `!` before the parameters – this will maintain the aspect ratio, while returning an image within the prescribed dimension.\n",
    "\n",
    "So to to create a thumbnail with a maximum dimension of 200 px, we can use `!200,200`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<a href=\"images/slv-1164978-size.jpg\"><img src=\"images/slv-1164978-size.jpg\"></a>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "image_url = f'{image_id}/full/!200,200/0/default.jpg'\n",
    "display_image(image_url, 'size')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also supply a percentage. So for an image that's 10% of the original, we'd specify `pct:10`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<a href=\"images/slv-1164978-size-pct.jpg\"><img src=\"images/slv-1164978-size-pct.jpg\"></a>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "image_url = f'{image_id}/full/pct:10/0/default.jpg'\n",
    "display_image(image_url, 'size-pct')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Rotate and reflect the image\n",
    "\n",
    "The third parameter is just the number of degrees the image should be rotated by. Let's rotate by 45 degrees."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<a href=\"images/slv-1164978-rotate.jpg\"><img src=\"images/slv-1164978-rotate.jpg\"></a>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# For easy display we're asking for a maximum width of 300 pixels\n",
    "# We're also asking for the result as a PNG, so that the background is transparent\n",
    "image_url = f'{image_id}/full/300,/45/default.png'\n",
    "display_image(image_url, 'rotate')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we add a `!` at the start the image is also reflected. So to just reverse the image we can use `!0`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<a href=\"images/slv-1164978-reflect.jpg\"><img src=\"images/slv-1164978-reflect.jpg\"></a>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# For easy display we're asking for a maximum width of 300 pixels\n",
    "image_url = f'{image_id}/full/300,/!0/default.jpg'\n",
    "display_image(image_url, 'reflect')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Back to front and upside down!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<a href=\"images/slv-1164978-rotate-reflect.jpg\"><img src=\"images/slv-1164978-rotate-reflect.jpg\"></a>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# For easy display we're asking for a maximum width of 300 pixels\n",
    "image_url = f'{image_id}/full/300,/!180/default.jpg'\n",
    "display_image(image_url, 'rotate-reflect')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Change the quality\n",
    "\n",
    "The quality parameter specifies whether the image is delivered as color, grayscale or black and white. Let's try converting to a bitonal (black and white) image."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<a href=\"images/slv-1164978-bitonal.jpg\"><img src=\"images/slv-1164978-bitonal.jpg\"></a>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# For easy display we're asking for a maximum width of 300 pixels\n",
    "image_url = f'{image_id}/full/300,/0/bitonal.jpg'\n",
    "display_image(image_url, 'bitonal')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Change the format\n",
    "\n",
    "To change the format of the image, just change the file extension at the end of the url. So to get a JPEG:\n",
    "\n",
    "```\n",
    "https://rosetta.slv.vic.gov.au:443/cantaloupe/iiif/2/IE1164978:FL15631103.tif/full/max/0/default.jpg\n",
    "```\n",
    "\n",
    "or a TIFF:\n",
    "\n",
    "```\n",
    "https://rosetta.slv.vic.gov.au:443/cantaloupe/iiif/2/IE1164978:FL15631103.tif/full/max/0/default.tif\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----\n",
    "\n",
    "Created by [Tim Sherratt](https://timsherratt.org) for the [GLAM Workbench](https://glam-workbench.github.io/).\n",
    "\n",
    "If you find this useful, please consider supporting my work on [Patreon](https://www.patreon.com/timsherratt)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}