openseadragon-capture 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ravi Shankar Saini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# openseadragon-capture
+
+Capture high-quality screenshots from OpenSeadragon viewers with optional overlay layers.
+
+## Installation
+
+```bash
+npm install openseadragon-capture
+```
+
+## Usage
+
+```typescript
+import OpenSeadragon from 'openseadragon';
+import { createScreenshot } from 'openseadragon-capture';
+
+// Initialize OpenSeadragon viewer with CORS support
+const viewer = OpenSeadragon({
+  id: 'viewer',
+  tileSources: 'path/to/your/image.dzi',
+  crossOriginPolicy: 'Anonymous' // Required for screenshot export
+});
+
+// Wait for viewer to open
+viewer.addHandler('open', async () => {
+  // Create screenshot instance
+  const screenshot = createScreenshot(viewer);
+
+  // Capture as Blob (recommended - memory efficient)
+  const blob = await screenshot.toBlob({
+    format: 'png',
+    quality: 0.9,
+    scale: 2
+  });
+
+  // Or capture as data URL
+  const dataUrl = await screenshot.capture({
+    format: 'png',
+    quality: 0.9,
+    overlays: [overlayCanvas]
+  });
+
+  // Or download directly
+  await screenshot.download('screenshot.png', {
+    overlays: [overlayCanvas]
+  });
+});
+```
+
+## API
+
+### `createScreenshot(viewer: OpenSeadragon.Viewer): OpenSeadragonScreenshot`
+
+Creates a screenshot instance for the given viewer.
+
+### `toBlob(options?: ScreenshotOptions): Promise<Blob>`
+
+Captures the viewer as a Blob. Recommended for memory efficiency.
+
+**Throws:** Error if viewer is not open or canvas is unavailable.
+
+### `capture(options?: ScreenshotOptions): Promise<string>`
+
+Captures the viewer as a data URL.
+
+**Throws:** Error if viewer is not open or canvas is unavailable.
+
+### `download(filename: string, options?: ScreenshotOptions): Promise<void>`
+
+Captures and downloads the screenshot with the specified filename.
+
+### ScreenshotOptions
+
+```typescript
+export type ScreenshotFormat = 'png' | 'jpeg' | 'webp';
+
+interface ScreenshotOptions {
+  /** Output image format. @default 'png' */
+  format?: ScreenshotFormat;
+  
+  /** Image quality (0-1). @default 0.9 */
+  quality?: number;
+  
+  /** 
+   * Upscaling factor applied via canvas interpolation.
+   * Does NOT fetch higher-resolution tiles.
+   * @default 1 
+   */
+  scale?: number;
+  
+  /** 
+   * Overlay canvases to composite.
+   * Must already be in viewer pixel space with transforms applied.
+   */
+  overlays?: HTMLCanvasElement[];
+  
+  /** 
+   * If true, temporarily fits entire image to viewport before capture.
+   * Causes momentary viewport change.
+   * @default true 
+   */
+  fitImageToViewport?: boolean;
+  
+  /** 
+   * Index of the tiled image to capture (for multi-image viewers).
+   * @default 0 
+   */
+  imageIndex?: number;
+}
+```
+
+## Important Limitations
+
+⚠️ **CORS Requirement**: Images must be served with CORS headers. Set `crossOriginPolicy: 'Anonymous'` in viewer config. CORS errors will cause capture to fail.
+
+⚠️ **Scale Behavior**: The `scale` parameter upscales via canvas interpolation. It does NOT fetch higher-resolution tiles. For true high-resolution exports, tiles must be loaded at the target resolution.
+
+⚠️ **Viewport Changes**: `fitImageToViewport: true` temporarily changes the viewport to fit the entire image, which may cause visual flicker.
+
+⚠️ **Overlay Requirements**: Overlay canvases must already be in viewer pixel space with transforms applied. Overlays with mismatched dimensions will be stretched.
+
+⚠️ **Timing**: Capture waits for tiles to load using heuristic-based timing. May fail if tiles load slowly.
+
+⚠️ **Memory**: Large scale factors can create very large canvases (warning shown if exceeding 16MP).
+
+## Production Considerations
+
+- Always handle promise rejections (CORS errors are common)
+- Use `toBlob()` instead of `capture()` for better memory management
+- Wait for viewer 'open' event before capturing
+- Test with your specific tile sources and CORS configuration
+- Validate overlay canvas dimensions match viewer canvas
+- Be cautious with large scale factors to avoid memory issues
+
+## License
+
+MIT

package/dist/cjs/capture.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenSeadragonScreenshot = void 0;
+exports.createScreenshot = createScreenshot;
+class OpenSeadragonScreenshot {
+    constructor(viewer) {
+        this.viewer = viewer;
+    }
+    async capture(options = {}) {
+        const blob = await this.toBlob(options);
+        return new Promise((resolve, reject) => {
+            const reader = new FileReader();
+            reader.onloadend = () => resolve(reader.result);
+            reader.onerror = () => reject(new Error('Failed to convert blob to data URL'));
+            reader.readAsDataURL(blob);
+        });
+    }
+    async toBlob(options = {}) {
+        this.ensureViewerReady();
+        const { format = 'png', quality = 0.9, scale = 1, overlays = [], fitImageToViewport = true, imageIndex = 0 } = options;
+        const stage = await this.prepareCapture(scale, overlays, fitImageToViewport, imageIndex);
+        return this.renderStage(stage, format, quality);
+    }
+    ensureViewerReady() {
+        if (!this.viewer.isOpen()) {
+            throw new Error('[OpenSeadragon Capture] Viewer is not open. Wait for the "open" event before capturing.');
+        }
+    }
+    async prepareCapture(scale, overlays, fitImageToViewport, imageIndex) {
+        await this.waitForDraw();
+        if (fitImageToViewport) {
+            const canvas = await this.captureFullImage(imageIndex);
+            return { canvas, overlays, scale };
+        }
+        const canvas = this.getCanvas();
+        return { canvas, overlays, scale };
+    }
+    getCanvas() {
+        const canvas = this.viewer.drawer?.canvas;
+        if (!canvas) {
+            throw new Error('[OpenSeadragon Capture] Canvas not available. Ensure viewer is fully initialized.');
+        }
+        return canvas;
+    }
+    waitForDraw() {
+        return new Promise((resolve) => {
+            const timeout = setTimeout(() => {
+                requestAnimationFrame(() => resolve());
+            }, 100);
+            this.viewer.addOnceHandler('animation-finish', () => {
+                clearTimeout(timeout);
+                requestAnimationFrame(() => resolve());
+            });
+            this.viewer.forceRedraw();
+        });
+    }
+    async captureFullImage(imageIndex) {
+        const tiledImage = this.viewer.world.getItemAt(imageIndex);
+        if (!tiledImage) {
+            throw new Error(`[OpenSeadragon Capture] No image at index ${imageIndex}`);
+        }
+        const currentBounds = this.viewer.viewport.getBounds();
+        const bounds = tiledImage.getBounds();
+        try {
+            this.viewer.viewport.fitBounds(bounds, true);
+            await this.waitForFullLoad(tiledImage);
+            return this.getCanvas();
+        }
+        finally {
+            this.viewer.viewport.fitBounds(currentBounds, true);
+        }
+    }
+    waitForFullLoad(tiledImage) {
+        if (tiledImage.getFullyLoaded()) {
+            return this.waitForDraw();
+        }
+        return new Promise((resolve) => {
+            tiledImage.addOnceHandler('fully-loaded-change', () => {
+                this.waitForDraw().then(resolve);
+            });
+        });
+    }
+    validateOverlays(canvas, overlays) {
+        for (const overlay of overlays) {
+            if (overlay.width !== canvas.width || overlay.height !== canvas.height) {
+                console.warn(`[OpenSeadragon Capture] Overlay dimensions (${overlay.width}x${overlay.height}) ` +
+                    `do not match viewer canvas (${canvas.width}x${canvas.height}). ` +
+                    `Overlay will be stretched.`);
+            }
+        }
+    }
+    renderStage(stage, format, quality) {
+        return new Promise((resolve, reject) => {
+            try {
+                const outputCanvas = document.createElement('canvas');
+                const outputCtx = outputCanvas.getContext('2d', { alpha: format === 'png' });
+                if (!outputCtx) {
+                    reject(new Error('[OpenSeadragon Capture] Failed to get canvas context'));
+                    return;
+                }
+                outputCanvas.width = stage.canvas.width * stage.scale;
+                outputCanvas.height = stage.canvas.height * stage.scale;
+                const maxPixels = 16777216;
+                if (outputCanvas.width * outputCanvas.height > maxPixels) {
+                    console.warn(`[OpenSeadragon Capture] Output canvas is very large (${outputCanvas.width}x${outputCanvas.height}). ` +
+                        `This may cause memory issues.`);
+                }
+                this.validateOverlays(stage.canvas, stage.overlays);
+                outputCtx.imageSmoothingEnabled = true;
+                outputCtx.imageSmoothingQuality = 'high';
+                outputCtx.drawImage(stage.canvas, 0, 0, outputCanvas.width, outputCanvas.height);
+                for (const overlay of stage.overlays) {
+                    if (overlay.width > 0 && overlay.height > 0) {
+                        outputCtx.drawImage(overlay, 0, 0, outputCanvas.width, outputCanvas.height);
+                    }
+                }
+                outputCanvas.toBlob((blob) => blob ? resolve(blob) : reject(new Error('[OpenSeadragon Capture] Failed to create blob')), `image/${format}`, quality);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : 'Unknown error';
+                reject(new Error(`[OpenSeadragon Capture] ${message}. Check CORS policy if using remote images.`));
+            }
+        });
+    }
+    async download(filename, options = {}) {
+        const blob = await this.toBlob(options);
+        const url = URL.createObjectURL(blob);
+        try {
+            const link = document.createElement('a');
+            link.download = filename;
+            link.href = url;
+            link.click();
+        }
+        finally {
+            if (typeof requestIdleCallback === 'undefined') {
+                setTimeout(() => URL.revokeObjectURL(url), 100);
+            }
+            else {
+                requestIdleCallback(() => URL.revokeObjectURL(url), { timeout: 1000 });
+            }
+        }
+    }
+}
+exports.OpenSeadragonScreenshot = OpenSeadragonScreenshot;
+function createScreenshot(viewer) {
+    return new OpenSeadragonScreenshot(viewer);
+}

package/dist/cjs/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createScreenshot = exports.OpenSeadragonScreenshot = void 0;
+var capture_1 = require("./capture");
+Object.defineProperty(exports, "OpenSeadragonScreenshot", { enumerable: true, get: function () { return capture_1.OpenSeadragonScreenshot; } });
+Object.defineProperty(exports, "createScreenshot", { enumerable: true, get: function () { return capture_1.createScreenshot; } });

package/dist/esm/capture.js

@@ -0,0 +1,142 @@
+export class OpenSeadragonScreenshot {
+    constructor(viewer) {
+        this.viewer = viewer;
+    }
+    async capture(options = {}) {
+        const blob = await this.toBlob(options);
+        return new Promise((resolve, reject) => {
+            const reader = new FileReader();
+            reader.onloadend = () => resolve(reader.result);
+            reader.onerror = () => reject(new Error('Failed to convert blob to data URL'));
+            reader.readAsDataURL(blob);
+        });
+    }
+    async toBlob(options = {}) {
+        this.ensureViewerReady();
+        const { format = 'png', quality = 0.9, scale = 1, overlays = [], fitImageToViewport = true, imageIndex = 0 } = options;
+        const stage = await this.prepareCapture(scale, overlays, fitImageToViewport, imageIndex);
+        return this.renderStage(stage, format, quality);
+    }
+    ensureViewerReady() {
+        if (!this.viewer.isOpen()) {
+            throw new Error('[OpenSeadragon Capture] Viewer is not open. Wait for the "open" event before capturing.');
+        }
+    }
+    async prepareCapture(scale, overlays, fitImageToViewport, imageIndex) {
+        await this.waitForDraw();
+        if (fitImageToViewport) {
+            const canvas = await this.captureFullImage(imageIndex);
+            return { canvas, overlays, scale };
+        }
+        const canvas = this.getCanvas();
+        return { canvas, overlays, scale };
+    }
+    getCanvas() {
+        const canvas = this.viewer.drawer?.canvas;
+        if (!canvas) {
+            throw new Error('[OpenSeadragon Capture] Canvas not available. Ensure viewer is fully initialized.');
+        }
+        return canvas;
+    }
+    waitForDraw() {
+        return new Promise((resolve) => {
+            const timeout = setTimeout(() => {
+                requestAnimationFrame(() => resolve());
+            }, 100);
+            this.viewer.addOnceHandler('animation-finish', () => {
+                clearTimeout(timeout);
+                requestAnimationFrame(() => resolve());
+            });
+            this.viewer.forceRedraw();
+        });
+    }
+    async captureFullImage(imageIndex) {
+        const tiledImage = this.viewer.world.getItemAt(imageIndex);
+        if (!tiledImage) {
+            throw new Error(`[OpenSeadragon Capture] No image at index ${imageIndex}`);
+        }
+        const currentBounds = this.viewer.viewport.getBounds();
+        const bounds = tiledImage.getBounds();
+        try {
+            this.viewer.viewport.fitBounds(bounds, true);
+            await this.waitForFullLoad(tiledImage);
+            return this.getCanvas();
+        }
+        finally {
+            this.viewer.viewport.fitBounds(currentBounds, true);
+        }
+    }
+    waitForFullLoad(tiledImage) {
+        if (tiledImage.getFullyLoaded()) {
+            return this.waitForDraw();
+        }
+        return new Promise((resolve) => {
+            tiledImage.addOnceHandler('fully-loaded-change', () => {
+                this.waitForDraw().then(resolve);
+            });
+        });
+    }
+    validateOverlays(canvas, overlays) {
+        for (const overlay of overlays) {
+            if (overlay.width !== canvas.width || overlay.height !== canvas.height) {
+                console.warn(`[OpenSeadragon Capture] Overlay dimensions (${overlay.width}x${overlay.height}) ` +
+                    `do not match viewer canvas (${canvas.width}x${canvas.height}). ` +
+                    `Overlay will be stretched.`);
+            }
+        }
+    }
+    renderStage(stage, format, quality) {
+        return new Promise((resolve, reject) => {
+            try {
+                const outputCanvas = document.createElement('canvas');
+                const outputCtx = outputCanvas.getContext('2d', { alpha: format === 'png' });
+                if (!outputCtx) {
+                    reject(new Error('[OpenSeadragon Capture] Failed to get canvas context'));
+                    return;
+                }
+                outputCanvas.width = stage.canvas.width * stage.scale;
+                outputCanvas.height = stage.canvas.height * stage.scale;
+                const maxPixels = 16777216;
+                if (outputCanvas.width * outputCanvas.height > maxPixels) {
+                    console.warn(`[OpenSeadragon Capture] Output canvas is very large (${outputCanvas.width}x${outputCanvas.height}). ` +
+                        `This may cause memory issues.`);
+                }
+                this.validateOverlays(stage.canvas, stage.overlays);
+                outputCtx.imageSmoothingEnabled = true;
+                outputCtx.imageSmoothingQuality = 'high';
+                outputCtx.drawImage(stage.canvas, 0, 0, outputCanvas.width, outputCanvas.height);
+                for (const overlay of stage.overlays) {
+                    if (overlay.width > 0 && overlay.height > 0) {
+                        outputCtx.drawImage(overlay, 0, 0, outputCanvas.width, outputCanvas.height);
+                    }
+                }
+                outputCanvas.toBlob((blob) => blob ? resolve(blob) : reject(new Error('[OpenSeadragon Capture] Failed to create blob')), `image/${format}`, quality);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : 'Unknown error';
+                reject(new Error(`[OpenSeadragon Capture] ${message}. Check CORS policy if using remote images.`));
+            }
+        });
+    }
+    async download(filename, options = {}) {
+        const blob = await this.toBlob(options);
+        const url = URL.createObjectURL(blob);
+        try {
+            const link = document.createElement('a');
+            link.download = filename;
+            link.href = url;
+            link.click();
+        }
+        finally {
+            if (typeof requestIdleCallback === 'undefined') {
+                setTimeout(() => URL.revokeObjectURL(url), 100);
+            }
+            else {
+                requestIdleCallback(() => URL.revokeObjectURL(url), { timeout: 1000 });
+            }
+        }
+    }
+}
+export function createScreenshot(viewer) {
+    return new OpenSeadragonScreenshot(viewer);
+}

package/dist/esm/index.js

@@ -0,0 +1 @@
+export { OpenSeadragonScreenshot, createScreenshot } from './capture';

package/dist/types/capture.d.ts

@@ -0,0 +1,26 @@
+import OpenSeadragon from 'openseadragon';
+export type ScreenshotFormat = 'png' | 'jpeg' | 'webp';
+export interface ScreenshotOptions {
+    format?: ScreenshotFormat;
+    quality?: number;
+    scale?: number;
+    overlays?: HTMLCanvasElement[];
+    fitImageToViewport?: boolean;
+    imageIndex?: number;
+}
+export declare class OpenSeadragonScreenshot {
+    private readonly viewer;
+    constructor(viewer: OpenSeadragon.Viewer);
+    capture(options?: ScreenshotOptions): Promise<string>;
+    toBlob(options?: ScreenshotOptions): Promise<Blob>;
+    private ensureViewerReady;
+    private prepareCapture;
+    private getCanvas;
+    private waitForDraw;
+    private captureFullImage;
+    private waitForFullLoad;
+    private validateOverlays;
+    private renderStage;
+    download(filename: string, options?: ScreenshotOptions): Promise<void>;
+}
+export declare function createScreenshot(viewer: OpenSeadragon.Viewer): OpenSeadragonScreenshot;

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export { OpenSeadragonScreenshot, createScreenshot } from './capture';
+export type { ScreenshotOptions, ScreenshotFormat } from './capture';

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "openseadragon-capture",
+  "version": "1.0.0",
+  "description": "Capture high-quality screenshots from OpenSeadragon viewers with optional overlay layers.",
+  "type": "module",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "workspaces": [
+    "site",
+    "tests"
+  ],
+  "scripts": {
+    "clean": "node ./scripts/clean.mjs",
+    "build": "npm run build:dual",
+    "build:dual": "npm run clean && tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json",
+    "dev": "npm run -w site dev",
+    "build:demo": "npm run build && npm run -w site build",
+    "deploy:demo": "npm run build && npm run build:demo && git subtree push --prefix site/dist origin gh-pages",
+    "test": "npm run -w tests test",
+    "test:run": "npm run -w tests test:run",
+    "prepare": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rssaini01/openseadragon-capture.git"
+  },
+  "keywords": [
+    "openseadragon",
+    "canvas",
+    "overlay",
+    "screenshot",
+    "export"
+  ],
+  "author": "Ravi Shankar Saini",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/rssaini01/openseadragon-capture/issues"
+  },
+  "homepage": "https://github.com/rssaini01/openseadragon-capture/",
+  "devDependencies": {
+    "@types/openseadragon": "^5.0.1",
+    "openseadragon": "^5.0.1",
+    "typescript": "^5.9.3"
+  }
+}