psLib Image Processing Library

0.6.0

Introduction

This library contains the Pan-STARRS Image Processing Pipeline (IPP) common library, psLib. The intended use is to provide a set of basic software functions in which can be used throughout the Pan-STARRS project to simplify programming tasks. Among the benefits are:

Reuse of code
Simplification of testing
Streamlining of code
Isolation of functionality that may be subject to change

The capabilities provided by psLib are grouped into the following areas which are also reflected in the file system directory structure:

System Utilities
Data Collections
Image Operations
Data Manipulation
Astronomy

This list is sorted in hierarchical order: The later entries depend on the functions and data types of the earlier entries.

The installed code for psLib consists of header files and binary libraries in the form of static and/or shared library, depending on the configuration options. To assist in using the library, a script "pslib-config" is supplied that provides the compiler and linker options.

3rd Party Libraries

Before building psLib from source, several 3rd party software libraries must be installed. These include:

GNU Scientific Library (GSL)
- Available at http://www.gnu.org/software/gsl
- Compatibility tested with version 1.4
Fastest Fourier Transform in the West (FFTW), version 3, with single-precison float support
- Available at http://www.fftw.org
- Compatibility tested with version is 3.0.1
- The '--enable-float' option is required in the configure step to enable single-precision float support. Use 'configure --help' for more information of the configuration options for this library.
C Flexible Image Transport System Input output (CFITSIO), version 2.480 or later
- Available at http://heasarc.gsfc.nasa.gov/docs/software/fitsio
- Compatibility tested with version 2.490, requires at least 2.480
Gnome XML C parser and toolkit (libxml2)
- Available at http://www.xmlsoft.org
- Compatibility tested with version 2.6.12 and 2.6.16

Though not required to build the base library, several 3rd party software libraries are needed for particular functionality.

Doxygen Documentation System
- Required for creation of documentation
- Available at http://www.doxygen.org
- Compatibility tested with version 1.3.2 and 1.3.8
- The optional companion package, GraphViz (a.k.a., the 'dot' command), is recommended to enable header-file dependency diagrams
MySQL
- Required for database functionality
- Available at http://dev.mysql.com
- Compatibility tested with version 4.1.10a, requires at least 4.1.2
- A server running locally is required for testing.
Autoconf/Automake
- Required only if making from CVS
- Available at http://www.gnu.org/software/autoconf and http://www.gnu.org/software/automake
- Compatibility tested with version 2.59 (autoconf) and 1.9.2 (automake)

We recommend using the particular versions listed as compatibility tested, as that is the only versions of the external libraries tested to work well with psLib. Though it is quite possible that later versions of the libraries listed will also work as well, care must be taken when upgrading these libraries to verify that its functionality is compatible with the tested version.

How to Obtain the Source

Tested versions of psLib are put into a tar file and can be downloaded from:

https://mhpcc.pan-starrs.org/code/releases

Though MHPCC recommends using the released packaged tar files descibed above, both recent daily development snapshots and direct CVS access is available. The recent daily snapshots are available at:

https://mhpcc.pan-starrs.org/code/snapshots

These snapshots represents development code as found in CVS on the day specified in the filename. This code set may not be functional, vary in testing, etc. Reasonable efforts are made to ensure that the code does actually compile, but given the nature of code development, even that is not always the case. Use snapshots with great caution.

If one has a login account on mhpcc.pan-starrs.org, direct CVS access is possible. Example of the commands required for direct CVS retrieval are as follows:

$ cvs -d:ext:USERNAME@mhpcc.pan-starrs.org:/data/panstarrs/cvsroot co -r RELEASEBRANCH psLib

where:

USERNAME is your login name on the server
RELEASEBRANCH is the desired release branch, e.g. rel5.

How to Build and Test the psLib library

The source uses autoconf/automake to build control the build process. If, and only if, the source came from CVS or a CVS snapshot, the configuration script will have to be made via:

$ cd psLib
$ make -f Makefile.cvs

This creates the configure script and Makefile templates.

The recommended steps to build the library are:

$ cd psLib
$ ./configure
$ make
$ make check
$ make install

This builds, tests, and installs the library.

The configure step allows users to specify specific locations for the third party libraries (see "3rd Party Libraries" for a list), disabling of select functionality (e.g., database and perl module), installation location, etc. An enumeration of the options for configure, and the default values, can be obtained via "./configure --help".

Though 'make check' compiles and runs the test suite, one can also use custom scripts to run all the tests and just a particular test. To run the unit test suite, do the following:

$ cd psLib/test
$ ./FullUnitTest

This has the advantage over 'make check' in that it does not stop when a test fails and it collects some very basic statistics on the results. To run a particular test, do the following:

$ runTest testfilename

How to Create Code Documentation

Both HTML and man page documentation may be generated from the inline documentation embedded in the code using the following commands:

$ cd psLib
$ make docs

This places documentation in PREFIX/docs/psLib, where PREFIX is set using the configure script.

Also, a prebuilt set of code documentation for both the releases and last CVS snapshot can be found at:

https://mhpcc.pan-starrs.org/docs/

Generated on Wed Jun 15 11:00:56 2005 for Pan-STARRS Foundation Library by

1.4.1