vpMe.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:
 * Moving edges.
 */

 
#ifndef VP_ME_H
#define VP_ME_H
 
#include <visp3/core/vpConfig.h>
#include <visp3/core/vpImage.h>
#include <visp3/core/vpMath.h>
#include <visp3/core/vpMatrix.h>
 
#ifdef VISP_HAVE_NLOHMANN_JSON
#include VISP_NLOHMANN_JSON(json.hpp)
#endif
 
BEGIN_VISP_NAMESPACE
class VISP_EXPORT vpMe
{
public:
  typedef enum
  {
    OLD_THRESHOLD = 0,
    NORMALIZED_THRESHOLD = 1
  } vpLikelihoodThresholdType;
 
public:
  vpMe();

  vpMe(const vpMe &me);

  virtual ~vpMe();

  vpMe &operator=(const vpMe &me);
 
#if (VISP_CXX_STANDARD >= VISP_CXX_STANDARD_11)
  vpMe &operator=(const vpMe &&me);
#endif

  void checkSamplestep(double &sample_step)
  {
    if (sample_step < m_min_samplestep) {
      sample_step = m_min_samplestep;
    }
  }

  inline unsigned int getAngleStep() const { return m_anglestep; }

  inline int getInitRange() const { return m_init_range; }

  inline vpMatrix *getMask() const { return m_mask; }

  inline unsigned int getMaskNumber() const { return m_mask_number; }

  inline int getMaskSign() const { return m_mask_sign; }

  inline unsigned int getMaskSize() const { return m_mask_size; }

  inline double getMinSampleStep() const { return m_min_samplestep; }

  inline double getMu1() const { return m_mu1; }

  inline double getMu2() const { return m_mu2; }

  inline int getNbTotalSample() const { return m_ntotal_sample; }

  inline int getPointsToTrack() const { return m_points_to_track; }

  inline unsigned int getRange() const { return m_range; }

  inline double getSampleStep() const { return m_sample_step; }

  inline int getStrip() const { return m_strip; }

  inline double getThreshold() const { return m_threshold; }

  inline double getThresholdMarginRatio() const { return m_thresholdMarginRatio; }

  inline double getMinThreshold() const { return m_minThreshold; }

  inline bool getUseAutomaticThreshold() const { return m_useAutomaticThreshold; }

  inline vpLikelihoodThresholdType getLikelihoodThresholdType() const { return m_likelihood_threshold_type; }

  void initMask(); // convolution masks - offset computation

  void print();

  void setAngleStep(const unsigned int &anglestep) { m_anglestep = anglestep; }

  inline void setInitRange(const int &initRange) { m_init_range = initRange; }

  void setMaskNumber(const unsigned int &mask_number);

  void setMaskSign(const int &mask_sign) { m_mask_sign = mask_sign; }

  void setMaskSize(const unsigned int &mask_size);

  void setMinSampleStep(const double &min_samplestep) { m_min_samplestep = min_samplestep; }

  void setMu1(const double &mu_1) { this->m_mu1 = mu_1; }

  void setMu2(const double &mu_2) { this->m_mu2 = mu_2; }

  void setNbTotalSample(const int &ntotal_sample) { m_ntotal_sample = ntotal_sample; }

  void setPointsToTrack(const int &points_to_track) { m_points_to_track = points_to_track; }

  void setRange(const unsigned int &range) { m_range = range; }

  void setSampleStep(const double &sample_step) { m_sample_step = sample_step; }

  void setStrip(const int &strip) { m_strip = strip; }

  void setThreshold(const double &threshold) { m_threshold = threshold; }

  inline void setThresholdMarginRatio(const double &thresholdMarginRatio)
  {
    if (thresholdMarginRatio > 1.) {
      throw(vpException(vpException::badValue, "Threshold margin ratio must be between 0 and 1 if you want to use automatic threshold computation, or negative otherwise"));
    }
    m_thresholdMarginRatio = thresholdMarginRatio;
    m_useAutomaticThreshold = (m_thresholdMarginRatio > 0) && (m_minThreshold > 0);
  }

  inline void setMinThreshold(const double &minThreshold)
  {
    m_minThreshold = minThreshold;
    m_useAutomaticThreshold = (m_thresholdMarginRatio > 0) && (m_minThreshold > 0);
  }

  void setLikelihoodThresholdType(const vpLikelihoodThresholdType likelihood_threshold_type) { m_likelihood_threshold_type = likelihood_threshold_type; }
 
private:
  vpLikelihoodThresholdType m_likelihood_threshold_type; 
  double m_threshold;
  double m_thresholdMarginRatio; 
  double m_minThreshold; 
  bool m_useAutomaticThreshold; 
  double m_mu1;       
  double m_mu2;       
  double m_min_samplestep;
  unsigned int m_anglestep;
  int m_mask_sign;
  int m_init_range; 
  unsigned int m_range; 
  double m_sample_step; 
  int m_ntotal_sample;
  int m_points_to_track; 
  unsigned int m_mask_size;
  unsigned int m_mask_number;
  int m_strip;
  vpMatrix *m_mask; 
 
#ifdef VISP_HAVE_NLOHMANN_JSON
  friend void to_json(nlohmann::json &j, const vpMe &me);

  friend void from_json(const nlohmann::json &j, vpMe &me);
#endif
};
 
#ifdef VISP_HAVE_NLOHMANN_JSON
 
#if defined(__clang__)
// Mute warning : declaration requires an exit-time destructor [-Wexit-time-destructors]
// message : expanded from macro 'NLOHMANN_JSON_SERIALIZE_ENUM'
#  pragma clang diagnostic push
#  pragma clang diagnostic ignored "-Wexit-time-destructors"
#endif
 
NLOHMANN_JSON_SERIALIZE_ENUM(vpMe::vpLikelihoodThresholdType, {
  {vpMe::vpLikelihoodThresholdType::OLD_THRESHOLD, "old"},
  {vpMe::vpLikelihoodThresholdType::NORMALIZED_THRESHOLD, "normalized"}
});
 
#if defined(__clang__)
#  pragma clang diagnostic pop
#endif
 
inline void to_json(nlohmann::json &j, const vpMe &me)
{
  j = {
    {"thresholdType", me.getLikelihoodThresholdType()},
    {"threshold", me.getThreshold()},
    {"thresholdMarginRatio", me.getThresholdMarginRatio()},
    {"minThreshold", me.getMinThreshold()},
    {"mu", {me.getMu1(), me.getMu2()}},
    {"minSampleStep", me.getMinSampleStep()},
    {"sampleStep", me.getSampleStep()},
    {"initRange", me.getInitRange()},
    {"range", me.getRange()},
    {"ntotalSample", me.getNbTotalSample()},
    {"pointsToTrack", me.getPointsToTrack()},
    {"maskSize", me.getMaskSize()},
    {"nMask", me.getMaskNumber()},
    {"maskSign", me.getMaskSign()},
    {"strip", me.getStrip()}
  };
}
 
inline void from_json(const nlohmann::json &j, vpMe &me)
{
  if (j.contains("thresholdType")) {
    me.setLikelihoodThresholdType(j.value("thresholdType", me.getLikelihoodThresholdType()));
  }
  me.setThreshold(j.value("threshold", me.getThreshold()));
  me.setThresholdMarginRatio(j.value("thresholdMarginRatio", me.getThresholdMarginRatio()));
  me.setMinThreshold(j.value("minThreshold", me.getMinThreshold()));
 
  if (j.contains("mu")) {
    std::vector<double> mus = j.at("mu").get<std::vector<double>>();
    assert((mus.size() == 2));
    me.setMu1(mus[0]);
    me.setMu2(mus[1]);
  }
  me.setMinSampleStep(j.value("minSampleStep", me.getMinSampleStep()));
  me.setSampleStep(j.value("sampleStep", me.getSampleStep()));
  me.setRange(j.value("range", me.getRange()));
  me.setInitRange(j.value("initRange", me.getInitRange()));
  me.setNbTotalSample(j.value("ntotalSample", me.getNbTotalSample()));
  me.setPointsToTrack(j.value("pointsToTrack", me.getPointsToTrack()));
  me.setMaskSize(j.value("maskSize", me.getMaskSize()));
  me.setMaskSign(j.value("maskSign", me.getMaskSign()));
  me.setStrip(j.value("strip", me.getStrip()));
  if (j.contains("angleStep") && j.contains("nMask")) {
    std::cerr << "both angle step and number of masks are defined, number of masks will take precedence" << std::endl;
    me.setMaskNumber(j["nMask"]);
  }
  else if (j.contains("angleStep")) {
    me.setAngleStep(j["angleStep"]);
  }
  else if (j.contains("nMask")) {
    me.setMaskNumber(j["nMask"]);
  }
  me.initMask();
}
 
#endif
 
END_VISP_NAMESPACE
#endif