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:

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