gocam.hh

   1 /*
   2
   3 GoCam - A computer vision tool for extracting moves from go videos
   4 Copyright (C) 2005 Teemu Hirsimäki
   5 Email: teemu.hirsimaki [at domain] iki.fi
   6
   7 This program is free software; you can redistribute it and/or modify
   8 it under the terms of the GNU General Public License as published by
   9 the Free Software Foundation; either version 2 of the License, or (at
  10 your option) any later version.
  11
  12 This program is distributed in the hope that it will be useful, but
  13 WITHOUT ANY WARRANTY; without even the implied warranty of
  14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 General Public License for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with this program; if not, write to the Free Software
  19 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  20 USA.
  21
  22 */
  23
  24 #ifndef GOCAM_HH
  25 #define GOCAM_HH
  26
  27 #include "geom.hh"
  28 #include <CImg.h>
  29 #include <vector>
  30
  31 using namespace cimg_library;
  32
  33 /**
  34     \mainpage GoCam - A C++ Library for Analysing Go Videos
  35
  36 */
  37
  38
  39 /** Main classes for the gocam analysis. */
  40 namespace gocam {
  41
  42   /** A class for analysing images of go boards and storing various
  43    * information about the analysis.
  44    *
  45    * The complete analysis is performed simply by calling the
  46    * analyse() function after setting the original image with the
  47    * reset() function.  The analysis steps can also be called
  48    * individually if it is desired to debug the steps or display
  49    * intermediate results.  The steps are
  50    * \li compute_line_images()
  51    * \li compute_hough_image()
  52    * \li compute_initial_grid()
  53    * \li grow_grid()
  54    *
  55    * The compute_hough_image() method does nothing, if the x- and
  56    * y-dimensions of \ref hough_image are already positive.  This
  57    * allows the use of a precomputed hough image when new analysis
  58    * features are tested in later phases.
  59    */
  60   struct Analyser {
  61     /** The Default constructor */
  62     Analyser();
  63
  64     /** Reset the class for analysing a new image.
  65      *  \param img = the image to analyse
  66      */
  67     void reset(const CImg<float> &img);
  68
  69     /** Complete analyse of the image. */
  70     void analyse();
  71
  72     /** Compute the line image in \ref line_image. */
  73     void compute_line_images();
  74
  75     /** Compute the hough image in \ref hough_image.
  76      *
  77      * If \c hough_image has height and width already, the computation
  78      * is skipped.  This allows to load a precomputed hough image to
  79      * save time in debugging later parts of the analysis.
  80      */
  81     void compute_hough_image();
  82
  83     /** Compute an initial small grid from the Hough image.
  84      *
  85      * Each line in the original image can be seen as a local maximum
  86      * in the Hough image.  Since parallel lines in the original
  87      * image have almost the same angle, the corresponding peaks form
  88      * an almost vertical series of maximums in the Hough image.
  89      * This function finds a set of lines that form a small grid in
  90      * the Hough image.
  91      */
  92     void compute_initial_grid();
  93
  94     /** Fix end points of the lines to match the perpendicular lines. */
  95     void fix_end_points();
  96
  97     /** Tune a single line to match the line image.
  98      *
  99      * \warning Does not check that the line stays inside the image
 100      * boundaries.
 101      *
 102      * \param line = the line to be tuned
 103      * \param d1 = the testing segment for the first end point
 104      * \param d2 = the testing segment for the second end point
 105      */
 106     void tune_line(geom::Line &line, geom::Line d1, geom::Line d2);
 107
 108     /** Tune the grid lines to match the line image.
 109      *
 110      * \note Assumes that the grid lines are sorted correctly.
 111      */
 112     void tune_grid();
 113
 114     /** Grow the grid to the full size.
 115      * \param only_once = if true, only one step of growing is performed
 116      */
 117     void grow_grid(bool only_once = false);
 118
 119     /** Grow line series by adding a new line to the best direction.
 120      * \param series = the line series to process (0 = horizontal, 1 =
 121      * vertical)
 122      */
 123     void add_best_line(int series);
 124
 125     /** Grow the grid to the full size. */
 126
 127
 128   private:
 129
 130     /** Compute differences of the rhos of the lines.
 131      *
 132      * \note Assumes that the vector of lines is sorted already.
 133      *
 134      * \param vec = a vector of lines
 135      * \return a vector containing differences between the rhos of the lines.
 136      */
 137     std::vector<float> rho_differences(const std::vector<geom::LineRT> &vec);
 138
 139     /** Compute the score of the addition of a new line.
 140      * \param new_line = the new line to add at the edge of the grid
 141      * \param next_line = the line next to the new line (the old edge line)
 142      * \param lines = the perpendicular lines to the above two lines
 143      * \return the score of the addition: the average of the pixel
 144      * values of the new line segments in the line image.
 145      */
 146     float score_new_line(const geom::Line &new_line,
 147                          const geom::Line &next_line,
 148                          const std::vector<geom::Line> &lines);
 149
 150   public:
 151
 152     /** @name Parameters for the analysis */
 153     //@{
 154
 155     /** Verbosity level. */
 156     int verbose;
 157
 158     /** The size of the board (default 19). */
 159     int board_size;
 160
 161     /** The width of the peak filter used to compute the line image
 162      * (default 5).
 163      */
 164     int line_peak_filter_width;
 165
 166     /** The width of the peak filter used to enhance the Hough image
 167      * (default 5).
 168      */
 169     int hough_peak_filter_width;
 170
 171     /** The standard deviation of the centered Gaussian to get the
 172      * weighted line image.
 173      *
 174      * The value is used for both x and y-dimensions, and is relative
 175      * to the size of the image.  Value 1.0 means a standard deviation
 176      * of half of the image.  The default is 0.2.
 177      */
 178     float line_image_sigma;
 179
 180     /** The approximate maximum width of the series used for the
 181      * initial grid (default 10). */
 182     int approx_series_width;
 183
 184     /** The range to remove around the first approximate theta (default 25). */
 185     int approx_theta_remove_range;
 186
 187     /** The width of the median peak remover used for the initial grid
 188      * (default 10).
 189      */
 190     int median_peak_remove_width;
 191
 192     /** The number of lines for the initial grid (default 5). */
 193     int num_initial_lines;
 194
 195     /** The maximum number of lines for the initial grid before taking
 196      * the middlemost lines (default 10).
 197      */
 198     int max_initial_lines;
 199
 200     //@}
 201
 202
 203
 204     /** @name Intermediate results of the analysis */
 205     //@{
 206
 207     CImg<float> image; //!< The original image
 208     CImg<float> line_image; //!< The line image
 209
 210     /** The line image weighted with a centered Gaussian. */
 211     CImg<float> weighted_line_image;
 212
 213     /** Hough transform of the weighted line image. */
 214     CImg<float> hough_image;
 215
 216     /** Horizontally blurred version of the Hough transform. */
 217     CImg<float> blurred_hough_image;
 218
 219     /** The sum of columns of \c blurred_hough_image. */
 220     CImg<float> blurred_column_sum;
 221
 222     /** The approximate positions of the vertical series of maximums. */
 223     int approx_theta[2];
 224
 225     /** Vertical maximum cuts of the series. */
 226     CImg<float> max_rho[2];
 227
 228     /** The initial grid lines in polar system.
 229      *
 230      * The two vectors contain the horizontal and vertical lines
 231      * respectively.
 232      */
 233     std::vector<geom::LineRT> initial_lines[2];
 234
 235     /** The grid lines in Euclidian space.
 236      *
 237      * The two vectors contain the horizontal and vertical lines
 238      * respectively.
 239      */
 240     std::vector<geom::Line> lines[2];
 241
 242     //@}
 243
 244   };
 245
 246 };
 247
 248 #endif /* GOCAM_HH */