PDS_JP2: Binary Distribution Installation

This is the description of the installation process for the binary distribution of the HiRISE PDS_JP2 software subsystem.

Documentation:

Documentation files in HTML format are included in the docs directory. The software Overview (also found in docs/html/HiRISE/PDS_JP2/index.html) is the best place to start. The collection of documentation files is not location dependent; they can be moved wherever is appropriate for the local site. The documentation contains links to the Planetary Image Research Laboratory (PIRL) web site where the documentation for dependent support libraries is located.

Install procedures:

The name of the distribution package filename will indicate on what kind of system the binaries were built. The format of the filename is:

PDS_JP2-<version>_<OS>-<arch>.<pkg>

where <version> is the version number of the PDS_JP2 distribution and <OS> and <arch> are the operating system and hardware architecture used to build the distribution. <pkg> is the type of distribution package which may be a gzipped tar archive (tar.gz) or a Mac disk image (dmg).

Note: The link names of the package files on the download web page do not include the <version> in their names; these links will get the current version of the software.

Mac disk image package -

For Apple Mac (Darwin) systems the disk image packages are probably the best choice that will be the easiest to install. After the disk image file has been downloaded it can be opened (by double-clicking or using the "open" command) if the browser does not do this automatically. The disk image contains a PDS_JP2-<version>_Darwin-<arch>.mpkg file which when opened, will run the GUI installer that guides the user through the installation process. The standard install will copy the libraries, applications and documentation to the lib, bin and docs subdirectories of the /usr/local directory, creating the directories as needed. Using the Customize option an alternative installation location can be specified. Note: The installer requires the user to provide system administrator authentication.

Tar archive package -

The tar archive packages are generic for all systems. After downloading the distribution file unpack the package into a convenient location:

tar xzf PDS_JP2-<version>_<OS>-<arch>.tar.gz

This will produce a PDS_JP2-<version>_<OS>-<arch> directory ($PDS_JP2_DIR for short). The distribution files can be used in place; no additional installation is required. However, it is usually convenient to install the distribution files in locations where application, library and documentation files are typically found, but these locations depend on the particular system and how it is being administered.

An Installer script is included that provides assistance in copying the distribution files to appropriate installation locations. To use it:

cd $PDS_JP2_DIR
./Installer

Prompts will be given for the library, application and documention installation pathnames. All pathnames will be confirmed writable by the user before the installation of the distribution files is completed.

An Uninstaller script is also provided that can selectively remove the application, library and documentation files. These scripts must be run in their original $PDS_JP2_DIR directory location along with the other files of the distribution package.

Run-time requirements:

The following sections provide details about the software run-time requirements, including configuring the user environment appropriately.

Applications -

These are command line user interface (CLUI) applications. The command line syntax usage and description of how they operate is located in the documentation. Just entering the application name to a shell will print a CLUI syntax summary; use the -Help option to get a complete syntax usage description.

The binary executable files for the PDS_to_JP2 and JP2_to_PDS applications are in the bin directory. They must be found in the command PATH of the user's shell.

One solution is to copy the application files to a system location where third party executables are usually found. This location is system dependent; the /usr/local/bin directory is a good posibility. You may need the assistance of a system administrator to do this.

Another solution is to set the PATH environment variable to contain the pathname to the bin directory in this distribution. For example, users of the csh shell (or one of its variants) might add the following lines to their .login file in their home directory:

if (-d $PDS_JP2_DIR/bin) then
  if ($?PATH) then
    setenv PATH $PDS_JP2_DIR/bin:$PATH
  else
    setenv PATH $PDS_JP2_DIR/bin
endif

For users of the Bourne shell (or one of its variants) the following lines added to their .profile file in the home directory are equivalent:

if [ -d $PDS_JP2_DIR/bin ] ; then
  if [ -z $PATH ] ; then
    export PATH=$PDS_JP2_DIR/bin
  else
    export PATH=$PDS_JP2_DIR/bin:$PATH
  fi
fi

After a login the command PATH will be set correctly.

These applications depend on the included libraries and the system libraries which are dynamically linked at runtime.

Libraries -

Other than system libraries all third party libraries on which the PDS_JP2 applications depend are included in the lib directory. The applications are dynamically linked to these libraries so the runtime linker must know where to find them.

As with the binary executable application files, one solution is to copy the libraries, and their linked names, to an appropriate location where third party libraries are usually found. This location is system dependent; the /usr/local/lib directory is a good posibility. You may need the assistance of a system administrator to do this. Alternatively, the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Apple's OS X operating system) environment variable may be set to contain the pathname to the lib directory in this distribution. This is done in the same way as was done for the PATH environment variable. Don't forget to use DYLD_LIBRARY_PATH instead of LD_LIBRARY_PATH on an Apple OS X (Darwin) system.

The system libraries should all be included as part of the operating system installation. Currently these operating systems and hardware architectures, with the listed system libraries, are supported:

Source code:

PDS_JP2 is open source software distributed under the terms of the GNU General Public License as published by the Free Software Foundation. A source code distribution should be available from the same site where the binary distribution was obtained.

Contact:

Questions or comments about the PDS_JP2 software may be sent to PDS_JP2@pirl.lpl.arizona.edu which will be delivered to the developer contact.

In general, when operational problems occur, an error message is provided describing the problem and identifying the software classes involved. Problem reports should include all this information. Comments and suggestions that could improve this application's usefulness are welcome.

Credits:

This software was developed at -

for the purposes of managing observation data sets produced by -

Copyrights:

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

The PDS_JP2 software is Copyright (c) 2006-2007 Arizona Board of Regents on behalf of the Planetary Image Research Laboratory, Lunar and Planetary Laboratory at the University of Arizona.


The Kakadu Software libraries are included in the binary applications distribution for use with the PDS_JP2 applications only. They are Copyright (c) Dr. David Taubman, all rights reserved, and licensed by NewSouth Innovations Pty Limited ACN 000 263 025 ("NSi"). Please visit the Kakadu Software web site (http://www.kakadusoftware.com/) for further information.