[libpc] Itermania

[Michael P. Gerlek]

I have landed the new Iterator system.  The intent is that the following
"semantics" shall apply to Stages and their Iterators...


Stages:

* A Stage should be a const object which holds info about the
file/stage/whatever.

* Each Stage knows how to create an Iterator for its own type.

* Multiple iterators on a stage should be perfectly safe.

* (some of the stage implementations are not complete yet for
thread-safety/const-correctness; am fixing today)

* A stage has a getNumPoints() function.  This returns 0 or nonzero.  If
nonzero, that is how many points are available from the stage.  If zero,
check getPointCountType() -- if it returns the Unknown enum, then that stage
has no idear how many points it has.  Example: for a crop filter attached to
LAS reader for a 1000-point file, the reader stage will say 1000 but the
filter will say "unknown".  Example: a drone streaming down las data will
say "unknown" because the number of points is effectively
unknowable/infinite.


Iterators:

* An Iter has three "impl" functions you need to provide (pure virtuals).

* readImpl(data) will fill up the data buffer, setting at most
data.getCapacity() points -- data.getNumPoints() is how many points were
actually set, and this value is also returned from the function

* skipImpl(count) will advance the stage by up to that many points, and
return the number of points it actually advanced (these two values may be
different if you try to skip past the end of the file or beyond the number
of points possible)

* atEndImpl() will return true iff there are no more points to be read from
that stage

* The above three Impl functions are protected; their public counterparts
are read(), skip(), and atEnd().  The public versions wrap the protected
versions, so as to be able to provide the bookkeeping for keeping track of
the "current point index" of the iterator.

* The "current point index" is defined as a value which starts at 0 and
increments by N every time you read (or skip) N points.  This "ordering" of
points is an artificial construct maintained by the iterator -- it might
have no meaning in the "real" world, e.g. a database doesn't have a (simple)
notion of the "7th" point.

* For example, consider a DecimationFilter F with the step size set to 10
attached to a LasReader R with a file of 1000 points:

       PointData buffer(capacity=4)

       numRead = F.read(buffer)
       assert(numRead == 1)
       assert(R.getIndex() == 4)
       assert(F.getIndex()==1)

       numRead = F.read(buffer)
       assert(numRead == 0)
       assert(R.getIndex() == 8)
       assert(F.getIndex()==1)

       numRead = F.read(buffer)
       assert(numRead == 1)
       assert(R.getIndex() == 12)
       assert(F.getIndex()==2)



-mpg