Added API docs to ImageViewer

refs #5058

Code/Mantid/MantidQt/ImageViewer/inc/MantidQtImageViewer/ColorMaps.h

@@ -8,9 +8,10 @@
 /**
     @class ColorMaps 
   
-       This class provides convenient access to several useful color maps
-    for the ImageView data viewer.
- 
+       This class has static methods to construct some useful color scales
+    and to build a lookup table to brighten an image, so low-level 
+    intensities become more visible 
+
     @author Dennis Mikkelson 
     @date   2012-04-03 
      

Code/Mantid/MantidQt/ImageViewer/inc/MantidQtImageViewer/DataArray.h

@@ -43,32 +43,48 @@ namespace ImageView
 class EXPORT_OPT_MANTIDQT_IMAGEVIEWER DataArray
 {
   public:
+
+    // Construct a DataArray "wrapper" around the data and region info
     DataArray( double xmin,     double xmax,
                double ymin,     double ymax,
                bool   is_log_x,
                size_t n_rows,   size_t n_cols,
                float *data );
 
+    // Get the smallest 'x' value actually covered by this DataArray
     double GetXMin()    const;
+
+    // Get the largest 'x' value actually covered by this DataArray
     double GetXMax()    const;
+
+    // Get the smallest 'y' value actually covered by this DataArray
     double GetYMin()    const;
+
+    // Get the largest 'y' value actually covered by this DataArray
     double GetYMax()    const;
 
+    // Check if the returned array is binned logarithmically in 'x'
     bool   GetIsLogX()  const;
 
+    // Get smallest value recorded in this DataArray
     double GetDataMin() const;
+
+    // Get largest value recorded in this DataArray
     double GetDataMax() const;
 
+    // Get the actual number of rows in this DataArray
     size_t GetNRows()   const;
+
+    // Get the actual number of columns in this DataArray
     size_t GetNCols()   const;
 
-    // get simple array containing all values
+    // Get simple array containing all values, packed in a 1-D array
     float* GetData()    const;
 
-    // get value at specified row and column
+    // Get the value at the specified row and column
     double GetValue( int row, int col ) const;
 
-    // get value from row and column containing the specified point
+    // Get the value from the row and column containing the specified point
     double GetValue( double x, double y ) const;
 
   private:

Code/Mantid/MantidQt/ImageViewer/inc/MantidQtImageViewer/EventWSDataSource.h

@@ -48,11 +48,11 @@ namespace MantidQt
 namespace ImageView
 {
 
-
 class EXPORT_OPT_MANTIDQT_IMAGEVIEWER EventWSDataSource: public ImageDataSource
 {
   public:
 
+    /// Construct a DataSource object around the specifed EventWorkspace
     EventWSDataSource( EventWorkspace_sptr ev_ws );
 
    ~EventWSDataSource();
@@ -69,6 +69,7 @@ class EXPORT_OPT_MANTIDQT_IMAGEVIEWER EventWSDataSource: public ImageDataSource
                               size_t  n_cols,
                               bool    is_log_x );
 
+    /// Get a list containing pairs of strings with information about x,y
     void GetInfoList( double x,
                       double y,
                       std::vector<std::string> &list );

Code/Mantid/MantidQt/ImageViewer/inc/MantidQtImageViewer/GraphDisplay.h

@@ -46,32 +46,38 @@ namespace ImageView
 class EXPORT_OPT_MANTIDQT_IMAGEVIEWER GraphDisplay 
 {
   public:
-     GraphDisplay( QwtPlot*      graph_plot, 
-                   QTableWidget* graph_table,
-                   bool          is_vertical );
 
-    ~GraphDisplay();
+   /// Construct a GraphDisplay to display in the specifed plot and table    
+   GraphDisplay( QwtPlot*      graph_plot, 
+                 QTableWidget* graph_table,
+                 bool          is_vertical );
 
-     void SetDataSource( ImageDataSource* data_source );
+  ~GraphDisplay();
 
-     void SetData( const QVector<double> & xData,
-                   const QVector<double> & yData,
-                         double            image_x,
-                         double            image_y );
+   /// Set the source of information for the table of position information 
+   void SetDataSource( ImageDataSource* data_source );
 
-     void SetPointedAtPoint( QPoint point );
+   /// Set the actual data that will be displayed on the graph
+   void SetData( const QVector<double> & xData,
+                 const QVector<double> & yData,
+                       double            image_x,
+                       double            image_y );
+
+   /// Record the point that the user is currently pointing at with the mouse
+   void SetPointedAtPoint( QPoint point );
 
   private:
-     void ShowInfoList( double x, double y );
+   /// Show information about the point (x, y) on the graph, in the info table
+   void ShowInfoList( double x, double y );
 
-     QwtPlot*          graph_plot;
-     QwtPlotCurve*     curve;
-     QTableWidget*     graph_table;
-     ImageDataSource*  data_source;
+   QwtPlot*          graph_plot;
+   QwtPlotCurve*     curve;
+   QTableWidget*     graph_table;
+   ImageDataSource*  data_source;
 
-     bool    is_vertical;
-     double  image_x;
-     double  image_y;
+   bool    is_vertical;
+   double  image_x;
+   double  image_y;
 };
 
 } // namespace MantidQt 

Code/Mantid/MantidQt/ImageViewer/inc/MantidQtImageViewer/IVConnections.h

@@ -57,11 +57,14 @@ class EXPORT_OPT_MANTIDQT_IMAGEVIEWER IVConnections: public QWidget
 
 public:
 
-   IVConnections( Ui_MainWindow* ui, 
-                  ImageDisplay*  image_display,
-                  GraphDisplay*  h_graph_display,
-                  GraphDisplay*  v_graph_display );
-   ~IVConnections();
+  /// Construct the object that links the GUI components to the other specifed
+  /// higher level objects.
+  IVConnections( Ui_MainWindow* ui, 
+                 ImageDisplay*  image_display,
+                 GraphDisplay*  h_graph_display,
+                 GraphDisplay*  v_graph_display );
+
+  ~IVConnections();
 
 public slots:
   void somethingChanged();

Code/Mantid/MantidQt/ImageViewer/inc/MantidQtImageViewer/ImageDataSource.h

@@ -47,17 +47,29 @@ class EXPORT_OPT_MANTIDQT_IMAGEVIEWER ImageDataSource
 {
   public:
 
+    /// construct data source with specified total range and data size
     ImageDataSource( double total_xmin, double total_xmax,
                      double total_ymin, double total_ymax,
                      size_t total_rows, size_t total_cols );
 
     virtual ~ImageDataSource();
 
+    /// Get the smallest 'x' value covered by the data
     virtual double GetXMin()    const;
+
+    /// Get the largest 'x' value covered by the data
     virtual double GetXMax()    const;
+
+    /// Get the smallest 'y' value covered by the data
     virtual double GetYMin()    const;
+
+    /// Get the largest 'y' value covered by the data
     virtual double GetYMax()    const;
+
+    /// Get the total number of rows of data
     virtual size_t GetNRows()   const;
+
+    /// Get the total number of columns of data
     virtual size_t GetNCols()   const;
 
     /// Get a DataArray roughly spaning the specified rectangle.  NOTE: The
@@ -74,8 +86,7 @@ class EXPORT_OPT_MANTIDQT_IMAGEVIEWER ImageDataSource
     /// Convenience method to get data covering the full range at max resolution
     virtual DataArray* GetDataArray( bool is_log_x );
 
-    /// Get list of pairs of strings to display in table, with info about data
-    /// at location x, y
+    /// Get list of pairs of strings with info about the data at location x, y
     virtual void GetInfoList( double x, 
                               double y,
                               std::vector<std::string> &list ) = 0;

Code/Mantid/MantidQt/ImageViewer/inc/MantidQtImageViewer/ImageDisplay.h

@@ -52,6 +52,8 @@ namespace ImageView
 class EXPORT_OPT_MANTIDQT_IMAGEVIEWER ImageDisplay
 {
   public:
+
+     /// Make an ImageDisplay to display with the given widgets and controls 
      ImageDisplay( QwtPlot*       image_plot, 
                    SliderHandler* slider_handler,
                    GraphDisplay*  h_graph,
@@ -60,20 +62,26 @@ class EXPORT_OPT_MANTIDQT_IMAGEVIEWER ImageDisplay
 
      ~ImageDisplay();
 
+     /// Set the source of the image data and information for the table
      void SetDataSource( ImageDataSource* data_source );
 
-     /// Rebuild image from data source, due to resize or scroll bar
+     /// Rebuild image from data source, due to resize or scroll bar movement
      void UpdateImage();
 
+     /// Change the color table used to map intensity to color
      void SetColorScale( std::vector<QRgb> & new_color_table );
 
+     /// Change the control parameter (0...100) used to brighten the image
      void SetIntensity( double control_parameter );
 
+     /// Record the point that the user is currently pointing at with the mouse
      void SetPointedAtPoint( QPoint point );
 
+  private:
+     /// Get the rectangle currently covered by the image in pixel coordinates
      void GetDisplayRectangle( QRect &rect );
 
-  private:
+     /// Show information about the point (x, y) on the image in the table
      void ShowInfoList( double x, double y );
 
      std::vector<QRgb>    color_table;

Code/Mantid/MantidQt/ImageViewer/inc/MantidQtImageViewer/ImagePlotItem.h

@@ -51,12 +51,16 @@ class EXPORT_OPT_MANTIDQT_IMAGEVIEWER ImagePlotItem : public QwtPlotItem
 
 public:
 
+  /// Construct basic plot item with NO data to plot.
   ImagePlotItem();
 
+  /// Specify the data to be plotted and the color table to use
   void SetData( DataArray* data_array, std::vector<QRgb>* color_table );
 
+  /// Set a non-linear lookup table to scale data values before mapping to color
   void SetIntensityTable( std::vector<double>*  intensity_table );
 
+  /// Draw the image (this is called by QWT and must not be called directly.)
   virtual void draw(      QPainter    * painter,
                     const QwtScaleMap & xMap, 
                     const QwtScaleMap & yMap,

Code/Mantid/MantidQt/ImageViewer/inc/MantidQtImageViewer/ImageView.h

@@ -52,7 +52,10 @@ namespace ImageView
 class EXPORT_OPT_MANTIDQT_IMAGEVIEWER ImageView 
 {
   public:
+
+     /// Construct an ImageView to display data from the specified data source 
      ImageView( ImageDataSource* data_source );
+
     ~ImageView();
 
   private:

Code/Mantid/MantidQt/ImageViewer/inc/MantidQtImageViewer/SliderHandler.h

@@ -47,21 +47,23 @@ class EXPORT_OPT_MANTIDQT_IMAGEVIEWER SliderHandler
 {
   public:
 
+    /// Construct object to manage image sliders from the specified UI
     SliderHandler( Ui_MainWindow* iv_ui );
 
+    /// Configure the image sliders for the specified data and drawing area
     void ConfigureSliders( QRect            draw_area, 
                            ImageDataSource* data_source );
 
-    bool VSliderOn();
-
+    /// Return true if the image horizontal slider is enabled.
     bool HSliderOn();
 
-    // NOTE: x_min will be the smaller column number in the array, corresponding
-    //       to lower values on the calibrated x-scale
+    /// Return true if the image vertical slider is enabled.
+    bool VSliderOn();
+
+    /// Get the range of columns to display in the image.
     void GetHSliderInterval( int &x_min, int &x_max );
 
-    // NOTE: y_min will be the smaller row number in the array, corresponding
-    //       to lower values on the calibrated y-scale
+    /// Get the range of rows to display in the image.
     void GetVSliderInterval( int &y_min, int &y_max );
 
   private:

Code/Mantid/MantidQt/ImageViewer/inc/MantidQtImageViewer/TestDataSource.h

@@ -46,6 +46,7 @@ class EXPORT_OPT_MANTIDQT_IMAGEVIEWER TestDataSource: public ImageDataSource
 {
   public:
 
+    /// Construct a DataSource object to provide fake data for testing
     TestDataSource( double total_xmin, double total_xmax,
                     double total_ymin, double total_ymax,
                     size_t total_rows, size_t total_cols );
@@ -64,6 +65,7 @@ class EXPORT_OPT_MANTIDQT_IMAGEVIEWER TestDataSource: public ImageDataSource
                               size_t  n_cols,
                               bool    is_log_x );
 
+    /// Get a list containing pairs of strings with information about x,y
     void GetInfoList( double x,
                       double y,
                       std::vector<std::string> &list );

Code/Mantid/MantidQt/ImageViewer/inc/MantidQtImageViewer/TrackingPicker.h

@@ -45,6 +45,8 @@ class EXPORT_OPT_MANTIDQT_IMAGEVIEWER TrackingPicker : public QwtPlotPicker
   Q_OBJECT
 
 public:
+
+  /// Construct a tracking picker to work with the specified canvas
   TrackingPicker(QwtPlotCanvas* canvas);
 
   /// Disable (or enable) position readout at cursor position, even if
@@ -53,13 +55,12 @@ class EXPORT_OPT_MANTIDQT_IMAGEVIEWER TrackingPicker : public QwtPlotPicker
   void HideReadout( bool hide );
 
 signals:
+  /// This signal will be emitted for each mouse moved event
   void mouseMoved() const;
 
 protected:
 
-  // Unhide base class method (to avoid Intel compiler warning)
-//  using QwtPlotPicker::trackerText;
-
+  /// Override base class method, to emit a mousedMoved() signal for each move
   QwtText trackerText( const QPoint & point ) const;
   QwtText trackerText( const QwtDoublePoint & pos) const;
 

Code/Mantid/MantidQt/ImageViewer/src/ColorMaps.cpp

@@ -10,7 +10,17 @@ namespace MantidQt
 namespace ImageView
 {
 
-
+/**
+ * Get a color map of the specified type, with the specified number of 
+ * colors by interpolating between key colors.
+ * @param name         The name of the color scale as listed in the
+ *                     enum ColorMaps::ColorScale
+ * @param n_colors     The number of colors to use when forming the 
+ *                     color map.  The number of colors must be at least 7
+ *                     for some of the constructed color maps.
+ * @param color_table  Vector of colors that will be cleard and filled out 
+ *                     with the requested color map.
+ */
 void ColorMaps::getColorMap( ColorScale          name, 
                              size_t              n_colors,
                              std::vector<QRgb> & color_table )