[boost] GGL Review Results

Subject: [boost] GGL Review Results
From: Hartmut Kaiser (hartmut.kaiser_at_[hidden])
Date: 2009-11-28 12:34:44

Hi all,

The review of the Generic Geometry Library is over now. We have had vibrant
discussions with regards to the library itself. In addition those stirred up
a lot of controversial discussion about the Boosts review process. In this
review results I will concentrate on the library at hands.

Formally this review ended with 12 YES and 2 NO votes. This result reflects
the overall discussion and the general consensus of this library being worth
to be included into Boost. 

Based on this result and the discussions the Generic geometry Library has
been formally accepted into Boost.

It is worth highlighting that most of the reviewers emphasized the excellent
quality of the library design. Here are some quotes:
- "The design is very clear. I think it can serve as a standard example of
how to cover a big non trivial problem domain using meta-programming,
partial specialization and tag dispatch to make it uniformly accessible by a
set of generic algorithms." 
- "The design looks clear enough so that I was able to understand about what
was being done. Adding concept checking is a good idea. It also surely is a
modern generic design."
- "I am quite pleased with the use of tag-dispatching and strategies. I was
happy to see this approach taken and by looking at the documentation and
source code it seems sound. I believe this approach offers the greatest
latitude for a generic library."

At the same time the 2 NO votes reflect a couple of shortcomings which still
need to be addressed before final inclusion into SVN. Here is a list of
contingencies noted by the reviewers:

- Robustness: algorithmic robustness and arithmetic stability have been
discussed widely. The consensus of the reviewers is that all algorithms need
to be robust and that the user should be able to make sure all calculations
are arithmetically stable. GGL addresses arithmetic stability by allowing to
instantiate all algorithms with arbitrary number types. But it turns out not
the entire library has been converted to use this scheme yet. Any design
issues that would prevent strong robustness guarantees (without drastic
refactoring) in the future should be identified and fixed prior to release.
The documentation needs to reflect the actual guarantees and complexities of
every algorithm.

- Concepts: more refinement needs to be done for the existing concepts. At
least 2 users claimed to not have been able to adapt their data structures
to the existing scheme. The library aims for defining the concepts and
interfaces for future geometry related work in Boost, so these use cases
need to be addressed. Users mentioned the missing concept inheritance. This
might be a good way to address the current problems of concepts being too
fine grained and too difficult to use. What needs to be done at minimum is
to enhance the flexibility of the concept mechanism enabling to adapt user
provided data structures more easily. The concepts need to be sound even in
the light of extensions.

- Boolean operations: while the library provides a set of Boolean operations
those seem to be not complete and/or robust in terms of
clockwise/counterclockwise geometries, closed/open polygons. Robust Boolean
operations are a strong requirement, so this should be fixed as reported by
at least one reviewer.

- Documentation: the documentation of the library is not complete and needs
additional effort. Using Doxygen alone as a documentation tool has its
(known) shortcomings when it comes to generic libraries. The authors already
mentioned to plan to switch to QuickBook after review allowing to have
better control over the generated docs. 

- Testing: several reviewers mentioned the need for a thorough testing
framework allowing the verification of the correctness of the algorithms in
a wide range of use cases. Different test strategies need to be employed,
such as high volume and random tests, known border case tests, tests using
different numeric precision types, etc.

Minor (non-contingency) issues:

- Names of used concepts: currently the library is using mainly terms as
established by the OpenGIS Consortium (OGC). This is misleading for users
coming from different (non-GIS) domains. It has been suggested to introduce
different namespaces for the different geometry domains (GIS, graphics, 3D,
etc.) allowing to use the expected terminology established in that
particular domain. 

- Name of the library: the name 'GGL - Generic Geometry Library' is
misleading as it is not a generic geometry library but a library using
generic programming techniques related to geometry. It has been suggested to
use the name Boost.Geometry instead. This is not a requirement imposed by
the review results, but I would like to suggest to the authors to consider
renaming.

- Integration with Boost.Units has been suggested. The library does not need
to be completetly integrated with Boost.Units, although it appears to be
reasonable to deal with types as exposed by Boost.Units especially for
distance and area calculations.

- Spatial data structures (such as spatial trees) have been mentioned to be
crucial for a geometry related library. While the library can't implement
all possible data structures in this field it can (and should) define
concepts and interfaces allowing future extensions while maintaining
interoperability.

- In addition to that the reviewers made a lot of remarks related to
different smaller inconsistencies part of which already have been addressed
during the review. Barend has a full list of the remaining ones and promised
to address all of them.

Last but not least I would like to encourage cooperation between the authors
of this library and the author of Boost.Polygon as both libraries have their
strength' worth combining. In an ideal world and at some point I would like
to see both libraries to be merged. But this is obviously not something to
expect really soon.

At this point I would like to thank all who participated in the review and,
certainly, the authors for submitting this excellent library to Boost.

Regards Hartmut
GGL Review Manager

-------------------
Meet me at BoostCon
http://boostcon.com