WKT RFC - Call for a vote...

[Steve Lime]

Hi all: I've integrated the comments from Franks and Sean (many thanks!) into the attached version (can also be found in CVS HEAD). I'd like to call for a vote from technical committee members on the proposal. Since this is a holiday weekend I propose letting voting continue through next Tuesday. I'll start things off with a +1...

Steve

Stephen Lime
Data & Applications Manager

Minnesota DNR
500 Lafayette Road
St. Paul, MN 55155
651-297-2937
-------------- next part --------------
===============================================================
  MS RFC 2: Creating line features and/or shapes using WKT
===============================================================

:Date: 2005/07/13 
:Author: Steve Lime
:Contact: steve.lime at DNR.STATE.MN.US
:Last Edited: $Date: 2005/09/03 03:48:24 $
:Status: Proposed

Description: Developing inline features or shapes within MapScript can be a 
bit cumbersome.  One alternative would be to allow users to define feature 
using the Well-Known Text format.  The proposed solution would allow users 
to use this format:

1) within a mapfile
2) via URL
3) via MapScript
4) via MapServer query template

Instead of writing a new WKT parser we would provide access to underlying GEOS 
or OGR functionality to do this. Notes about the actual implementation are
included below.

Files affected
~~~~~~~~~~~~~~~~~

- mapfile.h => new constant, WKT
- maplexer.l => recognize the new constant
- mapfile.c => process new mapfile parameter with FEATURE block (WKT), and 
  update URL parsing in a similar manner
- mapgeos.cpp => wrap GEOS WKT reading/writing code
- mapogr.cpp => wrap OGR WKT reading/writing code
- mapprimitive.c => wrap the GEOS and OGR WKT writer/reading code, this would 
  be the "public" interface 
- maptemplate.c => update the shpxy tag with a "-wkt" option so it would output
  the WKT version of a shape. Placing here would allow us to take advantage of
  the projection support already in place, plus any future options (thining, buffers
  and so on).
- mapscript/swiginc/shape.i => update constructor to pass a WKT string and to
  define a "toString" method that would output a WKT string. Similar modifications
  would have to be made within PHP/MapScript, patterned after the SWIG-based
  interface.

Backwards compatabilty issues
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

N/A, new functionality

Implementation Details
~~~~~~~~~~~~~~~~~~~~~~

 - The C API will take the form:

  shapeObj *msShapeFromWKT( const char * );
  char *msShapeToWKT( shapeObj * ); 

  These are contrary to some of the older code (e.g. msLayerNextShape()). However there 
  are 2 places the WKT APIs will be used: 1) MapScript and 2) creating inline features 
  via URL or MapFiles. In both cases the above functions would be prefered.

 - In MapScript, creating a shape will take the form of an overloaded constructor, e.g.:

   $shape = new shapeObj($mapscript::MS_SHAPE_LINE);  OR
   $shape = new shapeObj('LINESTRING(0 0,1 1,1 2)');

 - In MapScript, a toWKT() method will be added to shapeObj object. 

 - WKT is geometry only.  The attributes, index, tileindex, classindex,
   and text fields do not exist in WKT and will have to be set "elsewhere".

 - There is no widely supported, or standardized approach to "measure"
   values in WKT though Refractions does support it in "EWKT".  For now it
   is assumed that measure values will not be preserved from WKT.

 - There is a well defined way of including Z coordinates and these should
   be carried through if MapServer is built with Z and M support enabled.

 - Development will be accompanied by a set of tests. Sean Gillies has already created
   a test case or two.

 Transformations shapeObj to WKT
 -------------------------------

 - MS_SHAPE_POINT: If numlines and numpoints are one, then this is converted
   to a POINT object in WKT.  If there are more points, this is converted
   to a MULTIPOINT object.

 - MS_SHAPE_LINE: if numlines is 1 then this will be translated to a LINESTRING
   otherwise it will be translated to a MULTILINESTRING.

 - MS_SHAPE_POLYGON: MapServer does not keep track of interior and exterior
   rings in a shape, since the scanline rasterization mechanism of GD 
   does not require this information.  However, when converting to WKT we
   need to know whether we have a single polygon with holes, or multiple
   polygons (more than one exterior ring).   If numlines is 1, we can directly
   translate to POLYGON(), otherwise the rings will need to be analysed to 
   identify outer rings, and to associate inner rings with their outher ring.
   If more than one outer ring exist, a MULTIPOLYGON will be produced, 
   otherwise a POLYGON will be produced.

 - MS_SHAPE_NULL: This results in an empty WKT string.  

 Transformations WKT to shapeObj
 -------------------------------

 - POINT: Translates to an MS_SHAPE_POINT object with one point and one line.

 - LINESTRING: Translates to an MS_SHAPE_LINE object with one line. 

 - POLYGON: Translates to an MS_SHAPE_POLYGON object with one line for the
   outer ring and one line for each inner ring.

 - MULTIPOINT: Translates to an MS_SHAPE_POINT object with one line, and one
   point for each line. 

 - MULTILINESTRING: Translates to an MS_SHAPE_LINE object with one line for
   each linestring in the container. 

 - MULTIPOLYGON: Translates into an MS_SHAPE_POLYGON with each ring of each
   polygon being a line in the resulting polygon object. 

 - GEOMETRYCOLLECTION: Treat as MULTIPOINT, MULTILINESTRING or MULTIPOLYGON if
   the contents are all compatible, otherwise throw an exception. 

Bug ID
~~~~~~~~

unassigned

Voting history
~~~~~~~~~~~~~~~~~

None