Chart.h
Go to the documentation of this file.
1 //===========================================================================
2 /*!
3  * \file Chart.h
4  *
5  * \brief Chart.h
6  *
7  * \author T.Voss
8  * \date 2011
9  *
10  * \par Copyright (c) 1998-2007:
11  * Institut f&uuml;r Neuroinformatik<BR>
12  * Ruhr-Universit&auml;t Bochum<BR>
13  * D-44780 Bochum, Germany<BR>
14  * Phone: +49-234-32-25558<BR>
15  * Fax: +49-234-32-14209<BR>
16  * eMail: Shark-admin@neuroinformatik.ruhr-uni-bochum.de<BR>
17  * www: http://www.neuroinformatik.ruhr-uni-bochum.de<BR>
18  * <BR>
19  *
20  *
21  * <BR><HR>
22  * This file is part of Shark. This library is free software;
23  * you can redistribute it and/or modify it under the terms of the
24  * GNU General Public License as published by the Free Software
25  * Foundation; either version 3, or (at your option) any later version.
26  *
27  * This library is distributed in the hope that it will be useful,
28  * but WITHOUT ANY WARRANTY; without even the implied warranty of
29  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
30  * GNU General Public License for more details.
31  *
32  * You should have received a copy of the GNU General Public License
33  * along with this library; if not, see <http://www.gnu.org/licenses/>.
34  *
35  */
36 //===========================================================================
37 #ifndef SHARK_CORE_CHART_H
38 #define SHARK_CORE_CHART_H
39 
40 #include <boost/property_tree/ptree.hpp>
41 #include <boost/variant.hpp>
42 
43 namespace shark {
44 
45  namespace tag {
46  /**
47  * \brief Tags the first (left) x-axis of a chart.
48  */
49  struct FirstXAxis {};
50 
51  /**
52  * \brief Tags the second (right) x-axis of a chart.
53  */
54  struct SecondXAxis {};
55 
56  /**
57  * \brief Tags the first (bottom) y-axis of a chart.
58  */
59  struct FirstYAxis {};
60 
61  /**
62  * \brief Tags the second (top) y-axis of a chart.
63  */
64  struct SecondYAxis {};
65  }
66 
67  /**
68  * \brief Models an abstract chart.
69  *
70  * Allows for programmatically "plotting" of numerical data without the
71  * the need to worry about the actual rendering of the chart.
72  *
73  */
74  class Chart {
75  public:
76 
77  /**
78  * \brief Constant that marks an axis as enabled.
79  */
80  static const bool AXIS_ENABLED = true;
81 
82  /**
83  * \brief Constant that marks an axis as disabled.
84  */
85  static const bool AXIS_DISABLED = false;
86 
87  /**
88  * \brief Default c'tor.
89  *
90  * Enabled the left x-axis and the bottom y-axis. All other axis are
91  * disabled.
92  */
93  Chart( ) : m_firstXAxis( AXIS_ENABLED ),
94  m_firstYAxis( AXIS_ENABLED) {
95  }
96 
97  /**
98  * \brief Models the horizontal alignment of elements.
99  */
100  enum HorizontalAlignment {
101  LEFT,
102  CENTER,
103  RIGHT
104  };
105 
106  /**
107  * \brief Models the vertical alignment of elements.
108  */
109  enum VerticalAlignment {
110  TOP,
111  MIDDLE,
112  BOTTOM
113  };
114 
115  /**
116  * \brief Models an axis and its attributes like its title and its scale.
117  */
118  struct Axis {
119 
120  /**
121  * \brief Models the scale of the axis.
122  */
123  enum Scale {
124  LINEAR_SCALE, ///< Default setting.
125  LOG_10_SCALE
126  };
127 
128  /**
129  * \brief C'tor.
130  *
131  * \param [in] isEnabled Flag that indicate whether the axis shall be enabled or not.
132  */
133  Axis( bool isEnabled = false ) : m_isEnabled( isEnabled ),
134  m_scale( LINEAR_SCALE ) {}
135 
136  /**
137  * \brief Access the properties of the axis.
138  *
139  * In addition to the attributes that are explicitly modelled
140  * arbitrary key/value pairs can be associated with the axis.
141  * These key/value-pairs might be used by renderers to further customize the
142  * output.
143  *
144  * \returns A mutable reference to the properties, allows for l-value semantics.
145  */
146  boost::property_tree::ptree & properties() {
147  return( m_properties );
148  }
149 
150  /**
151  * \brief Access the properties of the axis.
152  *
153  * In addition to the attributes that are explicitly modelled
154  * arbitrary key/value pairs can be associated with the axis.
155  * These key/value-pairs might be used by renderers to further customize the
156  * output.
157  *
158  * \returns An immutable reference to the properties.
159  */
160  const boost::property_tree::ptree & properties() const {
161  return( m_properties );
162  }
163 
164  /**
165  * \brief (De-)Serializes the axis, its attributes and properties.
166  *
167  * \tparam Archive The type of the archive.
168  * \param [in, out] a The archive to read from/write to.
169  * \param [in] version Currently unused.
170  */
171  template<typename Archive>
172  void serialize( Archive & a, const unsigned int version ) {
173  (void) version; // Currently unused
174  a & m_scale;
175  a & m_title;
176  a & m_properties;
177  }
178 
179  bool m_isEnabled; ///< Indicates whether the axis is enabled or not.
180 
181  Scale m_scale; ///< The scaling of the axis.
182  std::string m_title; ///< The title of the axis.
183 
184  boost::property_tree::ptree m_properties; ///< The properties of the axis.
185  };
186 
187  /**
188  * \brief Models the title of a chart.
189  */
190  struct Title {
191  std::string m_text; ///< The title text of the chart.
192  HorizontalAlignment m_horizontalAlignment; ///< The horizontal alignment of the title text, default value: CENTER.
193  VerticalAlignment m_verticalAlignment; ///< The vertical alignment of the title text, default value: MIDDLE.
194 
195  boost::property_tree::ptree m_properties; ///< Renderer specific properties of the title, modelled as kez/value pairs.
196 
197  /**
198  * \brief Default c'tor.
199  */
200  Title() : m_horizontalAlignment( CENTER ),
201  m_verticalAlignment( MIDDLE ) {}
202 
203  /**
204  * \brief Accesses the properties of the title.
205  *
206  * In addition to the attributes that are explicitly modelled
207  * arbitrary key/value pairs can be associated with the axis.
208  * These key/value-pairs might be used by renderers to further customize the
209  * output.
210  *
211  * \returns A mutable reference to the properties, allows for l-value semantics.
212  */
213  boost::property_tree::ptree & properties() {
214  return( m_properties );
215  }
216 
217  /**
218  * \brief Accesses the properties of the title.
219  *
220  * In addition to the attributes that are explicitly modelled
221  * arbitrary key/value pairs can be associated with the axis.
222  * These key/value-pairs might be used by renderers to further customize the
223  * output.
224  *
225  * \returns An immutable reference to the properties.
226  */
227  const boost::property_tree::ptree & properties() const {
228  return( m_properties );
229  }
230 
231  /**
232  * \brief (De-)Serializes the title, its attributes and properties.
233  *
234  * \tparam Archive The type of the archive.
235  * \param [in, out] a The archive to read from/write to.
236  * \param [in] version Currently unused.
237  */
238  template<typename Archive>
239  void serialize( Archive & a, const unsigned int version ) {
240  (void) version; // Currently unused
241  a & m_text;
242  a & m_horizontalAlignment;
243  a & m_verticalAlignment;
244  a & m_properties;
245  }
246  };
247 
248  /**
249  * \brief Models a series and its underlying data.
250  */
251  struct Series {
252 
253  /**
254  * \brief Models a single value, might either be numeric or a category.
255  */
256  typedef boost::variant< double, std::string > ValueType;
257 
258  /**
259  * \brief Models a pair of x-y values.
260  */
261  typedef std::pair< ValueType, ValueType > ElementType;
262 
263  /**
264  * \brief Models the type of the series.
265  */
266  enum Type {
267  AREA_TYPE,
268  AREA_SPLINE_TYPE,
269  BAR_TYPE,
270  COLUMN_TYPE,
271  LINE_TYPE,
272  PIE_TYPE,
273  SCATTER_TYPE,
274  SPLINE_TYPE
275  };
276 
277  /**
278  * \brief Default c'tor.
279  */
280  Series() : m_type( SCATTER_TYPE ) {}
281 
282  /**
283  * \brief Accesses the properties of the series.
284  *
285  * In addition to the attributes that are explicitly modelled
286  * arbitrary key/value pairs can be associated with the series.
287  * These key/value-pairs might be used by renderers to further customize the
288  * output.
289  *
290  * \returns A mutable reference to the properties, allows for l-value semantics.
291  */
292  boost::property_tree::ptree & properties() {
293  return( m_properties );
294  }
295 
296  /**
297  * \brief Accesses the properties of the series.
298  *
299  * In addition to the attributes that are explicitly modelled
300  * arbitrary key/value pairs can be associated with the series.
301  * These key/value-pairs might be used by renderers to further customize the
302  * output.
303  *
304  * \returns An immutable reference to the properties
305  */
306  const boost::property_tree::ptree & properties() const {
307  return( m_properties );
308  }
309 
310  /**
311  * \brief (De-)Serializes the series, its data, attributes and properties.
312  *
313  * \tparam Archive The type of the archive.
314  * \param [in, out] a The archive to read from/write to.
315  * \param [in] version Currently unused.
316  */
317  template<typename Archive>
318  void serialize( Archive & a, const unsigned int version ) {
319  (void) version; // Currently unused
320  a & m_type;
321  a & m_name;
322  a & m_data;
323  a & m_properties;
324  }
325 
326  Type m_type; ///< Type of the series, default value: SCATTER.
327  std::string m_name; ///< Name of the series.
328 
329  std::vector< ElementType > m_data; ///< Data of the series.
330 
331  boost::property_tree::ptree m_properties; ///< Optional properties of the series.
332  };
333 
334  /**
335  * \brief Accesses the title of the chart.
336  * \returns A mutable reference to the title of the chart, allows for l-value semantic.
337  */
338  Title & title() {
339  return( m_title );
340  }
341 
342  /**
343  * \brief Accesses the title of the chart.
344  * \returns An immutable reference to the title of the chart.
345  */
346  const Title & title() const {
347  return( m_title );
348  }
349 
350  /**
351  * \brief Accesses the first (left) x-axis.
352  * \returns An mutable reference to the axis, allows for l-value semantics.
353  */
354  Axis & axis( tag::FirstXAxis ) {
355  return( m_firstXAxis );
356  }
357 
358  /**
359  * \brief Accesses the first (bottom) y-axis.
360  * \returns An mutable reference to the axis, allows for l-value semantics.
361  */
362  Axis & axis( tag::FirstYAxis ) {
363  return( m_firstYAxis );
364  }
365 
366  /**
367  * \brief Accesses the second (right) x-axis.
368  * \returns An mutable reference to the axis, allows for l-value semantics.
369  */
370  Axis & axis( tag::SecondXAxis ) {
371  return( m_secondXAxis );
372  }
373 
374  /**
375  * \brief Accesses the second (bottom) y-axis.
376  * \returns An mutable reference to the axis, allows for l-value semantics.
377  */
378  Axis & axis( tag::SecondYAxis ) {
379  return( m_secondYAxis );
380  }
381 
382  /**
383  * \brief Accesses the first (left) x-axis.
384  * \returns An immutable reference to the axis.
385  */
386  const Axis & axis( tag::FirstXAxis ) const {
387  return( m_firstXAxis );
388  }
389 
390  /**
391  * \brief Accesses the second (right) x-axis.
392  * \returns An immutable reference to the axis.
393  */
394  const Axis & axis( tag::SecondXAxis ) const {
395  return( m_secondXAxis );
396  }
397 
398  /**
399  * \brief Accesses the first (left) y-axis.
400  * \returns An immutable reference to the axis.
401  */
402  const Axis & axis( tag::FirstYAxis ) const {
403  return( m_firstYAxis );
404  }
405 
406  /**
407  * \brief Accesses the second (top) y-axis.
408  * \returns An immutable reference to the axis.
409  */
410  const Axis & axis( tag::SecondYAxis ) const {
411  return( m_secondYAxis );
412  }
413 
414  /**
415  * \brief Accesses the vector of series objects.
416  * \returns A mutable reference to the vector, allows for l-value semantics.
417  */
418  std::vector< Series > & series() {
419  return( m_series );
420  }
421 
422  /**
423  * \brief Accesses the vector of series objects.
424  * \returns An immutable reference to the vector.
425  */
426  const std::vector< Series > & series() const {
427  return( m_series );
428  }
429 
430  /**
431  * \brief Accesses the properties of the chart.
432  *
433  * In addition to the attributes that are explicitly modelled
434  * arbitrary key/value pairs can be associated with the chart.
435  * These key/value-pairs might be used by renderers to further customize the
436  * output.
437  *
438  * \returns A mutable reference to the properties, allows for l-value semantics.
439  */
440  boost::property_tree::ptree & properties() {
441  return( m_properties );
442  }
443 
444  /**
445  * \brief Accesses the properties of the chart.
446  *
447  * In addition to the attributes that are explicitly modelled
448  * arbitrary key/value pairs can be associated with the chart.
449  * These key/value-pairs might be used by renderers to further customize the
450  * output.
451  *
452  * \returns An immutable reference to the properties
453  */
454  const boost::property_tree::ptree & properties() const {
455  return( m_properties );
456  }
457 
458  /**
459  * \brief (De-)Serializes the title, its attributes and properties.
460  *
461  * \tparam Archive The type of the archive.
462  * \param [in, out] a The archive to read from/write to.
463  * \param [in] version Currently unused.
464  */
465  template<typename Archive>
466  void serialize( Archive & a, const unsigned int version ) {
467  a & m_title;
468 
469  a & m_firstXAxis;
470  a & m_secondXAxis;
471  a & m_firstYAxis;
472  a & m_secondYAxis;
473 
474  a & m_series;
475  a & m_properties;
476  }
477 
478  Title m_title;
479 
480  Axis m_firstXAxis;
481  Axis m_secondXAxis;
482  Axis m_firstYAxis;
483  Axis m_secondYAxis;
484 
485  std::vector< Series > m_series;
486 
487  boost::property_tree::ptree m_properties;
488  };
489 
490 }
491 
492 #endif // SHARK_CORE_CHART_H