JeVois  1.5
JeVois Smart Embedded Machine Vision Toolkit
Share this page:
ParameterDef.H
Go to the documentation of this file.
1 // ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
2 //
3 // JeVois Smart Embedded Machine Vision Toolkit - Copyright (C) 2016 by Laurent Itti, the University of Southern
4 // California (USC), and iLab at USC. See http://iLab.usc.edu and http://jevois.org for information about this project.
5 //
6 // This file is part of the JeVois Smart Embedded Machine Vision Toolkit. This program is free software; you can
7 // redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software
8 // Foundation, version 2. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
9 // without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
10 // License for more details. You should have received a copy of the GNU General Public License along with this program;
11 // if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
12 //
13 // Contact information: Laurent Itti - 3641 Watt Way, HNB-07A - Los Angeles, CA 90089-2520 - USA.
14 // Tel: +1 213 740 3527 - itti@pollux.usc.edu - http://iLab.usc.edu - http://jevois.org
15 // ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
16 /*! \file */
17 
18 // This code is inspired by the Neuromorphic Robotics Toolkit (http://nrtkit.org)
19 
20 #pragma once
21 
23 #include <memory>
24 
25 namespace jevois
26 {
27  template <class T> class ParameterCore;
28 
29  // ######################################################################
30  //! A category to which multiple ParameterDef definitions can belong
31  /*! All the ParameterDef classes which belong to the same category will show up next to each other when the user
32  requests the help message. \ingroup parameter */
34  {
35  //! Constructor
36  ParameterCategory(std::string const & name_ = "General Options", std::string const & description_ = "");
37 
38  std::string name; //!< The name of the category
39  std::string description; //!< An optional short description of the category
40  };
41 
42  // ######################################################################
43  //! Base class for a Parameter definition
44  /*! This exposes the string-based interface to the definition while derived class templates will expose the
45  value-based interface. Users should never directly create a ParameterDefBase, but should instead create a properly
46  templated ParameterDef<T>, as ParameterDef<T> derives from ParameterBase. \ingroup parameter */
48  {
49  public:
50  //! Construct a ParameterDefBase
51  ParameterDefBase(std::string const & name, std::string const & description,
52  ParameterCategory const & category = ParameterCategory());
53 
54  //! Destructor
55  virtual ~ParameterDefBase();
56 
57  //! The parameter name (without the leading "--")
58  std::string const & name() const;
59 
60  //! Description of what the parameter does
61  std::string const & description() const;
62 
63  //! The Parameter category
64  ParameterCategory const & category() const;
65 
66  //! Default value in string representation
67  virtual std::string const defaultValueString() const = 0;
68 
69  //! Valid values in string representation
70  virtual std::string const validValuesString() const = 0;
71 
72  protected:
73  std::string itsName; //!< Our name
74  std::string itsDescription; //!< Our description string
75  ParameterCategory itsCategory; //!< Our category
76  };
77 
78  // ######################################################################
79  //! A Parameter Definition
80  /*! ParameterDef is used to specify the name, description, default value, category, and optionally valid values for a
81  Parameter. The value tye of the parameter is specified by template parameter T.
82 
83  See \ref validvalues for definitions of specifications for valid values, allowing any value, values from a list,
84  values in a range, values that match a regex, etc.
85 
86  \ingroup parameter */
87  template <class T>
89  {
90  public:
91  //! Construct a ParameterDef with no given valid values, valid values are whatever T can take
92  ParameterDef(std::string const & name, std::string const & description, T const & defaultValue,
93  ParameterCategory const & category);
94 
95  //! Create a Parameter definition with specified valid values from a ValidValueSpec
96  template <template <typename> class ValidValuesSpec>
97  ParameterDef(std::string const & name, std::string const & description, T const & defaultValue,
98  ValidValuesSpec<T> const & validValuesSpec, ParameterCategory const & category);
99 
100  //! Shorthand to create a Parameter definition with specified valid values from a list
101  /*! If your Parameter can only be set to a finite list of values, you can use this convenience constructor
102  to specify them.
103 
104  For example, if you want to create a Parameter for some kernel convolution for which you only have
105  kernels of sizes 3, 5, 7 and 9 you could create a ParameterDef as follows:
106  \code
107  ParameterDef<int> KernelSizeDef("kernel_size", "The size of the convolution kernel", 3, { 3, 5, 7, 9} );
108  \endcode
109 
110  The list of valid values will be shown for this parameter in the help message. */
111  ParameterDef(std::string const & name, std::string const & description, T const & defaultValue,
112  std::vector<T> const & validvalues, ParameterCategory const & category);
113 
114  //! Shorthand to create a Parameter definition with specified valid values from a range (bounds inclusive)
115  ParameterDef(std::string const & name, std::string const & description, T const & defaultValue,
116  jevois::Range<T> const & validrange, ParameterCategory const & category);
117 
118  //! Shorthand to create a Parameter definition with specified valid values from a step range (bounds inclusive)
119  ParameterDef(std::string const & name, std::string const & description, T const & defaultValue,
120  jevois::StepRange<T> const & validrange, ParameterCategory const & category);
121 
122  //! Shorthand to create a Parameter definition with specified valid values in a regex
123  /*! This allows for highly flexible valid values definitions. For example, say you want an int parameter to be in
124  range [0..59] but it could also have value 72, your regex would be:
125 
126  \verbatim
127  ^(([0-5]?[0-9])|72)$
128  \endverbatim */
129  ParameterDef(std::string const & name, std::string const & description, T const & defaultValue,
130  boost::regex const & validregex, ParameterCategory const & category);
131 
132  //! Get the default value that was specified for this Parameter definition
133  T const defaultValue() const;
134 
135  //! Default value in string representation
136  virtual std::string const defaultValueString() const;
137 
138  //! Valid values in string representation
139  virtual std::string const validValuesString() const;
140 
141  private:
142  friend class ParameterCore<T>;
143  T itsDefaultValue;
144  std::shared_ptr<ValidValuesSpecBase<T> > itsValidValuesSpec;
145  void checkDefaultValue();
146  };
147 
148 } // namespace jevois
149 
150 // Include inlined implementation details that are of no interest to the end user
152 
153 
A generic range class with a step.
Definition: StepRange.H:69
ParameterCategory(std::string const &name_="General Options", std::string const &description_="")
Constructor.
Definition: ParameterDef.C:25
A changeable parameter for a Component, core class.
Definition: Parameter.H:183
std::string itsName
Our name.
Definition: ParameterDef.H:73
std::string description
An optional short description of the category.
Definition: ParameterDef.H:39
A Parameter Definition.
Definition: ParameterDef.H:88
A category to which multiple ParameterDef definitions can belong.
Definition: ParameterDef.H:33
Base class for a Parameter definition.
Definition: ParameterDef.H:47
A generic range class.
Definition: Range.H:80
std::string name
The name of the category.
Definition: ParameterDef.H:38
ParameterCategory itsCategory
Our category.
Definition: ParameterDef.H:75
std::string itsDescription
Our description string.
Definition: ParameterDef.H:74