This is a readme file for the PFS tools package.  
-------------------------------------------------------------------

!IMPORTANT note on upgrading applications from pfstools 1.1 to 1.2!

pfs library from pfstools 1.2 is 100% backward compatible with the
library from the previous version. However, the naming of the
pkgconfig file has changed. Thus if you used PKG_CHECK_MODULES macro
in your configure.ac script, you have to modify:
--------
PKG_CHECK_MODULES(PFS, pfs-1.0 >= 1.0,,
  AC_MSG_ERROR(pfstools package required. Download it from http://pfstools.sourceforge.net/))
--------
to
--------
PKG_CHECK_MODULES(PFS, pfs >= 1.2,,
  AC_MSG_ERROR(pfstools package required. Download it from http://pfstools.sourceforge.net/))
--------
Since the library API has been slightly extended, the version of the
library is changed from 1.0 to 1.2 (to be consitent with the version
of pfstools).
       
1. Compilation
-------------------------------------------------------------------

1.1 To build from a 'tar' archive:

> ./configure <options>

for example following command will configure PFS tools to be installed
in user's 'local/' directory:

> ./configure --prefix=$HOME/local --with-octave-dir=$HOME/local/lib

then compile

> make

and install

> make install

NOTE: When you specify a different compiler using for example
CXX=g++-3.2, libtool may incorrectly interpret compiler and use gcc
instead of g++ to link the pfs library. This results in reallocation
error in programs that link dynamically to that library. This is
probably a bug in the libtool.

NOTE: Automake 1.6 or later is required!
        
1.2 To build from CVS:

> ./reconf

or

> libtoolize
> aclocal
> autoheader
> automake --add-missing
> autoconf

then proceed as in the case of the 'tar' archive distribution. You may
need to experiment with different versions of automake, aclocal and
autoconf (automake-1.9, aclocal-1.9 and automake2.50 work on Debian).

2. Directory Layout
-------------------------------------------------------------------

doc - documentation
src - all sources go there
  pfs          - pfs library
  fileformat   - readers and writters for various file formats
  octave       - GNU Octave scripts and libraries
  pfsview      - qt application for viewing hdr images and other data
                 that can be stored in the pfs stream


3. Dependencies
-------------------------------------------------------------------

Some of the pfs tools require external libraries to be built. As
reusing as much of existing code as possible is quite reasonable, it
also causes quite a lot of problems when linking with several
libraries that come in different versions. To alleviate some of such
linking problems, the configure script of the pfs tools disables
compilation of those applications for which the external libraries can
not be found. Consequently, some of the pfs applications may not be
installed after 'make install', even though the compilation was
successful.

A list of external libraries and applications that depend on them:

libtiff  - pfsintiff, pfsouttiff
libpbm   - pfsinppm, pfsoutppm
        http://netpbm.sourceforge.net/
ImageMagick++ - pfsinimgmagick, pfsoutimgmagick
        http://www.imagemagick.org/script/index.php
jpeghdr - pfsinjpeghdr, pfsoutjpeghdr
        jpeghdr library can be found on the DVD included with the book
        "High Dynamic Range Imaging: Acquisition, Display, and
        Image-Based Lighting" by Erik Reinhard, Greg Ward, Sumanta
        Pattanaik and Paul Debevec. (The Morgan Kaufmann Series in
        Computer Graphics)       
openexr libraries - pfsinexr, pfsoutexr
        http://www.openexr.com/
mkoctfile (for building Octave's modules) - pfsread.oct,
           pfswrite.oct, pfstransform_colorspace.oct
libqt    - pfsview
        http://www.trolltech.com/
dcraw - pfsindcraw
        http://www.cybercom.net/~dcoffin/dcraw/


3. Documentation
-------------------------------------------------------------------

First check the list of frequently asked questions in ./doc/faq.txt. A
manual page accompanies each tool from the package. Simply enter 'man
<command_name>' to get some help. For pfs library API documentation
check DoxyGen documentation or header files. If you want to include
reading or writing of a pfs stream in your applications, refer to
./doc/pfs_format_spec.pdf.
