HTML5 PivotViewer

  - Introduction
  - Download
  - Tutorial
  - Examples


This tutorial will teach you how to create a Deep Zoom Collection that can be viewed and filtered in HTML5 PivotViewer using an example dataset. This procedure may be applied to any tab delimited data file that contains paths to png or jpg images.

Recommended Prerequisites

  • A directory in a UNIX file system to store a collection of images and the CXML metadata file. The directory should be mounted and visible on a web server (we use Apache) to allow you to view the data in Pivot at each stage.
  • Perl (5 or above)
  • Python (2.6 or above)

Creating a basic collection

Download and unpack the example tar gzipped file (using tar xvfz pivot_demo.tar.gz). This includes everything you need to get started. The only additional files you may need to install are some standard Perl and Python libraries. See the actual code for details.

Another thing to note is the Javascript libraries referenced in the index.html page in the demo and scripts refers to Javascript directories that are located in the root directory ('/') of the server. We find it more convenient to do this and then set up a DocumentRoot directive in the Apache conf file that actually points to the directory on the file system the source is installed in.

So for example, we have the following:

      DocumentRoot /wwwdata/pivot/html5pivotviewer

which means when Apache sees root being referred to in a URL it actually uses /wwwdata/pivot/html5pivotviewer/.

In the downloaded pivot_demo directory there is a shell script ( which runs a sequence of commands to generate the required files to create a HTML5 PivotViewer data files which runs the following steps:

  • Generate an cxml document from a tab delimited input file that defines a collection for PivotViewer to read (
  • Generate a tiling pyramid for each each image in the collection ( There are various ways of doing this. This script calls a Python library called DeepZoom, but another option is VIPS which may be more efficient in terms of inodes since it stores the pyramid as a multi-image TIFF. We are looking to integrate this into PivotViewer.

Many of our collections rely on the output of imaging tools such as Fiji to generate montages and metadata. In the example supplied, we are looking at colocalisation as described in the paper by Clynes et al. (2014). In the paper we process a multichannel TIFF, extract some properties about the cell nucleus, namely the number of structures or foci in the cell that are overlapping or close to each other and create a png file that is a montage representing different aspects of the analysis. For each image we create a tab delimited row in a text file containing this data. You can see an example of this in the file.

(We don't include the scripts that did the image analysis, generate initial pngs or jpgs and file because we want to show you how create a PivotView rather than focus on image analysis. Email for more information on this.)

We use the following directory structure:

project nameTop-level DirectoryThe metadata, cxml collection file, file and sub directroies below
binDirectoryBespoke scripts and macros to generate intermediate output for HTML5 PivotViewer*
rawDirectoryRaw images from the microscope (tiffs) pre segmentation**.
inDirectoryTiffs of each cell after segmentation**.
imgDirectoryxml DeepZoom files, DeepZoom tiling files (png or jpg) files.
outDirectoryOutput (png or jpg) files.

*In the download it includes scripts for generating tiling pyramids and cxml file used by PivotViewer. These are called by the script.

**These are empty in the download but the directory is retained to show you the type of structure we use in real world situations.

This structure is optional but we find it convenient since all custom scripts, parameters and datafiles are kept together.

Creating a basic collection

The best way to understand the process is read the script and then try running it in the pivot_demo directory.


In,bin/ creates a collection xml (cxml) file which contains meta information for each image file that can be queried and bin/ creates xml files for each image and a subdirectory containing a pyramid of the image tiles at the different zoom levels.

View in HTML5 PivotViewer

Go to the example page to try out using HTML5 PivotViewer within a web browser.

Setting up HTML5 PivotViewer on your web server from the Git repository

See the instructions in the Git respository.

CBRG support