Skip to content
A RESTful Service for generation, caching and providing DeepZoom Tiles as used especially by OpenSeadragon Viewer
Java JavaScript HTML CSS
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
.gitignore
API.textile
CONFIG.textile
README.textile
pom.xml

README.textile

About

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 (https://openseadragon.github.io/) into web pages for displaying images in a zoomable format.

The DeepZoom-Tool uses VIPS as pyramidal tiles generator.

Install

Prerequisites

  • 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 https://github.com/hbz/DeepZoomService.git
  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

Install

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 https://github.com/hbz/DeepZoomService.git
  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

Usage

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

<html>
 <head>
  <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>
 </head>
<body>
p. 

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>
 <div>
  <ul>
   <li>
    <a class="dz_image_url" href="http://localhost/opensd/sagrada_portal.png" 
       target="_blank">Nordportal (?) der Sagrada Familia
    </a>
   </li>
   <li>
    <a class="dz_image_url" href="http://localhost/opensd/sagrada.jpg" 
       target="_blank">Innenraum Sagrada Familia
    </a>
   </li>
  </ul>
 </div>
</div>
<script language="javascript" type="text/javascript"> 
$(document).ready(getImageUrl);
function getImageUrl(){
	$("li.dz_image_url").each(function(){
		$(this).attr("style", "cursor: pointer;");
		$(this).click(function(){
			imageUrl = $(this).html(); 
			$("#openseadragon1").dialog("open");
			deepZoomService();
			return false;
		});
	});
	$('#openseadragon1').dialog({
	      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;
		if(viewer){
        	viewer.destroy();
        }
		viewer = OpenSeadragon({
          id: "openseadragon1",
          prefixUrl: "../OSimages/",
          tileSources: {
        	  Image: {
        		  xmlns:    "http://schemas.microsoft.com/deepzoom/2008",
        		  Url: tileSourcesFn.Url + "/",
                  Format:   tileSourcesFn.Format, 
                  Overlap:  tileSourcesFn.Overlap, 
                  TileSize: tileSourcesFn.TileSize,
                  Size: {
                      Height: tileSourcesFn.Size.Height,
                      Width:  tileSourcesFn.Size.Width
                  }
        	  }
          },
          showNavigator: "true",
        });
    });
	
}
</script>
p. 

Known Issues

Because of an incompatibility between Java8 and tomcat6 JSP-Example pages are not deployed within environments running tomcat6 with Java8 (see https://bugs.openjdk.java.net/browse/JDK-8155223 for details). Nevertheless services are running without trouble on these environments

Releases

Version 0.3.

Status

Beta

License

LGPL
Copyright 2015 Hochschulbibliothekszentrum des Landes Nordrhein-Westfalen (http://www.hbz-nrw.de)

You can’t perform that action at this time.