cozy-iiif 0.1.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "cozy-iiif",
+  "version": "0.1.0",
+  "description": "A developer-friendly collection of abstractions and utilities built on top of @iiif/presentation-3 and @iiif/parser",
+  "license": "MIT",
+  "author": "Rainer Simon",
+  "keywords": [
+    "IIIF"
+  ],
+  "homepage": "https://github.com/rsimon/cozy-iiif#readme",
+  "bugs": {
+    "url": "https://github.com/rsimon/cozy-iiif/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rsimon/cozy-iiif.git"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "vite build"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./level-0": "./dist/level-0/index.js"
+  },
+  "devDependencies": {
+    "vite": "^6.1.0",
+    "vite-plugin-dts": "^4.5.0"
+  },
+  "dependencies": {
+    "@iiif/parser": "^2.1.7",
+    "@iiif/presentation-3": "^2.2.3",
+    "p-throttle": "^7.0.0"
+  }
+}

package/src/Cozy.ts

@@ -0,0 +1,182 @@
+import { Canvas, Manifest } from '@iiif/presentation-3';
+import { convertPresentation2  } from '@iiif/parser/presentation-2';
+import { Traverse } from '@iiif/parser';
+import { CozyCanvas, CozyManifest, CozyParseResult, ImageServiceResource } from './types';
+import { 
+  getImages, 
+  getLabel, 
+  getMetadata, 
+  getPropertyValue, 
+  getThumbnailURL, 
+  normalizeServiceUrl, 
+  parseImageService 
+} from './core';
+
+export const Cozy = {
+  
+  parseURL: async (input: string): Promise<CozyParseResult> => {
+    try {
+      new URL(input);
+    } catch {
+      return {
+        type: 'error',
+        code: 'INVALID_URL',
+        message: 'The provided input is not a valid URL'
+      };
+    }
+
+    let response: Response;
+
+    try {
+      response = await fetch(input);
+      if (!response.ok) {
+        return {
+          type: 'error',
+          code: 'INVALID_HTTP_RESPONSE',
+          message: `Server responded: HTTP ${response.status} ${response.statusText ? `(${response.statusText})` : ''}`
+        }
+      }
+    } catch (error) {
+      return {
+        type: 'error',
+        code: 'FETCH_ERROR',
+        message: error instanceof Error ? error.message : 'Failed to fetch resource'
+      };
+    }
+
+    const contentType = response.headers.get('content-type');
+    
+    if (contentType?.startsWith('image/')) {
+      return {
+        type: 'plain-image',
+        url: input
+      };
+    }
+
+    if (contentType?.includes('text/html')) {
+      return {
+        type: 'webpage',
+        url: input
+      };
+    }
+
+    try {
+      const json = await response.json();
+
+      const context = Array.isArray(json['@context'])
+        ? json['@context'].find(str => str.includes('iiif.io/api/'))
+        : json['@context'];
+
+      if (!context) {
+        return {
+          type: 'error',
+          code: 'INVALID_MANIFEST', 
+          message: 'Missing @context'
+        }
+      };
+
+      const id = getPropertyValue<string>(json, 'id');
+
+      if (!id) {
+        return { 
+          type: 'error',
+          code: 'INVALID_MANIFEST', 
+          message: 'Missing id property' 
+        }
+      }
+
+      if (context.includes('presentation/2') || context.includes('presentation/3')) {
+        const majorVersion = context.includes('presentation/2') ? 2 : 3;
+
+        return {
+          type: 'manifest',
+          url: input,
+          resource: parseManifestResource(json, majorVersion)
+        };
+      }
+      
+      if (context.includes('image/2') || context.includes('image/3')) {
+        const resource = parseImageResource(json);
+        return resource ? {
+          type: 'iiif-image',
+          url: input,
+          resource
+        } : {
+          type: 'error',
+          code: 'INVALID_MANIFEST',
+          message: 'Invalid image service definition'
+        }
+      }
+
+      return {
+        type: 'error',
+        code: 'INVALID_MANIFEST',
+        message: 'JSON resource is not a recognized IIIF format'
+      };
+    } catch {
+      return {
+        type: 'error',
+        code: 'UNSUPPORTED_FORMAT',
+        message: 'Could not parse resource'
+      };
+    }
+
+  }
+
+}
+
+const parseManifestResource = (resource: any, majorVersion: number): CozyManifest => {
+
+  const parseV3 = (manifest: Manifest) => {
+    const canvases: Canvas[] = [];
+
+    const modelBuilder = new Traverse({
+      canvas: [canvas => { if (canvas.items) canvases.push(canvas) }]
+    });
+  
+    modelBuilder.traverseManifest(manifest);
+    
+    return canvases.map((c: Canvas) => {
+      const images = getImages(c);
+      return {
+        source: c,
+        id: c.id,
+        width: c.width,
+        height: c.height,
+        images,
+        getLabel: getLabel(c),
+        getMetadata: getMetadata(c),
+        getThumbnailURL: getThumbnailURL(c, images)
+      } as CozyCanvas;
+    });
+  }
+
+  const v3: Manifest = majorVersion === 2 ? convertPresentation2(resource) : resource;
+
+  const canvases = parseV3(v3);
+
+  return {
+    source: v3,
+    id: v3.id,
+    majorVersion,
+    canvases,
+    getLabel: getLabel(v3),
+    getMetadata: getMetadata(v3)
+  }
+}
+
+const parseImageResource = (resource: any) => {
+  const { width, height } = resource;
+
+  const service = parseImageService(resource);
+  if (service) {
+    return {
+      type: service.profileLevel === 0 ? 'level0' : 'dynamic',
+      service: resource,
+      width,
+      height,
+      majorVersion: service.majorVersion,
+      serviceUrl: normalizeServiceUrl(getPropertyValue<string>(resource, 'id'))
+    } as ImageServiceResource;
+  }
+}

package/src/core/canvas.ts

@@ -0,0 +1,107 @@
+import { Canvas, IIIFExternalWebResource } from '@iiif/presentation-3';
+import { Traverse } from '@iiif/parser';
+import { getPropertyValue } from './resource';
+import { getImageURLFromService, getRegionURL, isImageService, parseImageService } from './image-service';
+import { 
+  CozyImageResource, 
+  DynamicImageServiceResource, 
+  ImageServiceResource, 
+  Level0ImageServiceResource, 
+  StaticImageResource 
+} from '../types';
+
+export const getThumbnailURL = (canvas: Canvas, images: CozyImageResource[] = []) => (minSize = 400) => {
+  const { width, height } = canvas;
+
+  if (!width || !height) return;
+
+  const aspect = width / height;
+  const isPortrait = aspect < 1;
+  
+  const h = Math.ceil(isPortrait ? minSize / aspect : minSize);
+  const w = Math.ceil(isPortrait ? minSize : minSize / aspect);
+
+  if (canvas.thumbnail && canvas.thumbnail.length > 0) {
+    const thumbnail = canvas.thumbnail[0];
+
+    if ('service' in thumbnail && Array.isArray(thumbnail.service)) {
+      const service = thumbnail.service.find(s => isImageService(s));
+      if (service)
+        return getImageURLFromService(service, w, h);
+    }
+
+    if ('id' in thumbnail) return thumbnail.id;
+  }
+
+  for (const image of images) {
+    if (image.type === 'dynamic' || image.type === 'level0') {
+      return getImageURLFromService(image.service, w, h);
+    } else if (image.type === 'static') {
+      // console.warn('Static image canvas');
+      return image.url;
+    }    
+  }
+}
+
+export const normalizeServiceUrl = (url: string) =>
+  url.endsWith('/info.json') ? url : `${url.endsWith('/') ? url : `${url}/`}info.json`;
+
+const toCozyImageResource = (resource: IIIFExternalWebResource) => {
+  const { format, height, width } = resource;
+
+  const id = getPropertyValue(resource, 'id');
+
+  const imageService = (resource.service || []).find(isImageService);
+
+  const service = imageService ? parseImageService(imageService) : undefined; 
+  if (service) {
+    const image = {
+      source: resource,
+      type: service.profileLevel === 0 ? 'level0' : 'dynamic',
+      service: imageService,
+      width,
+      height,
+      majorVersion: service.majorVersion,
+      serviceUrl: normalizeServiceUrl(getPropertyValue<string>(imageService, 'id'))
+    } as ImageServiceResource;
+
+    if (service.profileLevel === 0) {
+      return image as Level0ImageServiceResource;
+    } else {
+      return {
+        ...image,
+        getRegionURL: getRegionURL(image)
+      } as DynamicImageServiceResource;
+    }
+  } else {
+    return {
+      source: resource,
+      type: 'static',
+      width,
+      height,
+      url: id,
+      format
+    } as StaticImageResource;
+  }
+} 
+
+export const getImages = (canvas: Canvas): CozyImageResource[] => {
+  const images: CozyImageResource[] = [];
+
+  const builder = new Traverse({
+    annotation: [anno => {
+      if (anno.motivation === 'painting') {
+        const bodies = anno.body ? 
+          Array.isArray(anno.body) ? anno.body : [anno.body] 
+          : [];
+
+        const imageResources = bodies.filter(b => (b as IIIFExternalWebResource).type === 'Image');
+        images.push(...imageResources.map(toCozyImageResource));
+      }
+    }]
+  });
+
+  builder.traverseCanvas(canvas);
+
+  return images;
+}

package/src/core/image-service.ts

@@ -0,0 +1,103 @@
+import { ImageService2, ImageService3, Service } from '@iiif/presentation-3';
+import { getPropertyValue } from './resource';
+import { Bounds, CozyImageResource } from '../types';
+
+type ImageService = ImageService2 | ImageService3;
+
+export const isImageService = (data: any): data is ImageService => {
+  const t = getPropertyValue<string>(data, 'type');
+  return t.startsWith('ImageService');
+}
+
+export const parseImageService = (service: Service) => {
+  const t = getPropertyValue<string>(service, 'type');
+  const context = getPropertyValue<string>(service, 'context');
+
+  if (t === 'ImageService2' || context?.includes('image/2')) {
+    const service2 = service as ImageService2;
+
+    const labels = ['level0', 'level1', 'level2'];
+    const profiles = Array.isArray(service2.profile) ? service2.profile : [service2.profile];
+
+    const levels = profiles
+      .map(profile => labels.findIndex(level => profile.toString().includes(level)))
+      .filter(l => l > -1)
+      .sort((a, b) => b - a); // Sort descending
+
+    return { majorVersion: 2, profileLevel: levels[0] };
+  } else if (t || context) {
+    // Image API 3
+    const service3 = service as ImageService3;
+    return { majorVersion: 3, profileLevel: parseInt(service3.profile)}
+  }
+}
+
+export const getImageURLFromService = (
+  service: ImageService2 | ImageService3,
+  width: number,
+  height: number
+): string => {
+  const id = getPropertyValue(service, 'id');
+
+  const compliance = service.profile || '';
+
+  const isLevel0 = typeof compliance === 'string' &&
+    (compliance.includes('level0') || compliance.includes('level:0'));
+  
+  if (isLevel0) {
+    // For level 0, find the closest pre-defined size
+    if ('sizes' in service && Array.isArray(service.sizes)) {
+      const suitableSize = service.sizes
+        .sort((a, b) => (b.width * b.height) - (a.width * a.height))
+        .filter(s => (s.width * s.height) >= width * height)[0];
+        
+      if (suitableSize)
+        return `${id}/full/${suitableSize.width},${suitableSize.height}/0/default.jpg`;
+    }
+
+    // Fallback: full image
+    return `${id}/full/full/0/default.jpg`;
+  }
+
+  return `${id}/full/!${width},${height}/0/default.jpg`;
+}
+
+export const getRegionURLFromService = (
+  service: ImageService2 | ImageService3,
+  bounds: Bounds,
+  minSize: number
+): string => {
+  const id = getPropertyValue(service, 'id');
+  const compliance = service.profile || '';
+
+  const isLevel0 = typeof compliance === 'string' &&
+    (compliance.includes('level0') || compliance.includes('level:0'));
+
+  // TODO
+  if (isLevel0) return;
+
+  const { x, y, w , h } = bounds;
+
+  const aspect = w / h;
+  const isPortrait = aspect < 1;
+  
+  const height = Math.ceil(isPortrait ? minSize / aspect : minSize);
+  const width = Math.ceil(isPortrait ? minSize : minSize / aspect);
+
+  const regionParam = `${Math.round(x)},${Math.round(y)},${Math.round(w)},${Math.round(h)}`;
+  return `${id}/${regionParam}/!${width},${height}/0/default.jpg`;
+}
+
+export const getRegionURL = (
+  image: CozyImageResource
+) => (
+  bounds: Bounds,
+  minSize = 400
+): string | undefined => {
+  if (image.type === 'dynamic') {
+    return getRegionURLFromService(image.service, bounds, minSize);
+  } else {
+    // TODO
+    console.error('Level 0 or static image canvas: unspported');
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,3 @@
+export * from './canvas';
+export * from './image-service';
+export * from './resource';

package/src/core/resource.ts

@@ -0,0 +1,41 @@
+import { InternationalString, MetadataItem } from '@iiif/presentation-3';
+import { CozyMetadata } from '../types';
+
+export const getPropertyValue = <T extends unknown = any>(data: any, name: string) => {
+  let prop: any = data[name];
+
+  if (!prop)
+    prop = data[`@${name}`];
+
+  return prop as T;
+}
+
+export const getStringValue = (propertyValue: string | InternationalString, locale = 'en') => {
+  if (typeof propertyValue === 'string') return propertyValue;
+  
+  const localized = propertyValue[locale];
+  if (localized) {
+    return localized[0];
+  } else {
+    const values = Object.values(propertyValue).reduce<string[]>((flattened, value) => {
+      return Array.isArray(value) ? [...flattened, ...value] : [...flattened, value]
+    }, []);
+
+    return values.length > 0 ? values[0] : undefined;
+  }
+}
+
+export const getLabel = (data: any) => (locale = 'en') => {
+  const propertyValue = getPropertyValue<string | InternationalString>(data, 'label');
+  return propertyValue ? getStringValue(propertyValue, locale) : undefined;
+} 
+
+export const getMetadata = (data: any) => (locale?: string): CozyMetadata[] => {
+  const metadata = getPropertyValue(data, 'metadata') as MetadataItem[];
+  if (!metadata) return [];
+
+  return metadata.map(({ label, value }) => ({
+    label: getStringValue(label, locale),
+    value: getStringValue(value, locale)
+  }));
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './core';
+export * from './types';
+export * from './Cozy';

package/src/level-0/crop-region.ts

@@ -0,0 +1,109 @@
+import { Bounds, Level0ImageServiceResource } from '../types';
+import { getThrottledLoader } from './throttled-loader';
+import { ImageInfo, Tile } from './types';
+
+const getTileUrl = (info: ImageInfo, bounds: Bounds): string => {
+  const { x, y, w, h } = bounds;
+  const tileWidth = info.tiles[0].width;
+  const tileHeight = info.tiles[0].height|| info.tiles[0].width;
+  return `${info['@id']}/${x * tileWidth},${y * tileHeight},${w},${h}/${tileWidth},/0/default.jpg`;
+}
+
+const getTilesForRegion = (info: ImageInfo, bounds: Bounds): Tile[] => {
+  const tileWidth = info.tiles[0].width;
+  const tileHeight = info.tiles[0].height || info.tiles[0].width; // fallback for square tiles
+  const maxWidth = info.width;
+  const maxHeight = info.height;
+
+  const startTileX = Math.floor(bounds.x / tileWidth);
+  const startTileY = Math.floor(bounds.y / tileHeight);
+  const endTileX = Math.ceil((bounds.x + bounds.w) / tileWidth);
+  const endTileY = Math.ceil((bounds.y + bounds.h) / tileHeight);
+
+  const tiles: Tile[] = [];
+  
+  for (let y = startTileY; y < endTileY; y++) {
+    for (let x = startTileX; x < endTileX; x++) {
+      // Skip tiles outside image bounds
+      if (x * tileWidth >= maxWidth || y * tileHeight >= maxHeight) {
+        continue;
+      }
+
+      // Calculate actual tile dimensions (might be smaller at edges)
+      const effectiveWidth = Math.min(tileWidth, maxWidth - (x * tileWidth));
+      const effectiveHeight = Math.min(tileHeight, maxHeight - (y * tileHeight));
+
+      tiles.push({
+        x,
+        y,
+        width: effectiveWidth,
+        height: effectiveHeight,
+        url: getTileUrl(info, { x, y, w: effectiveWidth, h: effectiveHeight })
+      });
+    }
+  }
+
+  return tiles;
+}
+
+export const cropRegion = async (resource: Level0ImageServiceResource, bounds: Bounds): Promise<Blob> => {
+  const info = await fetch(resource.serviceUrl).then(res => res.json());
+
+  const tiles = getTilesForRegion(info, bounds);
+  
+  const canvas = document.createElement('canvas');
+  const ctx = canvas.getContext('2d');
+  
+  if (!ctx)
+    // Should never happen
+    throw new Error('Error initializing canvas context');
+  
+  const tileWidth = info.tiles[0].width;
+  const tileHeight = info.tiles[0].height || info.tiles[0].width;
+
+  const tilesWidth = (Math.ceil(bounds.w / tileWidth) + 1) * tileWidth;
+  const tilesHeight = (Math.ceil(bounds.h / tileHeight) + 1) * tileHeight;
+
+  canvas.width = tilesWidth;
+  canvas.height = tilesHeight;
+
+  const loader = getThrottledLoader({ callsPerSecond: 20 });
+
+  // TODO implement polite harvesting!
+  await Promise.all(tiles.map(async (tile) => {
+    const img = await loader.loadImage(tile.url);
+    const x = (tile.x * tileWidth) - bounds.x;
+    const y = (tile.y * tileHeight) - bounds.y;
+    ctx.drawImage(img, x, y);
+  }));
+
+  const cropCanvas = document.createElement('canvas');
+  cropCanvas.width = bounds.w;
+  cropCanvas.height = bounds.h;
+
+  const cropCtx = cropCanvas.getContext('2d');
+  
+  if (!cropCtx)
+    throw new Error('Error initializing canvas context');
+
+  // Copy cropped region
+  cropCtx.drawImage(canvas, 
+    0, 0, bounds.w, bounds.h,
+    0, 0, bounds.w, bounds.h
+  );
+
+  return new Promise((resolve, reject) => {
+    cropCanvas.toBlob(
+      (blob) => {
+        if (blob) {
+          resolve(blob);
+        } else {
+          reject(new Error('Failed to create blob'));
+        }
+      },
+      'image/jpeg',
+      0.95
+    );
+  });
+
+}

package/src/level-0/get-thumbnail.ts

@@ -0,0 +1,113 @@
+import { Level0ImageServiceResource } from '../types';
+import { getThrottledLoader } from './throttled-loader';
+import { ImageInfo, Size, Tile } from './types';
+
+const getBestScaleFactor = (info: ImageInfo, minSize?: Partial<Size>): number => {
+  // Sort descending
+  const scaleFactors = info.tiles[0].scaleFactors.sort((a, b) => b - a); 
+  
+  if (!minSize) 
+    // Just return highest scale factor
+    return scaleFactors[0];
+
+  const scaleX = minSize.width ? info.width / minSize.width : Infinity;
+  const scaleY = minSize.height ? info.height / minSize.height : Infinity;
+
+  const scale = Math.min(scaleX, scaleY);
+
+  // Find the smallest scale factor that still meets our minimum size requirements
+  for (const factor of scaleFactors) {
+    if (factor <= scale)
+      return factor;
+  }
+
+  // If no scale factor is small enough, return the smallest available
+  return scaleFactors[scaleFactors.length - 1];
+};
+
+const getThumbnailDimensions = (info: ImageInfo, minSize?: Partial<Size>): Size => {
+  const scaleFactor = getBestScaleFactor(info, minSize);
+
+  let width = Math.ceil(info.width / scaleFactor);
+  let height = Math.ceil(info.height / scaleFactor);
+
+  if (minSize) {
+    const aspectRatio = info.width / info.height;
+    
+    if (minSize.width && width < minSize.width) {
+      width = minSize.width;
+      height = Math.ceil(width / aspectRatio);
+    }
+    
+    if (minSize.height && height < minSize.height) {
+      height = minSize.height;
+      width = Math.ceil(height * aspectRatio);
+    }
+  }
+
+  return { width, height };
+}
+
+const getThumbnailTiles = (info: ImageInfo, minSize?: Partial<Size>): Tile[] => {
+  const scaleFactor = getBestScaleFactor(info, minSize);
+
+  const tileWidth = info.tiles[0].width;
+  const tileHeight = info.tiles[0].height || info.tiles[0].width;
+  
+  const cols = Math.ceil(info.width / (tileWidth * scaleFactor));
+  const rows = Math.ceil(info.height / (tileHeight * scaleFactor));
+  
+  const tiles = [];
+  
+  for (let y = 0; y < rows; y++) {
+    for (let x = 0; x < cols; x++) {
+      const actualWidth = Math.min(tileWidth, 
+        (info.width - x * tileWidth * scaleFactor) / scaleFactor);
+
+      const actualHeight = Math.min(tileHeight, 
+        (info.height - y * tileHeight * scaleFactor) / scaleFactor);
+        
+      if (actualWidth <= 0 || actualHeight <= 0) continue;
+      
+      tiles.push({
+        url: `${info['@id']}/${x * tileWidth * scaleFactor},${y * tileHeight * scaleFactor},${actualWidth * scaleFactor},${actualHeight * scaleFactor}/${Math.ceil(actualWidth)},/0/default.jpg`,
+        width: Math.ceil(actualWidth),
+        height: Math.ceil(actualHeight), 
+        x: x * tileWidth,
+        y: y * tileHeight
+      });
+    }
+  }
+  
+  return tiles;
+}
+
+export const getThumbnail = async (resource: Level0ImageServiceResource, minSize?: Partial<Size>): Promise<Blob> => {
+  const info = await fetch(resource.serviceUrl).then(res => res.json());
+
+  const tiles = getThumbnailTiles(info, minSize);
+  const dimensions = getThumbnailDimensions(info, minSize);
+  
+  const canvas = document.createElement('canvas');
+  canvas.width = dimensions.width;
+  canvas.height = dimensions.height;
+
+  const ctx = canvas.getContext('2d');
+  if (!ctx) 
+      throw new Error('Error creating canvas context');
+
+  const loader = getThrottledLoader();
+
+  await Promise.all(tiles.map(async (tile) => {
+    const img = await loader.loadImage(tile.url);
+    ctx.drawImage(img, tile.x, tile.y);
+  }));
+
+  return new Promise((resolve, reject) => {
+    canvas.toBlob(blob => {
+      if (blob) resolve(blob);
+      else reject(new Error('Failed to create blob'));
+    }, 'image/jpeg', 0.85);
+  });
+  
+}