Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


The hbz DeepZoom-Tool implements a RESTful service generates, caches and provides pyramidal (deep zoom able) tiles. It provides a JSONP object which can integrated via OpenSeadragen ( into web pages for displaying images in a zoomable format.

The DeepZoom-Tool uses VIPS as pyramidal tiles generator.

Codacy Badge



  • Maven
  • Java SDK, Version 1.7 and higher (openjdk)
  • VIPS, Version 7.30 or higher required!
  • Tomcat, Version 6 and higher

VIPS can be installed from the Software Repositories of many Linux Distributions (not included in SLES 11 and 12). Please be aware that VIPS versions lower than Version 7.30 do not provide the dzsave-Method required for the DeepZoom-Tool

Quick Install

Quick Install is thought for testing purposes. With this configuration free install you can run the service without much efforts. Quick Install means data for tiles will be chached inside the deployed servlet container. Its not recommended to use Quick Install for production environment.

  1. Get with: git clone
  2. Check that src/main/resources/conf/deepzoomer.cfg has workingDir Property is setted to absolute path to webapp directory (this is needed to be changed if you want to use a data diretory outside of tomcat webapp
  3. Deploy with: mvn clean test war:war
  4. Copy deepzoom.war into the tomcat webapp-dir
  5. Open Browser and run http://localhost:8080/deepzoom/example to get an example web page


For running the service on production environment it’s highly recommended to store tiles outside the deployed servlet container. For that you have to create directories outside tomcats webapps directory and contextes for tomcat to access these directories 1.

  1. Get with: git clone
  2. Create web accessible temp and tilesCache directory outside tomcat’s webapp directory 2.
    • These directories must be accessible by tomcat-user.
    • Use appropriate context.xml to configure tomcat for taking this workingDir into account.
  3. Change deepzoomer.cfg according our Server settings: workingDir should be the directory containing temp and tilesCache dirs. wdPath is the name of context: e.g. /workingDir/wdPath/tempDir

Its also recommended to generate an apache vhost to access the service via proxy or rewrite.

1 For ubuntu also compare with implementation of /usr/share/tomcat7-example via /etc/tomcat7/Catalina/example.xml

2 See CONFIG.textile for detailed example


To integrate the Service API into your web site, you have to proceed with 3 easy steps.

1. Include required libraries into your web page

  <link rel="stylesheet" type="text/css" href="css/jquery-ui.min.css"/>
  <script src="js/openseadragon.min.js"></script>
  <script src="js/jquery-1.9.1.min.js"></script>
  <script src="js/jquery-ui.min.js"></script>

2. Use jQuery to identify the html-Elements that should make use of the service and add OpenSeadragon viewer to these html-Elements

<div style="clear:both;">Kleine Auswahl von Bildern</div>
    <a class="dz_image_url" href="http://localhost/opensd/sagrada_portal.png" 
       target="_blank">Nordportal (?) der Sagrada Familia
    <a class="dz_image_url" href="http://localhost/opensd/sagrada.jpg" 
       target="_blank">Innenraum Sagrada Familia
<script language="javascript" type="text/javascript"> 
function getImageUrl(){
		$(this).attr("style", "cursor: pointer;");
			imageUrl = $(this).html(); 
			return false;
	      modal: true,
	      autoOpen: false,
	      height: ($(window).height() - 60),
	      width: ($(window).width() - 60),
	      buttons: {
	        Ok: function() {
	          $( this ).dialog( "close" );

3. Add OpenSeadragon code

var serviceUrl = "http://localhost:8080/deepzoom/api/getDzi?imageUrl=";
var callbackString = "&callback=?";
var imageUrl = "http://localhost/opensd/Bambusgarten.png";
var viewer = null;
var tileSourcesFn;
function deepZoomService (){
	var url = serviceUrl + imageUrl + callbackString;
	$.getJSON(url, function(json){
		tileSourcesFn = json;
		viewer = OpenSeadragon({
          id: "openseadragon1",
          prefixUrl: "../OSimages/",
          tileSources: {
        	  Image: {
        		  xmlns:    "",
        		  Url: tileSourcesFn.Url + "/",
                  Format:   tileSourcesFn.Format, 
                  Overlap:  tileSourcesFn.Overlap, 
                  TileSize: tileSourcesFn.TileSize,
                  Size: {
                      Height: tileSourcesFn.Size.Height,
                      Width:  tileSourcesFn.Size.Width
          showNavigator: "true",

Known Issues

Because of an incompatibility between Java8 and tomcat6 JSP-Example pages are not deployed within environments running tomcat6 with Java8 (see for details). Nevertheless services are running without trouble on these environments


Version 0.3.




Copyright 2015 Hochschulbibliothekszentrum des Landes Nordrhein-Westfalen (


A RESTful Service for generation, caching and providing DeepZoom Tiles as used especially by OpenSeadragon Viewer






No releases published


No packages published