31:[] 2f:{"title":"IDs and URIs in Allmaps","cells":[{"id":0,"value":"# IDs and URIs in Allmaps","pinned":false,"hidden":false,"mode":"md"},{"id":421,"value":"Allmaps can georeference and warp any map that’s available through IIIF.\nAllmaps stores and accesses georeference data based on the URIs of IIIF resources like [Manifests](https://iiif.io/api/presentation/3.0/#52-manifest) and [Images](https://iiif.io/api/image/3.0/).","pinned":false,"hidden":false,"mode":"md"},{"id":81,"value":"In this notebook, we’ll use the following IIIF Manifest:","pinned":false,"hidden":false,"mode":"md"},{"id":82,"value":"manifestUrl = \"https://www.loc.gov/item/88695674/manifest.json\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":544,"value":"Open this manifest in [Mirador](https://projectmirador.org/embed/?manifest=${manifestUrl}).","pinned":false,"hidden":false,"mode":"md"},{"id":56,"value":"We can fetch this URL and see its JSON contents:","pinned":false,"hidden":false,"mode":"md"},{"id":67,"value":"manifest = fetch(manifestUrl).then((response) => response.json())","pinned":false,"hidden":false,"mode":"ojs"},{"id":89,"value":"The URI of the Manifest can be found in its `id` field (in version 2 of the IIIF Presentation API, the `@id` field is used instead):","pinned":false,"hidden":false,"mode":"md"},{"id":95,"value":"manifestUri = manifest['@id'] || manifest['id']","pinned":false,"hidden":false,"mode":"ojs"},{"id":69,"value":"The `@allmaps/iiif-parser` module can parse IIIF data:","pinned":false,"hidden":false,"mode":"md"},{"id":60,"value":"parsedManifest = iiifParser.Manifest.parse(manifest)","pinned":false,"hidden":false,"mode":"ojs"},{"id":103,"value":"This manifest consists of ${parsedManifest.canvases.length} canvas and 1 image:","pinned":false,"hidden":false,"mode":"md"},{"id":31,"value":"

\n \n

","pinned":false,"hidden":false,"mode":"html"},{"id":122,"value":"parsedImageWithMap = parsedManifest.canvases[imageWithMapIndex].image","pinned":false,"hidden":false,"mode":"ojs"},{"id":442,"value":"The same image, a bit larger. We can see that this image contains __two__ maps.","pinned":false,"hidden":false,"mode":"md"},{"id":121,"value":"

","pinned":false,"hidden":false,"mode":"html"},{"id":451,"value":"The components of Allmaps function by passing IIIF URIs in their URLs. To georeference the map above, we can open [Allmaps Editor](https://editor.allmaps.org/#/collection?url=${manifestUri}) and pass the URI of the Manifest:\n\nhttps://editor.allmaps.org/#/collection?url=${manifestUri}","pinned":false,"hidden":false,"mode":"md"},{"id":471,"value":"We can also use the Image URI of the ${imageWithMapIndex + 1}th image instead of the Manifest URI:","pinned":false,"hidden":false,"mode":"md"},{"id":145,"value":"imageUri = parsedImageWithMap.uri","pinned":false,"hidden":false,"mode":"ojs"},{"id":462,"value":"We can use this Image URI to open the map in [Allmaps Editor](https://editor.allmaps.org/#/collection?url=${imageUri}/info.json):\n\nhttps://editor.allmaps.org/#/collection?url=${imageUri}/info.json\n\n(In the current version of Allmaps Editor, we need to append `info.json` to the Image URI.)","pinned":false,"hidden":false,"mode":"md"},{"id":138,"value":"__Each IIIF manifest can contain multiple IIIF images, and each IIIF image can contain multiple maps:__","pinned":false,"hidden":false,"mode":"md"},{"id":11,"value":"dot`digraph {\n node [shape=box];\n\n edge [\n arrowhead=\"inv\"\n ];\n\n rankdir=LR;\n \"IIIF Manifest\" -> \"IIIF Canvas\" -> \"IIIF Image\" -> Map; \n}`","pinned":false,"hidden":false,"mode":"ojs"},{"id":611,"value":"## Computing short identifiers from IIIF URIs","pinned":false,"hidden":false,"mode":"md"},{"id":508,"value":"To make the components of Allmaps easier to use and the data easier to store in a database, the the [SHA-1](https://en.wikipedia.org/wiki/SHA-1) hash function is used to turn IIIF URIs into 16-character __Allmaps IDs__.","pinned":false,"hidden":false,"mode":"md"},{"id":624,"value":"Long IIIF URI:\n\n```js\n\"${manifestUri}\"\n```\n\nIts Allmaps ID, the first 16 characters of the SHA-1 hash of the URI:\n\n```js\n\"${manifestId}\"\n```\n\nAllmaps uses its [`@allmaps/id`](https://observablehq.com/@allmaps/the-allmaps-id-module) module to compute these identifiers:","pinned":false,"hidden":false,"mode":"md"},{"id":21,"value":"manifestId = allmapsId.generateId(manifestUri)","pinned":true,"hidden":false,"mode":"ojs"},{"id":6,"value":"imageId = allmapsId.generateId(imageUri)","pinned":true,"hidden":false,"mode":"ojs"},{"id":231,"value":"`@allmaps/id` can be used to generate Allmaps IDs from any URI. For more details about the module, see [this Observable notebook](https://observablehq.com/@allmaps/the-allmaps-id-module). `@allmaps/id` is a JavaScript module that can be used in browsers and with Node.js. This notebook loads and uses this module as well, see the [Imports & constants](#cell-45) section.","pinned":false,"hidden":false,"mode":"md"},{"id":609,"value":"## Using the Allmaps API to retrieve georeference data","pinned":false,"hidden":false,"mode":"md"},{"id":499,"value":"After georeferencing a IIIF Manifest or Image with Allmaps Editor, the georeference data is stored in the Allmaps API. If you know the Allmaps ID of a IIIF resource, you can access its georeference data:","pinned":false,"hidden":false,"mode":"md"},{"id":373,"value":"annotationUrl = `https://annotations.allmaps.org/manifests/${manifestId}`","pinned":true,"hidden":false,"mode":"ojs"},{"id":164,"value":"annotation = fetch(annotationUrl).then((response) => response.json())","pinned":true,"hidden":false,"mode":"ojs"},{"id":487,"value":"You can open this annotation in a new tab to see the complete contents.","pinned":false,"hidden":false,"mode":"md"},{"id":504,"value":"The pixel masks of the two maps in the georeferenced image:","pinned":false,"hidden":false,"mode":"md"},{"id":296,"value":"","pinned":false,"hidden":false,"mode":"html"},{"id":396,"value":"[Allmaps Viewer](https://viewer.allmaps.org/?url=${annotationUrl}) can warp IIIF maps real-time in the browser with WebGL. This works by passing the URL of a Georeference Annotation:\n\nhttps://viewer.allmaps.org/?url=${annotationUrl}","pinned":false,"hidden":false,"mode":"md"},{"id":690,"value":"## Using the Allmaps API by using a IIIF URI","pinned":false,"hidden":false,"mode":"md"},{"id":731,"value":"It's also possible to use the Allmaps API to compute the Allmaps ID and redirect you to the Georeference Annotation:","pinned":false,"hidden":false,"mode":"md"},{"id":704,"value":"annotationUrlByIIIFUri = `https://annotations.allmaps.org/?url=${manifestUri}`","pinned":false,"hidden":false,"mode":"ojs"},{"id":706,"value":"annotationByIIIFUri = fetch(annotationUrlByIIIFUri).then((response) =>\n response.json()\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":166,"value":"This also works for URIs of IIIF Images (without `info.json`).","pinned":false,"hidden":false,"mode":"md"},{"id":388,"value":"## Computed data","pinned":false,"hidden":false,"mode":"md"},{"id":152,"value":"maps = annotationParser.parseAnnotation(annotation)","pinned":false,"hidden":false,"mode":"ojs"},{"id":361,"value":"mapCenters = maps.map((map) => turf.center(turf.polygon([[...map.pixelMask, map.pixelMask[0]]])).geometry.coordinates)","pinned":false,"hidden":false,"mode":"ojs"},{"id":45,"value":"## Imports & constants","pinned":false,"hidden":false,"mode":"md"},{"id":417,"value":"imageWithMapIndex = 0","pinned":false,"hidden":false,"mode":"ojs"},{"id":530,"value":"mapIndex = 1","pinned":false,"hidden":false,"mode":"ojs"},{"id":248,"value":"tileWidth = Math.round(width / columns) * 2","pinned":false,"hidden":false,"mode":"ojs"},{"id":255,"value":"columns = 5","pinned":false,"hidden":false,"mode":"ojs"},{"id":117,"value":"","pinned":false,"hidden":false,"mode":"html"},{"id":220,"value":"turf = require('@turf/turf')","pinned":false,"hidden":false,"mode":"ojs"},{"id":657,"value":"annotationParser = import(\n \"https://cdn.skypack.dev/@allmaps/annotation@1.0.0-beta.5\"\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":26,"value":"iiifParser = import('@allmaps/iiif-parser@1.0.0-beta.4')","pinned":false,"hidden":false,"mode":"ojs"},{"id":24,"value":"allmapsId = import('https://cdn.skypack.dev/@allmaps/id@1.0.0-beta.5')","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W31","stdlib":"1","titling":"auto"}