vpDot2.h

/*
 * ViSP, open source Visual Servoing Platform software.
 * Copyright (C) 2005 - 2025 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 https://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.
 */

 
#ifndef VP_DOT2_H
#define VP_DOT2_H
 
#include <visp3/core/vpColor.h>
#include <visp3/core/vpConfig.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>
 
BEGIN_VISP_NAMESPACE

class VISP_EXPORT vpDot2 : public vpTracker
{
public:
  vpDot2();
  VP_EXPLICIT vpDot2(const vpImagePoint &ip);
  vpDot2(const vpDot2 &twinDot);
 
  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);
    const unsigned int index_0 = 0;
    const unsigned int index_1 = 1;
    const unsigned int index_2 = 2;
 
    nij[index_0] = mu20 / m00;
    nij[index_1] = mu11 / m00;
    nij[index_2] = mu02 / m00;
 
    return nij;
  }
 
  double getArea() const;

  inline vpRect getBBox() const
  {
    vpRect bbox;
 
    bbox.setRect(m_bbox_u_min, m_bbox_v_min, (m_bbox_u_max - m_bbox_u_min) + 1,
                 (m_bbox_v_max - m_bbox_v_min) + 1);
 
    return bbox;
  }

  inline vpImagePoint getCog() const { return m_cog; }
 
  double getDistance(const vpDot2 &distantDot) const;
  void getEdges(std::list<vpImagePoint> &edges_list) const { edges_list = m_ip_edges_list; }

  std::list<vpImagePoint> getEdges() const { return m_ip_edges_list; }

  double getEllipsoidBadPointsPercentage() const { return m_allowedBadPointsPercentage; }
 
  double getEllipsoidShapePrecision() const;
  void getFreemanChain(std::list<unsigned int> &freeman_chain) const;
 
  inline double getGamma() const { return m_gamma; }
  inline unsigned int getGrayLevelMin() const { return m_gray_level_min; }
  inline unsigned int getGrayLevelMax() const { return m_gray_level_max; }
  double getGrayLevelPrecision() const;
 
  double getHeight() const;
  double getMaxSizeSearchDistPrecision() const;

  double getMeanGrayLevel() const { return m_mean_gray_level; }

  vpPolygon getPolygon() const { return (vpPolygon(m_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) { m_cog = ip; }

  void setComputeMoments(bool activate) { m_compute_moment = activate; }

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

  void setGraphics(bool activate) { m_graphics = activate; }

  void setGraphicsThickness(unsigned int thickness) { m_thickness = thickness; }

  inline void setGrayLevelMin(const unsigned int &min)
  {
    const unsigned int val_max = 255;
    if (min > val_max) {
      m_gray_level_min = val_max;
    }
    else {
      m_gray_level_min = min;
    }
  }

  inline void setGrayLevelMax(const unsigned int &max)
  {
    const unsigned int val_max = 255;
    if (max > val_max) {
      m_gray_level_max = val_max;
    }
    else {
      m_gray_level_max = max;
    }
  }
 
  void setGrayLevelPrecision(const double &grayLevelPrecision);
  void setHeight(const double &height);
  void setMaxSizeSearchDistPrecision(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 = nullptr);
 
  // Static funtions
  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);
 
#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 m_firstBorder_u; }

  unsigned int getFirstBorder_v() const { return m_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;
 
  typedef struct vpSearchDotsInAreaGoodGermData
  {
    const vpImage<unsigned char> &m_I;
    const vpRect &m_area;
    unsigned int &m_u;
    unsigned int &m_v;
    std::list<vpDot2> &m_niceDots;
    std::list<vpDot2> &m_badDotsVector;
 
    vpSearchDotsInAreaGoodGermData(const vpImage<unsigned char> &I, const vpRect &area,
                                   unsigned int &u, unsigned int &v,
                                   std::list<vpDot2> &niceDots, std::list<vpDot2> &badDotsVector)
      : m_I(I)
      , m_area(area)
      , m_u(u)
      , m_v(v)
      , m_niceDots(niceDots)
      , m_badDotsVector(badDotsVector)
    {
 
    }
  } vpSearchDotsInAreaGoodGermData;
 
  void searchDotsAreaGoodGerm(vpSearchDotsInAreaGoodGermData &data);
  vpImagePoint m_cog;
 
  double m_width;
  double m_height;
  double m_surface;
  unsigned int m_gray_level_min; // minumum gray level for the dot. Pixel with lower level don't belong to this dot.
 
  unsigned int m_gray_level_max; // maximum gray level for the dot. Pixel with higher level don't belong to this dot.
  double m_mean_gray_level;      // Mean gray level of the dot
  double m_grayLevelPrecision;
  double m_gamma;
  double m_sizePrecision;
  double m_ellipsoidShapePrecision;
  double m_maxSizeSearchDistPrecision;
  double m_allowedBadPointsPercentage;
  // Area where the dot is to search
  vpRect m_area;
 
  // other
  std::list<unsigned int> m_direction_list;
  std::list<vpImagePoint> m_ip_edges_list;
 
  // flag
  bool m_compute_moment; // true moment are computed
  bool m_graphics;       // true for graphic overlay display
 
  unsigned int m_thickness; // Graphics thickness
 
  // Bounding box
  int m_bbox_u_min, m_bbox_u_max, m_bbox_v_min, m_bbox_v_max;
 
  // The first point coordinate on the dot border
  unsigned int m_firstBorder_u;
  unsigned int m_firstBorder_v;
 
};
 
END_VISP_NAMESPACE
#endif