Dear GGL authors, This is still not a review. However, the documentation issue I found doesn't allow be to submit a (positive) review before the issue is clarified.
- What is your evaluation of the documentation?
Looks like "work in progress" to me. There are examples, but examples are not a sufficient substitute for a proper documentation. But I wonder whether it's just me, or whether the documentation is really insufficient. I know the library has a "ring concept", so let's try to find out from the documentation what it is. On "Related Pages" -> "OGC (Open Geospatial Consortium)" the following definition can be found: linear_ring: Sequence of point values with linear interpolation between points, which is closed and not self-intersecting On "Modules" -> "geometry concepts: defines and checks concepts for geometries" -> "ring concept More..." the following can be found: template<typename Geometry> class ggl::concept::Ring< Geometry > ring concept Formal definition: The ring concept is defined as following: * there must be a specialization of traits::tag defining ring_tag as type * it must behave like a Boost.Range * there can optionally be a specialization of traits::point_order defining the order or orientation of its points, clockwise or counterclockwise. * either it can behave like the std library, having pushback * or it can implement a mechanism for clearing and adding points. This is the same as the for the concept Linestring, and described there. Note: to fulfil the concepts, no traits class has to be specialized to define the point type. The point type is taken using boost::range_value<X>::type Both explanations don't seem to clarify what a ring really, so let's continue to browse the documentation. On "Modules" -> "A Generic Geometry Library (web-copy of article for BoostCon'09)", it is described how a triangle can be handled as a linear ring. This is indeed illuminating, because I learn from it that a "ring" is indeed a geometric figure with a non-zero area, and that there is no requirement for the first and last point of the ring to be equal. And "Example" -> "c04_b_custom_triangle_example.cpp" also contains the example from the article, so I went and tried it. It seemed to work well, but then I tried what happens when I comment out the area specialization. Suddenly the area was zero??? And I'm really confused now: What I initially wanted to find out was whether a ring is a geometric figure with a non-zero area. Now I'm wondering whether there is a requirement for the first and last point of a ring to be equal. A look at "Example" -> "c04_a_custom_triangle_example.cpp" indicates that this might indeed be the case: struct triangle : public boost::array<ggl::point_xy<double>, 4> My conclusion is that the documentation of the "geometry concepts" is insufficient, because I'm not even able now to tell whether there is a bug in the library or a bug in the example. And that the examples that are provided instead of a proper documentation contradict each other doesn't help either. 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? b) Why are there two examples that more or less contradict each other? 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? Regards, Thomas
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
Hi Bahrend, Thanks for your answers. Because I'm not sure I fully understood your clarifications, I decided to repeat your answers in my own words, so you can correct me if I misunderstood them. 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? You agree. b) Why are there two examples that more or less contradict each other? Because you planned to introduce the concept of closeness at one time, but renounced on it for the review. 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? There is no bug in the area function. If the concept of closeness would have been introduced, both "..." and "..." would have been correct. The example just demonstrates that this would be possible. Regards, Thomas
Hi Thomas,
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?
You agree.
Agree that it could be enhanced, but please add that we refer to OGC which documents the meaning of geometric semantics and concepts in detail.
b) Why are there two examples that more or less contradict each other?
Because you planned to introduce the concept of closeness at one time, but renounced on it for the review.
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?
There is no bug in the area function. If the concept of closeness would have been introduced, both "..." and "..." would have been correct. The example just demonstrates that this would be possible.
Thanks for summarizing, yes, I agree on these formulations, with addition Regards, Barend
participants (2)
-
Barend Gehrels -
Thomas Klimpel