[mapserver-commits] r8044 - trunk/docs/howto
svn at osgeo.org
svn at osgeo.org
Fri Nov 21 22:28:37 EST 2008
Author: hobu
Date: 2008-11-21 22:28:37 -0500 (Fri, 21 Nov 2008)
New Revision: 8044
Modified:
trunk/docs/howto/dynamic-charting.txt
Log:
convert to ReST
Modified: trunk/docs/howto/dynamic-charting.txt
===================================================================
--- trunk/docs/howto/dynamic-charting.txt 2008-11-21 21:41:33 UTC (rev 8043)
+++ trunk/docs/howto/dynamic-charting.txt 2008-11-22 03:28:37 UTC (rev 8044)
@@ -1,20 +1,235 @@
-Starting with version 5.0, MapServer included the ability to automatically draw pie or bar graphs whose values are taken and adjusted from attributes of a data-source.
-<p>This document assumes that you are already familiar with MapServer application development and especially setting up <a class="reference" href="../../reference/mapfile">.map files</a>. Readers can also check out the <a class="reference" href="../../reference/vector_data">Vector Data Access Guide</a>, which has lots of
-examples of how to access specific data sources.</p><h2>Setup</h2><h3>Supported Renderers</h3>Dynamic charts are supported solely with the GD and AGG renderers. Attempting to add a chart layer with any other renderer (e.g. PDF or SWF) will result in an error. Rendering quality with the GD renderer is less than optimal, especially with small graphs, due to the lack of subpixel rendering functions.<br /><br /><table class="plain"><tbody><tr><th colspan="2">Output from AGG and GD Renderers</th></tr><tr><td><img class="image-left" src="renderer-agg" alt="AGG rendered example" /></td><td><img class="image-left" src="gd-renderer" alt="GD rendered example" /> <br /></td></tr><tr><td>AGG<br /></td><td>GD</td></tr></tbody></table><br /><br /><h2>Adding a Chart Layer to a Mapfile</h2><h3><br /></h3><h3>Layer Type</h3>A new type of layer has been added to the mapfile syntax. To specify a chart layer, use:<br /><pre>LAYER<br />...<br /> TYPE CHART<br />...<br />END<br /></pre><p>No other specific keywords have been added in order to keep the number of different keywords to a minimum in the mapfile syntax, therefore all the chart specific configuration is determined by PROCESSING directives.</p><h3><br /></h3><h3>Specifying the Size of each Chart</h3>The size of each chart is specified by the CHART_SIZE directive. If two values are given for this parameter, this will specify the width and height of each chart (this only applies for bar graphs). By default, the charts are 20x20 pixels.<br /><pre>LAYER<br /> TYPE CHART<br /> PROCESSING "CHART_SIZE=21" # specify size of the chart for pie or bar graphs<br /> #PROCESSING "CHART_SIZE=20 10" # specify width and height for bar graphs<br />...<br />END<br /></pre>
-<br/>
-For those living on the bleeding edge, the diameter of a pie chart can be bound to an attribute starting from trunk version of 2007-10-20. details <a href="http://trac.osgeo.org/mapserver/ticket/2136">here</a>
-<br/><br/>
-<h3>Specifying the Values to be Plotted</h3>Each value to be plotted (i.e. a slice in a pie chart, or a bar in a par graph) is specified in a CLASS of the chart layer. The value to be plotted is taken from the SIZE keyword from the first STYLE block of the class. This is semantically a bit awkward, but keeps the number of different keywords to a minimum in the mapfile syntax. The value given to the SIZE keyword could of course be given a static value, but dynamic charting really only makes sense with attribute binding.<br /><pre>LAYER<br />...<br /> CLASS<br /> NAME "value 1" #include a NAME keyword if you want this class to be included in the legend<br /> STYLE<br /> SIZE [attribute] #specify which value from the data source will be used as the value for the graph<br /> ....<br /> END<br /> END<br /> CLASS<br /> ...<br /> END<br />...<br />END<br /></pre>At least 2 CLASS blocks must be specified before charting can occur (but you already knew this if you want your charts to convey at least <i>some</i> information ;) ).<br /><br /><h3>Specifying Style</h3>The styling of each value in the charts is specified by the usual mapserver syntax. Only one style per class is supported, any other STYLE block will be silently ignored. Only a subset of the styling keywords are supported:<br /><pre>STYLE<br /> SIZE [attribute]<br /> COLOR r g b #specify the fill color<br /> OUTLINECOLOR r g b #if present will draw an outline around the corresponding bar or slice<br /> WIDTH w #specify the width of the outline if OUTLINECOLOR is present (defaults to 1)<br /> OFFSET a b #only for pie charts. 'a' is the number of pixels the corresponding slice will be<br /> #offset relative to the center of the pie. This is usefull for emphasising a specific <br /> #value in each chart. 'b' is required by the mapfile parser but is ignored.<br />END<br /></pre><br /><h2>Pie Charts</h2>This is the default type of chart that is rendered. This can also be specifically set with a PROCESSING keyword in the layer attributes:<br /><pre>PROCESSING "CHART_TYPE=PIE"</pre>For each shape in the layer's datasource, the STYLE SIZE is used to set the relative size (value) of each pie slice, with the angles of the slices that are automatically computed so as to form a full pie. For example:<br /><pre class="literal-block">LAYER<br /> NAME "Ages"<br /> TYPE CHART<br /> CONNECTIONTYPE postgis<br /> CONNECTION "blabla"<br /> DATA "the_geom from demo"<br /> PROCESSING "CHART_TYPE=pie"<br /> PROCESSING "CHART_SIZE=30"<br /> STATUS ON<br /> CLASS<br /> NAME "Population Age 0-19"<br /> STYLE<br /> SIZE [v1006]<br /> COLOR 255 244 237<br /> END<br /> END<br /> CLASS<br /> NAME "Population Age 20-39"<br /> STYLE<br /> SIZE [v1007]<br /> COLOR 255 217 191<br /> END<br /> END<br /> CLASS<br /> NAME "Population Age 40-59"<br /> STYLE<br /> SIZE [v1008]<br /> COLOR 255 186 140<br /> END<br /> END <br />END</pre>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.<br /><br /><h2>Bar Graphs</h2>Bar graph drawing is set with a PROCESSING keyword in the layer attributes:<br /><pre>PROCESSING "CHART_TYPE=BAR"</pre>For each shape in the layer's datasource, the STYLE SIZE is used to set the relative size (value) of each bar in the graph. By default, the vertical axis of each bar graph is scaled for the values of the corresponding shape, and will always include the origin (=0). For example:<br /><ul><li>a shape whose STYLE SIZEs contains values {5,8,10,3} will be plotted on a graph whose vertical axis spans 0 to 10.</li><li>a shape whose STYLE SIZEs contains values {-5,-8,-10,-3} will be plotted on a graph whose vertical axis spans -10 to 0.</li><li>a shape whose STYLE SIZEs contains values {-5,-8,10,3} will be plotted on a graph whose vertical axis spans -8 to 10.</li></ul><br />Additional PROCESSING directives are used to optionally specify the bounds of vertical axes so that the graphs for all the shapes can be plotted with the same scale:<br /><pre>PROCESSING "CHART_BAR_MINVAL=val"<br />PROCESSING "CHART_BAR_MAXVAL=val"<br /></pre>
-Values in the datasource that are above CHART_BAR_MAXVAL or below CHART_BAR_MINVAL will be clipped respectively to these values. If only one of these directives is included, the other will be automatically adjusted for each shape to include at least the origin, i.e. the graphs for all the shapes will be in the same scale <i>only if </i>all the values are of the same sign (positive or negative).<br /><br /><h3><a class="toc-backref" name="about-this-document" href="../ogr_howto/#table-of-contents"></a></h3><h2>About This Document</h2><h3>Copyright Information</h3><div id="copyright-information" class="section"><p>Copyright (c) 2007, Thomas Bonfort.</p>
-<p>This documentation is covered by the same Open Source license as the MapServer
-software itself. See MapServer's <a class="reference" href="../../../License">License and Credits</a> page for the complete
-text.<br /><a class="toc-backref" name="disclaimer" href="../ogr_howto/#table-of-contents"></a><br /></p></div><h3>Disclamer</h3><div id="copyright-information" class="section"><p>No liability for the contents of this document can be accepted.
-Use the concepts, examples and other content at your own risk.
-As this is a new edition of this document, there may be errors
-and inaccuracies that may be damaging to your system.
-Although this is highly unlikely, the author(s) do not take any
-responsibility for that: proceed with caution.</p></div>
-<div id="disclaimer" class="section">
-</div><br />
\ No newline at end of file
+*****************************************************************************
+ Dynamic Charting
+*****************************************************************************
+
+:Author: Thomas Bonfort
+:Contact: thomas.bonfort at gmail.com
+:Revision: $Revision$
+:Date: $Date$
+:Last Updated: 2007/10/23
+
+.. sectnum::
+
+.. contents:: Table of Contents
+ :depth: 2
+ :backlinks: top
+
+Starting with version 5.0, MapServer included the ability to automatically draw
+pie or bar graphs whose values are taken and adjusted from attributes of a
+datasource.
+
+This document assumes that you are already familiar with MapServer application
+development and especially setting up :ref:reference/mapfile mapfiles. Readers
+can also check out the :ref:vector_data Vector Data Access Guide, which has lots of
+examples of how to access specific data sources.
+
+Setup
+-------------------------------------------------------------------------------
+
+Supported Renderers
+...............................................................................
+
+Dynamic charts are supported solely with the GD and AGG renderers.
+
+Attempting to add a chart layer with any other renderer (e.g. PDF or SWF) will
+result in an error. Rendering quality with the GD renderer is less than optimal,
+especially with small graphs, due to the lack of subpixel rendering functions.
+
+Output from AGG and GD Renderers
+
+.. image:: renderer-agg.png
+.. image:: gd-renderer.png
+
+
+Adding a Chart Layer to a Mapfile
+-------------------------------------------------------------------------------
+
+Layer Type
+...............................................................................
+
+A new type of layer has been added to the mapfile syntax. To specify a chart
+layer, use
+
+::
+
+LAYER
+...
+ TYPE CHART
+ ...
+END
+
+No other specific keywords have been added in order to keep the number of
+different keywords to a minimum in the mapfile syntax, therefore all the
+chart specific configuration is determined by PROCESSING directives.
+
+Specifying the Size of each Chart
+...............................................................................
+
+The size of each chart is specified by the CHART_SIZE directive. If two values
+are given for this parameter, this will specify the width and height of each
+chart (this only applies for bar graphs). By default, the charts are 20x20
+pixels.
+
+::
+
+LAYER
+ TYPE CHART
+ PROCESSING "CHART_SIZE=21" # specify size of the chart for pie or bar graphs
+ #PROCESSING "CHART_SIZE=20 10" # specify width and height for bar graphs
+ ...
+END
+
+For those living on the bleeding edge, the diameter of a pie chart can be bound
+to an attribute starting from trunk version of 2007-10-20. Details located at http://trac.osgeo.org/MapServer/ticket/2136
+
+Specifying the Values to be Plotted
+...............................................................................
+
+Each value to be plotted (i.e. a slice in a pie chart, or a bar in a par graph)
+is specified in a CLASS of the chart layer. The value to be plotted is taken
+from the SIZE keyword from the first STYLE block of the class. This is
+semantically a bit awkward, but keeps the number of different keywords to a
+minimum in the mapfile syntax. The value given to the SIZE keyword could of
+course be given a static value, but dynamic charting really only makes sense
+with attribute binding.
+
+::
+
+LAYER
+...
+ CLASS
+ # include a NAME keyword if you want this class to be included
+ # in the legend
+ NAME "value 1"
+ STYLE
+ # specify which value from the data source will be used as the
+ # value for the graph
+ SIZE [attribute]
+ ...
+ END
+ END
+ CLASS
+ ...
+ END
+...
+END
+
+At least 2 CLASS blocks must be specified before charting can occur (but
+you already knew this if you want your charts to convey at least *some*
+information ;) ).
+
+Specifying Style
+...............................................................................
+
+The styling of each value in the charts is specified by the usual MapServer
+syntax. Only one style per class is supported, any other STYLE block will
+be silently ignored. Only a subset of the styling keywords are supported:
+
+::
+
+STYLE
+ SIZE [attribute]
+ # specify the fill color
+ COLOR r g b
+
+ # if present will draw an outline around the corresponding bar or slice
+ OUTLINECOLOR r g b
+
+ #specify the width of the outline if OUTLINECOLOR is present (defaults to 1)
+ WIDTH w
+
+ # only for pie charts. 'a' is the number of pixels the corresponding
+ # slice will be offset relative to the center of the pie. This is useful
+ # for emphasizing a specific value in each chart. 'b' is required by the
+ # mapfile parser but is ignored.
+ OFFSET a b
+END
+
+Pie Charts
+-------------------------------------------------------------------------------
+
+This is the default type of chart that is rendered. This can also be
+specifically set with a PROCESSING keyword in the layer attributes:
+
+::
+
+PROCESSING "CHART_TYPE=PIE"
+
+For each shape in the layer's datasource, the STYLE SIZE is used to set
+the relative size (value) of each pie slice, with the angles of the slices
+that are automatically computed so as to form a full pie. For 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.
+
+Bar Graphs
+-------------------------------------------------------------------------------
+
+Bar graph drawing is set with a PROCESSING keyword in the layer attributes:
+
+::
+
+PROCESSING "CHART_TYPE=BAR"
+
+For each shape in the layer's datasource, the STYLE SIZE is used to set the
+relative size (value) of each bar in the graph. By default, the vertical axis
+of each bar graph is scaled for the values of the corresponding shape, and
+will always include the origin (=0). For example
+
+ * a shape whose STYLE SIZEs contains values {5,8,10,3} will be plotted
+ on a graph whose vertical axis spans 0 to 10.
+ * a shape whose STYLE SIZEs contains values {-5,-8,-10,-3} will be plotted
+ on a graph whose vertical axis spans -10 to 0.
+ * a shape whose STYLE SIZEs contains values {-5,-8,10,3} will be plotted
+ on a graph whose vertical axis spans -8 to 10.
+
+Additional PROCESSING directives are used to optionally specify the bounds
+of vertical axes so that the graphs for all the shapes can be plotted with
+the same scale:
+
+::
+
+PROCESSING "CHART_BAR_MINVAL=val"
+PROCESSING "CHART_BAR_MAXVAL=val"
+
+Values in the datasource that are above CHART_BAR_MAXVAL or below
+CHART_BAR_MINVAL will be clipped respectively to these values. If only one of
+these directives is included, the other will be automatically adjusted for
+each shape to include at least the origin, i.e. the graphs for all the
+shapes will be in the same scale <i>only if </i>all the values are of the
+same sign (positive or negative).
\ No newline at end of file
More information about the mapserver-commits
mailing list