Re: [boost] [Review] GGL review starts today, November 5th

Subject: Re: [boost] [Review] GGL review starts today, November 5th
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2009-11-11 13:37:20

Thomas Klimpel wrote:
> 1)
> 
> I wonder whether it would be possible to change the name "GGL" to 
> "Boost.Geometry".
 > [...]
> I first thought that this change of name would disturb existing users
>  of the library, but found out that they will have to change their 
> code anyway:
> [...]

The layout of GGL source tree follows Boost convention.
In spite of that, you are right, users will likely have to update
their GGL-based source code

> Then I thought that the name GGL might be a reference to GIL.

That's how I personally refer to name GGL.

> GGL on the other hand provides just one point, linestring, 
> linear_ring, polygon, box and segment class template, because the 
> representation isn't really the challenge in the context of geometry.

Not really. GGL proposes some definitions of types for basic
fundamental geometries. However, user does not have too stick to them.
Moreover, it is expected that users may want to not to touch
these (pre-)defined types but define their own types.
It is presented in examples with "custom" word in name
http://geometrylibrary.geodan.nl/formal_review/examples.html

In other words, GGL works well with user-defined types for geometries
and such geometries shall be assumed to be first-class citizens.

> This is all perfect, but I just think that the "generic" in case of 
> GGL refers to all the different "legacy" classes that essentially all
> use the same underlying representation of the geometry (point, box,
> ...), but are incompatible because of different names and 
> conventions, whereas the generic in GIL and STL refers to 
> fundamentally different representations of the underlying object that
> is unavoidable in principle.

As I've explained above, I believe, the genericness that can be observed
in GIL and STL is also observable in GGL

> 2)
> 
> A second remark concerns the OGC names. Let's take the following
 > code from 07_graph_route_example.cpp to illustrate:
> 
> 
>     // Init a bounding box, lateron used to define SVG map
>     ggl::box_2d box;
>     ggl::assign_inverse(box);
> 
>     // Read the cities
>     typedef boost::tuple<point_type, std::string, vertex_type> city_type;
>     std::vector<city_type> cities;
>     read_wkt<point_type>("data/cities.wkt", cities, box);
> 
> ...
> 
> // Read an ASCII file containing WKT's, fill a vector of tuples
> // The tuples consist of at least <0> a geometry and <1> an identifying string
> template <typename Geometry, typename Tuple, typename Box>
> void read_wkt(std::string const& filename, std::vector<Tuple>& tuples, Box& box)
> {
> ...
>     ggl::combine(box, ggl::make_envelope<Box>(geometry));
> ...
> }
> 
> 
> What does "ggl::assign_inverse"

It performs a kind of default-initialisation on the box, so the box
may be considered as not valid in terms of domain:

"the min corner is very large, the max corner is very small"

Obviously, zero-initialisation would not be appropriate here, so the 
inverse one is performed

http://geometrylibrary.geodan.nl/formal_review/group__access.html

> and "make_envelope" do?

It calculates envelope of given geometry:

http://geometrylibrary.geodan.nl/formal_review/group__envelope.html

> These are apparently OGC names,
 > but I spend quite some time trying to verify
 > that this is indeed the case.

Strictly speaking, they are not accurate OGC names.
However, "envelope: refers to concept described in OGC specifications.
AFAIK, the "assign_inverse" is a custom concept, not OGC.

> In fact, I just ended up accepting that
> this is probably indeed that case. These OGC names are OK, but ask yourself
 > the question whether you would be able to understand the quoted
> code if you would not already know what "ggl::assign_inverse" and "make_envelope"
 > do (I know it's easy to look it up in the documentation, but that
 > is not the point). In fact, I will not tell you now, but I tried to
 > be fair when quoting the source code, so as not to remove potentially
 > clarifying comments or context.

The make_envelope follows convention like make_pair utility.
I agree that purpose of assign_inverse may not be obvious from its name.

Perhaps, name like make_inverse would be more clear and consistent.

Good naming is an art on it's own :-)

> The bottom line is that when the OGC conventions already force me to accept
 > confusing names,

As far as my own understanding is considered, GGL does not aim to
force OGC conventions. However, it uses some of OGC definitions,
those that are applicable to general geometry problems.
For example, envelope is a short but still descriptive name of MBR

http://en.wikipedia.org/wiki/Minimum_bounding_rectangle

 > it would at least be nice to know how I can
 > verify that these are indeed OGC names.
 > What are the reference documents I have to read to learn this?

Regarding use of OGC elements in GGL, the basic documents are those
directly related to OGC Simple Features

http://en.wikipedia.org/wiki/Simple_Features

It is "OpenGIS Simple Features Specification", specifically
"OpenGIS Simple Features Specifications For SQL" (99-049)

Thomas, thank you for comments.

Barend,

I think it would be good to give precise references here:
http://geometrylibrary.geodan.nl/formal_review/ogc.html

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net