Component.H

Go to the documentation of this file.

/*---------------------------------------------------------------------+
 | Library QgarLib, graphics analysis and recognition                  |
 | Copyright (C) 2002  Qgar Project, LORIA                             |
 |                                                                     |
 | This library is free software; you can redistribute it and/or       |
 | modify it under the terms of the GNU Lesser General Public          |
 | License version 2.1, as published by the Free Software Foundation.  |
 |                                                                     |
 | This library is distributed in the hope that it will be useful,     |
 | but WITHOUT ANY WARRANTY; without even the implied warranty of      |
 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                |
 | See the GNU Lesser General Public License for more details.         |
 |                                                                     |
 | The GNU Lesser General Public License is included in the file       |
 | LICENSE.LGPL, in the root directory of the Qgar packaging. See      |
 | http://www.gnu.org/licenses/lgpl.html for the terms of the licence. |
 | To receive a paper copy, write to the Free Software Foundation,     |
 | Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.       |
 |                                                                     |
 | Contact Project Qgar for any information:                           |
 |   LORIA - équipe Qgar                                               |
 |   B.P. 239, 54506 Vandoeuvre-lès-Nancy Cedex, France                |
 |   email: qgar-contact@loria.fr                                      |
 |   http://www.qgar.org/                                              |
 *---------------------------------------------------------------------*/


#ifndef __COMPONENT_H_INCLUDED__
#define __COMPONENT_H_INCLUDED__


/**
 * @file    Component.H
 * @brief   Header file of classes qgar::Component.
 *
 * @author   <a href="mailto:qgar-develop@loria.fr?subject=Qgar fwd Gérald Masini">Gérald Masini</a>
 * @date     March 17, 2004  17:17
 * @since    Qgar 2.1
 */


// For RCS/CVS use: Do not delete
/* $Id: Component.H,v 1.28 2005/07/29 16:28:09 gerald Exp $ */


// STL
#include <list>
// QGAR
#include <qgarlib/GenImage.H>
namespace qgar
{
  // Avoid #include's when not necessary
  class BoundingBox;
  template <class T> class GenPoint;
  class Maer;
}



namespace qgar
{


/**
 * @class Component Component.H "qgarlib/Component.H"
 * @ingroup GRAPHPROC_CC
 * @brief A (connected) component.
 *
 * Representation of a component:
 *
 * - a pointer to the corresponding component image,
 * - a label,
 * - the label of the component in which the current component is included,
 * - a color, black or white (see qgar::QGEbw),
 * - the coordinates of the top left pixel of the component,
 * - the bounding box of the component,
 * - the MAER (see class qgar::Maer) of the component,
 *   which is computed when first accessed,
 * - the contour points of the component (each point corresponds
 *   to a change in the current contour direction, based on 8-connexity),
 *   which are computed when first accessed or when the MAER is accessed,
 * - the area (in pixels) of the component.
 *
 * @author <a href="mailto:qgar-develop@loria.fr?subject=Qgar fwd Gérald Masini">Gérald Masini</a>
 * @date   Mar 17, 2004  17:17
 * @since  Qgar 2.1
 */
class Component
{
// -------------------------------------------------------------------
// T Y P E   D E F I N I T I O N
// -------------------------------------------------------------------
public:

  /** @name Types related to a component */
  //        ============================
  //@{

  /**
   * @brief Type of a component label.
   */
  typedef short label_type;

  //@}

// -------------------------------------------------------------------
// P U B L I C    M E M B E R S
// -------------------------------------------------------------------
public:

  /** @name Constructors */
  //        ============
  //@{

  /**
   * @brief Default constructor.
   */
  Component();

  /**
   * @brief Create from full data.
   *
   * @param aPCompImg      pointer to the corresponding component image
   * @param aLabel         label
   * @param anInLabel      label of comprising component
   * @param aBW            color (black or white)
   * @param aXTopLeftPix   X coordinate of the top left pixel
   * @param aYTopLeftPix   Y coordinate of the top left pixel
   * @param aXTopLeft      top left X coordinate of the bounding box
   * @param aYTopLeft      top left Y coordinate of the bounding box
   * @param aXBottomRight  bottom right X coordinate of the bounding box
   * @param aYBottomRight  bottom right Y coordinate of the bounding box
   * @param anAreaPixels   area (in pixels)
   */
  Component(GenImage<label_type>* aPCompImg,
            int   aLabel,
            int   anInLabel,
            QGEbw aBW,
            int   aXTopLeftPix,
            int   aYTopLeftPix,
            int   aXTopLeft,
            int   aYTopLeft,
            int   aXBottomRight,
            int   aYBottomRight,
            int   anAreaPixels);

  /**
   * @brief Copy constructor.
   * @param aCComp  a connected component
   *
   * @warning Perform a deep copy: The whole data
   * of the given connected component is duplicated.
   */
  Component(const Component& aCComp);

  //@}


  /** @name Destructor */
  //        ==========
  //@{

  /**
   * @brief Virtual destructor.
   */
  virtual ~Component();

  //@}


  /** @name Labels */
  //        ======
  //@{

  /**
   * @brief Maximum label.
   *
   * @warning This is a <b>static</b> data member.
   */
  static const label_type _MAX_LABEL;

  /**
   * @brief Label to express that an object is not yet labelled.
   *
   * @warning This is a <b>static</b> data member.
   */
  static const label_type _NO_LABEL;

  /**
   * @brief Get component label.
   */
  inline label_type label() const;

  /**
   * @brief Get label of comprising component.
   */
  inline label_type inLabel() const;

  //@}


  /** @name Color */
  //        ======
  //@{

  /**
   * @brief Get color.
   */
  inline QGEbw color() const;

  //@}


  /** @name Coordinates */
  //        ===========
  //@{

  /**
   * @brief Get X coordinate of the top left pixel of the component.
   */
  inline int xTopLeftPix() const;

  /**
   * @brief Get Y coordinate of the top left pixel of the component.
   */
  inline int yTopLeftPix() const;

  /**
   * @brief Get bounding box.
   */
  const BoundingBox& accessBoundingBox() const;

  /**
   * @brief Get a copy of the bounding box.
   */
  BoundingBox boundingBox() const;

  /**
   * @brief Get density with regard to the bounding box.
   *
   * The density is the ratio between the area (number of pixels)
   * of the component and the area of its bounding box.
   */
  double densityBox() const;

  //@}


  /** @name Area */
  //        ====
  //@{

  /**
   * @brief Get component area (in pixels).
   */
  inline int areaPixels() const;

  //@}


  /** @name Access to the MAER (Minimum-Area Encasing Rectangle) */
  //        ====================================================
  //@{

  /**
   * @brief Get the MAER.
   *
   * @warning The MAER is computed and <b>stored</b>
   *          when first accessed.
   */
  const Maer& accessMaer();

  /**
   * @brief Get a copy of the MAER.
   *
   * @warning The MAER is computed and <b>stored</b>
   *          when first accessed.
   */
  Maer maer();

  /**
   * @brief Get MAER area in pixels.
   *
   * @warning
   * - The MAER is computed and <b>stored</b> when first accessed.
   * - The area of the MAER is calculated in the <b>continuous</b>
   *   2D space and is provided by the corresponding data of the
   *   object representing the MAER:
   *   <b>(aComponent.accessMaer())->area()</b>, for example.
   *   As connected components are constructed in the 2D
   *   <b>discrete</b> space, an <b>approximated value</b> of
   *   the MAER area is also available in pixels.
   */
  int maerAreaPixels();

  /**
   * @brief Get density with regard to the MAER.
   *
   * The density is the ratio between the area (number of pixels)
   * of the component and the area of its MAER.
   *
   * @warning The MAER is computed and <b>stored</b>
   *          when first accessed.
   */
  double densityMaer();

  //@}


  /** @name Contour */
  //        =======
  //@{

  /**
   * @brief Get a pointer to the component contour.
   *
   * @warning
   * - The component contour is computed and <b>stored</b>
   *   when first accessed
   * - The coordinates of the contour points are
   *   <b>double</b> numbers
   */
  const std::list<DPoint>& accessContour();

  /**
   * @brief Get a copy of the component contour.
   *
   * @warning
   * - The component contour is computed and <b>stored</b>
   *   when first accessed
   * - The coordinates of the contour points are
   *   <b>double</b> numbers
   */
  std::list<DPoint> contour();

  //@}


  /** @name Operators */
  //        =========
  //@{

  /**
   * @brief Assignment.
   * @param aCComp  connected component to be assigned
   */
  Component& operator=(const Component& aCComp);

  //@}


// -------------------------------------------------------------------
// P R O T E C T E D    M E M B E R S
// -------------------------------------------------------------------
protected:

  /** @name Pixel map of the corresponding component image */
  //        ==============================================
  //@{

  /**
   * @brief Pointer to the corresponding component image.
   */
  GenImage<label_type>* _pCompImg;

  //@}


  /** @name Labels */
  //        ======
  //@{

  /**
   * @brief Label of the component.
   *
   * @warning <b>It must be an integer number: long, short...</b>
   */
  label_type _label;

  /**
   * @brief Label of the comprising component.
   */
  label_type _inLabel;

  //@}


  /** @name Color */
  //        =====
  //@{

  /**
   * @brief Color.
   */
  QGEbw _color;

  //@}


  /** @name Coordinates */
  //        ===========
  //@{

  /**
   * @brief X coordinate of the top left pixel of the component.
   */
  int _xTopLeftPix;

  /**
   * @brief Y coordinate of the top left pixel of the component.
   */
  int _yTopLeftPix;

  /**
   * @brief Bounding box.
   */
  BoundingBox _boundingBox;

  //@}


  /** @name Area */
  //        ====
  //@{

  /**
   * @brief Component effective area (in pixels).
   */
  int _areaPixels;

  //@}


  /** @name MAER (Minimum-Area Encasing Rectangle) */
  //        ======================================
  //@{

  /**
   * @brief Minimum-Area Enclosing Rectangle (MAER).
   */
  Maer* _maer;

  /**
   * @brief Minimum-Area Enclosing Rectangle (MAER).
   */
  int _maerAreaPixels;

  //@}


  /** @name Contour */
  //        =======
  //@{

  /**
   * @brief List of the points of the contour component.
   *
   * Each point corresponds to a change in the current contour
   * direction, based on 8-connexity.
   */
  std::list<DPoint> _contour;

  //@}


// -------------------------------------------------------------------
// P R I V A T E    M E M B E R S
// -------------------------------------------------------------------
private:

  // =================================================================
  /** @name Tables to compute coordinates during contour following

@verbatim
  +---+---+---+
  |   | 1 | 2 |
  +---+---+---+
  | 7 | *-->3 |
  +---+---+---+
  | 6 | 5 | 4 |
  +---+---+---+
@endverbatim

  The outside of the component is always on the left when moving
  along the contour direction. The figure above gives an example:
  when following a contour in the EAST direction, the first new
  possible contour point (1) is at NORTH of the current point (*),
  the second (2) at NORTH-EAST, and so on.

@verbatim
             new contour directions (see table _s_new_dir)
             W   NW  N   NE  E   SE  S   SW  W   NW  N   NE  E   SE
 
  indexes    0   1   2   3   4   5   6   7   8   9   10  11  12  13
           +---+---+---+---+---+---+---+---+---+---+---+---+---+---+
_s_incr_x  | -1| -1| 0 | 1 | 1 | 1 | 0 | -1| -1| -1| 0 | 1 | 1 | 1 |
           +---+---+---+---+---+---+---+---+---+---+---+---+---+---+
           +---+---+---+---+---+---+---+---+---+---+---+---+---+---+
_s_incr_y  | 0 | -1| -1| -1| 0 | 1 | 1 | 1 | 0 | -1| -1| -1| 0 | 1 |
           +---+---+---+---+---+---+---+---+---+---+---+---+---+---+
             N   NE  E   SE  S   SW  W   NW
             entries corresponding to current contour directions
@endverbatim

  The _s_incr_x (resp. y) table (see figure above) contains the X
  (resp. Y) increment to get the X (resp. Y) coordinates of the 7
  possible next contour points (points 1 to 7 on 1st figure) from
  the X (resp. Y) coordinate of the current point (*). The current
  contour direction (EAST on 1st figure) determines the first index
  to enter the tables.

@verbatim
             new contour directions
             W   NW  N   NE  E   SE  S   SW  W   NW  N   NE  E   SE
           +---+---+---+---+---+---+---+---+---+---+---+---+---+---+
_s_new_dir | 6 | 7 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 0 | 1 | 2 | 3 |
           +---+---+---+---+---+---+---+---+---+---+---+---+---+---+
@endverbatim

  Once a new contour point is found, table _s_new_dir gives the
  corresponding new contour direction, using the index corresponding
  to the new contour point in table _s_incr_x or _s_incr_y.
  */
  // =================================================================
  //@{

  /**
   * @brief Table for X coordinates increments.
   */
  static const int _s_incr_x[14];

  /**
   * @brief Table for Y coordinates increments.
   */
  static const int _s_incr_y[14];

  /**
   * @brief Table for new contour directions.
   */
  static const int _s_new_dir[14];

  //@}


  /** @name Auxiliary functions */
  //        ===================
  //@{

  /**
   * @brief Compute the external contour (hull) of the component.
   *
@verbatim
    . . . . . . . . .    . . . . . . . . .
    . . . . * . . . .    . . . . C . . . .
    . . . * . * . . .    . . . C . C . . .
    . . * . * . * . .    . . C . * . C . .
    . * . * * * . * .    . C . * * * . C .
    . . * . * . * . .    . . C . * . C . .
    . . . * . * . . .    . . . C . C . . .
    . . . . * . . . .    . . . . C . . . .
    . . . . . . . . .    . . . . . . . . .
@endverbatim
   *
   * In the example above, '*' is a black pixel, '.' is a white
   * pixel, and 'C' is a pixel of the resulting contour.
   */
  void PRIVATEcomputeContour();

  /**
   * @brief Compute the MAER (Minimum-Area Encasing Rectangle).
   */
  void PRIVATEcomputeMaer();

  //@}

// -------------------------------------------------------------------
}; // class Component




// IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII
// IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII
// I N L I N E    F U N C T I O N S    I M P L E M E N T A T I O N
// IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII
// IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII


// =====
// LABEL
// =====

// GET COMPONENT LABEL
inline Component::label_type
Component::label() const
{
  return _label;
}

// GET COMPRISING COMPONENT LABEL
inline Component::label_type
Component::inLabel() const
{
  return _inLabel;
}


// ======
// COLOR
// ======

// GET COLOR.
inline QGEbw
Component::color() const
{
  return _color;
}

// ===========
// COORDINATES
// ===========

// GET X COORDINATE OF THE TOP LEFT PIXEL
inline int
Component::xTopLeftPix() const
{
  return _xTopLeftPix;
}

// GET Y COORDINATE OF THE TOP LEFT PIXEL
inline int
Component::yTopLeftPix() const
{
  return _yTopLeftPix;
}


// ====
// AREA
// ====

// GET COMPONENT AREA.
inline int
Component::areaPixels() const
{
  return _areaPixels;
}


// IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII
// IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII
// END OF INLINE FUNCTIONS IMPLEMENTATION
// IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII
// IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII


} // namespace qgar 


#endif /* __COMPONENT_H_INCLUDED__ */