RHoughTransform3D.hh

Go to the documentation of this file.

//======================================================================
/*! \file RHoughTransform3D.hh
 *
 *  Include file for the class RHoughTransform3D
 */
//======================================================================

#ifndef R_HOUGH_TRANSFORM_3D_HH
#define R_HOUGH_TRANSFORM_3D_HH

//======================================================================

// GRootTools includes
#include "RBaseFunctions.hh"
#include "RSphereTesselation.hh"

// ROOT includes
#include "TH2.h"
#include "TH3.h"
#include "TPoint.h"
#include "TMath.h"
#include "TLine.h"

///! Identifier suffix for transform histogram
#define R_H3D_MAIN_XY   "MainXY"

///! Identifier suffix for transform histogram
#define R_H3D_LOCAL_XY    "ImprXY"

///! Identifier suffix for transform histogram
#define R_H3D_LOCAL_ANG   "ImprAng"

//======================================================================
/*! \class RHoughTransform3D
 *
 *  This class is a 3D adaptation of the Hough transform analysis, in
 *  order to search for lines in a 3D histogram.
 *
 *  The discretization of 3D directions is based on the tesselation of
 *  a sphere starting from an icosahedron (see class RSphereTesselation).
 *  The analysis is limited to the directions on the unit sphere defining
 *  unique directions, then only half of the tesselation points are
 *  considered.
 *
 *  <B>Line detection main procedure</B>
 *
 *  The line searching principle is the following:
 *  - each point of the sphere defines a (theta,phi) direction, with
 *    direction vector Uz;
 *  - for each direction, a perpendicular plane (Ux,Uy) is defined,
 *    and a corresponding 2D histogram is created (the histogram is
 *    created only once, and reused for each direction);
 *    - for each bin of the source 3D histogram, the (ux,uy,uz) coordinates
 *      are computed to score the (Ux,Uy) histogram;
 *    - the maximum value (score) for the (Ux,Uy) histogram defines the
 *      score for the direction (theta,phi);
 *  - the direction with the maximum score is considered for a line
 *    detection:
 *    - if the score is higher than the detection threshold, the detection
 *      is valid
 *
 *  Main procedure parameters:
 *  - directions discretization level (sphere tesselation)
 *  - 3D source (signal) histogram center, as origin point for the projections
 *  - 2D score histogram: size and binning along Ux and Uy directions (the
 *    histogram dimensions must be large enough to cover the projections of
 *    the source histogram)
 *
 *  <B>Line detection improvement</B>
 *
 *  The main detection procedure precision is limited to the sphere
 *  tessalation.
 *  Once a line is detected, a local analysis allows to refine the line
 *  parameters around the result of the main procedure.
 *
 *
 *  <B>Multiple lines search: detected line suppression</B>
 *
 *
 *  \par Configuration functions
 *
 *  Configuration at construction time:
 *
 \code

  TH3 *  hsrc = ...  // define the source histogram

  RHoughTransform3D h3d ( hsrc, u_short div = 2,
                          u_int nxy   = 100, double xymax = 100.,
                          double thr  = 0. );

 \endcode
 *
 *  Configuration functions:
 *
 *  \code

  TH3 *  hsrc = ...         // define the source histogram

  RHoughTransform3D h3d;    // empty analysis

  double  thr = 0.2;        // threshold for source histogram
  h3d.SetSourceHisto ( hsrc, thr );

  u_short div = 2;          // number of division for sphere tesselation (3D directions discretization)
  h3d.SetTesselation ( 2 );

  u_int   nxy   = 100;      // number of bins for (Ux,Uy) score histogram
  double  xymax = 100.;     // (Ux,Uy) score histogram axis limits: [-xymax;+xymax]
  h3d.SetTransformMain ( nxy, xymax, "UxUy_Score" );

  \endcode
 *
 *
 *
 *
 *  \par Line search functions
 *
 *  The main function to perform the line analysis search is
 *  RHoughTransform3D::AnalyseTransformMain().
 *
 *  This function computes the score histogram (Ux,Uy) for each direction
 *  of the 3D directions discretization.
 *  The direction with maximum score is memorized as the result of the
 *  analysis.
 *
 *  The score histogram for 1 direction is filled with the
 *  RHoughTransform3D::ComputeTransformXY() function.
 *
 */
class RHoughTransform3D
{
  //------------------------------------------------------------
  /*! \object_doc{RHoughTransform3D} */
  GObject(RHoughTransform3D);
  //------------------------------------------------------------

  /*! Weight limit for ignoring point*/
  static  double  epsilon;

  /*! Option for threshold on histogram amplitude for contributing to the analysis*/
  static const u_int  optThreshold  = 0x00000002;

  /*! Option for amplitude as weight of histogram point*/
  static const u_int  optAmplitude  = 0x00000004;

  /*! Option for smoothing the Hough transform histogram*/
  static const u_int  optSmooth     = 0x00000008;

  /*! Option for angles in degrees*/
  static const u_int  optdegree     = 0x00000010;

  /*! Mode for line suppression: sharp cut*/
  static const u_short  modeCut     = 0x0000;

  /*! Mode for line suppression: gauss shape reduction*/
  static const u_short  modeGaus    = 0x0001;


  /*! Conversion factor from radians to degrees*/
  static const double   rad2deg;

  /*! Conversion factor from degrees to radians*/
  static const double   deg2rad;


  protected:
    RSphereTesselation  sphere;     ///< Discretized representation of directions on a sphere
    int               * sph_pts;    ///< Array of selected points for unique representation of 3D directions
    int               * sph_seg;    ///< Array of segments connecting the selected points
    TVector3          * sph_ux;     ///< Unit X vector for discretization directions
    TVector3          * sph_uy;     ///< Unit X vector for discretization directions
    double            * sph_score;  ///< Score for discretization directions
    u_int               npts;       ///< Number of selected points
    u_int               nseg;       ///< Number of selected segments

    TH3         * src_histo;        ///< Pointer to the histogram to analyse
    TVector3      src_center;       ///< Image histogram center
    double        threshold;        ///< Threshold value

    u_int         src_data_dim;     ///< Reduced source data dimension
    u_int         src_data_num;     ///< Number of source data points
    TVector3    * src_data_pos;     ///< Array of source data point positions
    double      * src_data_weight;  ///< Array of source data point weight

    // maximum search data
    TH2         * h_anal_xy;      ///< Pointer to the Ux-Uy weight histogram for the analysed direction
    string        hxy_id;         ///< Identifier for created histogram name

    double        hxy_max;        ///< Maximum value for current Ux-Uy weight histogram
    double        hxy_max_x;      ///< X value for analysis maximum
    double        hxy_max_y;      ///< Y value for analysis maximum
    double        hxy_max_theta;  ///< Theta value for analysis maximum
    double        hxy_max_phi;    ///< Phi value for analysis maximum
    bool          analysis_done;  ///< Whether the analysis has been performed

    double        hxy_last_score; ///< Maximum score for current direction
    double        hxy_last_x;     ///< X value for current direction maximum
    double        hxy_last_y;     ///< Y value for current direction maximum
    double        hxy_last_theta; ///< Theta value for current direction maximum
    double        hxy_last_phi;   ///< Phi value for current direction maximum

    // main / improved (local) analysis
    TH2         * h_main_xy;      ///< Pointer to the Ux-Uy score histogram for the main analysis (all directions)
    TH2         * h_local_xy;     ///< Pointer to the Ux-Uy score histogram for the improved local analysis
    TH2         * h_local_ang;    ///< Pointer to the Theta-Phi score histogram for the improved local analysis
    TVector3    * pt_local;       ///< Array of vectors from local analysis
    bool          local_analysis; ///< Whether the ongoing analysis is local

    TAttLine  line_att;         ///< Lines draw attributes (ROOT)

    u_int     options;          ///< Transform options

  public:

  //------------------------------------------------------------
  /** @name Constructors, affectation, destructor */
  //@{
    RHoughTransform3D ( TH3 * hptr = NULL,
                        u_short div = 2, u_int nxy = 0, double xymax = 0.,
                        double thr = 0., const string & id = "" );
    virtual ~RHoughTransform3D ( );
  //@}

  //------------------------------------------------------------
  /** @name Transform analysis options */
  //@{
    u_int GetOptions                   ( ) const;   // inline
    bool  GetOptionThreshold           ( ) const;   // inline
    bool  GetOptionAmplWeight          ( ) const;   // inline
    bool  GetOptionThresholdAmplWeight ( ) const;   // inline
    bool  GetOptionSmooth              ( ) const;   // inline

    virtual void  SetOptionAmplWeight ( bool thr = false );
    virtual void  SetOptionUnitWeight ( );

    virtual void  SetOptionSmooth   ( );    // inline
    virtual void  SetOptionNoSmooth ( );    // inline

    virtual void  SetOptionDegree   ( );    // inline
    virtual void  SetOptionRadian   ( );    // inline
    virtual bool  IsOptionDegree ( ) const; // inline
    virtual bool  IsOptionRadian ( ) const; // inline
  //@}

  //------------------------------------------------------------
  /** @name Transform analysis parameters */
  //@{
    TH3           * GetSourceHisto ( ) const;     // inline
    TH3           * GetWeightHisto ( const string & hname = "" ) const;
    virtual double  GetWeight      ( double pval ) const;

    const TVector3  & GetSourceCenter ( ) const;    // inline
          TVector3  & GetSourceCenter ( );          // inline
    virtual void      SetSourceCenter ( const TVector3 & ctr );

    virtual int     SetSourceHisto ( TH3 * hptr, double thr = 0. );
    virtual void    SetThreshold ( double thr );      // inline

    virtual void    ResetSourceData  ( );
    virtual void    InitSourceData   ( );
    virtual void    UpdateSourceData ( );

    virtual void                        ResetTesselation ( );
    virtual const RSphereTesselation  & SetTesselation ( u_short div );

    int   GetNpoints   ( ) const;   // inline
    int   GetNsegments ( ) const;   // inline
    const RSphereTesselation & GetSphereTesselation ( ) const;  // inline

    const RTesselationPoint   & GetPoint   ( int ip ) const;    // inline
    const RTesselationSegment & GetSegment ( int is ) const;    // inline

    virtual void    SetTransformId ( const string & id ); // inline
    virtual void    ResetTransform      ( );
    virtual void    ResetTransformMain  ( );
    virtual void    ResetTransformLocal ( );

    virtual TH2   * SetTransformMain    ( u_int nxy, double xymax );
    virtual TH2   * SetTransformLocal   ( u_int nxy, double dxy, u_int na, double da );

  //@}

  //------------------------------------------------------------
  /** @name Transform analysis functions */
  //@{

    virtual int   SetAnalysisMain  ( );
    virtual int   SetAnalysisLocal ( );
    virtual int   ComputeTransformXY ( u_int ip );
    virtual int   ComputeTransformXY ( double theta, double phi, bool deg = false );
    virtual int   ComputeTransformXY ( TVector3 ux, TVector3 uy );

    TH2 * GetLocalHistoAngle ( );   // inline
    TH2 * GetLocalHistoUxUy  ( );   // inline

    // maximum search analysis
    virtual void  ResetAnalysis ( );
    virtual int   AnalyseTransformMain  ( );
    virtual int   AnalyseTransformLocal ( );

    double        GetMaxScore ( ) const;
    double        GetMaxScore ( double & theta, double & phi, double & ux, double & uy ) const;


    // previously found lines suppression

    virtual void  SuppressSourceLine ( double theta, double phi,
                                       double ux, double uy, double width,
                                       u_short mode = modeCut, u_short sdiv = 1 );

    virtual void  SuppressSourceLine ( TVector3 Pt, TVector3 dir,
                                       double width,
                                       u_short mode = modeCut, u_short sdiv = 1 );

    virtual u_int SearchLineSuppress ( double hthr, u_int nlmax = 1,
                                       double * thtab = NULL, double * rtab = NULL, double * htab = NULL,
                                       u_short sdiv = 1 );
  //@}

  //------------------------------------------------------------
  /** @name ROOT related functions */
  //@{
    virtual void  SetLineColor ( Color_t c );         // inline
    virtual void  SetLineWidth ( Width_t w );         // inline
    virtual void  SetLineStyle ( Style_t s );         // inline
    virtual void  SetLineAtt   ( TAttLine & att );    // inline

    const TAttLine & GetLineAtt ( ) const;            // inline
          TAttLine & GetLineAtt ( );                  // inline

    TPolyMarker3D * CreatePoints3D  ( ) const;
    TPolyLine3D   * CreateSegment3D ( int is ) const;
    TList         * CreateLines3D   ( const TAttLine latt = TAttLine(kRed+1,2,1 ) ) const;

    TList         * CreateScorePoints3D ( Color_t col = kAzure+1, Style_t sty = 20, double siz = 1.0 ) const;
    TList         * CreateLocalPoints3D ( Color_t col = kRed+1, Style_t sty = 20, double siz = 1.0 ) const;

    TPolyLine3D   * CreateLine3D ( ) const;
    TPolyLine3D   * CreateLine3D ( double theta, double phi, double ux, double uy ) const;

  /*! For ROOT dictionary.*/
  ClassDef(RHoughTransform3D,0);
  //@}
};

//----------------------------------------------------------------------
//  Inline functions
#include "icc/RHoughTransform3D.icc"


//======================================================================

#endif