WKT RFC - Call for a vote...

[Sean Gillies]

Hi Steve,

Comment inline ...

On Sep 2, 2005, at 9:59 PM, Steve Lime wrote:

> This is a MIME message. If you are reading this text, you may want to
> consider changing to a mail reader or gateway that understands how to
> properly handle MIME multipart messages.
>
> --=__Part9FBDC8B2.0__=
> Content-Type: text/plain; charset=US-ASCII
> Content-Transfer-Encoding: quoted-printable
> Content-Disposition: inline
>
> 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
>
> --=__Part9FBDC8B2.0__=
> Content-Type: text/plain; name="ms-rfc-2.txt"
> Content-Transfer-Encoding: 8bit
> Content-Disposition: attachment; filename="ms-rfc-2.txt"
>
> ===============================================================
>   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)');
>

I think this will be fine, but for Python we'll need to set a default 
value for the shape type, and use a keyword arg like

     shape = mapscript.shapeObj(wkt='LINESTRING (...)')

I vote +1.

>  - 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
>
>
>
> --=__Part9FBDC8B2.0__=--
>
>
--
Sean Gillies
sgillies at frii dot com
http://zcologia.com