Re: [boost] GGL documentation issue

Subject: Re: [boost] GGL documentation issue
From: Barend Gehrels (barend_at_[hidden])
Date: 2009-11-18 08:42:28

Hi Thomas,

Thanks for spending so much time on our library.

You took the ring concept and it is difficult indeed. The ring is 
conceptually quite difficult, because:
- some people think it is having an area, so topological dimension is 2
- some people think it is a closed linestring, so topological dimension is 1
(See also a note in the file topological_dimensions.hpp on this)

This has been discussed on the list before. We *need* something, 
internally, that is having an area. Because a polygon consists of rings, 
and the area of a polygon is the sum of the area of its rings. All 
mathematics like this in GGL internally needs to go for topological 
dimension 2.

If you look into our source-document, the OGC SF specification 
(http://tinyurl.com/ggl-ogc1), you will see a similar thing, in the UML 
diagram:
- a polygon consists of zero or more linear rings
- a linear ring is derived from a linestring

So this contradiction is there also and I understand that it is 
confusing in GGL documentation as well. We will enhance this, or it 
might even be better to take another name. Many libraries do have a 
polygon (which is our ring) and a polygon_with_holes (which is our 
polygon) but we choose to don't use this because of OGC. In fact the 
ring-concept is more or less a "helper" geometry, I mean: point, 
linestring and polygon are the "main" geometries.

Because we're using OGC conventions we didn't take the effort to copy or 
adapt all descriptions that are already there (see same document). 
Therefore, indeed, we might have missed something, or more things, that 
are essential for people who are less familiar with OGC. And we could 
expect that because GGL is more than GIS, so sorry for this omission.

> Please clarify:
> a) Do you agree that the documentation of the "geometry concepts" is currently insufficient, because both the intended semantic meaning and the exact constraints on valid "values" for objects modeling the "geometric concepts" are not documented?
>   
So yes, it should be extended

> c) Is there a bug in the area function, or are both "Modules" -> "A Generic Geometry Library (web-copy of article for BoostCon'09)" and "Example" -> "c04_b_custom_triangle_example.cpp" wrong?
>   
The article is published in '09 and most of it is written in '08, we're 
nearly a year further now. Indeed it is contradictory, sorry for this. 
We have pondered about the closeness. Should a ring always be closed or 
should it be flexible. In '08 we thought to add something to the concept 
which says so, like we did for orientation. So a triangle there has 3 
points then, if it no needs to be closed. In the months after, we didn't 
add this yet, it would make the options we already have (I mean the 
whole combinatorial explosion we have on geometry-types, 
coordinate-systems, dimensions, orientations) even more complex, and it 
was not feasible to handle it in the prepration of this submission.

An optional traits closed/nonclosed, the way we did this for 
orientation, can be added later, if this wish is expressed by the boost 
community.

> b) Why are there two examples that more or less contradict each other?
>   
This is a consequence of the closeness. It is perfectly thinkable to 
create a triangle modelled as a "ring", override *all *dispatch methods, 
and have it non-closed. This is the approach of example b. However, you 
should override everything. To implement it more easily, you can 
override only one method (the area as done here). But it should be 
*closed *then. Anyway, I agree with you that it is inconvenient to show 
it like this, and we will adapt those samples, thanks for pointing this out.

Regards, Barend