ms-rfc-29.txt

.. _rfc29:

====================================================
  MS RFC 29: Dynamic Charting Capability
====================================================

:Date: 2007/06/15
:Author: Daniel Morissette
:Contact: dmorissette at mapgears.com
:Last Edited: 2007/07/31
:Status: Adopted (2007/07/05) - Completed (2007/07/09)
:Version: MapServer 5.0

Overview
--------

This RFC proposes the addition of simple dynamic charting capability in 
MapServer 5.0 by integrating the patch proposed by Thomas Bonfort in 
ticket #1800.

Note: this is already implemented and working (as a patch in ticket 1800).
This RFC is to document the new feature and (hopefully) include it in the
MapServer 5.0 release.

Technical Solution
------------------

A new CHART layer type is created and the initial implementation would
support pie and bar charts.

PROCESSING directives are used to set the layer's CHART_TYPE (pie or bar) and 
CHART_SIZE,

Then we have one class for each pie slice or bar from the chart. Inside each 
class, the STYLE COLOR defines the color of the pie slice or bar, and the
STYLE SIZE is used to set the relative size (value) of each pie slice or bar. 
This is mostly useful in combination with attribute binding of course. e.g.

Example:

::

  LAYER
      NAME "Ages"
      TYPE CHART
      CONNECTIONTYPE postgis
      CONNECTION "blabla"
      DATA "the_geom from demo"
      PROCESSING "CHART_TYPE=pie"
      PROCESSING "CHART_SIZE=30"
      STATUS ON
      CLASS
        NAME "Population Age 0-19"
        STYLE
          SIZE [v1006]
          COLOR 255 244 237
        END
      END
      CLASS
        NAME "Population Age 20-39"
        STYLE
          SIZE [v1007]
          COLOR 255 217 191
        END
      END
      CLASS
        NAME "Population Age 40-59"
        STYLE
          SIZE [v1008]
          COLOR 255 186 140
        END
      END 
  END


In the example above, if for a given shape we have v1006=1000, v1007=600 and 
v1008=400 then the actual pie slices for each class will be respectively 50%, 
30% and 20% of the total pie size. If we produced bar charts then the values 
would represent the relative height of the bars with the largest value 
(highest bar) being 100% of the chart height.

The following attachment to ticket 1800 contains a sample map produced
by the layer definition above:

https://trac.osgeo.org/mapserver/attachment/ticket/1800/chart-test.jpg

The layer's legend behaves as usual and produces one color sample per class.

Issues and limitations
----------------------

* The initial implementation supports only GD output formats. However 
  Thomas Bonfort has offered to implement an AGG version once support 
  for it is available. This is considered a future enhancement outside 
  of the scope of this RFC. Update 2007/09/06: chart rendering is supported
  by the AGG renderer too.

* Should we use special keywords instead of PROCESSING parameters to specify
  the chart type and size?

* The values of each class are taken from the SIZE of the corresponding STYLE,
  which is semantically awkward (but that saves us from creating new keywords)


MapScript Implications
----------------------

The new CHART type (constant) would be exposed via MapScript. There are no
other MapScript implications.


Files affected
--------------

::

 map.h          (new MS_LAYER_CHART constant)
 mapfile.c
 maplexer.l     (new CHART keyword)
 mapdraw.c      (hooks to call chart rendering code)
 mapchart.c     (implementation of chart rendering)
 maplegend.c    (add case for chart layer type)
 Makefile.in    (addition of mapchart.o)
 makefile.vc    (addition of mapchart.obj)


Note:

The patch from ticket 1800 also contains changes to mappostgis.c and 
mapmygis.c to treat layer type CHART the same way as POLYGON but I'm not
exactly sure why or if the same needs to be done for other data sources.
This will need further review before being released.

Backwards compatibility issues
------------------------------

None. This is a new feature.

Bug ID
------

* 1800: https://github.com/mapserver/mapserver/issues/1800

Future enhancements:

* 2136: https://github.com/mapserver/mapserver/issues/2136
* 2145: https://github.com/mapserver/mapserver/issues/2145

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

* http://mapserver.gis.umn.edu/docs/howto/dynamic-charting

Voting history
--------------

Vote completed on 2007/07/05:

+1 from DanielM, SteveW, AssefaY

Questions/Comments from the review period
-----------------------------------------

* Q: Does this assume a POLYGON data type input only? Can LINE and POINT data
  sources also be supported?

  A: The current implementation works only for polygon data sources. I could 
  extend it to work on point data sources as well fairly easily I think.

  I'm not sure about line data sources though. I guess we could do like we do 
  for ANNOTATION layers and use msPolylineLabelPoint() to determine the 
  location of the chart. 

  Ticket #2145 has been opened to track this enhancement: 
  https://github.com/mapserver/mapserver/issues/2145

* Q: Could we support attribute binding in CHART_SIZE = [size]? This would 
  allow you to show the relative size of hits at a point and have the chart 
  show the percentage contributions in the wedges.

  A: While this would be a nice feature, we will keep it as a potential 
  enhancement for a future release. See
  ticket #2136: https://github.com/mapserver/mapserver/issues/2136