DOCUMENTATION FOR MINI-VICAR DISTRIBUTION
INTRODUCTION
------------
This software is a small subset of the VICAR image processing system, with
additions for Mars Express processing. VICAR is developed and maintained
by the Multimission Image Processing Lab at NASA's Jet Propulsion Laboratory
(JPL) in Pasadena, CA. See for details on
VICAR, or to get a complete version.
The Mars Express-specific programs ("hw" subtree) are maintained by the
Deutsches Zentrum fuer Luft- und Raumfahrt (DLR), Berlin-Adlershof, Germany.
This stripped-down version accomplishes three major tasks:
* Image display
* Image file format conversion
* processing for Mars Express HRSC images
The source code is also provided, together with scripts to build the software
under Solaris or RedHat Linux.
The image converter is written in Java, so it should run on any platform
that has Java 1.4.2 or later. Note that you may have to create your own
launcher scripts, though.
SYSTEM REQUIREMENTS
-------------------
This distribution has been built and tested on Sun Solaris 9 (SPARC)
and Red Hat Enterprise Linux (Intel x86).
While other versions of those operating
systems may work, they are not guaranteed.
You may be able to build the software on other operating systems, but no
support is provided for them.
X-windows and Motif is required to run the xvd display program. xvd is built
to use the standard Motif supplied with the operating systems.
Java (JDK) version 1.4.2 or later is needed to use the image file format
converter. In addition, Java Advanced Imaging (JAI) 1.1.2 or later, and
JAI Image I/O Tools 1.0 or later, are needed. These are generally installed
inside the JDK 1.4.2 tree. See the section on Java installation for details.
The converter is pure Java, so it should run on any platform which has a
JDK 1.4.2 (including Windows and Mac OS X). However, you will have to copy
the .jar files and set $CLASSPATH accordingly for these systems.
The Java code also requires Jakarta-ORO and Xerces from Apache, but the
necessary .jar files are included in the distribution.
C and C++ compiler are required to build the software.
A Fortran compiler is helpful, but not necessary. Solaris is set up to use
the Standard Sun-supplied (Workshop 5) compilers, while Linux is
set up to use the standard gcc/g++ compilers (3.2.3).
INSTALLING JAVA
---------------
If the image converter is to be used, Java, JAI, and the Image I/O tools
must be installed. These products all come from Sun Microsystems, and are
not included with the distribution due to space and licensing reasons.
It is possible that Sun might reorganize their website, so the links below
could break. If that happens, just look for the appropriate page to install
the given piece. The links are correct as of this writing.
JDK 1.4.2
The Java Developer's Kit (JDK) includes the Java Runtime Environment (JRE),
the compiler (javac), and other tools. The JRE is all that is really
required, but it is best to install the entire JDK.
The JDK is available at:
Click on J2SE 1.4.2 (or the latest version available). Installation
instructions are provided on the site, and with the download. In general,
you have a choice of installing the JDK in a system-wide, shared location,
or in a private directory. Either will work; which you choose depends on
your environment.
JAI 1.1.2
Java Advanced Imaging (JAI) is a standard "Optional Package" from Sun.
It provides advanced facilities for image manipulation. The current
release is available at:
Click on Java Advanced Imaging 1.1.2 Download, or the latest release.
Installation instructions are provided at the site. You again have a
choice of installing the package into the JDK, or keeping it separate.
Installing into the JDK is the recommended option. If you keep it
separate, you will have to set up $CLASSPATH and $LD_LIBRARY_PATH
(or Windows equivalent) in order to find the package. Note that JAI
includes native code but this is not required; there is a pure Java
implementation of all features. So if your platform is not on the
"supported" list (e.g. Mac OS X), that should not matter. As long
as you have a full JDK 1.4.2, it should work.
Image I/O Tools 1.0
The JAI Image I/O Tools is a separate package that provides image I/O
support for many common formats (including TIFF). It is a separate
download from JAI but shares much in common with JAI, including the
web site, option to install into JDK or keep separate, and native code
issues. See the JAI instructions above. It is (also) available at:
Click on Java Advanced Imaging Image I/O Tools 1.0 Download, or the
latest release.
INSTALLING MINI-VICAR
---------------------
The mini-VICAR distribution can be run directly from the DVD, or copied
to disk. To copy it to disk, simply use a tar copy:
% cd dataset/SOFTWARE
% mkdir
% cp *.ZIP
% cd
% unzip MINIVICAR.ZIP
% unzip GEOCAL.ZIP
% setenv M94GEOCAL /GEOCAL
% build_mini_vicar.csh `pwd`
% build_mini_vicar_java.csh `pwd`
If you want to minimize disk space, a run-time-only version can be created
by deleting the following directories (and their subdirectories):
external
vicar/MotifApp
vicar/gui/inc
vicar/gui/prog
vicar/gui/sub
vicar/hw/inc
vicar/hw/prog
vicar/hw/sub
vicar/olb
vicar/p1
vicar/p2/inc vicar/p2/sub
vicar/p2/prog
vicar/rtl
vicar/shell_vicar
vicar/stae
vicar/java
vicar/html/javadoc
They are only required for building. In addition, all binaries exist in
directories named for the platform, "sun-solr" or "x86-linux". You can
delete all such directories for the platform you are not using.
SETTING UP VICAR
----------------
Each time you log in, three commands must be issued to set up VICAR:
% setenv V2TOP /vicar
% source $V2TOP/vicset1.csh
% source $V2TOP/vicset2.csh
$V2TOP should contain directories such as p2, hw, and gui.
These commands can be put in your .cshrc if you wish. If you do so,
the following is recommended for efficiency:
if ($?V2TOP == 0) then
setenv V2TOP /wherever/vicar
source $V2TOP/vicset1.csh
endif
source $V2TOP/vicset2.csh
RUNNING VICAR PROGRAMS
----------------------
This covers running the "standard" VICAR programs label and the MEX processing
programs; xvd and the image converter are covered separately below.
It is important to remember that mini-VICAR is an extraction from a very large
(and much more complete!) system, so some of the rules to run programs may not
seem to make sense, but they generally do when viewed in the larger context.
Executables exist in one of two places:
$R2LIB (program "label")
$HWLIB (HRSC specific processing programs: hrfill,dlrto8,
hrortho,frameortho)
Run programs from the shell like any other...
% $HWLIB/hrortho ...parameters...
Parameters are specified using "shell-VICAR" conventions. These are
slightly different than the "TAE" command parser historically used with
VICAR programs (thus the examples in the help may not match exactly what
you'd actually type).
Each executable has a .pdf file associated with it in the same directory
(this is NOT an Adobe Portable Document File!). The top of the .pdf has
parameter definitions, while the bottom has program help. The help is
extracted into HTML in the documentation directory, but the parameter
listings can be useful to look at.
Parameters are specified positionally, or in a keyword=value format.
Positionally means you can just enter parameter values; each value is
assigned to the parameter in order. keyword=value allows you to enter
any keyword you want, without worring about the order. Once you start
with keyword=value parameters, the rest of the command line must stay with
that method.
So if the first four parameters are "inp", "out", "dtm", and "dirout", you
could enter them in several ways:
% $HWLIB/hrortho inp=a out=b dtm=c
% $HWLIB/hrortho a b c
% $HWLIB/hrortho a
% $HWLIB/hrortho a dtm=c out=b
Some parameters can take multiple values (their count is > 1). For these,
enclose the value in parentheses and separate the values with commas or spaces
Because of shell quoting rules, the parentheses themselves must be quoted or
escaped. For example:
% $HWLIB/dlr12to8 \(a,b,c,d\)
% $HWLIB/dlr12to8 "(a,b,c,d)"
% $HWLIB/dlr12to8 inp=\( a b c d \)
Some parameters are keywords. These can be specified using the normal
value rules. But a shortcut also exists: -value (like any other Unix
command-line switch). These can be mixed with keyword=value parameters.
For example:
% $HWLIB/dlr12to8 hisfile=yes
% $HWLIB/dlr12to8 -yes
% $HWLIB/dlr12to8 a out=b -no dnmin=50
Specifying strings to the programs sometimes can be tricky. Shell quoting
rules can get in the way at times. This is usually only a problem if the
strings contain spaces or other special characters.
The program "label" deserves special consideration. It is composed of
several "subcommands". Specify which subcommand you want with -subcmd
immediately after the program name, before any other parameters. For example:
% $R2LIB/label -list a
% $R2LIB/label -remove a b
For the purposes of this distribution, -list and -remove are the only
subcommands you're likely to need. label -list prints out the image label,
and label -remove removes it entirely, leaving you with a "raw" file of
nothing but pixels (sort of a poor-man's image converter) that is easy to
read in other programs.
The string quoting rules with label -add or -replace can get very tricky,
but since it is not likely you will need those, they are not discussed further
here. If you have a problem, contact one of the DLR or VICAR personnel.
RUNNING XVD
-----------
xvd is a Motif-based image display program specifically designed to work
well with very large images. It displays images in the VICAR format only.
(the full VICAR distribution also works with PDS images).
Somewhat out-of-date help on xvd is available at:
and can be brought up via the help menu, if your system is configured to
accept "netscape" as a command. However, the program is mostly self-
explanatory and little help should be needed.
Note that xvd should be in your $PATH, but if not, it can be found in
$GUILIB.
If you run xvd with no arguments, a load dialog pops up. Note that xvd
can load three separate files for a color image: red, green, and blue can
be either separate, or combined into one file.
xvd can be run with command line arguments. The most common is simply
the image to load:
% xvd image.dat
% xvd image.red image.grn image.blu
Note that the second and third filenames have a shortcut, if only the
extension changed:
% xvd image.red .grn .blu
Most of the Mars Express images contain 16-bit data. In order to convert
this to 8-bit data for display, a linear stretch is performed based on a
data range. This data range can be modified via the Edit/Data Range menu
item.
The default is for automatic determination of the data range. To do this,
xvd reads the entire image, looks for the maximum and minimum value, and
uses that for the initial data range. While this works well most of the
time, it can take painfully long when displaying a huge image, as is common
with Mars Express. In order to get around this, the minimum and maximum
data range can be specified on the command line, if they are known ahead
of time:
% xvd -min 0 -max 4095 image.dat
If the image contains map projection information, the latitude/longitude
under the cursor can be displayed by selecting Tools/Lat/Lon Display.
If this selection is disabled, proper map labels were not found in the
image.
The rest of the program should be pretty self-explanatory. Explore the
menus, and have fun.
RUNNING THE IMAGE CONVERTER
---------------------------
The image converter is a simple program based on Java 1.4's Image I/O Plugin
capability. It can read or write any kind of file for which there is a
registered plugin. JDK 1.4 comes with JPEG and PNG (and GIF for read-only).
JAI Image I/O Tools adds _many_ other formats including TIFF and PNM.
Mini-VICAR itself adds VICAR and PDS formats (actually, a subset of PDS
dealing with images only). If you have your own favorite format, simply
register it with Image I/O (which usually means just add it to your
$CLASSPATH - see the Image I/O documentation from Sun), and the converter
will be able to make use of it.
If you run the converter with no arguments:
% java jpl.mipl.io.SimpleConvert
It will print a usage message, as well as listing all of the available output
image types.
Running the program is simple: give it the input file, output filename, and
the format you want to convert to:
% java jpl.mipl.io.SimpleConvert file.vic file.tiff tiff
% java jpl.mipl.io.SimpleConvert file.jpeg file.png png
Note that TIFF files will be written with a strip size of 8. Other formats
use default tile sizes.
Much of the Mars Express data has 16 bits per pixel. Very few of the image
formats can handle this (most expect 8 bits per pixel). TIFF, VICAR, and
PDS do. If you get an error with some other format, this is likely the cause.
PROGRAM DOCUMENTATION
---------------------
HTML help for the VICAR programs is available in the distribution:
/doc/vichelp/index_p2.html
/doc/vichelp/index_hw.html
HTML javadoc help for the Java code is also available:
/vicar/html/javadoc/index.html