Introduction

The reference implementation currently consists of a set of commandline tools and a suite of GUI tools. It can be downloaded at the VHIST homepage [1].

a) The commandline tools (VHIST core):

• vhistadd - commandline tool for creating VHIST files.
• vhistxs - commandline tool for extracting embedded data from VHIST files. Minimum implementation to short the basic principle.
• vhistxl - commandline tool for extracting embedded data from VHIST files, including facilities to extract individual embedded files and validate embedded files or sections.

b) The GUI tools:

• VHISTzard - an application that helps configuring commandline options for vhistadd and creating VHIST files without using the commandline. Moreover, it can be used to find and view existing VHIST files.

Platform independence was an important goal when we conceived VHIST and its Reference Implementation. We believe that VHIST core should work well on a wide range of systems for which a Python distribution [2] (equal or better to version 2.4, not Python 3) exists, especially on anything manufactured in this millenium.

We use C++ and Nokia's Qt libraries [3] for the development of VHISTzard. The Windows and Mac OS X distributions of VHIST ship a precompiled version of VHISTzard with the appropriate libraries and should run out of the box.

MS Windows

A standard installer is available that can deploy a ready-to-run version of VHISTzard including all commandline tools. This setup does not require a Python distribution, as all commandline tools have been compiled into ready-to-use standalone ".exe" programs. Alternatively, you can install Python (using a proper installer [2]) and use the "source" distribution of VHIST.

Mac OS X

a ready-to-run version of VHISTzard is available for this platform and can be installed as a standard Mac application. Installing the source distribution is also possible, a suitable Python distribution is part of the operating system since Mac OS X 10.3 (for older systems it can be easily installed without compromising other applications that might rely on the older versions). VHIST should work just fine with the newer "Intel" Macs (tested with Tiger and Leopard) and for the older PPC platform.

Linux

Python should be ubiquitous on this platform. Use python -v to check whether your installed version is recent enough (it very likely is). A version equal or better to version 2.4 should work. Python 3 or newer is not supported at the moment. If the installed version is not recent enough, you should consider upgrading it. Please refer to the documentation of your distribution.

If for some reason Python is not installed on your system, please refer to the documentation for your linux distribution on how to install Python.

To compile VHISTzard, a recent version of Nokia's Qt (including the development tools and header files) is needed. A Qt package is part of most recent Linux distributions, either pre-installed or as part of the package repositories. If your Linux distribution does not provide a version Qt, pre-compiled versions can be found at http://qt.nokia.com/downloads.

The general idea behind VHIST is to provide a robust and simple means for documenting steps of a workflow by logging and optionally embedding all relevant information about the steps: which files were used, which files were written, what software package was used in which version and with what parameters.

An example from medical imaging is the process (workflow) to create an image volume suitable for scientific/diagnostics purposes. In this case, a typical workflow step might be the application of an image filter (tool, this example works best with a commandline tool) to an image, present as an input file (infile). The commandline used in this workflow step, in addition to some filter option (say, Gauss filter size), could be added to the VHIST file using Attributes. Assuming the filter application creates a new file containing the filtered image volume, we can add this file as an output file (outfile) to the generated documentation. It is recommended practice to have vhistadd embed (see Files: Embedded Vs. Reported) any logfile the filter application might write.

An attribute is a key-value pair. vhistadd provides commandline options for specifying either pre-defined or user-defined keys. We make this distinction to ensure that a basic set of attributes is universally available (e.g. description, or title). This is a prerequisite for comparing VHIST files from different sources. Attributes can be specified for the workflow step and even for individual in- and outfiles. The type and meaning of the value depends on the key and is described in the documentation of the individual options.

VHIST files are stacks of sections which can be validated independently and usually refer to one workflow step. Sections are appended at the end of an existing file, so no previous data is changed. This is related to incremental writing of PDF [4] files. If you want to add on to a VHIST file containing information about previous workflow steps (this is recommended) you need to specify a VHIST root file (this can be any VHIST file).

The vhistadd implementation uses the terms reported and embedded, meaning similar but slightly different things.

A reported file is a file whose file properties are reported in the automatically generated XML summary [1] (which contains structured information on one workflow step and is suitable for automated processing) and in the corresponding "human-readable" PDF part of the VHIST document.

An embedded file's properties are also listed in the XML summary and the PDF listing. However, in this case the contents of the file are also completely contained in the VHIST document, either in compressed or uncompressed form.

Embedded files can be extracted by various means, e.g. with a PDF browser, VHISTzard, vhistxs, vhistxl. You can embed binary data in VHIST files.