===========================
2D MINKOWSKI TENSOR PACKAGE
===========================

This program calculates the Minkowski valuations of planar shapes.

The program uses an external library called "Eigen" for the vector subroutines.
For your convenience, the relevant headers are included in this package.
"Eigen" can be obtained from

    http://eigen.tuxfamily.org

and is available under the GNU General Public License.

The program uses an external library called "GetOpt_pp" for parsing the command
line.
For your convenience, the relevant headers are included in this package.
"GetOpt_pp" can be obtained from

    http://code.google.com/p/getoptpp/

and is available under the GNU General Public License, version 3.


==================
BUILDING & TESTING
==================

Type "make" to compile Papaya.

Type instead "make DEBUG=0 clean all" to create a version without debugging
code.  Normally, this is not necessary as Papaya is relatively quick.

Type "make test" to run the (currently minimal) testsuite.


==========
INVOCATION
==========

Parameters to Papaya are set in a configuration file.  A commented example
can be found in "papaya.conf", some more in the "demos" folder.

By default, Papaya uses the values found in the "papaya.conf" file.

Some command-line flags are supported to overide values there, for ease
of scripting.  To load a configuration file different from the default:

    papaya -c another.conf

Use a configuration file, but override the input file and output path:

    papaya -c a.conf -i input.poly -o outputdir

You can also override the segmentation threshold using the --threshold
argument:

    papaya -i input.pgm -o outputdir --threshold 0.5


=====
DEMOS
=====

There are a number of demos on how to use Papaya in the demos/ folder.

1. Poisson-Voronoi cells   (demos/voronoi)

Creates a realization of a Poisson point process, and calculates the Minkowski
Tensors of its Voronoi diagram.  Driver script written in Python, uses qhull
(qhull.org) to calculate the Voronoi diagram.

2. Writing .poly data  (demos/poly_circle)

A small script that produces a circle in .poly file format, and a Papaya .conf
file to calculate all the tensors.

==========================
REQUIREMENTS ON INPUT DATA
==========================

Input data can be provided either in pixelized form, i.e. as a 
digital image with square pixels or as a series of polygons.
Currently, the code processes images in .pgm format and reads
polygons out of .poly files.  Further readers can be written
by the user.

The data to be analyzed should be free of singular entities like
 contours consisting of a single vertex
 contours having edges with length zero
 contours having inflections of pi or minus pi

Data generated from pixelized images via marching squares algorithm does
not have such problems.  There is code to "fix" existing data which
has features like the above by deleting the offending vertices (see
function fix_contours).


=================================
DOCUMENTATION OF POLY FILE FORMAT
=================================

A .poly file consists of two sections, separated by the keywords "POINTS",
"POLYS", and "END".

The second section defines the actual polygons.  Each polygon is introduced by
a number, and a colon (:), followed by references to the vertices (integers >=
1) in counterclockwise order.  Finally, to indicate a closed polyon, the
character "<" terminates the line.

Non-closed polygons are presently unsupported; Papaya ignores the request to
construct an open polygon and constructs a closed one.

Vertices in clockwise order describe a hole in a body (an inner contour as
opposed to the outer contour).

The actual coordinates of each vertex are defined in the first section; again,
each vertex is introduced by a number and a colon; coordinates are given as
floating-point numbers, and the third component (z) is zero.

Minimal example of a file describing a quadrilateral:

POINTS
1: 2.00000000000000000000e+00 1.00000000000000000000e+00 0.
2: 1.00000000000000000000e+00 1.50000000000000000000e+00 0.
3: 0.00000000000000000000e+00 1.00000000000000000000e+00 0.
4: 9.99999999999999777955e-01 5.00000000000000000000e-01 0.
POLYS
1: 1 2 3 4 <
END

There is example code how to write a simple .poly file from Python in the
testdata/mkcircle script.


================================
DOCUMENTATION OF PGM FILE FORMAT
================================

These files are plain portable graymaps / bitmaps (*.pbm, *.pgm), as introduced
by the netpbm package ages ago.  Most graphics software can write this format,
e.g. ImageMagick, GIMP.

On most unixoid systems (Linux, Mac), you can use the convert command to produce
PGM images.

    convert a.png a.pgm

Note that pixelization inherently introduces artificial anisotropy.  If you can
avoid pixelization, you should provide .poly input to Papaya.


==============
KNOWN PROBLEMS
==============

0. Documentation incomplete, and I know it.  I'm sorry.  If you have a
   problem using this package, don't hesitate to contact me.

   sebastian.kapfer@fau.de


===============
ACKNOLEDGEMENTS
===============

Thanks to:  Gerd Schroeder-Turk, Michael Klatt, Walter Mickel, Matthias
Hoffmann.


=========
CHANGELOG
=========

version 1.8
 * documentation updates.

version 1.7
 * fix reading of multi-line comments in PGM files.

version 1.6
 * fix compilation of Eigen with later GCC (4.7 and up)
 * fix the comment at the top of the tensor* files produced by PAPAYA.
   it previously said eval1/eval2 eventhough the value was eval2/eval1.
 * new --compute option; this allows to save only a subset of the computed data
   to disk.  for example papaya --compute tensors,scalars would compute the
   tensors and scalar functionals, but not the vector functionals, and not
   write the "contours.gp" and "labels.gp" GNUPLOT scripts.
   valid values include:  scalars, vectors, W020, W120, W220, W102, W211,
   contours, labels, tensors (= shorthand for W020,W120,W220,W102,W211)
   the default is to write everything to disk.
 * fix a bug causing the message
        'Inconsistency found while intersecting line/point'
   on some pixelized inputs.  The reason was a flawed test consistency
   test retained from a development version.
 * Papaya will refuse to do center of curvature reference points when
   curvature vanishes for some labels.

version 1.5
 * fix the odd number of intersects numerical problem when processing
   pixelized data in by_domain mode; it is no longer necessary to use
   fudged coordinates for the clipping box.
 * fix W020 labelling in by_domain mode -- this was broken as a result
   of the previous bug.  this affected only the W000, W010, W020 tensors.
 * normalization of the Minkowski functionals can be changed to the 'new'
   style by using --normalization=new.  Default is still unnormalized.
 * Papaya can create directories for the output prefix now.
   Set [output] mkdir = true.

version 1.4
 * read binary PGM images (previously only ASCII) and PBM images
 * add error checking to Poisson-Voronoi demo
 * increase maximum number of labels (you can always set an even larger number
   by choosing the constant MAX_LABELS in minkval.h)
 * fix a warning, better error messages, remove spurious header file
 * in labels = by_domain mode, output the centers of the domains to 
   a separate output file
 * in labels = by_domain mode, the numbering of the labels was broken
   when domainsx != domainsy.

version 1.3
 * add Poisson-Voronoi demo.
 * fix compilation issues (missing header)
 * add version number to the output files produced
 * more docs

version 1.2
 * fix compilation on cygwin by using a custom isnan
 * fix a testcase lacking a directory
 * remove debugging messages

version 1.1
 * fix bug in W020 tensor

version 1.0
 * initial public release