Visual Servoing Platform  version 3.6.1 under development (2024-07-18)
vpMe.h
1 /*
2  * ViSP, open source Visual Servoing Platform software.
3  * Copyright (C) 2005 - 2024 by Inria. All rights reserved.
4  *
5  * This software is free software; you can redistribute it and/or modify
6  * it under the terms of the GNU General Public License as published by
7  * the Free Software Foundation; either version 2 of the License, or
8  * (at your option) any later version.
9  * See the file LICENSE.txt at the root directory of this source
10  * distribution for additional information about the GNU GPL.
11  *
12  * For using ViSP with software that can not be combined with the GNU
13  * GPL, please contact Inria about acquiring a ViSP Professional
14  * Edition License.
15  *
16  * See https://visp.inria.fr for more information.
17  *
18  * This software was developed at:
19  * Inria Rennes - Bretagne Atlantique
20  * Campus Universitaire de Beaulieu
21  * 35042 Rennes Cedex
22  * France
23  *
24  * If you have questions regarding the use of this file, please contact
25  * Inria at visp@inria.fr
26  *
27  * This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
28  * WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
29  *
30  * Description:
31  * Moving edges.
32  */
33 
39 #ifndef VP_ME_H
40 #define VP_ME_H
41 
42 #include <visp3/core/vpConfig.h>
43 #include <visp3/core/vpImage.h>
44 #include <visp3/core/vpMath.h>
45 #include <visp3/core/vpMatrix.h>
46 
47 #ifdef VISP_HAVE_NLOHMANN_JSON
48 #include <nlohmann/json.hpp>
49 #endif
50 
133 class VISP_EXPORT vpMe
134 {
135 public:
139  typedef enum
140  {
142  OLD_THRESHOLD = 0,
145  NORMALIZED_THRESHOLD = 1
146  } vpLikelihoodThresholdType;
147 
148 public:
152  vpMe();
153 
157  vpMe(const vpMe &me);
158 
162  virtual ~vpMe();
163 
167  vpMe &operator=(const vpMe &me);
168 
169 #if (VISP_CXX_STANDARD >= VISP_CXX_STANDARD_11)
173  vpMe &operator=(const vpMe &&me);
174 #endif
175 
181  void checkSamplestep(double &sample_step)
182  {
183  if (sample_step < m_min_samplestep) {
184  sample_step = m_min_samplestep;
185  }
186  }
187 
193  inline unsigned int getAngleStep() const { return m_anglestep; }
194 
200  inline vpMatrix *getMask() const { return m_mask; }
201 
209  inline unsigned int getMaskNumber() const { return m_mask_number; }
210 
216  inline int getMaskSign() const { return m_mask_sign; }
217 
225  inline unsigned int getMaskSize() const { return m_mask_size; }
226 
233  inline double getMinSampleStep() const { return m_min_samplestep; }
234 
240  inline double getMu1() const { return m_mu1; }
241 
247  inline double getMu2() const { return m_mu2; }
248 
254  inline int getNbTotalSample() const { return m_ntotal_sample; }
255 
261  inline int getPointsToTrack() const { return m_points_to_track; }
262 
268  inline unsigned int getRange() const { return m_range; }
269 
275  inline double getSampleStep() const { return m_sample_step; }
276 
282  inline int getStrip() const { return m_strip; }
283 
291  inline double getThreshold() const { return m_threshold; }
292 
300  inline double getThresholdMarginRatio() const { return m_thresholdMarginRatio; }
301 
310  inline double getMinThreshold() const { return m_minThreshold; }
311 
318  inline bool getUseAutomaticThreshold() const { return m_useAutomaticThreshold; }
319 
327  inline vpLikelihoodThresholdType getLikelihoodThresholdType() const { return m_likelihood_threshold_type; }
328 
333  void initMask(); // convolution masks - offset computation
334 
338  void print();
339 
345  void setAngleStep(const unsigned int &anglestep) { m_anglestep = anglestep; }
346 
354  void setMaskNumber(const unsigned int &mask_number);
355 
361  void setMaskSign(const int &mask_sign) { m_mask_sign = mask_sign; }
362 
370  void setMaskSize(const unsigned int &mask_size);
371 
378  void setMinSampleStep(const double &min_samplestep) { m_min_samplestep = min_samplestep; }
379 
385  void setMu1(const double &mu_1) { this->m_mu1 = mu_1; }
386 
392  void setMu2(const double &mu_2) { this->m_mu2 = mu_2; }
393 
399  void setNbTotalSample(const int &ntotal_sample) { m_ntotal_sample = ntotal_sample; }
400 
408  void setPointsToTrack(const int &points_to_track) { m_points_to_track = points_to_track; }
409 
415  void setRange(const unsigned int &range) { m_range = range; }
416 
422  void setSampleStep(const double &sample_step) { m_sample_step = sample_step; }
423 
429  void setStrip(const int &strip) { m_strip = strip; }
430 
466  void setThreshold(const double &threshold) { m_threshold = threshold; }
467 
475  inline void setThresholdMarginRatio(const double &thresholdMarginRatio)
476  {
477  if (thresholdMarginRatio > 1.) {
478  throw(vpException(vpException::badValue, "Threshold margin ratio must be between 0 and 1 if you want to use automatic threshold computation, or negative otherwise"));
479  }
480  m_thresholdMarginRatio = thresholdMarginRatio;
481  m_useAutomaticThreshold = (m_thresholdMarginRatio > 0) && (m_minThreshold > 0);
482  }
483 
491  inline void setMinThreshold(const double &minThreshold)
492  {
493  m_minThreshold = minThreshold;
494  m_useAutomaticThreshold = (m_thresholdMarginRatio > 0) && (m_minThreshold > 0);
495  }
496 
505  void setLikelihoodThresholdType(const vpLikelihoodThresholdType likelihood_threshold_type) { m_likelihood_threshold_type = likelihood_threshold_type; }
506 
507 private:
508  vpLikelihoodThresholdType m_likelihood_threshold_type;
510  double m_threshold;
511  double m_thresholdMarginRatio;
512  double m_minThreshold;
513  bool m_useAutomaticThreshold;
514  double m_mu1;
515  double m_mu2;
516  double m_min_samplestep;
517  unsigned int m_anglestep;
518  int m_mask_sign;
519  unsigned int m_range;
520  double m_sample_step;
521  int m_ntotal_sample;
522  int m_points_to_track;
524  unsigned int m_mask_size;
526  unsigned int m_mask_number;
529  int m_strip;
530  vpMatrix *m_mask;
531 
532 #ifdef VISP_HAVE_NLOHMANN_JSON
539  friend void to_json(nlohmann::json &j, const vpMe &me);
540 
588  friend void from_json(const nlohmann::json &j, vpMe &me);
589 #endif
590 };
591 
592 #ifdef VISP_HAVE_NLOHMANN_JSON
593 NLOHMANN_JSON_SERIALIZE_ENUM(vpMe::vpLikelihoodThresholdType, {
594  {vpMe::vpLikelihoodThresholdType::OLD_THRESHOLD, "old"},
595  {vpMe::vpLikelihoodThresholdType::NORMALIZED_THRESHOLD, "normalized"}
596 });
597 
598 inline void to_json(nlohmann::json &j, const vpMe &me)
599 {
600  j = {
601  {"thresholdType", me.getLikelihoodThresholdType()},
602  {"threshold", me.getThreshold()},
603  {"thresholdMarginRatio", me.getThresholdMarginRatio()},
604  {"minThreshold", me.getMinThreshold()},
605  {"mu", {me.getMu1(), me.getMu2()}},
606  {"minSampleStep", me.getMinSampleStep()},
607  {"sampleStep", me.getSampleStep()},
608  {"range", me.getRange()},
609  {"ntotalSample", me.getNbTotalSample()},
610  {"pointsToTrack", me.getPointsToTrack()},
611  {"maskSize", me.getMaskSize()},
612  {"nMask", me.getMaskNumber()},
613  {"maskSign", me.getMaskSign()},
614  {"strip", me.getStrip()}
615  };
616 }
617 
618 inline void from_json(const nlohmann::json &j, vpMe &me)
619 {
620  if (j.contains("thresholdType")) {
621  me.setLikelihoodThresholdType(j.value("thresholdType", me.getLikelihoodThresholdType()));
622  }
623  me.setThreshold(j.value("threshold", me.getThreshold()));
624  me.setThresholdMarginRatio(j.value("thresholdMarginRatio", me.getThresholdMarginRatio()));
625  me.setMinThreshold(j.value("minThreshold", me.getMinThreshold()));
626 
627  if (j.contains("mu")) {
628  std::vector<double> mus = j.at("mu").get<std::vector<double>>();
629  assert((mus.size() == 2));
630  me.setMu1(mus[0]);
631  me.setMu2(mus[1]);
632  }
633  me.setMinSampleStep(j.value("minSampleStep", me.getMinSampleStep()));
634  me.setSampleStep(j.value("sampleStep", me.getSampleStep()));
635  me.setRange(j.value("range", me.getRange()));
636  me.setNbTotalSample(j.value("ntotalSample", me.getNbTotalSample()));
637  me.setPointsToTrack(j.value("pointsToTrack", me.getPointsToTrack()));
638  me.setMaskSize(j.value("maskSize", me.getMaskSize()));
639  me.setMaskSign(j.value("maskSign", me.getMaskSign()));
640  me.setStrip(j.value("strip", me.getStrip()));
641  if (j.contains("angleStep") && j.contains("nMask")) {
642  std::cerr << "both angle step and number of masks are defined, number of masks will take precedence" << std::endl;
643  me.setMaskNumber(j["nMask"]);
644  }
645  else if (j.contains("angleStep")) {
646  me.setAngleStep(j["angleStep"]);
647  }
648  else if (j.contains("nMask")) {
649  me.setMaskNumber(j["nMask"]);
650  }
651  me.initMask();
652 }
653 
654 #endif
655 
656 END_VISP_NAMESPACE
657 #endif
error that can be emitted by ViSP classes.
Definition: vpException.h:60
@ badValue
Used to indicate that a value is not in the allowed range.
Definition: vpException.h:73
Implementation of a matrix and operations on matrices.
Definition: vpMatrix.h:169
Definition: vpMe.h:134
bool getUseAutomaticThreshold() const
Indicates if the contrast threshold of the vpMeSite is automatically computed.
Definition: vpMe.h:318
int getMaskSign() const
Definition: vpMe.h:216
void setMu1(const double &mu_1)
Definition: vpMe.h:385
void setMinThreshold(const double &minThreshold)
Definition: vpMe.h:491
void setPointsToTrack(const int &points_to_track)
Definition: vpMe.h:408
void initMask()
Definition: vpMe.cpp:383
vpLikelihoodThresholdType getLikelihoodThresholdType() const
Definition: vpMe.h:327
double getMinSampleStep() const
Definition: vpMe.h:233
void setMaskSign(const int &mask_sign)
Definition: vpMe.h:361
void setRange(const unsigned int &range)
Definition: vpMe.h:415
void setLikelihoodThresholdType(const vpLikelihoodThresholdType likelihood_threshold_type)
Definition: vpMe.h:505
void setNbTotalSample(const int &ntotal_sample)
Definition: vpMe.h:399
void setAngleStep(const unsigned int &anglestep)
Definition: vpMe.h:345
void setMaskNumber(const unsigned int &mask_number)
Definition: vpMe.cpp:552
int getNbTotalSample() const
Definition: vpMe.h:254
void setThreshold(const double &threshold)
Definition: vpMe.h:466
void setStrip(const int &strip)
Definition: vpMe.h:429
void checkSamplestep(double &sample_step)
Definition: vpMe.h:181
unsigned int getAngleStep() const
Definition: vpMe.h:193
double getThresholdMarginRatio() const
Definition: vpMe.h:300
void setMinSampleStep(const double &min_samplestep)
Definition: vpMe.h:378
double getMu1() const
Definition: vpMe.h:240
unsigned int getMaskNumber() const
Definition: vpMe.h:209
int getPointsToTrack() const
Definition: vpMe.h:261
int getStrip() const
Definition: vpMe.h:282
void setSampleStep(const double &sample_step)
Definition: vpMe.h:422
double getMu2() const
Definition: vpMe.h:247
double getThreshold() const
Definition: vpMe.h:291
unsigned int getMaskSize() const
Definition: vpMe.h:225
void setMaskSize(const unsigned int &mask_size)
Definition: vpMe.cpp:560
void setThresholdMarginRatio(const double &thresholdMarginRatio)
Definition: vpMe.h:475
void setMu2(const double &mu_2)
Definition: vpMe.h:392
vpMatrix * getMask() const
Definition: vpMe.h:200
double getSampleStep() const
Definition: vpMe.h:275
unsigned int getRange() const
Definition: vpMe.h:268
vpLikelihoodThresholdType
Definition: vpMe.h:140
double getMinThreshold() const
Definition: vpMe.h:310