[libpc] RE: Itermania

[Michael P. Gerlek]

The below actually refers to the "SequentialIterator" class.  There is also
now a "RandomIterator" which sports these pure virtual methods:

   - readImpl(data)
   - seek(N)

The read() is the same as the sequential case, and the seek takes an
absolute position index (as opposed to the sequential's forward-only
relative delta).

Stages now have methods "bool supportsSequentialIterator()" and "bool
supportsRandomIterator()".  Today, only three guys support randomness:
CacheFilter, FauxReader, and LiblasReader.

-mpg


> -----Original Message-----
> From: Michael P. Gerlek [mailto:mpg at flaxen.com]
> Sent: Wednesday, March 23, 2011 9:53 AM
> To: libpc at lists.osgeo.org
> Subject: Itermania
> 
> 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