Geometry Boost List: [ggl] Upcoming changes in I/O formats structure

Subject: [ggl] Upcoming changes in I/O formats structure
From: Mateusz Łoskot (mateusz)
Date: 2011-12-07 19:25:47

Folks,

Lately, I have discussed with Barend and Bruno proposal to change
structure of I/O formats. The motivation is to make it clear and simple,
but fairly well-structure at the same time.

I have applied necessary changes in my working copy and
I would like to commit it soon.
So, this message is a pre-commit announcement and warning.

Basically, changes I/O formats structure include:
1) Get rid of domain or format standardisation body, so structure is flattened.
2) Introduce some basic convention for naming files/folders per format layout.
3) Separate I/O formats for simple geometries from multi-geometries

The new layout layout looks like this:

geometry/io/<FORMAT>/<FORMAT>.hpp  (unsure, see note [1] below)
geometry/io/<FORMAT>/read.hpp
geometry/io/<FORMAT>/write.hpp
geometry/io/<FORMAT>/iomanip.hpp (see note [2])
geometry/io/<FORMAT>/detail/...  (.hpp files with private
implementation details)

Note [1] Boost.Geometry stores all-in-one headers inside related
folder, for example
boost/geometry/geometries/geometries.hpp
but not at one level above:
boost/geometry/geometries.hpp
Most/many Boost libraries use the latter convention
So, I'm not sure if all-in-one headers for formats should be:
geometry/io/<FORMAT>/<FORMAT>.hpp
or
geometry/io/<FORMAT>.hpp
For now, I keep it geometry/io/<FORMAT>/<FORMAT>.hpp

Note [2] the iomanip.hpp used to be named stream_<FORMAT>.hpp.
If present, the stream_<FORMAT>.hpp defines stream manipulators for format.
I renamed it to iomanip.hpp to follow std naming of <iomanip> what is
more self-descriptive and exactly indicates purpose of the header.

Similar layout will be used for I/O for multi-geometries:
geometry/multi/io/<FORMAT>/...

Similar layout will be also used for I/O extensions:
boost/geometry/extensions/io/<FORMAT>/...
boost/geometry/extensions/multi/io/<FORMAT>/...

So, for example, the new structure will be:

boost/geometry/io/dsv/
boost/geometry/io/wkt
boost/geometry/multi/io/dsv//
boost/geometry/multi/io/wkt/

Finally, we have planned to move two formats from extensions to the
set of released formats:
- SVG
- WKT

The OGC WKT (Well-Known-Text) format is a simple and popular
GIS-derived format, however it has no GIS-specific
features built-in, so it is a perfect general purpose format for 2D
geometries (and soon 3D too).
The WKT format has complete implementation, so it is a mature piece of software.
We already use WKT format in tests, so it is a required piece of our kit.

The SVG is a popular format and it is extremely useful as it is the
only format so far which
we can use for visualisations of Boost.Geometry objects.

Next, I'm going to complete implementation of OGC WKB
(Well-Known-Binary) format and
move it to default set. The WKB format is a binary equivalent of WKT format

To summary, in near future I would like to have the following set of
formats released as built-in:

boost/geometry/io/dsv/
boost/geometry/io/svg/
boost/geometry/io/wkb/
boost/geometry/io/wkt/

If there are any objections or suggestions of improvements, please speak now.

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org
Member of ACCU, http://accu.org