
Geometry : 
Subject: [ggl] [doc] New draft of Reference based on DoxygentoBoostbook
From: barend (barend.gehrels)
Date: 20100313 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:
> http://mateusz.loskot.net/tmp/ggl/qbk/
[http://mateusz.loskot.net/tmp/ggl/qbk/]
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
can
also contain coordinate systems, degree/radian, which are not really
constants or enumerations, but empty classes having the same
functionality.
There is
some
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
more)
 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
objections.
point_type is listed twice, one directs to point_order. This is
probably something in the source file which is Doxygentagged
erroneously.
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
source
tree) and will then disappear automatically (probably, I don't
know exactly how you configure this). The same for sectionalize which
will
move to detail/sections. Reason for this is that some of the reviewers
stated that it was not always clear which functions are for endusers,
and
indeed, this functionality not really meant for end users.
If there is a subgroup Overlay, which is a good idea, it would
contain
difference, sym_difference, intersection, union and dissolve. Grouping
is
always difficult because there are always algorithms on which can be
debated
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
extension.
I don't see the need for parse anymore here (I think it was not part of
the
review), so I propose to move it to extensions/algorithms/parse.
[1] This is not about this reference but about arithmetic. One of
the
reviewers, in an offlist review, meant that the arithmetic functions
should
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
as
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
for
Games and it states the same, often they are shared together. However,
my
opinion is that it is confusing to have one structure for two things.
Calculating the dot product for points is something which sounds strange
to
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
by
Emil Dotchevski would be used for this functionality (provided that
library
is accepted). It would also replace our uBlasusage (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
geometry::point
> 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...
URL: http://lists.osgeo.org/pipermail/ggl/attachments/20100313/cdd3f05a/attachment.html
Geometry list run by mateusz at loskot.net