Modules/ImageProcessor/RasterImageProcessor/RasterSpecialist.h

Go to the documentation of this file.

/**
* @file RasterSpecialist.h
* 
* This file contains the definition of class RasterSpecialist.
*
* @author <a href="mailto:sadprofessor@web.de">Bernd Schmidt</a>
*/
#ifndef RASTERSPECIALIST_H
#define RASTERSPECIALIST_H


#include "RasterImageProcessor.h"
#include "Tools/Math/Geometry.h"
#include <list>
#include <vector>


/** Relevant directions for scan methods. */
enum RasterDirections{
  north = 0,
  northEast,
  east,
  southEast,
  south,
  southWest,
  west,
  northWest,
  numberOfRasterDirections
};

/** @class RasterSpecialist 
* Base-class for RasterSpecialists.
* A RasterSpecialist is detecting shapes in the image.
* @author <a href="mailto:sadprofessor@web.de">Bernd Schmidt</a>
*/
class RasterSpecialist  
{
public:
  struct LinePair;
  struct ColoredLP;
  struct GridLP;

  /** 
  * @class LinePair
  * This struct represents a line on the image. It holds also informations 
  * about the color and the number of segment it belongs to.
  * The segment number is needed for the segmentation algorithms.
  */
  struct LinePair{
    /** Constructor */
    LinePair();
    /** Constructor 
    *
    *   @param vec1 The start point.
    *   @param vec2 The end point.
    */
    LinePair(Vector2<int> vec1,Vector2<int> vec2);
    /** Constructor 
    *
    *   @param vec1 The start point.
    *   @param vec2 The end point.
    *   @param c The color class.
    */
    LinePair(Vector2<int> vec1,Vector2<int> vec2,colorClass c);
    /** The first point.*/
    Vector2<int> v1;
    /** The second point.*/
    Vector2<int> v2;
    /** The number of segment.*/
    int segment;
    /** The color.*/
    colorClass color;

    /** Defines the default order for LinePairs.
    * order is lexigographical in v1 (v1.y,v1.x).
    * @param other The LinePair to be compared.
    * @return True if other is greater.
    */
    bool operator <(const LinePair& other){
      return v1.y < other.v1.y || 
           v1.y == other.v1.y && v1.x < other.v1.y ;
    }
  };
  
  /** @class ColoredLP
  *   Four colors for the vector2 begin and end representing in/out colors
  *   0 and 1 should be v1-in and v1-out, same for  
  *   2 and 3  v2-in and v2-out
  */
  struct ColoredLP:LinePair{
    colorClass inOut[4];
  };
  
  /** @class GridLP 
  * Holds also information about the position in a grid. */
  struct GridLP:LinePair{
    /** The column of the grid.*/
    int column;
    /** The start point.*/
    int d1;
    /** The end point.*/
    int d2;
  };


  typedef struct{
    int operator()(const LinePair& pair1,const LinePair& pair2){
      return abs(pair1.v1.x - pair1.v2.x) > abs(pair2.v1.x - pair2.v2.x);
    }
  }  LineCompare;

  struct ListSizeOrder{
    bool operator()(const std::list<LinePair >& l1, const std::list<LinePair >& l2){
      return l1.size() < l2.size();
    }
  };

  struct VectorSizeOrder{
    bool operator()(const std::vector<LinePair >& l1, const std::vector<LinePair >& l2){
      return l1.size() < l2.size();
    }
  };

  struct SegmentNumberOrder{
    bool operator()(const LinePair& pair1, const LinePair& pair2){
      return pair1.segment < pair2.segment;
    }
  };

  /** @class Box
  * This class represents a BoundingBox in the image.
  * The box is parallel to the axes of the coordinate-system.
  */
  class Box{
  public:
    /** Constructor 
    *
    *   @param minX
    *   @param minY
    *   @param maxX
    *   @param maxY
    */
    Box(int minX,int minY,int maxX,int maxY);
    
    /** Minimal x-coordinate of the box.*/
    int minX;
    /** Minimal y-coordinate of the box.*/
    int minY;
    /** Maximal x-coordinate of the box.*/
    int maxX;
    /** Maximal y-coordinate of the box.*/
    int maxY;
      
    /** After calling this method, this is the union of box and this.
    *   @param box input
    */
    void merge(Box& box){
      if (box.minX < minX) minX = box.minX;
      if (box.maxX > maxX) maxX = box.maxX;
      if (box.minY < minY) minY = box.minY;
      if (box.maxY > maxY) maxY = box.maxY;
    }
    /** Adds a point to the bounding-box. The resulting bounding box is the smallest box
    *   that contains (x,y) and this(before adding the point).
    *
    *   @param x The x coordinate to add.
    *   @param y The y coordinate to add.
    */
    void add(int x,int y){
      if (x<minX) minX = x;
      else if (x>maxX) maxX = x;
      if (y<minY) minY = y;
      else if(y>maxY) maxY = y;
    }
    /** Resets the bounding box. After resetting the bounding box lies at position (x,y)
    *   and the width and height of it are 0.
    *   
    *   @param x The x coordinate.
    *   @param y The y coordinate.
    */
    void reset(int x, int y){
      minX = x;
      minY = y;
      maxX = x;
      maxY = y;
    }
    /** Tests if the bounding box contains the point at position (x,y).
    *   
    *   @param x The x coordinate.
    *   @param y The y coordinate.
    *   @return 
    */
    bool inside(int x, int y){
      return (x>=minX && y>=minY && x<=maxX && y<=maxY);
    }
  };

  
  typedef const unsigned char* I_Pin ;
  
  /** The Constructor. 
  * For creation the RasterImageProcessor is needed.
  * @param imagePro The ImageProcessor the specialist belongs to.
  */
  RasterSpecialist(RasterImageProcessor &imagePro);
  /** The Destructor. */
  virtual ~RasterSpecialist();
  
  /** getter for the type of specialist 
  *   @return The type of the specialist.
  */
  virtual int getType() = 0;
  /** Initializes the specialist before running the detection algorithm. */
  virtual void init() = 0;
  /** Executes the detection algorithm. */
  virtual void executePostProcessing(){/*do nothing*/}
  /** Invokes the specialist in the first scan stage at position (x,y)
    * (this member should be replaced later).
    *   @param x The x coordinate.
    *   @param y The y coordinate.
    */
  virtual void invokeOnPreScan(int x, int y){/*do nothing*/}
  /** Invokes the specialist in the second scan stage at position (x,y) 
    * (this member should be replaced later).
    *   @param x The x coordinate.
    *   @param y The y coordinate.  
    */
  virtual void invokeOnPostScan(int x, int y){/*do nothing*/}

  /** Tells if the specialist should be invoked in the pre-scan. */
  bool preScanNeeded;
  /** Tells if the specialist should be invoked in the post-scan.*/
  bool postScanNeeded;

protected:  
  /** Holds the related image processor.*/
  RasterImageProcessor *rip;
  /** Holds the height of the image.*/
  int const imageHeight;
  /** Holds the width of the image.*/
  int const imageWidth;
  /** A helper variable */
  Vector2<int> errorDummy;
  
  /** Runs a algorithm to cluster line pairs that might belong
  * to one region (segment).
  * 
  * preconstraint: Lines must be sorted in increasing x - order
  *
  * @param lines The lines to cluster.
  * @param segments The output as a vector.
  * @param spaceX Allowed space between two pairs in x-dimension.
  * @param spaceY Allowed space between two pairs in y-direction.
  */
  void createSegmentsFromLines(std::list<LinePair>& lines,
    std::vector<std::list<LinePair> >& segments,int spaceX,int spaceY);
  /** Runs a algorithm to cluster line pairs that might belong
  *   to one region (segment).
  * 
  *   preconstraint: Lines must be sorted in increasing y - order
  *
  *   @param lines The lines to cluster.
  *   @param segments The output as a vector.
  *   @param xSpace Allowed space between two pairs in x-dimension.
  *   @param ySpace Allowed space between two pairs in y-direction.
  *   @return 
  */
  bool createSegmentsFromLines2(std::list<LinePair>& lines,
    std::vector<std::list<LinePair> >& segments,int xSpace, int ySpace);
  /** Runs a algorithm to cluster GridLPs that might belong
  *   to one region (segment). The segmantation process is calculated
  *   in the coordinate system of the grid.
  *   
  *   preconstraint: Lines must be sorted in increasing y - order
  *
  *   @param lines The lines to cluster.
  *   @param segments The output as a vector.
  *   @param xSpace Allowed space between two pairs in x-dimension.
  *   @param ySpace Allowed space between two pairs in y-direction.
  *   @return 
  */
  bool createGridSegments(std::list<GridLP>& lines,
    std::vector<std::list<GridLP> >& segments,int xSpace, int ySpace);

  /** Runs a algorithm to cluster line pairs that might belong
  *   to one region (segment). Two line pairs only will belong to one 
  *   region, if the color of the two line pairs is the same.
  * 
  *   preconstraint: Lines must be sorted in increasing y - order
  *
  *   @param lines The lines to cluster.
  *   @param segments The output as a vector.
  *   @param xSpace Allowed space between two pairs in x-dimension.
  *   @param ySpace Allowed space between two pairs in y-direction.
  *   @return 
  */
  bool doColorSegmentation(std::vector<LinePair>& lines,
    std::vector<std::vector<LinePair> >& segments,int xSpace,int ySpace);
  /** precondition: Lines must be sorted in increasing y - order. 
  *
  *   @param input A region.
  *   @param output A vector of points, that represents the polygon.
  */
  void createConvexPoly(std::list<LinePair>& input,std::vector<Vector2<int> > output);

  /** Implemented with ColorTable interface.
  * @param v Input pixel.
  * @return The classified color of the pixel.
  */
  inline colorClass getColor(Vector2<int> v){
    return getColor(v.x,v.y); 
  };
  /** Implemented with ColorTable interface.
  * @param x X-coordinate of the requested pixel.
  * @param y Y-coordinate of the requested pixel.
  * @return The classified color of the pixel.
  */
  inline colorClass getColor(int x,int y){
    unsigned char cy = rip->image.image[y][0][x];
    unsigned char cu = rip->image.image[y][1][x];
    unsigned char cv = rip->image.image[y][2][x];
    ColorCorrector::correct(x,y,cy,cu,cv);
    return rip->colorTable.getColorClass(cy,cu,cv); 
  };
  /** Implemented with ColorTable interface.
  *   @param x X-coordinate of the requested pixel.
  *   @param y Y-coordinate of the requested pixel.
  *   @param color The color class to match.
  *   @return True if color equals getColor(x,y).
  */
  inline bool checkColor(int x,int y,colorClass color){
    return  color == getColor(x,y);
  };
  /** Implemented with ColorTable interface.
  *   @param v The requested pixel.
  *   @param color The color class to match.
  *   @return True if color equals getColor(x,y).
  */
  inline bool checkColor(Vector2<int> v,colorClass color){
    return  color == getColor(v.x,v.y);
  };


  /** Scans to the top, until the colorClass(x,y) changes or the border
  * of the image is reached.
  * @param x x-coordinate of the start
  * @param y y-coordinate of the start
  * @return Last pixel with the same colorClass of the given position 
  * represented as a Vector2<int>.
  */
  Vector2<int> scanNorth(int x,int y)
  { 
    Vector2<int> v(x,y);
    if (y<1) return v;
    search = getColor(v.x,v.y /*- rip->marginY*/);

    while (v.y > 0 && checkColor(v,search)) --v.y;
    ++v.y;

    return v;
  };
  /** Scans to the bottom, until getColor(x,y) changes or the border
  * of the image is reached.
  * @param x x-coordinate of the start
  * @param y y-coordinate of the start 
  * @return Last pixel with the same colorClass of the given position 
  * represented as a Vector2<int>.*/
  Vector2<int> scanSouth(int x,int y){
    Vector2<int> v(x,y);

    search = getColor(v.x,v.y /*- rip->marginY*/);

    while (v.y < (imageHeight - 1) && checkColor(v,search)) ++v.y;
    --v.y;
    return v;
  };
  /** Scans to the right side, until getColor(x,y) changes or the border
  * of the image is reached. 
  * @param x x-coordinate of the start
  * @param y y-coordinate of the start
  * @return Last pixel with the same colorClass of the given position 
  * represented as a Vector2<int>.*/
  Vector2<int> scanWest(int x,int y){
    Vector2<int> v(x,y);
    
    search = getColor(v.x /*- rip->marginX*/,v.y);

    while (v.x > 1 && checkColor(v,search))--v.x;
    ++v.x;
    return v;
  };
  /** Scans to the left side, until getColor(x,y) changes or the border
  * of the image is reached. 
  * @param x x-coordinate of the start
  * @param y y-coordinate of the start
  * @return Last pixel with the same colorClass of the given position 
  * represented as a Vector2<int>.*/
  Vector2<int> scanEast(int x,int y){
    Vector2<int> v(x,y);
    search = getColor(v.x /*+ rip->marginX*/,v.y);
    while (v.x < (imageWidth - 2) && checkColor(v,search))++v.x;
    --v.x;
    
    return v;
  };
  /** Scans to top left, until getColor(x,y) changes or the border
  * of the image is reached. 
  * @param x x-coordinate of the start
  * @param y y-coordinate of the start
  * @return Last pixel with the same colorClass of the given position 
  * represented as a Vector2<int>.*/
  Vector2<int> scanNW(int x,int y){
    Vector2<int> v(x,y);
    
    search = getColor(v.x,v.y);

    while (checkColor(v,search)){ 
      --v.x; 
      --v.y;
    }
    
    return v;
  };
  /** Scans to down left, until getColor(x,y) changes or the border
  * of the image is reached. 
  * @param x x-coordinate of the start
  * @param y y-coordinate of the start
  * @return Last pixel with the same colorClass of the given position 
  * represented as a Vector2<int>.*/
  Vector2<int> scanSW(int x,int y){
    Vector2<int> v(x,y);
    search = getColor(v.x,v.y);


    while (checkColor(v,search)){ 
      --v.x; 
      ++v.y;
    }
    
    return v;
  };
  /** Scans to down right, until getColor(x,y) changes or the border
  * of the image is reached. 
  * @param x x-coordinate of the start
  * @param y y-coordinate of the start
  * @return Last pixel with the same colorClass of the given position 
  * represented as a Vector2<int>.*/
  Vector2<int> scanSE(int x,int y){
    Vector2<int> v(x,y);
    search = getColor(v.x,v.y);

    while (checkColor(v,search)){ 
      ++v.x; 
      ++v.y;
    }
    
    return v; 
  };
  /** Scans to top right, until getColor(x,y) changes or the border
  * of the image is reached. 
  * @param x x-coordinate of the start
  * @param y y-coordinate of the start
  * @return Last pixel with the same colorClass of the given position 
  * represented as a Vector2<int>.*/
  Vector2<int> scanNE(int x,int y){
    Vector2<int> v(x,y);
    search = getColor(v.x,v.y);

    while (checkColor(v,search)){ 
      ++v.x; 
      --v.y;
    }
    
    return v;
  };
  /** Scans to the give direction, until getColor(x,y) changes or the border
  * of the image is reached.
  * @param v coordinates of the start
  * @param direction the scan-direction
  * @return Last pixel with the same colorClass of the given position 
  * represented as a Vector2<int>.*/
  Vector2<int> scan(Vector2<int> v,short direction){


    switch (direction){
    
    case 0:
      currentX = 0;
      currentY = -1;
    case 1:
      currentX = 0;
      currentY = +1;
      break;
    case 2:
      break;
      currentX = -1;
      currentY = 0;
    case 3:
      break;
      currentX = +1;
      currentY = 0;
    case 4:
      break;
      currentX = -1;
      currentY = -1;
    case 5:
      break;
      currentX = -1;
      currentY = +1;
    case 6:
      break;
      currentX = +1;
      currentY = +1;
    case 7:
      break;
      currentX = +1;
      currentY = -1;
    
    default:
      return errorDummy;  
    
    }
    search = getColor(v.x,v.y);

    while (checkColor(v,search)){  
      v.x =+ currentX; 
      v.y =+ currentY;
    }
    
    return v;
  }
  /** Scans in the given direction and stops if the given color is found
  * or the border of the image is reached.
  * @param v coordinates of the start
  * @param search colorClass to search for
  * @param direction the scan-direction
  * @return The first pixel where the expression 
  *     (search == getColor(x,y)) is true.
  */
  Vector2<int> scan(Vector2<int> v,short direction,colorClass search){


    switch (direction){
    
    case 0:
      currentX = 0;
      currentY = -1;
    case 1:
      currentX = 0;
      currentY = +1;
      break;
    case 2:
      break;
      currentX = -1;
      currentY = 0;
    case 3:
      break;
      currentX = +1;
      currentY = 0;
    case 4:
      break;
      currentX = -1;
      currentY = -1;
    case 5:
      break;
      currentX = -1;
      currentY = +1;
    case 6:
      break;
      currentX = +1;
      currentY = +1;
    case 7:
      break;
      currentX = +1;
      currentY = -1;
    
    default:
      return errorDummy;  
    
    }
    while (!checkColor(v,search)){   
      v.x =+ currentX; 
      v.y =+ currentY;
    }
    
    return v;
  }
  /** Scans in the given direction and stops if color changes.
  *   @param x x-coordinate of the start
  *   @param y y-coordinate of the start
  *   @param direction the scan-direction
  *   @return The last pixel with the same color as the start pixel.
  */
  inline Vector2<int> scan(int x,int y,short direction){
    Vector2<int> v(x,y);
    return scan(v,direction);
  }
  /** Calculates the distance to the line.
  *   @param line the line
  *   @param point the point
  *   @return the distance of the point to the line*/
  inline float getDistanceToLine(const Geometry::Line line,const Vector2<int>& point) {

    Vector2<double> pd((double)point.x,(double)point.y);

    if (line.direction.x == 0 && line.direction.y == 0) 
      return (float) Geometry::distance(pd, line.base);

    Vector2<double> normal;
    normal.x = line.direction.y;
    normal.y = -line.direction.x;
    normal.normalize();

    double c = normal * line.base;

    return float(normal * pd - c);
  }
  /** The theta function for the difference of two vectors.
  *   @param v1 First vector.
  *   @param v2 Second vector.
  *   @return A number between 0 and 360 with the same order as v.angle() .
  */
  inline double theta(Vector2<int>& v1, Vector2<int>& v2){
    double t = 0;
    int dx = v1.x - v2.x;
    int dy = v1.y - v2.y;
    int ax = abs(dx);
    int ay = abs(dy);
    if (dx == 0 && dy == 0) t = 0;
    else t = (double)dy /(double)(ax + ay);
    if (dx < 0) t = 2 - t;
    else if (dy < 0) t = 4 + t;
    return t*90; // multiplication with 90 is not needed for correct ordering
  }
  /** The theta function.
  *   @param v the input
  *   @return a number between 0 and 360 with the same order as v.angle() 
  */
  inline double theta(Vector2<int>& v){
    double t = 0;
    int ax = abs(v.x);
    int ay = abs(v.y);
    if (v.x == 0 && v.y == 0) t = 0;
    else t = (double)v.y /(double)(ax + ay);
    if (v.x < 0) t = 2 - t;
    else if (v.y < 0) t = 4 + t;
    return t*90; // multiplication with 90 is not needed for correct ordering
  }
  /** Helper.
  *   @param value the input
  *   @return sign of the given value.
  */
  inline int sign(int value){
    return value < 0 ? -1 : 1;
  }
  
private:
  /** A temporary variable for the direction offset.*/
  int currentX;
  /** A temporary variable for the direction offset.*/
  int currentY;
  /** A temporary variable.*/
  colorClass search;
  /** Offset value for Y channel.*/
  int const Y_VALUE;
  /** Offset value for U channel.*/
  int const U_VALUE;
  /** Offset value for V channel.*/
  int const V_VALUE;
  /** List for segmentation functions.*/
  std::list<std::list<LinePair> > segList;

  /** Tests if two runs have a distance smaller than the allowed space.
  *
  *   @param inSegment First run.
  *   @param newPair Second run.
  *   @param allowedSpace The allowed space between the pairs. The value may also be negative.
  *   @return True, if the distance is smaller than allowedSpace.
  */
  inline bool linePairsFit(LinePair& inSegment ,LinePair& newPair,int allowedSpace){
      return (!((inSegment.v2.x+allowedSpace<newPair.v1.x)
      ||(inSegment.v1.x-allowedSpace>newPair.v2.x)));
  }
  /** Tests if two runs have a distance smaller than the allowed space.
  *
  *   @param inSegment First run.
  *   @param newPair Second run.
  *   @param allowedSpace The allowed space between the pairs. The value may also be negative.
  *   @return True, if the distance is smaller than allowedSpace.
  */
  inline bool gridFit(GridLP& inSegment ,GridLP& newPair,int allowedSpace){
        return (!((inSegment.d2+allowedSpace<newPair.d1)
      ||(inSegment.d1-allowedSpace>newPair.d2)));
  }

  /** Tests if two runs have a distance smaller than the allowed space and if
  *   their color is the same.
  *
  *   @param inSegment First run.
  *   @param newPair Second run.
  *   @param allowedSpace The allowed space between the pairs. The value may also be negative.
  *   @return True, if the distance is smaller than allowedSpace and the color is equal.
  */
  inline bool linesFit(LinePair& inSegment ,LinePair& newPair,int allowedSpace){
    return (!((inSegment.v2.x+allowedSpace<newPair.v1.x)
      ||(inSegment.v1.x-allowedSpace>newPair.v2.x))
      && newPair.color == inSegment.color);
  }

};

#endif


/*
* Change log :
* 
* $Log: RasterSpecialist.h,v $
* Revision 1.6  2004/09/08 12:41:43  wachter
* - Fixed some warnings
* - Fixed some documentation in network-code
*
* Revision 1.5  2004/09/06 12:02:26  schmidtb
* commented almost all members, removed warnings in documentation

* did further code clean up
*
* Revision 1.4  2004/09/03 11:32:14  nistico
* References to MSH2004ColorCorrector removed, now uses the unified ColorCorrector
*
* Revision 1.3  2004/09/02 07:59:29  schmidtb
* Added RasterImageProcessor to repository, because we used it for the OpenChallenge.
*
* Revision 1.20  2004/05/27 11:18:48  schmidtb
* new version with further work for open challenge
*
* Revision 1.19  2004/05/25 13:27:34  schmidtb
* modified version of rip for open-challenge
*
* Revision 1.20  2004/04/22 16:57:26  pg_besc
* new version of RBallSpecialist2, now omnidirectional scans for detection
*
* Revision 1.19  2004/04/20 07:50:27  pg_besc
* new version of pre scan
*
* Revision 1.18  2004/03/17 17:06:09  koh
* added enemyOnlySpecialist;
* added enemySpecialist2;
* added some int and bool variables
*
* Revision 1.17  2004/03/11 20:32:58  schmidtb
* new version of rip
*
* Revision 1.16  2004/03/04 09:54:51  schmidtb
* color correction integrated
*
* Revision 1.15  2004/03/03 12:53:21  schmidtb
* color correction integrated
*
* Revision 1.14  2004/02/18 14:56:19  neubach
* new Segmentation established, code not cleared at all
*
* Revision 1.13  2004/02/04 13:00:49  schmidtb
* new version of BoxSpecialist
*
* Revision 1.12  2004/02/02 13:42:12  schmidtb
* merged sources of RIP. added som functions.
*
* Revision 1.11  2004/01/31 11:45:02  hyung
* modified enemyValidity-calculation;
* established basical enviroment for TrikotErkennung, based on Arrays and Lists, changes will take affect only #ifdef TrikotErkennung!
*
* Revision 1.10  2004/01/26 22:21:09  schmidtb
* bugfixed BoxSpecialist
*
* Revision 1.9  2004/01/26 20:37:56  schmidtb
* removed errors and warnings, merged versions of RGoalSpecialist
*
* Revision 1.8  2004/01/19 16:18:45  schmidtb
* GoalSpecialist recognizes Landmarks
*
* Revision 1.7  2004/01/15 13:45:02  schmidtb
* segmentation established
*
* Revision 1.6  2003/12/15 13:55:32  schmidtb
* Merged and patched new version of RasterImageProcessor.
*
* Revision 1.5  2003/12/08 15:02:55  schmidtb
* new version of RIP
*
* Revision 1.4  2003/12/04 09:51:23  schmidtb
* better BallSpecialist
*
* Revision 1.3  2003/12/02 21:59:02  schmidtb
* New version of RasterImageProcessor
*
* Revision 1.2  2003/11/20 10:26:56  schmidtb
* Ball Detection added
*
* Revision 1.1  2003/11/12 13:13:20  schmidtb
* new RasterImageProcessor added
*
*
*/

---