Plot2D.h

Go to the documentation of this file.
00001 /**
00002 \file    Plot2D.h
00003 \brief   The plotting class.
00004 
00005 \author  Glenn D. MacGougan (GDM)
00006 \date    2007-12-19
00007 \since   2007-12-19
00008 
00009 \b "LICENSE INFORMATION" \n
00010 Copyright (c) 2007, refer to 'author' doxygen tags \n
00011 All rights reserved. \n
00012 
00013 Redistribution and use in source and binary forms, with or without
00014 modification, are permitted provided the following conditions are met: \n
00015 
00016 - Redistributions of source code must retain the above copyright
00017   notice, this list of conditions and the following disclaimer. \n
00018 - Redistributions in binary form must reproduce the above copyright
00019   notice, this list of conditions and the following disclaimer in the
00020   documentation and/or other materials provided with the distribution. \n
00021 - The name(s) of the contributor(s) may not be used to endorse or promote 
00022   products derived from this software without specific prior written 
00023   permission. \n
00024 
00025 THIS SOFTWARE IS PROVIDED BY THE CONTRIBUTORS ``AS IS'' AND ANY EXPRESS 
00026 OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
00027 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00028 DISCLAIMED. IN NO EVENT SHALL THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
00029 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00030 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
00031 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
00032 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 
00033 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 
00034 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 
00035 SUCH DAMAGE.
00036 */
00037 
00038 #ifndef _PLOT2D_H_
00039 #define _PLOT2D_H_
00040 
00041 #include <string>
00042 #include <vector>
00043 #include "cplot.h"
00044 
00045 namespace namespace_Plot2D
00046 {
00047   /// \brief  The options needed for a series.
00048   struct PLOT2D_structSeriesInfo
00049   {
00050     std::string  DataPath;  //!< The path to the data file.
00051     unsigned X_Column;      //!< The zero based index of the x part of the series.
00052     unsigned Y_Column;      //!< The zero based index of the y part of the series.
00053     bool negate_X;          //!< A boolean to indicate if the user wants to plot -X vs Y.
00054     bool negate_Y;          //!< A boolean to indicate if the user wants to plot X vs -Y.
00055     bool IsConnected;       //!< Is the data connected with line?
00056     CPLOT_enumColor Color;  //!< The color of the points/lines for this series.
00057     std::string Label;      //!< The series label.
00058     std::string Units;      //!< The series label units.
00059     unsigned Precision;     //!< The precision for the statistics table if present.
00060     bool MarkOutlierData;   //!< Data outside the plot window can be indicated (in Cyan) along the plot borders by enabling this option.
00061     bool UsesRightYLabel;   //!< Indicates if data pertains to the right y label.
00062 
00063     PLOT2D_structSeriesInfo()
00064       : X_Column(0), 
00065       Y_Column(1), 
00066       negate_X(false),
00067       negate_Y(false),
00068       IsConnected(true), 
00069       Color(CPLOT_BLUE), 
00070       Precision(3), 
00071       MarkOutlierData(true), 
00072       UsesRightYLabel(false)
00073     {}
00074   };
00075 
00076 
00077   /// \brief   A 2D plotting class.
00078   class Plot2D
00079   { 
00080   public: 
00081 
00082     /// \brief    The default constructor (no data allocated yet).
00083     Plot2D();                                             
00084 
00085     /// \brief    The destructor.
00086     virtual ~Plot2D();
00087 
00088   private:
00089 
00090     /// \brief   The copy constructor. Disabled!
00091     Plot2D( const Plot2D& rhs ) {};
00092 
00093     /// \brief   The assignment operator. Disabled!
00094     void operator=(const Plot2D& rhs) {};
00095 
00096   public:
00097 
00098     /// \brief  Set the figure title.
00099     void SetTitle( const std::string title );
00100 
00101     /// \brief  Set the total number of series to plot.
00102     /// \return true if successful, false otherwise
00103     bool SetNrSeries( const int nrSeries );
00104 
00105     /// \brief  Set the plot size [cm].
00106     /// \return true if successful, false otherwise
00107     bool SetPlotSize( const int width_cm, const int height_cm );
00108 
00109 
00110     /// \brief  Set the x axis label. 
00111     /// \return true if successful, false otherwise
00112     bool Set_X_Label( const std::string label );
00113     
00114     /// \brief  Set the x axis grid lines on/off.
00115     /// \return true if successful, false otherwise
00116     bool Set_X_Axis_isGridOn( const bool isGridOn );
00117 
00118 
00119     /// \brief  Set the x axis lower limit. 
00120     ///  Otherwise it will be computed automatically based on the first series used.
00121     /// \return true if successful, false otherwise
00122     bool Set_X_Axis_LowerLimit( const double value );
00123 
00124     /// \brief  Set the x axis upper limit. 
00125     ///  Otherwise it will be computed automatically based on the first series used.
00126     /// \return true if successful, false otherwise
00127     bool Set_X_Axis_UpperLimit( const double value );
00128 
00129     /// \brief  Set the x axis tick start. 
00130     ///  Otherwise it will be computed automatically based on the first series used.
00131     /// \return true if successful, false otherwise
00132     bool Set_X_Axis_TickStart( const double value );
00133 
00134     /// \brief  Set the x axis tick size. 
00135     ///  Otherwise it will be computed automatically based on the first series used.
00136     /// \return true if successful, false otherwise
00137     bool Set_X_Axis_TickSize( const double value );
00138 
00139     /// \brief  Set the x axis tick end. 
00140     ///  Otherwise it will be computed automatically based on the first series used.
00141     /// \return true if successful, false otherwise
00142     bool Set_X_Axis_TickEnd( const double value );
00143 
00144     /// \brief  Set the y axis label. 
00145     /// \return true if successful, false otherwise
00146     bool Set_Y_Label( const std::string label );    
00147 
00148     /// \brief  Set the y axis grid lines on/off.
00149     /// \return true if successful, false otherwise
00150     bool Set_Y_Axis_isGridOn( const bool isGridOn );
00151 
00152 
00153     /// \brief  Set the y axis lower limit. 
00154     ///  Otherwise it will be computed automatically based on the first series used.
00155     /// \return true if successful, false otherwise
00156     bool Set_Y_Axis_LowerLimit( const double value );
00157 
00158     /// \brief  Set the y axis upper limit. 
00159     ///  Otherwise it will be computed automatically based on the first series used.
00160     /// \return true if successful, false otherwise
00161     bool Set_Y_Axis_UpperLimit( const double value );
00162 
00163     /// \brief  Set the y axis tick start. 
00164     ///  Otherwise it will be computed automatically based on the first series used.
00165     /// \return true if successful, false otherwise
00166     bool Set_Y_Axis_TickStart( const double value );
00167 
00168     /// \brief  Set the y axis tick size. 
00169     ///  Otherwise it will be computed automatically based on the first series used.
00170     /// \return true if successful, false otherwise
00171     bool Set_Y_Axis_TickSize( const double value );
00172 
00173     /// \brief  Set the y axis tick end. 
00174     ///  Otherwise it will be computed automatically based on the first series used.
00175     /// \return true if successful, false otherwise
00176     bool Set_Y_Axis_TickEnd( const double value );
00177 
00178 
00179     /// \brief  Set the right y label.
00180     /// \return true if successful, false otherwise
00181     bool SetRightYLabel( 
00182       const std::string label,            //!< The description string.
00183       double y_label_right_scale_factor,  //!< The scale factor.
00184       double y_label_right_bias,          //!< The bias.
00185       CPLOT_enumColor color               //!< The color.
00186       );
00187 
00188     /// \brief  Enable the special GPS x axis label with the UTCOffset specified.
00189     /// \param  UTCOffset always +ve
00190     /// \return true if successful, false otherwise
00191     bool SetGPSLabel( const int UTCOffset );
00192 
00193 
00194     /// \brief  Set the figure background color.
00195     /// \return true if successful, false otherwise
00196     bool SetBackgroundColor( const CPLOT_enumColor color );
00197 
00198     
00199     /// \brief  Enable/Disable the plot statisics.
00200     void EnablePlotStatistics( const bool enable );
00201 
00202 
00203     /// \brief  Set the labels and statistics to appear below the plot
00204     /// rather than to the right.
00205     void SetTheSeriesLabelsBelowThePlot( const bool setBelow );
00206 
00207 
00208     // Use either
00209     // SetSeriesInfo in combination with PlotAll()
00210     // or
00211     // call Plot( PLOT2D_structSeriesInfo &series ) repeatedly.
00212 
00213 
00214     /// \brief  Set the options for this series and get the data needed.
00215     /// \return true if successful, false otherwise    
00216     bool SetSeriesInfo( const unsigned index, PLOT2D_structSeriesInfo &series );
00217 
00218     /// \brief  Plot all the series set with SetSeriesInfo().
00219     /// \return true if successful, false otherwise        
00220     bool PlotAll();
00221 
00222 
00223     /// \brief  Call this function to plot a series. Call it repeatedly 
00224     /// to plot multiple series.
00225     /// \return true if successful, false otherwise
00226     bool Plot( PLOT2D_structSeriesInfo &series );
00227 
00228     
00229     /// \brief  Save the plot to the specified filename.
00230     /// \return true if successful, false otherwise
00231     bool SavePlotToBitmapFile( std::string filename );
00232 
00233   public:
00234 
00235     /// A struct for holding a matrix read from file.
00236     struct _PLOT2D_structMTX
00237     {
00238       double *data;   //!< The C sytle data container, data[row*ncols+col]
00239       unsigned nrows; //!< The number of rows.
00240       unsigned ncols; //!< The number of columns.
00241 
00242       _PLOT2D_structMTX()
00243         : data(NULL), nrows(0), ncols(0)
00244       {}
00245     };
00246 
00247   protected:
00248 
00249     bool m_ArePlotOptionsSet; //!< A boolean to indicate if m_opt.PlotOptions has been set.    
00250 
00251     CPLOT_structPlotOptions m_opt;
00252 
00253     std::string m_title;
00254     std::string m_x_label;
00255     std::string m_y_label;
00256     std::string m_y_label_right;
00257 
00258     CPLOT m_plot; //!< The plotting C 'object'.
00259 
00260     CPLOT_structSeries m_Series[12];  //!< The deep level series struct array.
00261 
00262     double m_xmin; //!< For all series the min x value.
00263     double m_xmax; //!< For all series the max x value.
00264     double m_ymin; //!< For all series the min y value.
00265     double m_ymax; //!< For all series the max y value.
00266     
00267     _PLOT2D_structMTX  m_mtx; //!< The matrix data that will be obtained from the file(s).
00268     std::string m_prev_datapath; //!< This is the path to the last data file used.
00269     
00270   };
00271 
00272 } // end namespace
00273 
00274 #endif // _PLOT2D_H_
00275