Planetary Image Research Laboratory

Department of Planetary Sciences
University of Arizona
Tucson, Arizona

xv image viewerwith PIRL enhancements

The xv software is
copyright by John Bradley.
It is redistributed here in unregistered form with permission.
This distribution is version xv-3.10a with patches applied and the PIRL
enhancements included.

The primary PIRL enhancement provides a module (xvPVL.c) that
implements the LoadPVL function. This module is designed to load any
PVL (Parameter Value Language) formatted image file, but does not
provide a save/write function. PVL is used by the Planetary Data System as a
"standard" for the distribution of products (primarily image files, but
there are other types) associated with spacecraft science missions.
Though there is a formal specification for PVL to be used with PDS
products, it has not been implemented consistently in the software that
produces the products for each mission. This has resulted in the
proliferation of software programs that are only able to handle the PDS
products associated with their mission. The xv program is very popular
in the Planetary and Space Sciences communities (e.g. there is a FITS
module for astronomical files) and so a module - xvPDS - was developed
to load PDS product imagery into xv. Over time, as modifications were
added to deal with the peculiarities of each PVL implementation, this
module came to be a cacophony of conditionals and cruft.

In the summer of 1998 I accepted the task of adding support for yet
another PVL implementation to the xvPDS module. I found that the xvPDS
module was employing an ad hoc file label parsing mechanism and had
hard-wired parameter names infused throughout the code. My efforts to
find a PVL library that could replace this with an easier to manage API
were unsuccessful: no PVL library that I found was able to handle all
of the PVL flavors.

So I decided to implement a PVL library that would be resilient enough
to handle any PVL implementation with minimal (and non-modal) knowledge
of the peculiarities of any particular flavor, be completely
independent of the contents of the PVL, take its input from an external
file or an internal buffer, output formal PVL according to the language
specification document, provide a simple yet complete and extensible
API, and offer tunable environment controls to the application. The
result was the
PIRL Parameter Value Logic (PPVL) library. PPVL has been proven
successful at reading all PVL files it encounters. This includes the
Pascal-like binary sized (a.k.a. variable length) records of the
Voyager products, VICAR labels that lack a (required) END statement,
etc. It will even provide a PVL interpretation of this file (up to the
word "END" in the previous sentence :-). The design philosophy of the
PPVL module is to provide the application with whatever can be provided
by a tolerant (or strict, if desired) PVL interpretation of the input
in a form, and with the tools, to make it easy to determine what is
useful to the application.

The PPVL library, included in the xv-PIRL distribution, is used by the
xvPVL module. Because the burden of dealing with the peculiarities of
various PVL implementations was removed, the xvPVL module was able to
grow much more sophisticated in its handling of the PVL file contents.
A table lists the parameter names that contain data values that are
converted into internal binary variables used by the program. Multiple
parameter names, from different products, may be associated with a
single variable (it's also possible to have the same parameter name
associate with more than one variable). When a new image file is
encountered with unexpected parameter names these names can be simply
entered into the table in association with the appropriate program
variable. Usually that is all that is required to teach xvPVL about a
new product.

The xvPVL module is able to handle a very wide variety of image data
structures. It can handle certain specialized compressed data (currently
vdcomp, clemdcmp and readmoc); signed and unsigned integer data up to
long precision, and floating point data up to double precision (but
only IEEE format, not VAX [until there is a demand]); byte swapped
data; selective data scaling of multi-byte data (xv only uses 8-bit
data for display); and band selection for multi-band data. Various
descriptive data is provided in the "image comments" window. However,
this may not have the info that you are looking for. The PPVL_report
utility can provide anything and everything that is contained in a PVL
label. Documentation for this utility, along with documentation on the
entire PPVL distribution, can be found in the PPVL/doc subdirectory.

Because the PVL in an image file primarily specifies scientific
meta-data associated with the image data, this format is used in
research application contexts that provide all of the parameter names
and their values. Therefore there has been no interest in providing the
capability to write image files using this format in the context of a
generalized image display program.

As of the PIRL v2.1 enhancement, USGS Digital Elevation Model (DEM)
input capability has been added. The USGS_DEM.{c.h} files are
standalone files for a USGS DEM file input API. These are used in
the implementation of the xvDEM module.

As of the PIRL v2.3.4 enhancement the Makefile/config.h structure has
been revised somewhat (what is really needed is proper autoconf
support). The config.h file no longer needs to be edited as all of its
options can be set in the Makefile. The config.h file was primarily
used to specify the command lines for the gunzip or uncompress
utilities for decompressing files to be displayed and the ghostscript
(gs) PostScript interpreter to render into a generic raster image
format. To facilitate changes to the xv operating environment (e.g.
when using a binary distribution of xv-PIRL) the main xv code has been
slightly modified to allow these utility command lines to be specified
at run time in several ways (see the config.h file for details). If the
utility commands are not specified their corresponding capabilities
will simply not be available; a capability can be turned off at run
time, even if a command line had been set when xv was compiled, by
specifying the empty string ("") for the corresponding utility command.
The Makefiles now have sections that can be used to build xv with
system supplied JPEG, TIFF, PPVL, PNG and zlib libraries rather than
using the distributions for these libraries that are bundled with xv
(the latter are static libraries, while the former may be shared
dynamic versions). The xvpng add-on module has also been incorporated for
PNG image file support.

N.B.: The xv-PIRL distribution includes several operating system
targeted Makefile files using gmake syntax that have been used at PIRL
to build xv for use on the corresponding operating systems. However,
there is certainly no certainty that any Makefile will work on any
system. While some effort has been made to ease the configuration
specification process in the Makefiles, they do not provide the ease of
an autoconf setup (it would be great if someone would do this). The
original Makefile.std and Imakefile files are available along with John
Bradley's INSTALL description text. All of these are very dated (as is
indicated by the last entry in John's CHANGELOG dated 12/29/94) and
unsupported at PIRL.

Caveat: The xv software must be registered for all but personal
use (see the README by John Bradley in the distribution). All the
software in this distribution is provided to you as-is with no warranty
of fitness whatsoever. If it works for you, great! If not, you can
complain to the author who may try to help. To encourage the author's
help it is strongly advised that a detailed problem description be
included with your complaint and that you be willing to work with the
author in coming to some resolution.