.. _rfc49:

======================================================================
MS RFC 49: Symbology, Labeling, and Cartography Improvements
======================================================================

:Date: 2009/01/26
:Authors: Thomas Bonfort, Stephen Lime
:Contact: Thomas.Bonfort at camptocamp.com , Steve.Lime at DNR.State.MN.US
:Status: Passed and Implemented
:Version: MapServer 5.4
:Id: $Id$

Purpose
-------------------------------------------------------------------------
This RFC regroups a few minor additions or changes to the MapServer rendering
or mapfile syntax.

These changes are/were all in RFC45, but were extracted to keep things
moving on as some of the stuff in RFC45 lacks funding in the near
future.


Fractional values for SIZE and WIDTH
-------------------------------------------------------------------------
AGG can deal with fractional widths and sizes but styleObj's define those
properties as int's.  Shouldn't be a big deal since both GD and AGG don't use
those values directly, rather they use scaled values with are cast or rounded
to an int if necessary. 

http://trac.osgeo.org/mapserver/ticket/2766


MINSCALEDENOM / MAXSCALEDENOM for STYLEs and LABELS
-------------------------------------------------------------------------
These keywords can reduce mapfile size and maintainance, by avoiding
creating multiple layers or classes.

http://trac.osgeo.org/mapserver/ticket/2865


OUTLINEWIDTH on line layers
------------------------------------------------------------------------
It is currently impossible to draw a outlined line with a scale-dependant
width.  We propose to add the OUTLINWIDTH keyword to the STYLE block, that
indicates the width in pixels that should be rendered around the main line
color.

The implementation of this lies in mapdraw.c. When a line's style block has an
outlinewidth, the underlying shape is actually drawn twice: once with it's
width adapted to account for the outlinewidth, and once normally. The current
caching mechanism for lines is preserved.

example usage:

::

  LAYER
    TYPE LINE
    SIZEUNITS meters
    CLASS
      STYLE
        COLOR 255 0 0
        OUTLINECOLOR 0 0 0
        OUTLINEWIDTH 1
        WIDTH 25 #this is in meters (ground units)
        MINWIDTH 1 #minimal width (in pixels) for far zoomed maps
        MAXWIDTH 20 #maximal width (in pixels) for close zoomed maps
      END
    END
  END
  
whatever the map extent or scale, this line layer would always be rendered by a
red line with a one pixel black outline.

http://trac.osgeo.org/mapserver/ticket/2865


add LABEL to layersObj
--------------------------------------------------------------------------------

.. note::
  
  This feature has not yet been implemented

so that a default can be defined for all classes (sort of like templates). A
class label would take precedent.

http://trac.osgeo.org/mapserver/ticket/XXX

Affected Files
--------------------------------------------------------------------------------
 
- mapfile.c 
- mapdraw.c (outlinewidth on lines, scale on styleobj)
- mapserver.h
- maplabel.c (scale on labels)

Documentation
--------------------------------------------------------------------------------

The documentation for the keywords will be aded to the main mapfile syntax docs.

Mapscript
--------------------------------------------------------------------------------

Getters and Setters for the keywords will be added for mapscript availability

Backwards Incompatibility
--------------------------------------------------------------------------------

None Expected

Comments from Review period
--------------------------------------------------------------------------------

- the LABELMETHOD proposal is withdrawn
- fractional values also for pattern,gap, offset:  a good candidate
  for 6.0 (when pattern and gap would be moved to the styleObj?)
- there was concensus for adding parametered scaling, usefull for
  thematic mapping (eg size proportional to a feature attribute)
  
  - by allowing simple expressions, eg SIZE  ( 18 + [poptotal] * ((
    43-18)/(5000-30000))  )
  - or by adding pseudoitems at the layer level:
    ::
      
      PSEUDOITEM
       'mySize' (mrange([itemname], mininput, maxinput, minoutput,
      maxoutput))
       'myText (commify(round([itemname], 2)) + ' ac')
      END
      
      LABELITEM 'myText'
      CLASS
       STYLE
        COLOR 255 0 0
        SIZE [mySize]
       END
       LABEL
        ...
       END
      END
      
   this enhancement will be addressed in a specific rfc.

Voting History
--------------------------------------------------------------------------------
+1 : SteveW, UmbertoN, TamasS, SteveL, DanielM (,AlanB)