vpDot2.h

/****************************************************************************
 *
 * ViSP, open source Visual Servoing Platform software.
 * Copyright (C) 2005 - 2019 by Inria. All rights reserved.
 *
 * This software is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * See the file LICENSE.txt at the root directory of this source
 * distribution for additional information about the GNU GPL.
 *
 * For using ViSP with software that can not be combined with the GNU
 * GPL, please contact Inria about acquiring a ViSP Professional
 * Edition License.
 *
 * See http://visp.inria.fr for more information.
 *
 * This software was developed at:
 * Inria Rennes - Bretagne Atlantique
 * Campus Universitaire de Beaulieu
 * 35042 Rennes Cedex
 * France
 *
 * If you have questions regarding the use of this file, please contact
 * Inria at visp@inria.fr
 *
 * This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
 * WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 *
 * Description:
 * Track a white dot.
 *
 * Authors:
 * Fabien Spindler
 *
 *****************************************************************************/

/*
  \file vpDot2.h
  \brief This tracker is meant to track some zones on a vpImage.
*/

#ifndef vpDot2_hh
#define vpDot2_hh

#include <visp3/core/vpColor.h>
#include <visp3/core/vpImage.h>
#include <visp3/core/vpImagePoint.h>
#include <visp3/core/vpPolygon.h>
#include <visp3/core/vpRect.h>
#include <visp3/core/vpTracker.h>

#include <list>
#include <vector>

class VISP_EXPORT vpDot2 : public vpTracker
{
public:
  vpDot2();
  explicit vpDot2(const vpImagePoint &ip);
  vpDot2(const vpDot2 &twinDot);
  virtual ~vpDot2();

  static vpMatrix defineDots(vpDot2 dot[], const unsigned int &n, const std::string &dotFile, vpImage<unsigned char> &I,
                             vpColor col = vpColor::blue, bool trackDot = true);

  void display(const vpImage<unsigned char> &I, vpColor color = vpColor::red, unsigned int thickness = 1) const;

  inline vpColVector get_nij() const
  {
    vpColVector nij(3);
    nij[0] = mu20 / m00;
    nij[1] = mu11 / m00;
    nij[2] = mu02 / m00;

    return nij;
  }

  double getArea() const;
  inline vpRect getBBox() const
  {
    vpRect bbox;

    bbox.setRect(this->bbox_u_min, this->bbox_v_min, this->bbox_u_max - this->bbox_u_min + 1,
                 this->bbox_v_max - this->bbox_v_min + 1);

    return (bbox);
  };
  inline vpImagePoint getCog() const { return cog; }

  double getDistance(const vpDot2 &distantDot) const;
  void getEdges(std::list<vpImagePoint> &edges_list) const { edges_list = this->ip_edges_list; };
  std::list<vpImagePoint> getEdges() const { return (this->ip_edges_list); };
  double getEllipsoidBadPointsPercentage() const { return allowedBadPointsPercentage_; }

  double getEllipsoidShapePrecision() const;
  void getFreemanChain(std::list<unsigned int> &freeman_chain) const;

  inline double getGamma() const { return this->gamma; };
  inline unsigned int getGrayLevelMin() const { return gray_level_min; };
  inline unsigned int getGrayLevelMax() const { return gray_level_max; };
  double getGrayLevelPrecision() const;

  double getHeight() const;
  double getMaxSizeSearchDistancePrecision() const;
  double getMeanGrayLevel() const { return (this->mean_gray_level); };
  vpPolygon getPolygon() const { return (vpPolygon(ip_edges_list)); };
  double getSizePrecision() const;
  double getWidth() const;

  void initTracking(const vpImage<unsigned char> &I, unsigned int size = 0);
  void initTracking(const vpImage<unsigned char> &I, const vpImagePoint &ip, unsigned int size = 0);
  void initTracking(const vpImage<unsigned char> &I, const vpImagePoint &ip, unsigned int gray_lvl_min,
                    unsigned int gray_lvl_max, unsigned int size = 0);

  vpDot2 &operator=(const vpDot2 &twinDot);
  friend VISP_EXPORT std::ostream &operator<<(std::ostream &os, vpDot2 &d);

  void print(std::ostream &os) { os << *this << std::endl; }
  void searchDotsInArea(const vpImage<unsigned char> &I, int area_u, int area_v, unsigned int area_w,
                        unsigned int area_h, std::list<vpDot2> &niceDots);

  void searchDotsInArea(const vpImage<unsigned char> &I, std::list<vpDot2> &niceDots);

  void setArea(const double &area);
  inline void setCog(const vpImagePoint &ip) { this->cog = ip; }
  void setComputeMoments(bool activate) { compute_moment = activate; }

  void setEllipsoidBadPointsPercentage(const double &percentage = 0.0)
  {
    if (percentage < 0.)
      allowedBadPointsPercentage_ = 0.;
    else if (percentage > 1.)
      allowedBadPointsPercentage_ = 1.;
    else
      allowedBadPointsPercentage_ = percentage;
  }

  void setEllipsoidShapePrecision(const double &ellipsoidShapePrecision);
  void setGraphics(bool activate) { graphics = activate; }
  void setGraphicsThickness(unsigned int t) { this->thickness = t; };
  inline void setGrayLevelMin(const unsigned int &min)
  {
    if (min > 255)
      this->gray_level_min = 255;
    else
      this->gray_level_min = min;
  };

  inline void setGrayLevelMax(const unsigned int &max)
  {
    if (max > 255)
      this->gray_level_max = 255;
    else
      this->gray_level_max = max;
  };
  void setGrayLevelPrecision(const double &grayLevelPrecision);
  void setHeight(const double &height);
  void setMaxSizeSearchDistancePrecision(const double &maxSizeSearchDistancePrecision);
  void setSizePrecision(const double &sizePrecision);
  void setWidth(const double &width);

  void track(const vpImage<unsigned char> &I, bool canMakeTheWindowGrow = true);
  void track(const vpImage<unsigned char> &I, vpImagePoint &cog, bool canMakeTheWindowGrow = true);

  static void trackAndDisplay(vpDot2 dot[], const unsigned int &n, vpImage<unsigned char> &I,
                              std::vector<vpImagePoint> &cogs, vpImagePoint *cogStar = NULL);

#ifdef VISP_BUILD_DEPRECATED_FUNCTIONS
public:
#else
private:
#endif
  double m00;  
  double m10;  
  double m01;  
  double m11;  
  double m20;  
  double m02;  
  double mu11; 
  double mu20; 
  double mu02; 
private:
  virtual bool isValid(const vpImage<unsigned char> &I, const vpDot2 &wantedDot);

  virtual bool hasGoodLevel(const vpImage<unsigned char> &I, const unsigned int &u, const unsigned int &v) const;
  virtual bool hasReverseLevel(const vpImage<unsigned char> &I, const unsigned int &u, const unsigned int &v) const;

  virtual vpDot2 *getInstance();

  void init();

  bool computeParameters(const vpImage<unsigned char> &I, const double &u = -1.0, const double &v = -1.0);

  bool findFirstBorder(const vpImage<unsigned char> &I, const unsigned int &u, const unsigned int &v,
                       unsigned int &border_u, unsigned int &border_v);
  void computeMeanGrayLevel(const vpImage<unsigned char> &I);

  unsigned int getFirstBorder_u() const { return this->firstBorder_u; }
  unsigned int getFirstBorder_v() const { return this->firstBorder_v; }

  bool computeFreemanChainElement(const vpImage<unsigned char> &I, const unsigned int &u, const unsigned int &v,
                                  unsigned int &element);
  void computeFreemanParameters(const int &u_p, const int &v_p, unsigned int &element, int &du, int &dv, float &dS,
                                float &dMu, float &dMv, float &dMuv, float &dMu2, float &dMv2);
  void updateFreemanPosition(unsigned int &u, unsigned int &v, const unsigned int &dir);

  bool isInImage(const vpImage<unsigned char> &I) const;
  bool isInImage(const vpImage<unsigned char> &I, const vpImagePoint &ip) const;

  bool isInArea(const unsigned int &u, const unsigned int &v) const;

  void getGridSize(unsigned int &gridWidth, unsigned int &gridHeight);
  void setArea(const vpImage<unsigned char> &I, int u, int v, unsigned int w, unsigned int h);
  void setArea(const vpImage<unsigned char> &I);
  void setArea(const vpRect &a);

  unsigned char getMeanGrayLevel(vpImage<unsigned char> &I) const;
  vpImagePoint cog;

  double width;
  double height;
  double surface;
  unsigned int gray_level_min; // minumum gray level for the dot.
                               // pixel with lower level don't belong
                               // to this dot.

  unsigned int gray_level_max; // maximum gray level for the dot.
                               // pixel with higher level don't belong
                               // to this dot.
  double mean_gray_level;      // Mean gray level of the dot
  double grayLevelPrecision;
  double gamma;
  double sizePrecision;
  double ellipsoidShapePrecision;
  double maxSizeSearchDistancePrecision;
  double allowedBadPointsPercentage_;
  // Area where the dot is to search
  vpRect area;

  // other
  std::list<unsigned int> direction_list;
  std::list<vpImagePoint> ip_edges_list;

  // flag
  bool compute_moment; // true moment are computed
  bool graphics;       // true for graphic overlay display

  unsigned int thickness; // Graphics thickness

  // Bounding box
  int bbox_u_min, bbox_u_max, bbox_v_min, bbox_v_max;

  // The first point coodinate on the dot border
  unsigned int firstBorder_u;
  unsigned int firstBorder_v;

  // Static funtions
public:
  static void display(const vpImage<unsigned char> &I, const vpImagePoint &cog,
                      const std::list<vpImagePoint> &edges_list, vpColor color = vpColor::red,
                      unsigned int thickness = 1);
  static void display(const vpImage<vpRGBa> &I, const vpImagePoint &cog, const std::list<vpImagePoint> &edges_list,
                      vpColor color = vpColor::red, unsigned int thickness = 1);
};

#endif