cozy-iiif 0.1.5 → 0.2.0

package/README.md

@@ -1,16 +1,15 @@
 # cozy-iiif
 
-**WORK IN PROGRESS**
-
-A developer-friendly collection of abstractions and utilities built on top of the IIIF Commons [@iiif/presentation-3](https://github.com/IIIF-Commons/presentation-3-types) and [@iiif/parser](https://github.com/IIIF-Commons/parser) libraries.
+A developer-friendly API for working with IIIF resources. Built on top of the IIIF Commons [@iiif/presentation-3](https://github.com/IIIF-Commons/presentation-3-types) and [@iiif/parser](https://github.com/IIIF-Commons/parser) libraries.
 
 ## Features
 
-- Resource identification for any URL: IIIF manifests, manifest, image services, static image, and more.
+- Resource identification for any URL: IIIF collection and presentation manifests, image services, static image, and more.
 - Developer-friendly TypeScript API for parsing and working with IIIF resources.
-- Seamless upgrade from IIIF Presentation API v2 to v3 using `@iiif/parser/`.
+- Seamless upgrade from IIIF Presentation API v2 to v3 (using `@iiif/parser` under the hood).
 - Preserves access to underlying `@iiif-presentation/3` types.
-- Provides helpers for stitching thumbnails and cropping regions from IIIF Level 0 tilesets.
+- Helpers for stitching thumbnails and cropping regions from IIIF Level 0 tilesets.
+- Helpers for adding annotations to Canvases and Presentation manifests.
 
 ## Installation
 
@@ -20,11 +19,192 @@ npm install cozy-iiif
 
 ## Basic Usage
 
-Todo...
+Identify and parse a URL:
+
+```ts
+import { Cozy } from 'cozy-iiif';
+
+const parsed = await Cozy.parseURL('https://www.example.com/manifest.json');
+
+if (parsed.type === 'manifest') {
+  const manifest = parsed.resource; // CozyManifest
+  console.log(`Presentation API ${manifest.majorVersion}`);
+} else if (parsed.type === 'collection') {
+  const collection = parsed.resource; // CozyCollection
+  console.log(`Collection, Presentation API ${collection.majorVersion}`);
+} else if (parsed.type === 'iiif-image') {
+  const image = parsed.resource; // CozyImageResource
+  console.log(`Image API ${image.majorVersion}`);
+} else if (parsed.type === 'plain-image') {
+  console.log('Plaing (JPEG or PNG) image');
+} else if (parsed.type === 'webpage') {
+  console.log('URL points to a web page!');
+} else if (parsed.type === 'error') {
+  console.log('Error:', parsed.code, parsed.message);
+}
+```
+
+Alternatively, you can parse an existing JSON object.
+
+```ts
+const json = await fetch('https://www.example.com/manifest.json').then(res => res.json());
+Cozy.parse(json);
+```
+
+Cozy provides normalized utility types for key IIIF entities: **CozyManifest**, 
+**CozyCanvas**, **CozyRange**, **CozyImageResource**, **CozyCollection**, etc. Each
+utility type provides helpers to simplify common access operations (e.g. metadata, 
+labels in different locales, etc.) and retains the original source data
+as a `source` field.
+
+```ts
+// Parsed CozyManifest
+const manifest = parsed.resource;
+
+// Default
+console.log(manifest.getLabel()); 
+
+// For locale (with fallback)
+console.log(manifest.getLabel('de'));
+
+// Metadata as normalized CozyMetada[]
+console.log(manifest.getMetadata());
+```
+
+### Thumbnail Helper
+
+CozyCanvas has a simple helper for getting a Thumbnail URL. The URL
+will use the `thumbnail` property if available, or the image service
+otherwise.
+
+```ts
+const firstCanvas = manifest.canvases[0];
+
+// With default size (400px smallest dimension)
+console.log(firstCanvas.getThumbnailURL());
+
+// With custom minimum smallest dimension
+console.log(firstCanvas.getThumbnailURL(600));
+```
+
+### Table of Contents Helper
+
+cozy-iiif includes a utility to easily get a table of contents for a Presentation manifest,
+based on the manifest's `structures` property.
+
+```ts
+// Returns a list of CozyTOCNode objects.
+const root = manifest.getTableOfContents(); 
+
+const logTOCNode = (node: CozyTOCNode) => {
+  console.log(node.getLabel());
+  node.children.forEach(logTOCNode);
+}
+    
+root.forEach(logTOCNode);
+```
+
+### Working with different Image Types and Levels
+
+The **CozyImageResource** type provides a helper property for identify the type and level of 
+an image.
 
-## API
+```ts
+const firstCanvas = manifest.canvases[0];
+const image = firstCanvas.images[0];
 
-Todo...
+console.log(image.type); // 'static', 'dynamic' or 'level0';
+```
+
+Dynamic images are served from an image server and have helpers to retrieve specific region URLs.
+
+```ts
+const bounds = {
+  x: 100,
+  y: 100,
+  w: 320,
+  h: 240
+};
+
+// With default minimum shortest dimension (400px);
+console.log(image.getRegionURL(bounds));
+
+// With custom minimum shorted dimension
+console.log(image.getRegionURL(bounds, 800));
+```
+
+## Cozy Helpers
+
+### Stitching and Cropping for Level 0 Tilesets
+
+Working with a Level 0 tileset, but need a thumbnail, or crop a region? The `cozy-iiif/level-0` module 
+has you covered! Cozy uses Web workers for background image processing and request throttling when 
+harvesting tilesets for stitching. Stitched images are harvested at the smallest possible size, 
+to keep things fast and prevent unnecessary downloads.
+
+
+**Thumbnails**
+
+```ts
+import { getThumbnail } from 'cozy-iiif/level-0';
+
+const firstImage = canvas.images[0];
+if (firstImage.type !== 'level0') {
+  // Normal thumbnail URL (string)
+  console.log(canvas.getThumbnailURL());
+} else {
+  getThumbnail(firstImage).then(blob => {
+    // Creates a data URL you can use as `src` for an image
+    console.log(URL.createObjectURL(blob));
+  });
+}
+```
+
+**Regions**
+
+```ts
+import { cropRegion } from 'cozy-iiif/level-0';
+
+const firstImage = canvas.images[0];
+
+const bounds = {
+  x: 100,
+  y: 100,
+  w: 320,
+  h: 240
+};
+
+if (firstImage.type === 'level0') {
+  cropRegion(firstImage, bounds).then(blob => {
+    console.log(URL.createObjectURL(blob));
+  });
+}
+```
+
+### Annotation Helpers
+
+Utilities for working with annotations on on Canvases.
+
+```ts
+import type { Annotation } from '@iiif/presentation-3';
+import { importAnnotations } from 'cozy-iiif/helpers';
+
+const annotations: Annotation[] = [{
+  id: 'https://iiif.io/api/cookbook/recipe/0021-tagging/annotation/p0002-tag',
+  type: 'Annotation',
+  motivation: 'tagging',
+  body: {
+    type: 'TextualBody',
+    value: 'Gänseliesel-Brunnen',
+    language: 'de',
+    format: "text/plain"
+  },
+  target: 'https://iiif.io/api/cookbook/recipe/0021-tagging/canvas/p1#xywh=265,661,1260,1239'
+}]
+
+// Generates a new CozyManifest with annotations from an original CozyManifest.
+const updated = importAnnotations(original, annotations);
+```
 
 ## License
 

package/dist/Cozy.d.ts

@@ -1,4 +1,5 @@
 import { CozyParseResult } from './types';
 export declare const Cozy: {
+    parse: (json: any, url?: string) => CozyParseResult;
     parseURL: (input: string) => Promise<CozyParseResult>;
 };

package/dist/helpers/import-annotations.d.ts

@@ -0,0 +1,3 @@
+import { Annotation } from '@iiif/presentation-3';
+import { CozyCanvas, CozyManifest } from '../types';
+export declare const importAnnotations: <T extends CozyManifest | CozyCanvas>(resource: T, annotations: Annotation[], namespace?: string) => T extends CozyCanvas ? CozyCanvas : CozyManifest;

package/dist/helpers/index.d.ts

@@ -0,0 +1 @@
+export * from './import-annotations';

package/dist/helpers/index.js

@@ -0,0 +1,93 @@
+const n = [];
+for (let t = 0; t < 256; ++t)
+  n.push((t + 256).toString(16).slice(1));
+function h(t, e = 0) {
+  return (n[t[e + 0]] + n[t[e + 1]] + n[t[e + 2]] + n[t[e + 3]] + "-" + n[t[e + 4]] + n[t[e + 5]] + "-" + n[t[e + 6]] + n[t[e + 7]] + "-" + n[t[e + 8]] + n[t[e + 9]] + "-" + n[t[e + 10]] + n[t[e + 11]] + n[t[e + 12]] + n[t[e + 13]] + n[t[e + 14]] + n[t[e + 15]]).toLowerCase();
+}
+let p;
+const m = new Uint8Array(16);
+function y() {
+  if (!p) {
+    if (typeof crypto > "u" || !crypto.getRandomValues)
+      throw new Error("crypto.getRandomValues() not supported. See https://github.com/uuidjs/uuid#getrandomvalues-not-supported");
+    p = crypto.getRandomValues.bind(crypto);
+  }
+  return p(m);
+}
+const b = typeof crypto < "u" && crypto.randomUUID && crypto.randomUUID.bind(crypto), c = { randomUUID: b };
+function x(t, e, i) {
+  var d;
+  if (c.randomUUID && !t)
+    return c.randomUUID();
+  t = t || {};
+  const u = t.random ?? ((d = t.rng) == null ? void 0 : d.call(t)) ?? y();
+  if (u.length < 16)
+    throw new Error("Random bytes length must be >= 16");
+  return u[6] = u[6] & 15 | 64, u[8] = u[8] & 63 | 128, h(u);
+}
+const a = (t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), U = (t, e) => {
+  if (e) {
+    const i = t.annotations;
+    if (i.length > 0) {
+      const u = new RegExp(`${a(t.id)}/${a(e)}/page/p(\\d+)$`), d = i.reduce((s, o) => {
+        const r = o.id.match(u);
+        if (r && r[1]) {
+          const g = parseInt(r[1]);
+          return Math.max(s, g);
+        } else
+          return s;
+      }, 1);
+      return `${t.id}/${e}/annotations/page/p${d}`;
+    } else
+      return `${t.id}/${e}/annotations/page/p1`;
+  } else
+    return `${t.id}/annotations/page/${x()}`;
+}, l = (t, e, i) => {
+  const u = {
+    id: U(t, i),
+    type: "AnnotationPage",
+    items: e
+  };
+  return {
+    source: {
+      ...t.source,
+      annotations: [...t.annotations, u]
+    },
+    id: t.id,
+    width: t.width,
+    height: t.height,
+    images: [...t.images],
+    annotations: [...t.annotations, u],
+    getLabel: t.getLabel,
+    getMetadata: t.getMetadata,
+    getThumbnailURL: t.getThumbnailURL
+  };
+}, $ = (t, e, i) => {
+  const u = (o) => {
+    const r = o.target;
+    if (r)
+      return typeof r == "string" ? r.substring(0, r.indexOf("#")) : r.source;
+  }, d = e.reduce((o, r) => {
+    const g = u(r);
+    return g && (o[g] || (o[g] = []), o[g].push(r)), o;
+  }, {}), s = t.canvases.map((o) => {
+    const r = d[o.id] || [];
+    return r.length > 0 ? l(o, r, i) : o;
+  });
+  return {
+    source: {
+      ...t.source,
+      items: s.map((o) => o.source)
+    },
+    id: t.id,
+    majorVersion: t.majorVersion,
+    canvases: s,
+    structure: t.structure,
+    getLabel: t.getLabel,
+    getMetadata: t.getMetadata,
+    getTableOfContents: t.getTableOfContents
+  };
+}, I = (t, e, i) => t.source.type === "Canvas" ? l(t, e, i) : $(t, e, i);
+export {
+  I as importAnnotations
+};