Installing scrollable, zoomable images

[CarwilB]

Advice on OpenSeadragon from Gemini 3:

That sounds like a great project! Integrating OpenSeadragon (OSD) into a Quarto website allows for high-performance, deep zooming on very large images.

Here is a step-by-step guide to installing OSD, preparing your image, and embedding it into a Quarto document.

---

1. Install OpenSeadragon (OSD)

Since Quarto processes Markdown and embeds HTML/JavaScript, you don't "install" OSD in the traditional sense, but you include its libraries in your project's HTML output.

A. Download the Library

You can include the OpenSeadragon library by placing the required JavaScript file in your Quarto project folder, or by linking directly to a CDN. Using a CDN is the simplest approach.

You will include the following line in the header of your document or in a partial:

<script src="https://cdnjs.cloudflare.com/ajax/libs/openseadragon/4.1.0/openseadragon.min.js"></script>

B. Create an HTML Container

In the Quarto document (.qmd file) where you want the viewer to appear, you need to create an empty div element. This is where OpenSeadragon will load the image.

<div id="openseadragon-viewer" style="width: 800px; height: 600px; background-color: #6c757d; border: 1px solid black;"></div>

• id="openseadragon-viewer": This ID is essential; you will reference it in the JavaScript initialization.
• style="...": Define the visible size of the viewer window. The image will be constrained by these dimensions.

---

2. Prepare the Zoomable Image

OpenSeadragon relies on a tiled image format to efficiently load only the parts of the image currently visible. Directly loading a single large image file (like a massive .jpg) will often fail or crash the browser.

A. Tiling the Image

You must use a tool to convert your large source image into a tiled format (Deep Zoom Image - DZI).

1. Use VIPS or deepzoom.py: Command-line tools like VIPS (specifically the vips dzsave command) or the Python script deepzoom.py are common for this.

2. Generate Tiles: Run the tool on your image (my-large-image.tiff):

   vips dzsave my-large-image.tiff my-image-tiles

   This creates a folder (my-image-tiles) containing thousands of small tiles, plus a Deep Zoom Image (.dzi) file (my-image-tiles.dzi). The .dzi file is a small XML file that tells OpenSeadragon how to reconstruct the image from the tiles.

3. Place Tiles: Place the generated my-image-tiles folder and the my-image-tiles.dzi file in a dedicated directory within your Quarto project (e.g., in a files/tiles/ folder).

---

3. Initialize OpenSeadragon in Quarto

You can embed the JavaScript initialization code directly into your .qmd document using an executable code block.

A. Quarto Code Block

Place the following code block directly after your HTML container (<div id="...">).

```{=html}
<script>
    // Wait for the HTML container to be ready before initializing OSD
    window.onload = function() {
        if (typeof OpenSeadragon !== 'undefined') {
            var viewer = OpenSeadragon({
                id: "openseadragon-viewer", // Matches the ID of the HTML container
                prefixUrl: "[https://cdnjs.cloudflare.com/ajax/libs/openseadragon/4.1.0/images/](https://cdnjs.cloudflare.com/ajax/libs/openseadragon/4.1.0/images/)", // Icons for the UI buttons
                tileSources: {
                    type: 'dzi', // Specifies the Deep Zoom Image format
                    url: 'files/tiles/my-image-tiles.dzi' // *** UPDATE THIS PATH ***
                },
                // Optional Configuration Settings
                showZoomControl: true,
                showHomeControl: true,
                showFullPageControl: true,
                visibilityRatio: 1,
                minZoomLevel: 0.5,
                maxZoomLevel: 5
            });
        } else {
            console.error("OpenSeadragon library not loaded.");
        }
    };
</script>

### B. Summary of Integration

The final structure in your `.qmd` file should look like this:

```markdown
---
title: "OSD Zoom Viewer"
format: html
---

## Deep Zoom Image Example

```{=html}
<script src="[https://cdnjs.cloudflare.com/ajax/libs/openseadragon/4.1.0/openseadragon.min.js](https://cdnjs.cloudflare.com/ajax/libs/openseadragon/4.1.0/openseadragon.min.js)"></script>

<div id="openseadragon-viewer" style="width: 100%; height: 70vh; background-color: #6c757d;"></div>

<script>
    window.onload = function() {
        var viewer = OpenSeadragon({
            id: "openseadragon-viewer",
            prefixUrl: "[https://cdnjs.cloudflare.com/ajax/libs/openseadragon/4.1.0/images/](https://cdnjs.cloudflare.com/ajax/libs/openseadragon/4.1.0/images/)",
            tileSources: {
                type: 'dzi',
                url: 'files/tiles/my-image-tiles.dzi' // CHECK YOUR PATH!
            }
        });
    };
</script>

Now, when you render your Quarto document, the OpenSeadragon viewer will load your tiled image and provide smooth, high-resolution zooming capabilities.