Boost logo

Geometry :

Subject: [ggl] [doc] New draft of Reference based on Doxygen-to-Boostbook
From: barend (barend.gehrels)
Date: 2010-03-13 05:30:57

Hi Mateusz,

> Yesterday I managed to get first good results of processing
> Doxygen XML output to Quickbook/Boostbook documentation.
> Here it is:

Again, it is giving a very good overview.

So here my feedback, most things are details. Along the way it is a
whole list now but the main message is: I'm really enthousiastic about
that page.

I like the main structure with Concepts first, then Models, then
Algorithms, and I also like the structure within the main sections with
separate headings and then the real functionality.

The Arithmetic section can (I think) put below the
algorithms, reason will follow below [1]

A section Strategies can be added below Algorithms

A section Constants and Enumerations can be added, probably above
Algorithms, with things like min_corner, max_corner, clockwise, etc. It
also contain coordinate systems, degree/radian, which are not really
constants or enumerations, but empty classes having the same

There is
functionality which is not yet there:

- compare
(equal_to, greater, less) which are not algorithms but policies which
can be
used for std::functions like unique and sort

- manipulators such as boost::geometry::dsv (and in extensions
there is

- iterators

Will we put the Extensions in this Register? I'm not sure about
that, probably not.

There are some functions that I doubted recently if they are on the
right place in core, and these are: num_points, num_interior_rings. Now
that I see them there, those are not really Access functions but more
utilities, they probably can be moved to Algorithms if there are no

point_type is listed twice, one directs to point_order. This is
probably something in the source file which is Doxygen-tagged

unique is also listed twice.

Is within a predicate?

The header For can be called for_each

The Overlay subsection will be moved to detail/overlay (in the
tree) and will then disappear automatically (probably, I don't
know exactly how you configure this). The same for sectionalize which
move to detail/sections. Reason for this is that some of the reviewers
stated that it was not always clear which functions are for end-users,
indeed, this functionality not really meant for end users.

If there is a subgroup Overlay, which is a good idea, it would
difference, sym_difference, intersection, union and dissolve. Grouping
always difficult because there are always algorithms on which can be
where it belongs.

Maybe we can group assign, append and clear together, they actually
form a sort of group together with make.

The parse is meant for latlong points, which are moved to an
I don't see the need for parse anymore here (I think it was not part of
review), so I propose to move it to extensions/algorithms/parse.

[1] This is not about this reference but about arithmetic. One of
reviewers, in an offlist review, meant that the arithmetic functions
be done on vectors and not on points. I mailed with Bruno about this.
In game engines it is often done like here, so a point is sometimes used
a vector, and v.v. because they have the same functionality, and for
performance reasons they should not be converted. I've a book about Math
Games and it states the same, often they are shared together. However,
opinion is that it is confusing to have one structure for two things.
Calculating the dot product for points is something which sounds strange
me, for vectors it is obvious.

My (personal) favourite solution would be that the LA engine
(with staticly sized vectors and matrices, based on concepts) proposed
Emil Dotchevski would be used for this functionality (provided that
is accepted). It would also replace our uBlas-usage (used by us in
transform). I hope this library will be reviewed soon and accepted. It
can then live as a companion of geometry: difference of two
-> la::vector, dot product, adding la::vector to geometry::point
gives geometry::point, etc.

If this all is the case we can restructure the arithmetic, because
dot/cross are more or less redundant, add_value etc also, add_point
would be
add_vector_to_point (or something like that, or not be renamed but
restructured internally).

Regards, Barend
-------------- next part --------------
An HTML attachment was scrubbed...

Geometry list run by mateusz at