psLib Image Processing Library

1.0.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:

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

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

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:

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

We recommend using the particular versions listed as compatibility tested, as that is the only versions 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

If one has a login account on mhpcc.pan-starrs.org, direct CVS access is also 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:

How to Build and Test

The source uses autoconf/automake to build control the build process. If, and only if, the source came from CVS, the configuration script will have to be made first via:
$ cd psLib
$ ./autogen.sh
This creates the required 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 Install

To install the library using the prefix given in the configure step, execute in the top build directory:
$ make install

Building and Linking your code to the psLib library

To assist the use of the library with your own code, a configuration tool is part of the psLib library package. This tool, pslib-config, is installed in the BIN directory, according to the options given to the configure script.

The required CFLAG options for the compiler stage of code that uses psLib can be obtained via 'pslib-config --cflags'. This outputs the cc options that supplies include path(s) required to find the psLib headers.

The required linking options, can be obtained via 'pslib-config --libs'. This outputs the ld options that supplies the library paths and files required to link to the pslib library.

Note: pslib-config usage above refers to the install locations of the library. To link to the library directly in the build area, you need to use 'pslib-config --build-cflags' and 'pslib-config --build-libs' instead. These options will modify the output to point to the non-installed (build) locations of the include files and libraries. (this feature is experimental)

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 releases and can be found at:

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


Generated on Fri Feb 2 22:24:35 2007 for pslib by  doxygen 1.5.1