How do I get started using OpenSeadragon?

I was wondering how to get started with OpenSeadragon. I have it installed through node.js according to the repository readme on github. Then I was looking at the API and it looks like you have to use the OpenSeadragon.Viewer function. But that is as far as I got. I just want to create a simple page with one deep-zooming image using OpenSeadragon.


You only need node.js if you're going to be modifying the OpenSeadragon source. If you just want to use OpenSeadragon, grab a built version from Then, assuming your project directory looks like so:


Your index.html could look like so:

    <style type="text/css">
      #foo {
        width: 400px;
        height: 300px;
    <div id="foo"></div>
    <script src="openseadragon/openseadragon.min.js"></script>
      var viewer = OpenSeadragon({
        id:            'foo',
        prefixUrl:     'openseadragon/images/',
        tileSources:   'dzi/foo.dzi'

I guess I should add something like this as a "getting started" on the web site!

So, to answer my question,

The dzc_output.xml file is in fact the DZI file. Microsoft sets the filetype to xml as browsers have difficulty with dzi according to information buried on their website.

The OpenSeaDragon website has an example page for Deep Zoom Composer created images. The example, XMLHTTPRequest for DZI XML or JSON, shows how to use DZI, but not XML.

I would like some guidance on this.

The export of Seadragon AJAX from Deep Zoom Composer is a collection of folders, xml files and images,

  • GeneratedImages (folder)
    • dzc_output_files (folder)
    • 0 (folder) ... (intervening folders)
    • 15 (folder)
    • dzc_output.xml (xml file)
    • scene.xml (xml file)
    • SparseImageScenedGraph.xml (xml file)

There is no DZI file anywhere in this collection. The text further states, " OpenSeadragon sniffs for whether the DZI is formatted as XML or JSON", and I don't know what this means.

Should it be possible to use the Deep Zoom Composer generated folder structure and files with the xml file data with OpenSeadragon?

iangilman's answer is still relevant and useful today. One thing I would add... if you are using Microsoft's Deep Zoom Composer to create your DZI, check the XML file. If it contains DisplayRects, delete them. OpenSeaDragon does not handle them correctly (see and will not display the image at all. Delete the entire section from the XML and everything works fine. There is some conversation about a potential performance impact, but I have not seen that issue myself.

Also, it looks like the height and width are critical - I removed them at one point and the entire image disappeared (0 height and 0 width I presume).

Need Your Help

Efficient foreach child evaluation in parallel

c# linq foreach parallel-processing

I have a list of objects, each with a bool ShouldRun() method on them.