/** @mainpage psLib Image Processing Library


@section intro 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, and 
 - 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 (libpslib.a) and shared (libpslib.so or libpslib.dylib, 
depending on operating system.) Assuming these components have been built and 
installed in the standard library path, psLib may be used within a program by 
including the line #include <pslib.h> and linking using the '-lpslib' option
while linking.


@section extinstall Required 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 is 1.4
 - Fastest Fourier Transform in the West (FFTW), version 3
     - Available at http://www.fftw.org
     - Compatibility tested with version is 3.0.1
 - 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 is 2.490
     - Versions earlier than 2.480 will not work as new functionality introduced in 2.480 is exercised
 - Doxygen Documentation System
     - Available at http://www.doxygen.org
     - Compatibility tested with version 1.3.6
     - The optional companion package, GraphViz (a.k.a., the 'dot' command), is recommended to enable header-file dependency diagrams
 - SLALIB 
     - We tested with the Fortran version of the library; this may cause an additional step to get things to link on untested systems/compilers, as there is no one standard for how the function-names appear in the library to C code.  The default way that psLib uses is all-lower case with a trailing '_', but one may need to add to CFLAGS in src/Makefile.Globals the following:
         - '-DFORTRAN_UNDERSCORE_PREFIX' if a '_' needs to be prefixed to the function names,
         - '-DFORTRAN_DOUBLE_UNDERSCORE_SUFFIX' if two the names needs two trailing '_'s., and/or
         - '-DFORTRAN_UPPERCASE' if the names appear as uppercase.
     - Available at http://star-www.rl.ac.uk/
     - Compatibility tested with package version number 2.4-12

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.

@section install How to Build from 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 daily development snapshots and direct CVS access is available.  The 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:
<pre>
$ cvs -d:ext:USERNAME@mhpcc.pan-starrs.org:/data/panstarrs/cvsroot co -r RELEASEBRANCH psLib
</pre>
where:
  - USERNAME is your login name on the server
  - RELEASEBRANCH is the desired release branch, e.g. rel1, rel2, etc.
    

@section build How to Build the psLib library.

The source should build using the Makefile in the psLib/src directory.  The
recommended steps are:
<pre>
$ cd psLib/src
$ make
$ make install
</pre>
<i>This builds and installs files to psLib/lib and psLib/include.</i>


@section run How to Build and Run Tests

Since psLib is a library, there is no executable, per se. However, to test the 
installation, users may execute the unit test suite.  To build the unit test
suite, do the following:
<pre>
$ cd psLib/test
$ make
$ make install
</pre>
<i>This builds and installs the unit test files to the psLib/testbin directory.</i>

To run the unit test suite, do the following:
<pre>
$ cd psLib/testbin
$ ./FullUnitTest
</pre>
or to run a particular test
<pre>
$ ./runTest testfilename
</pre>

Note: one can also fun the FullUnitTest from anywhere within psLib/test
without performing the above 'make installtests' command first.  To do this,
one needs to first set the PSLIB_ROOT environment variable to the top psLib
directory 'psLib'.  FullUnitTest will search for tests in the subdirectories
the the execution directory, perform a build of them (via 'make'), and run them.
This can be useful if one wants to tweak the test code and doesn't desire to
perform an install of all the tests each time the test file is touched.


@section doc 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:
<pre>
$ cd psLib/src
$ make docs
</pre>
<i>This places documentation in psLib/docs.</i>

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/

*/
