Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
273 lines (187 sloc) 10.9 KB


Software for browsing, sorting, and subsetting pre-generated images in a web browser.

Demonstration page

Table of Contents

  1. Useage Examples
  2. Installation
  3. Configuration
  4. Performance Hints

1. Use Examples

If remote images are available from an HTTP address and their URLs follow a simple pattern, the images can be viewed by appending a configuration string to the URL For alternative usage, including for viewing local images, see the Installation section below.

1.1 Example - no thumbnails

The directory contains image files with a pattern that can be represented by a [template]( template]) sunspots_512_$Y$m$d.jpg. Browse them using ViViz using the link$Y$m$d.jpg&start=2006-01-20&stop=P0D

The parameters passed to ViViz are

  • dir
  • strftime
  • start
  • stop

Given start and stop, one filename per day is generated by substituting $Y, $m, and $d in strftime; the final URL created by prepending dir to the list of filenames.

1.2 Example - thumbnails available

The directory contains images of two sizes. To specify different full and thumbnail images, use$Y$m$d.jpg&thumbstrftime=sunspots_512_$Y$m$d.jpg&start=2006-01-20&stop=P0D

1.3 Creating images and configuration

The program shows an example of using ViViz after a Python program creates a large set of images.

git clone
cd viviz/demos
python # Creates images, gallery configuration, and opens in browser

2. Installation

If images to view are not accessible from a public web page, installation is required.

2.1 Basic

A. In a web browser, open, select File > Save As > index.htm and save as /tmp/index.htm


B. on the command line, enter curl > /tmp/index.htm and then open file:///tmp/index.htm in a web browser.

The drop-down menus can be modified by editing the configuration near the top of index.htm with a text editor.

Arguments to index.htm can be sepecified in the address bar, e.g.,


2.2 Redirect

If you have a directory of images and would like to allow them to be easily browsed using ViViz, place the following in a file named index.htm in a directory containing the images.

<!DOCTYPE html>
<meta HTTP-EQUIV="REFRESH" content="0; url=$Y$m$d">

When selected, the user would be redirected to$Y$m$d

2.3 Web Server

In this mode, fullfiles and thumbfiles may be relative URLs to a file list.

Installation options:

curl > /server/root/dir/viviz/index.htm
# Open http://server/viviz/

(configuration variables are in index.htm)


cd /server/root/dir/; git clone
# Open http://server/viviz

(configuration variables are in index.js)

2.4 Full Application

In this mode, fullfiles and thumbfiles can be absolute URLs to a file list. This allows, for example, a list of files to be stored in a remote repository.

The full application includes a web server and a proxy server that retrieves remote file lists and remote catalogs and requires the installation of Node.js.

git clone
# or
curl >
unzip; mv viviz-master viviz


cd viviz
npm install --production
npm start

And then open http://localhost:8002/ with a web browser.

3. Configuration

3.1 Application

The variable VIVIZ["config"] in index.htm (or index.js, depending on installation method) contains all of the application options.

Any configuration option that appears in VIVIZ["config"] is over-ridden by a same-named option that appears in a gallery configuration or a parameter in the query string.

3.2 Gallery

The gallery configuration options are stored in an object in VIVIZ["catalog"].

To see the gallery configuration for the gallery in view, select the Gallery configuration link at the top of the page. See also index.htm (or index.js) for many examples of gallery configurations. The catalog shows many of the configuration options and features.

The main gallery configuration parameters are

  • fulldir or dir: A base URL for the location of full-sized image files (default is same directory of index.htm)
  • thumbdir: A base url for the location of reduced-size versions of the full-sized images (default is fulldir).
  • fullfiles or files: A list of image filenames that are appended to fulldir.
  • thumbfiles: A list of image filenames that are appended to thumbdir (default is fullfiles).

The format of the lists in fullfiles and thumbfiles is either a Javascript array of the form


or a quoted new-line separated string


or a relative relative URL to a JSON or text file for a [Web Server](#Web Server) installation:


and an absolute URL to an external JSON or text file for a [Full Application](#Full Application) installation:


When the list of files is long and the filenames have a pattern, the list of image URLs can be represented by sprintf or strftime pattern along with start and stop indices or dates.

When the list of full- or thumb-sized image files cannot be described using the above parameters, the lists can be specified using a script, where

  • script is a script that generates a list of files.

If any of the above parameters (excluding start and stop) applies only to either the full- or reduced-sized images, the parameters should be prefixed by full or thumb, respectively.

3.3 Scripts

Any Javascript code that can run in a browser is allowed and the functions [sprintf]( sprintf) and strftime are available.

The following three examples create the same list of four files. Note that % instead of $ must be used when using sprintf or strftime in a script. For the non-script parameters above, $ must be used.

function () {
	files = []
	for (i = 0; i < 4; i++) {
		files[i] = ['demo-200' + (i+1) + '.png']
	return files
function () {
	files = []
	for (i = 0; i < 4; i++) {
		files[i] = ['demo-' + sprintf('%02d',i+1) + '.png']
	return files
function () {
	files = []
	for (i = 0; i < 4; i++) {
		files[i] = ['demo-' + strftime('%Y',2000+i+1) + '.png']
	return files

3.4 Attributes and Filters

  • Each image can have zero or more attributes and each attribute can have zero or more filters that allow for showing only a subset of images.
  • Filters expressions can be either regular expressions (for string attributes) or logical expressions (for numeric attributes). To refer to the value of the attribute in logical expressions, use the this keyword.

3.4.1 Attributes

Each image in a file list can have zero or more that can be used to view a subset of the images. The JSON format is

	["file1.png", "attribute1", "attribute2", ..., "attributeM"],
	["fileN.png", "attribute1", "attribute2", ..., "attributeM"]

and the ASCII format is

file1.png, attribute1, attribute2, ..., attributeM
fileN.png, attribute1, attribute2, ..., attributeM

In the JSON case, attributes may be either strings or numbers (do not quote attributes that are numbers). In the ASCII case, all attributes are assumed to be strings unless they can be converted to floating point numbers.

To give attributes names, see the configuration for; the named attribute appears in the attribute drop-down menu.

3.4.2 Filters

See the configuration for for an example of allowing attributes to be filtered. (Select Age in the attribute drop-down menu and a filter drop-down will appear).

5. Performance Hints

  • Use thumbnail images.
  • Use interlaced PNG encoding for large full-sized images.
  • Use [PNGQuant]( PNGQuant) for compressing PNG images.
  • In gallery mode, the configuration variable lazyLoadMax controls how many thumbnail images are pre-loaded before and after the active thumbnail. It also controls how many full-sized images are pre-loaded. For small values of the parameter frameRate, which controls the frame rate (in milliseconds) when the play button is pressed, you may need to increase lazyLoadMax if blank images are shown as the animation progresses.
You can’t perform that action at this time.