****************************************************************
      STREAMING COMPUTATION OF 2D DELAUNAY TRIANGULATIONS
****************************************************************

This document describes the binaries for streaming *2D* Delaunay
triangulation. There is another README_3D.txt that describes how
to use this software for Delaunay triangulation in 3D.

The binaries are in the .\bin directory. The source code is in
the .\tools directory. The source code makes use of the library
SPlib that is in the .\lib and .\libD directories. Corresponding
include and source files are in the .\inc and .\src folders.

The concept of "spatial finalization" is implemented in form of
an adaptive quadtree whose cells are declared "finalized" if no
downstream points fall into them.

Only the x and y coordinate of the input points are considered so
that spatial finalization and Delaunay triangulation happen in the
x\y plane. The z coordinate is the elevation during visualization.

******************************************************************
          A QUICK GUIDE FOR GETTING YOUR HANDS DIRTY
******************************************************************

open a command shell and go into the .\bin directory and then just
copy and paste the following into the command line:
 
spfinalize -i ..\data\lidar_band.txt.gz -o ..\data\lidar_band.spb

sp_viewer -i ..\data\lidar_band.spb 

press <p>

sp_viewer -i ..\data\lidar_band.spb -del2

press <p>

spdelaunay2d -i ..\data\lidar_band.spb -o ..\data\lidar_band.smb

sm_viewer -i ..\data\lidar_band.smb

press <p>

for another datasets try:

spfinalize -i ..\data\pt0366.txyzar.gz -itxt -parse sxyz -o ..\data\pt0366.spb

sp_viewer -i ..\data\pt0366.spb

press <p>

sp_viewer -i ..\data\pt0366.spb -del2

press <p>

spdelaunay2d -i ..\data\pt0366.spb -o ..\data\pt0366.smb

sm_viewer -i ..\data\pt0366.smb

press <p>

for a dataset stored in multiple files try:

spfinalize -i pt.files -itxt -listoffiles -parse sxyz -o ..\data\pt.spb

sp_viewer -i ..\data\pt.spb

press <p>

sp_viewer -i ..\data\pt.spb -del2

press <p>

spdelaunay2d -i ..\data\pt.spb -o ..\data\pt.smb

sm_viewer -i ..\data\pt.smb

press <p>

or in pipelined mode

spfinalize -i pt.files -itxt -listoffiles -parse sxyz -ospb | spdelaunay2d -ispb -o pt.smb

and a longer pipe

spfinalize -i pt.files -itxt -listoffiles -parse sxyz -ospb | spdelaunay2d -ispb -osmb | sm_viewer -ismb -every 10000

finally let's look at some LIDAR points that are stored in multiple files in LAS format:

sp_viewer -i gilmer.files -ilas -listoffiles

now let's finalize & triangulate the points and pipe the TIN into a mesh viewer

spfinalize -i gilmer.files -ilas -listoffiles -ospb | spdelaunay2d -ispb -osmb | sm_viewer -ismb -every 10000

and now go and try your own data ...

              \*********************************************\
              \***            spfinalize.exe             ***\
              \*********************************************\

usage:

spfinalize -h

takes a point cloud as input and spatially finalizes it in two or
three passes.

it can also read *.obj, *.ply, *.off, and *.sm[abc] files (optionally
gzipped) but use only their vertex data, which is treated as a 2D input
with z being the height. we can write *.spa (Streaming Point Ascii) and
*.spb (Streaming Point Binary) files. The binary representaion is much
more IO-efficient!!! 

              \*********************************************\
              \***             sp_viewer.exe             ***\
              \*********************************************\

usage:

sp_viewer -h

visualizes a streaming 2D point cloud and its spatial finalization quadtree.

option '-flatten' will set the z coordinate of all read point to zero.
option '-del2' will visualize the state of streaming delaunay triangulation

press 'p' to play\stop
press 's' to step

toggle render mode with
 'u'  -  unfinalized space
 'a'  -  active triangles
 'i'  -  infinite triangles

toggle interaction mode with <space>

change point size with -\=

change line width with _\+

scale elevation values with [\]

move pointer above a triangle and press 'm'. shows you the circumcircle and
the quadcell of the grid that it intersects (if computed already).

move pointer above a quadcell and press 'n'. highlights this quadcell and one
circumcircle that intersects it (if there is one)

press 'q' or <ESC> to quit

the memory requirements are proportional to the maximal number of triangles
and vertices that are allocated concurrently (the actual number is output to
stderr in the end) and the maximal number of quadtree cells in the quadtree
that is used to maintain and query the finalized space.

if given a non-streaming point cloud nothing can get finalized and the memory
requirements are much higher (e.g. more than a standard delaunay triangulator).

              \*********************************************\
              \***           spdelaunay2d.exe            ***\
              \*********************************************\

usage:
spdelaunay2d -h

computes a delaunay triangulation of the input point cloud and outputs a streaming
mesh. for this to be efficient, the input cloud should be spatially finalized. if
the point cloud is not spatially finalized then we can not operate in a streaming
manner and incrementally build up the entire delaunay mesh in memory.

currently the streaming output mesh is not perfect, because not all vertices are
getting finalized (all those vertices that are incident to an infinite triangle).

              \*********************************************\
              \***             sm_viewer.exe             ***\
              \*********************************************\

usage:
sm_viewer -h

for visualizing the streaming output mesh (and the order in which it was created)