JeVois  1.21
JeVois Smart Embedded Machine Vision Toolkit
Share this page:
Loading...
Searching...
No Matches
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
25namespace 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,
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 type 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,
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
151#include <jevois/Component/details/ParameterDefImpl.H>
152
153
A changeable parameter for a Component, core class.
Definition Parameter.H:194
Base class for a Parameter definition.
ParameterCategory itsCategory
Our category.
ParameterCategory const & category() const
The Parameter category.
std::string const & name() const
The parameter name (without the leading "--")
std::string const & description() const
Description of what the parameter does.
std::string itsDescription
Our description string.
virtual std::string const validValuesString() const =0
Valid values in string representation.
virtual std::string const defaultValueString() const =0
Default value in string representation.
std::string itsName
Our name.
virtual ~ParameterDefBase()
Destructor.
A Parameter Definition.
ParameterDef(std::string const &name, std::string const &description, T const &defaultValue, ParameterCategory const &category)
Construct a ParameterDef with no given valid values, valid values are whatever T can take.
virtual std::string const defaultValueString() const
Default value in string representation.
ParameterDef(std::string const &name, std::string const &description, T const &defaultValue, jevois::StepRange< T > const &validrange, ParameterCategory const &category)
Shorthand to create a Parameter definition with specified valid values from a step range (bounds incl...
ParameterDef(std::string const &name, std::string const &description, T const &defaultValue, jevois::Range< T > const &validrange, ParameterCategory const &category)
Shorthand to create a Parameter definition with specified valid values from a range (bounds inclusive...
ParameterDef(std::string const &name, std::string const &description, T const &defaultValue, ValidValuesSpec< T > const &validValuesSpec, ParameterCategory const &category)
Create a Parameter definition with specified valid values from a ValidValueSpec.
ParameterDef(std::string const &name, std::string const &description, T const &defaultValue, std::vector< T > const &validvalues, ParameterCategory const &category)
Shorthand to create a Parameter definition with specified valid values from a list.
T const defaultValue() const
Get the default value that was specified for this Parameter definition.
virtual std::string const validValuesString() const
Valid values in string representation.
ParameterDef(std::string const &name, std::string const &description, T const &defaultValue, boost::regex const &validregex, ParameterCategory const &category)
Shorthand to create a Parameter definition with specified valid values in a regex.
A generic range class.
Definition Range.H:81
A generic range class with a step.
Definition StepRange.H:70
Main namespace for all JeVois classes and functions.
Definition Concepts.dox:2
A category to which multiple ParameterDef definitions can belong.
std::string name
The name of the category.
std::string description
An optional short description of the category.