pfstools 2.1.0 <13.11.2017>

This release adds support for .yuv video files encoded as PQ2020 or
HLG2020 (used by the reference implementation of h265). pfsview was
updated to used Qt5 instead of Qt4. Several compilation issues on
Ubuntu have been resolved.

	* Added: pfsinyuv/pfsoutyuv to handle uncompressed video .yuy
	* Added: Support for PQ2020 and HLG2020 color spaces (in pfs*yuv)
	* Added: pfsview now builds with Qt5 instead of Qt4
	* Fixed: pfsglview crashing on OSX (thanks to Michael)
	* Fixed: issues with compiling matlab MEX functions on Ubuntu
	* Added: installation instruction for Ubuntu (README.Ubuntu)
	* Added: experimemtal version of deghosting in pfshdrcalibrate (poor performance)


pfstools - README
-------------------------------------------------------------------

For issues related to Mac OSX installation - see README.OSX

For issues related to Windows installation - see README.Cygwin

For specific notes on Matlab installation - see README.matlab

For compilation with Visual Studio (experimental) - see README.VisualStudio

pfstools is a set of command line (and two GUI) programs for reading,
writing, manipulating and viewing high-dynamic range (HDR) images and
video frames. All programs in the package exchange data using unix
pipes and a simple generic HDR image format (pfs). The concept of the
pfstools is similar to netpbm package for low-dynamic range images.

pfstools offers also a good integration with GNU Octave and
matlab. pfstools can serve as a matlab or Octave toolbox for reading
and writing HDR images.

pfs in not just another format for storing HDR images. It is more an attempt to
integrate the existing HDR image formats by providing a simple data format that can
be used to exchange data between applications.

If you use the software for your research work, please consider citing
the paper:

Rafal Mantiuk, Grzegorz Krawczyk, Radoslaw Mantiuk and Hans-Peter Seidel.
High Dynamic Range Imaging Pipeline: Perception-motivated Representation
of Visual Content.
In: Proc. of Human Vision and Electronic Imaging XII. 649212.

@inproceedings{mantiuk:2007:hvei,
 author = {Mantiuk, Rafa{\l} and Krawczyk, Grzegorz and Mantiuk, Rados{\l}aw and Seidel, Hans-Peter},
 editor = {Rogowitz, Bernice E. and Pappas, Thrasyvoulos N. and Daly, Scott J.},
 title = {High Dynamic Range Imaging Pipeline: Perception-motivated Representation of Visual Content},
 booktitle = {Human Vision and Electronic Imaging XII},
 publisher = {SPIE},
 year = {2007},
 volume = {6492},
 number = {649212},
 series = {Proceedings of SPIE},
 address = {San Jose, USA},
 month = {February},
}

The paper is an introduction to both pfstools and HDR imaging in
general. It can be downloaded from:

http://pfstools.sourceforge.net/papers/mantiuk07hdr_pipeline.pdf

1. Compilation
-------------------------------------------------------------------
Is is strongly recommended to compile into an out-of-source directory:

cd <pfstools_dir>
mkdir build
cd build
cmake ../
make

If the compilation fails because of a missing library, you can disable the offending component by setting WITH_<component_name> to false. For example:

cmake -DWITH_MATLAB=false ../

to disable matlab support.

If you encounter any problems during compilation, run the make again with the option:

make VERBOSE=1

or, if you use nmake on Windows:

nmake /S

and report the problem with the complete error message to the google discussion group:

https://groups.google.com/forum/#!forum/pfstools

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

doc - documentation
src - all sources go there
  pfs          - pfs library (used by all tools)
  fileformat   - readers and writters for various file formats
  filter       - a range of "filters" from resize to changing color space
  octave       - GNU Octave scripts and libraries
  matlab       - matlab mex sources and functions
  pfsview      - qt application for viewing hdr images and other data
                 that can be stored in the pfs stream
  pfsglview    - similar as pfsview, but uses OpenGL & GLUT instead of Qt
  tmo          - contains tone-mapping operators (formerly pfstmo package)
  camera       - contains HDR merging and camera calibration tools
                 (formerly pfscalibration)
  hdrhtml      - makes HTML5 web-pages with viewable HDR images
  getopt       - used on Windows to compile using Visual Studio
  debian       - scripts to create Debian distro package. The scripts has not been updated and currently is not
                 working.


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

pfstools relies on a large number of libraries and other dependencies. However, the build script was designed to succeed even if some dependencies are missing. In that case, the tools that rely on those dependencies will not be compiled. If building with a certain dependency causes problems, it is possible to manually switch off that component by passing -DWITH_??=false to cmake.

Note that the development packages must be installed for all dependencies. They usually have '-dev' suffix.

Below is the list of all dependencies requires for pfstools. They are more or less given on an order of importance.

OpenEXR
	CMake switch: WITH_OpenEXR
	Tools: pfsinexr, pfsoutexr

ImageMagick
	CMake switch: WITH_ImageMagick
	Tools: pfsinimgmagick, pfsoutimgmagick
	Used to read/write most LDR files. Required for 16-bit file support. "pfsin"/"pfsout" will use NetPBM if ImageMagick is not available

NetPBM
	CMake switch: WITH_NetPBM
	Tools: pfsinppm, pfsoutppm, (pfsindcraw)
	Alternative method of reading/writing LDR images. Note that this package is also required for pfsindcraw as ImageMagick cannot handle files read from unix pipes.

TIFF
	CMake switch: WITH_TIFF
	Tools: pfsintiff, pfsouttiff
	TIFF images can also be read with pfsinimgmagick. This is a custom reader/writer, which supports LogLuv TIFF HDR image format.

QT 5
	CMake switch: WITH_QT
	Tools: pfsview
	"pfsview" is a primary HDR image viewer.
	If Qt library is not found, you need to specify the path to its cmake configuration files:

		cmake -D "CMAKE_PREFIX_PATH=~/Qt5location/qt5/5.7/gcc_64/" ../

OpenGL, GLUT (or FreeGLUT)
	CMake switch: WITH_pfsglview
	Tools: pfsglview
	pfsglview is a "backup" or alternative viewer. It is missing some features of pfsview, but offers faster zooming.

Matlab (mex)
	CMake switch: WITH_MATLAB
	Tools: all matlab scripts in src/matlab
	Note that you need to set matlab path to <install_dir>/share/pfstools/matlab

Octave
	CMake switch: WITH_Octave
	Tools: All Octave scripts in src/octave
	There are still some unresolved issues running Octave scripts under cygwin.

FFTW
	CMake switch: WITH_FFTW
	Tools: acceleration in pfstmo_durand02 (the TMO will be *very* slow otherwise)

GSL
	CMake switch: WITH_GSL
	Tools: pfstmo_mantiuk08
	The GSL math library is required for this TMO.

OpenCV
	CMake switch: WITH_OpenCV
	Tools: pfsalign
	Note that pfsalign requires SURF features, which are available on "nonfree" part of the library. Since part of the library is currently not included in most Linux distributions, so you will need to compile OpenCV from sources.

dcraw
	CMake switch: none
	Tools: pfsindcraw
	Download code from: http://www.cybercom.net/~dcoffin/dcraw/

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

First check the list of frequently asked questions in
./doc/faq.txt. Then browse relevant manual pages, which accompany each
program. The documentation for the pfs library API can be generated
with DoxyGen or found in the header files. If you want to include
reading or writing of pfs streams in your applications, refer to
./doc/pfs_format_spec.pdf.

pfstools can be compiled under Windows from the cygwin
environment. You can download cygwin from: http://www.cygwin.com/

You may need to install X window client to use pfsview or
pfsglview. Possibly a better alternative is to use a natively compiled
version of pfsview:
https://sourceforge.net/projects/pfstools/files/pfstools_visual_studio_incomplete/

Check README file for the complete list of dependencies.

OpenEXR library must be build from sources since no cygwin development
package is available. Sources can be downloaded from
http://www.openexr.com/. It is recommended to use cmake to compile
OpenEXR.

To compile pfstools from sources on OSX, you need:
1. XCode
2. Any of:
   Homebrew - http://brew.sh/ (recommended)
   Fink - http://www.finkproject.org/
   MacPorts - https://www.macports.org/

Refer to REAME file for the instruction on how to compile with cmake.

The build was tested to work on maxOS Sierra 10.12.6 on 13 Nov 2017 with Homebrew. The following notes can help get all dependencies recognized:

* Qt5: You need to add "-D CMAKE_PREFIX_PATH=/usr/local/opt/qt5" to cmake. The path should be pointing where the Qt5 is installed.


===== Image Magick =====

In case of problems with ImageMagick on Mountain Lion:

brew install libtool --universal
brew link libtool --force
brew install imagemagick --with-magick-plus-plus

pfstools is in the first order supported on Ubuntu as this is the OS we use on everyday basis.

The procedure below has been tested on Ubuntu 16.04 LTS

To compile pfstools on Ubuntu follow the steps:

1. Execute:

sudo apt-get install `cat ubuntu-packages-deps | tr '\n' ' '`

2. Install OpenCV with the "nonfree" modules

sudo add-apt-repository --yes ppa:xqms/opencv-nonfree
sudo apt-get update
sudo apt-get install libopencv-dev libopencv-nonfree-dev

3. If you want to install pfstools with Matlab support, follow the steps in README.Matlab

4. From the pfstools directory, execute:

mkdir build
cd build
cmake ../
make
sudo make install

pfstools can be compiled with Visual Studio using CMake build system. This file contains some troubleshooting hints.

Refer to README for details on building pfstools using CMake.

The compilation was tested with Visual Studio Express 2013.

Note that this compilation procedure is an alternative to using cygwin (refer to README.Cygwin).

=== QT ===
Download and install Qt4 (not Qt5) for Visual Studio from: http://qt-project.org/downloads

Then add entry to CMake variables:
QT_QMAKE_EXECUTABLE:FILEPATH=E:\Qt\4.8.5\bin\qmake
where E:\Qt\4.8.5\bin\qmake should be replaced with the path to qmake on your computer.

You may need to compile in Release mode. Otherwise some DLLs might be missing.

=== OpenEXR ===

Compiling OpenEXR on Windows with Visual Studio is not a task for faint hearted. Be prepared to fix quite a few issues with the code.

* If the compiler complains about missing "__builtin_trap()", add

#define PLATFORM_WINDOWS 1

to config/IlmBaseConfig.h

see

https://lists.nongnu.org/archive/html/openexr-devel/2013-12/msg00001.html

* If the compiler complains about "std::max", add missing include in all offending files:

#include <algorithm>

Other useful web pages:

http://buildopenexr.blogspot.co.uk/
http://blog.gmane.org/gmane.comp.video.openexr.devel

Matlab interface to pfstools can be found in src/matlab. It contains
both .m and mex functions, which need to be compiled before can be
used. Once pfstools is properly installed, you can browse help:

doc pfstools_matlab
or
cd <dir_with_m_and_mex_files>
doc ./Contents.m

If you have problems running some functions, you can execute (from matlab):

pfs_test_shell

to diagnose for common problems.

Follow the instructions below to install matlab interface to pfstools.

Linux, OSX and cygwin
=====================
cmake will search for matlab's mex scripts in typical locations. If it cannot be found, you need to pass the matlab directory to cmake:
	cmake -DMATLAB_ROOT=<path> ../

Matlab's MEX compiler commonly uses different version of gcc than is installed on the system. If this is the case, you may see messages, such as:

  Warning: You are using gcc version '5.4.0'. The version of gcc is not supported. The version currently supported with MEX is '4.7.x'. For a list of currently supported compilers see: http://www.mathworks.com/support/compilers/current_release.

Sometimes those warning can be ignored, other times mex commands will fail with "Invalid MEX-file". In the latter case, you need to install the correct version of the compiler:

sudo apt-get install g++-4.7

and then specify it when invoking cmake, for example:

cmake -DMEXGCC=/usr/bin/gcc-4.7 ../

After successfully compiling the code, add the directory INSTALLDIR/share/pfstools/pfstools_matlab to matlab path
  (File->Set Path).


Windows installation
====================

Note that matlab support on Windows has not been tested in 2.0.0. The notes below refer to 1.9.x version.

Under Windows you have to invoke NMAKE file manually. From ordinary DOS
shell (not cygwin), cd to src/matlab, then execute:

(path to your matlab instalation)/matlab/R2006b/bin/mex.bat -setup

mex.bat will ask to choose a configuration. Choose the one compatible
with your Visual Studio installation.

then execute:

NMAKE -f Makefile.win32

We tested compilation on Win32 with VS C++ compiler. cygwin and
pfstools must be installed. Then include this directory in matlab's
path (File/SetPath in maltab IDE menu). You may need to modify
pfs_shell() function that should return the command line for executing
'bash' from DOS shell.

Many matlab pfs_* functions need to execute shell functions, for
example pfsin. To make sure that they can be executed from matlab, all
environmental variables must be set. Currently this is done by the
pfs_shell function, which extends command line so that pfs* commands
are executed from bash (assuming that bash sets all necessary
environmental variables in .bashrc). If bash is not your default
shell, you may need to change this.


If no good-luck, then below is a loosely written trouble shooting:

1. From matlab, execute 'pfs_test_shell'. The function will perform a few tests
for the most common pfstools/matlab setup problems and will suggest the most likely
solution.

2. You can select a compiler for mex files using "mex -setup"

If you have more than one compiler, for instance you owe a Visual
Studio, then try various compilers. Sometimes things work with VC 8.0,
but not with VC 6.0, and sometimes the other way around.

3. If you want to compile with Visual Studio, use the "Visual Studio
200X Command Prompt" DOS shell.

Especially if "nmake" doesn't seem to be on your system.

4. All supplied Mex files do not depend on any library. So if you have
a problem within Matlab which looks like "The specified module could
not be found." it's not related to shared libraries. But it maybe
related to incompatible Visual Studio libraries, see point 1.

5. If you got everything running and type "pfsview(my_image)" and nothing shows up:

Check if X-Win32 or other X server is running, type "pfs_shell" in
Matlab and check if path is correct (and possibly adjust the path in
pfs_shell.m). Add a line to $HOME/.bash_login containing

"export DISPLAY=127.0.0.1:0"

6. Under Windows, if your Cygwin installation is not in c:\cygwin set Windows global variable:

CYGWIN_HOME='c:\MyDirectory\cygwin'

Of course, c:\MyDirectory should be replaced with a right path.


Known problems:

* Under Windows shell window flashes each time pfsput / pfsget command
  is executed

* pfs channel tags are not written to pfs-streams. No channel
  specific tags are written properly.

* Some file handles may not be closed properly.