[mapserver-commits] r10509 - trunk/docs/en/development/rfc

[svn at osgeo.org]

Author: tamas
Date: 2010-09-18 21:09:20 +0000 (Sat, 18 Sep 2010)
New Revision: 10509

Modified:
   trunk/docs/en/development/rfc/ms-rfc-61.txt
Log:
Clarify some things, and add reference to the corresponding ticket.

Modified: trunk/docs/en/development/rfc/ms-rfc-61.txt
===================================================================
--- trunk/docs/en/development/rfc/ms-rfc-61.txt	2010-09-17 20:52:33 UTC (rev 10508)
+++ trunk/docs/en/development/rfc/ms-rfc-61.txt	2010-09-18 21:09:20 UTC (rev 10509)
@@ -13,7 +13,7 @@
 
 Description: This RFC proposes a generic implementation for rendering
 the feature styles retrieved from the various data sources. In this
-regard we intend to enhance the existing STYLEITEM "AUTO" option
+regard we intend to enhance the existing STYLEITEM option
 which could now be specified for all layer types and not restricted
 to the OGR driver.
 
@@ -42,40 +42,66 @@
 
 
 Currently the style string transferred this way can only be rendered by
-the MapServer OGR driver, however it would be reasonable to implement this
+the MapServer OGR driver, however it would be reasonable to implement such
 option for all layer types in MapServer.
 
 Proposed New Syntax
 ~~~~~~~~~~~~~~~~~~~
 
-We can continue to use the current STYLEITEM "AUTO" syntax, which
-will now be implemented for all layers. In this case the default
-implementation will retrieve the style string from the attribute
-with the name 'OGR_STYLE'.
+This RFC wouldn't alter the current behaviour of STYLEITEM "AUTO" option, which causes
+the driver specific LayerGetAutoStyle vtable method to be called as before.
+If LayerGetAutoStyle is not implemented by a driver an error message is
+provided to the user "'STYLEITEM AUTO' not supported for this data source."
 
-In addition, we will implement support to specify the renamed
-attributes by using the STYLEITEM "mystyleattribute" in the layer
-definitions of the mapfile.
+We will however add support for specifying the feature attribute containing
+the style string in the form: STYLEITEM "mystyleattribute" which
+will tell mapserver to initialize the style from the specified attribute in
+a generic way.
 
+Supported Style Representations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We will implement support for either the current mapserver and OGR specific
+style representations. 
+
+The mapserver style representation follows the syntax of the STYLE and CLASS 
+entries in the mapfile format like the following sample:
+
+::
+
+  "STYLE BACKGROUNDCOLOR 128 0 0 COLOR 0 0 208 END"
+  
+By specifying the entire CLASS instead of a single style allows to use further options
+(like setting expressions, label attributes, multiple styles) on a per feature basis.
+
+In addition to the mapserver style the OGR style string format will also be supported
+as described in the following documentation: http://www.gdal.org/ogr/ogr_feature_style.html
+
+The actual style format will be identifyed at run-time according to the first characters of the
+style strings. This solution will allow to specify multiple style formats within the same layer.
+
+
 Implementation Details
 ~~~~~~~~~~~~~~~~~~~~~~
 
 In order to implement this enhancement the following changes should be
 made in the MapServer codebase:
 
-1) Modify msOGRLayerGetAutoStyle (in mapogr.cpp) and extract the bulk of the style
-   initialization into a separate function. We would add a new function where the style manager
-   would be initialized by using OGRStyleMgr::InitStyleString instead of OGRStyleMgr::InitFromFeature
-   msOGRLayerGetAutoStyle should also support extracting the style from an arbitrary field as
-   specified by the STYLEITEM parameter.
+1) Modify msDrawVectorLayer (in mapdraw.cpp) to invoke a new method (msLayerGetFeatureStyle) 
+   when STYLEITEM is set for a particular layer.
+   
+2) Implement msLayerGetFeatureStyle in maplayer.c which will call either msUpdateStyleFromString,
+   msUpdateClassFromString or the new method: msOGRUpdateStyleFromString according to
+   the actual style format retrieved from the layer.
 
-2) Modify LayerDefaultGetAutoStyle (in maplayer.c) to retrieve the style string attribute
-   and call the appropriate function in mapogr.cpp described above.
+3) Modify msOGRLayerGetAutoStyle (in mapogr.cpp) and extract the bulk of the style
+   initialization into a separate function (msOGRUpdateStyle). We will add a new function 
+   (msOGRUpdateStyleFromString) where the style manager will be initialized by using 
+   OGRStyleMgr::InitStyleString instead of OGRStyleMgr::InitFromFeature
    
-3) Modify msLayerWhichItems in (maplayer.c) to retrieve the attribute containing the style string
-   specified in the STYLEITEM parameter. Using STYLEITEM "AUTO" would require to retrieve the
-   attribute with name 'OGR_STYLE'. For those layers which override LayerGetAutoStyle with
-   a custom implementation (like the OGR driver) no additional attribute will be retrieved.
+4) Modify msLayerWhichItems in (maplayer.c) to retrieve the attribute containing the style string
+   specified in the STYLEITEM parameter. By using STYLEITEM "AUTO" no additional attribute 
+   will be retrieved just as before.
 
 MapScript Issues
 ~~~~~~~~~~~~~~~~
@@ -89,41 +115,43 @@
 
 To implement the solution the following files would require to be changed:
 
-- mapserver.h => Add the declaration of a new function implemented in mapogr.cpp
-- mapogr.cpp => Add a new function to process the style string
-- maplayer.c => Implement LayerDefaultGetAutoStyle, modify msLayerWhichItems
+- mapserver.h => Add the declaration for msLayerGetFeatureStyle and msOGRUpdateStyleFromString
+- mapogr.cpp => Add msOGRUpdateStyleFromString and msOGRUpdateStyle
+- maplayer.c => Modify msLayerWhichItems and implement msLayerGetFeatureStyle
+- mapdraw.c => Call msLayerGetFeatureStyle in addition to msLayerGetAutoStyle
 
 Backwards Compatibilty Issues
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Currently STYLEITEM "AUTO" has only been implemented in the OGR driver which
+Currently 'STYLEITEM "AUTO"' has only been implemented in the OGR driver which
 overrides LayerGetAutoStyle with a custom implementation. This behaviour would
 continue to work as previously since the generic implementation would not affect those
-drivers which provide custom implementation. However msOGRLayerGetAutoStyle should also
-be modified to initialize the style from an arbitrary attribute in addition to the
-"AUTO" option.
+drivers which provide custom auto style implementation.
 
+When using the 'STYLEITEM "mystyleattribute"' setting, we provide a generic implementation
+to set the style directly from the feature attribute and no driver specific
+function will be called. This option will work for all drivers in the same way.
+
 Further Considerations
 ~~~~~~~~~~~~~~~~~~~~~~
 
 In the future we may provide support further style representations in addition to
-the OGR style strings. Handling multiple style representations are not covered by
-this RFC, however the generic style implementation could easily be extended in this regard.
-This would require to add a new parameter (or a layer processing) option to select
-how the style attribute should actually be handled in MapServer.
+the mapserver and OGR style strings. Each new representation will require a 
+proper (and fast) method to identify the format from the style string itself.
 
-This generic approach would require the OGR driver to be compiled in. If we compile
-MapServer without OGR support we continue to provide an error message in case of an
-attempt to use the STYLEITEM option in the mapfiles.
+Using the OGR style format will require the OGR driver to be compiled in. If we compile
+MapServer without OGR support and the 'STYLEITEM "mystyleattribute"' option is used,
+those features may not be rendered correctly where the actual style format is OGR
+style string.
 
-Currently the OracleSpatial driver does override LayerGetAutoStyle just because to provide a
-custom error message when the STYLEITEM option is used. For this driver we should
-probably switch back to the "generic" implementation during the vtable initialization.
-
 Bug ID
 ~~~~~~
 
-Not yet assigned
+The ticket for RFC-61 (containing the implementation) can be found here.
+
+Bug 3544_
+ 
+.. _3544: http://trac.osgeo.org/mapserver/ticket/3544 
 
 Voting history
 ~~~~~~~~~~~~~~