/** @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
 - 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, 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 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
     - Available at http://star-www.rl.ac.uk/
     - Compatibility tested with package version number 2.4-12
     - 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.
 - Gnome XML C parser and toolkit (libxml2)
     - Available at http://www.xmlsoft.org
     - Compatibility tested with version 2-2.6.16-3

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, rel3, or rel4.


@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>

The make system of psLib allows users to specify specific locations for some of the
third party libraries (see "Required 3rd Party Libraries" for a list).  If
a location is not specified, the cooresponding library is assumed to be in
the standard library paths, e.g., /usr or /usr/local.  The following are the
environment variables that can be set before the make process above to force
the location of the third-party libraries:
  - sladir: Location of SLALIB
      - e.g., <pre>export sladir=/usr/local/star</pre>
  - xml2config: Location of the xml2-config configuration executable
      - e.g., <pre>export xml2config=/usr/bin/xml2-config</pre>

Also, the installation location of the library can be set using environment
variables.  The following are the supported variables for installation:
  - prefix: the installation prefix (default: current psLib directory)
      - e.g., <pre>export prefix=/usr/local</pre>
  - mandir: The man page installation location (default: $prefix/man)
  - includedir: The installation location for the header files (default: $prefix/include)
  - testbindir: Location for the test executables (default: $prefix/testbin)
  - libexecdir: Location for the library files (default: $prefix/lib)
  - TIME_CONFIG_FILE: Location of the 'psTime.config' configuration file (default: $(prefix)/config/psTime.config)

@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/

*/
