Docs/viviz

From Weigel's Research and Teaching Page

ViViz

Demo page

Software for browsing, sorting, and subsetting pre-generated images in a web browser. It is an outgrowth of the ViRBO project.

Use examples
1. Browse pre-existing images
2. Creating images and configuration
Installation
Configuration
Performance Hints

1. Use examples

1.1. Browse pre-existing images

If remote images are available from an HTTP address and their URLs follow a simple pattern, the images may be viewed by appending a string to the URL http://viviz.org/#. For alternative usage, including for viewing local images, see Installation.

Example

The directory http://sohowww.nascom.nasa.gov/data/synoptic/sunspots_earth/ contains image files with a pattern that can be represented by the template sunspots_512_$Y$m$d.jpg. Browse them using ViViz using the link

http://viviz.org/#dir=http://sohowww.nascom.nasa.gov/data/synoptic/sunspots_earth/&strftime=sunspots_512_$Y$m$d.jpg&start=2006-01-20&stop=P0D

Example

The directory http://sohowww.nascom.nasa.gov/data/synoptic/sunspots_earth/ contains images of two sizes. To specify different full and thumbnail images, use

http://viviz.org/#dir=http://sohowww.nascom.nasa.gov/data/synoptic/sunspots_earth/&fullstrftime=sunspots_1024_$Y$m$d.jpg&thumbstrftime=sunspots_512_$Y$m$d.jpg&start=2006-01-20&stop=P0D

1.2. Creating images and configuration

git clone https://github.com/rweigel/vivivz/
cd viviz/demos
python creategallery.py # Creates images, gallery configuration, and opens in browser

2. Installation

2.1. Basic

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

in a web browser, open http://viviz.org/index-inline.htm, select File > Save As > index.htm or
on the command line, enter curl http://viviz.org/index-inline.htm > index.htm

and then open the saved file index.htm file in a web browser.

To configure, either

modify one of the gallery configuration examples at the top of the saved index.htm file with a text editor, or
append arguments to index.htm in the address bar of a browser, e.g.,

file:///tmp/index.htm#dir=file:///path/to/images/&strftime=...&start=...&stop=...

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>
<html>
<head>
<meta HTTP-EQUIV="REFRESH" content="0; url=http://viviz.org/#dir=http://sohowww.nascom.nasa.gov/data/synoptic/sunspots_earth/&fullstrftime=sunspots_1024_$Y$m$d">
</head>
</html>
</nowiki>

For example, the above file existed in the directory

http://sohowww.nascom.nasa.gov/data/synoptic/sunspots_earth/index.htm

When selected, the user would be redirected to http://viviz.org/#dir=http://sohowww.nascom.nasa.gov/data/synoptic/sunspots_earth/&fullstrftime=sunspots_1024_$Y$m$d"

Use the alternative installation methods to keep users on your site instead of being redirected to a ViViz URL when viewing the images.

2.3. Web Server

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

Installation options:

curl http://viviz.org/index-inline.htm > /server/root/dir/index.htm

(configuration variables are in index.htm)

cd /server/root/dir/; git clone https://github.com/rweigel/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.

git clone https://github.com/rweigel/viviz

curl https://codeload.github.com/rweigel/viviz/zip/master > viviz-master.zip
unzip viviz-master.zip; mv viviz-master viviz

then

cd viviz
npm install --production
npm start
# 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 http://viviz.org/#catalog=Test 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

[["demo-2001.png"],["demo-2002.png"],["demo-2003.png"],["demo-2004.png"]]

or a quoted new-line separated string

"demo-2001.png\ndemo-2002.png\ndemo-2003.png\ndemo-2004.png"

or a relative relative URL to a JSON or text file for a #Web Server installation:

path/fullfiles.json
path/fullfiles.txt

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

http://server/path/fullfiles.json
http://server/path/fullfiles.txt

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.

sprintf is a formatted string expression (e.g., data-$04d.png)
strftime is a formatted time string expression (e.g., data-$Y$m$d.png for files of the form data-19990412.png)
start: Either an integer (for sprintf) or an ISO8601 date
stop: Either an integer (for sprintf) or an ISO8601 date

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 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 http://viviz.org/#catalog=Test&id=Demo/05d; the named attribute appears in the attribute drop-down menu.

3.4.2. Filters

See the configuration for http://viviz.org/#catalog=Test&id=Demo/05d for an example of allowing attributes to be filtered. (Select Age in the attribute drop-down menu and a filter drop-down will appear).

4. Performance Hints

Use thumbnail images.
Use interlaced PNG encoding for large full-sized images.
Use 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.

Retrieved from "http://rweigel.dynu.net/projects/index.php?title=Docs/viviz"