[libpc] Re: exposing capabilities, hiding classes

[Howard Butler]

* Discussion/design/evaluation of driver/Stage model.  Bring in Frank to discuss what he's learned from GDAL and OGR and what he might do different too.
* Decide on a documentation setup.  I'm leaning toward using Sphinx (Sphinx can do C++ docs with its domain stuff) and hand-crafted docs instead of Doxygen
* Polish up three drivers (Native LAS, libLAS-based LAS, Oracle Point Cloud)
* Entice Rosen et. al. to start playing around with MG4
* TXT driver?


On Feb 28, 2011, at 10:05 AM, Michael P. Gerlek wrote:

> Do we have a list of goals for the sprint?   (/me loves lists)
> 
> * Intro to the new libPC framework (mpg)
> 
> * new/sample driver/filter development (all)
>  - MrSID/MG4-lidar
>  - http://libe57.org/
>  - ...?
> 
> * ...?
> 
> -mpg
> 
> 
> 
>> -----Original Message-----
>> From: Howard Butler [mailto:hobu.inc at gmail.com]
>> Sent: Monday, February 28, 2011 7:57 AM
>> To: mpg at flaxen.com
>> Cc: 'Michael Smith'; libpc at lists.osgeo.org
>> Subject: Re: exposing capabilities, hiding classes
>> 
>> 
>> On Feb 28, 2011, at 9:56 AM, Michael P. Gerlek wrote:
>> 
>>> (CC'ing the list)
>>> 
>>> OK, I'll look at that today.  [I assume this is "traits" like char
>>> traits in strings?  I've seen them mentioned, but have never learned
>>> anything about them since I live in an 8-bit, old-fashioned, EN-us
>>> only world...]
>>> 
>>> In any case, I think this should be discussion #1 for the sprint (two
>>> weeks away, yikes) -- I think we can proceed as-is without any undue
>>> damage / excess pain to the future actual model?
>> 
>> yep.  We still need drivers cooked up for examples for the sprint
>> regardless....
>> 
>>> 
>>> -mpg
>>> 
>>>> -----Original Message-----
>>>> From: Howard Butler [mailto:hobu.inc at gmail.com]
>>>> Sent: Monday, February 28, 2011 7:37 AM
>>>> To: mpg at flaxen.com
>>>> Cc: Michael Smith
>>>> Subject: Re: exposing capabilities, hiding classes
>>>> 
>>>> What about traits-style as an alternative to the A and B you've set
>>>> up in
>>> the
>>>> email below?
>>>> 
>>>> 
>> http://www.boost.org/doc/libs/1_46_0/libs/type_traits/doc/html/boost_
>>>> ty
>>>> petraits/background.html
>>>> 
>>>> 
>>>> On Feb 25, 2011, at 5:47 PM, Michael P. Gerlek wrote:
>>>> 
>>>>> The idea under discussion is to find a way to not have to expose a
>>>>> zillion different classes to the user -- such as a LAS reader, a
>>>>> decimation filter, an Oracle writer, etc.  The reason for this idea
>>>>> is
>>> because
>>>> (1) it "feels"
>>>>> like exposing too many headers to the user and giving him too much
>>>>> to think about, and (2) every header we "expose" is one more area
>>>>> that we need to worry about keeping clean between releases.
>>>>> 
>>>>> To implement this idea, then, we want to expose "capabilities" or
>>>> "features"
>>>>> instead.  (I think of this as letting the user see an "abstract"
>>>>> feature set instead of an actual "implementation".)
>>>>> 
>>>>> Consider a workflow where we want to build a pipeline that reads a
>>>>> LAS file, crops it, and writes it out as LAZ using point format 7.
>>>>> In the current model this would look like:
>>>>> 
>>>>>  LasReader reader("foo.las")
>>>>> 
>>>>>  Bounds bounds(0,0,0,100,100,100)
>>>>>  Cropper filter(reader, bounds)
>>>>> 
>>>>>  LazWriter writer("bar.laz", filter)
>>>>> 
>>>>>  writer.write()
>>>>> 
>>>>> In the proposed model, this would look something like this:
>>>>> 
>>>>>  Stage reader = createStage(READER_LAS)
>>>>>  reader.setInputFile("foo.las")
>>>>> 
>>>>>  Stage filter = createStage(FILTER_CROP)
>>>>>  filter.setPrevStage(reader)
>>>>>  Bounds bounds(0,0,0,100,100,100)
>>>>>  filter.setBounds(bounds)
>>>>> 
>>>>>  Stage writer = createStage(WRITER_LAZ)
>>>>>  writer.setOutputFile("bar.laz")
>>>>>  writer.setPointType(X)
>>>>>  writer.setPrevStage(writer)
>>>>> 
>>>>>  writer.write()
>>>>> 
>>>>> In this world, the Stage base class always has these member
>>>>> functions, although setInputFile(), setOutputFile(), setBounds(),
>>>>> and
>>> setPrevStage().
>>>>> They are unimplemented, however, unless
>>>>> Stage.getCapabilities(FEATURE_NAME)==true.  ((In the above example,
>>>> we
>>>>> "know" the feature setInputFile() is available because we
>>>>> specifically asked
>>>>> createStage() for a kind of reader, but in general we would not
>>>>> "know".))
>>>>> 
>>>>> (Am I right so far?)
>>>>> 
>>>>> In the limit, then, this idea would mean that every new feature we
>>>>> come up with -- be it a writer, reader, or filter -- will have to be
>>>>> supported by the enum we pass to createStage() and possibly also
>>>>> have a corresponding member function in Stage.  This seems to mean
>>>>> that every time we want to add some new kind of operation, we need
>>>>> to modify (extend) a core component for that one new driver feature
>>>>> -- such as "setPointType", which only ever makes sense for a LAS
> writer.
>>>>> 
>>>>> Also, consider a libPC user who wants to add his own driver -- say,
>>>>> a particular filter that throws out some points based on his own
> criteria.
>>>>> Does he have to modify the createStage() and add members to Stage to
>>>>> do this?
>>>>> 
>>>>> I *think* I'm therefore against this idea, because we want a library
>>>>> that is very extensible, and we'd constantly be adding new stuff to
>>>>> the base class, which seems to me just as bad as the problem of
>>>>> exposing a zillion Stage-derived classes to the user.
>>>>> 
>>>>> So, is there a middle ground, I wonder?
>>>>> 
>>>>> -mpg
>>>>> 
>>>>> 
>>> 
>