JeVois  1.18
JeVois Smart Embedded Machine Vision Toolkit
Share this page:
PythonParameter.H
Go to the documentation of this file.
1 // ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
2 //
3 // JeVois Smart Embedded Machine Vision Toolkit - Copyright (C) 20122by 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 #pragma once
19 
21 #include <boost/python.hpp>
22 
23 namespace jevois
24 {
25  namespace python
26  {
27  //! Base helper class to allow creation of Parameter in python \ingroup python
29  {
30  public:
31  //! Constructor
33 
34  //! Remove param from component
35  virtual ~PyParHelperBase();
36 
37  //! Get the value, typed, then wrapped into python object
38  virtual boost::python::object get() = 0;
39 
40  //! Set the value from python object that should contain a value of the correct type
41  virtual void set(boost::python::object const & val) = 0;
42 
43  //! Set the parameter's callback
44  virtual void setCallback(boost::python::object const & cb) = 0;
45 
46  //! Access the associated C++ base Parameter
47  virtual std::shared_ptr<jevois::ParameterBase> par() const = 0;
48 
49  protected:
50  //! Access the associated C++ Component
51  jevois::Component * comp() const;
52 
53  private:
54  jevois::Component * itsComp;
55  };
56 
57  //! Typed class to allow creation of Parameter in Python \ingroup python
58  template <typename T>
60  {
61  public:
62  //! Create and add the parameter to the component
63  static std::shared_ptr<jevois::python::PyParHelperBase>
64  create(jevois::Component * comp, std::string const & name, std::string const & description,
65  boost::python::object const & defaultValue, jevois::ParameterCategory const & category);
66 
67  //! Create and add the parameter to the component
68  PyParHelper(jevois::Component * comp, std::string const & name, std::string const & description,
69  boost::python::object const & defaultValue, jevois::ParameterCategory const & category);
70 
71  //! Remove param from component
72  virtual ~PyParHelper();
73 
74  //! Get the value, typed, then wrapped into python object
75  boost::python::object get() override;
76 
77  //! Set the value from python object
78  void set(boost::python::object const & val) override;
79 
80  //! Set the parameter's callback
81  void setCallback(boost::python::object const & cb) override;
82 
83  //! Access the associated C++ base parameter, used to forward strget(), strset(), freeze(), etc to it
84  std::shared_ptr<jevois::ParameterBase> par() const override;
85 
86  protected:
87  std::shared_ptr<jevois::DynamicParameter<T>> itsParam;
88  boost::python::object itsPyCallback;
89  };
90  } // namespace python
91 
92  //! Wrapper for jevois Parameter in python
93  /*! This wrapper allows python modules to create JeVois Parameter objects, allowing users to interact with the
94  parameters through the console, JeVois-Inventor, or the JeVois-Pro GUI. This class does not actually contain the
95  parameter, it is just an interface. Parameters belong to the Component associated with the python code via
96  PythonWrapper. \ingroup python */
98  {
99  public:
100  //! Constructor. Adds a dynamic parameter to the Component associated with pyinst
101  PythonParameter(boost::python::object & pyinst, std::string const & name, std::string const & typ,
102  std::string const & description, boost::python::object const & defaultValue,
103  jevois::ParameterCategory const & category);
104 
105  //! Destructor. Removes the dynamic parameter from the associated Component
107 
108  //! Get the parameter name
109  std::string const & name() const;
110 
111  //! Get the parameter fully-qualified name, aka descriptor, including names of owning Component and all parents
112  std::string descriptor() const;
113 
114  //! Get the value of this Parameter
115  boost::python::object get() const;
116 
117  //! Set the value of this Parameter
118  /*! Will throw if the new value is not accepted, in which case the old value will remain in the Parameter. */
119  void set(boost::python::object const & newVal);
120 
121  //! Get the value as a string
122  std::string const strget() const;
123 
124  //! Set the value from a string representation of it
125  /*! @throws std::range_error if the given string cannot be converted to a Parameter value, or the value is invalid
126  according to our valid values spec or rejected by the Parameter's callback (if any). */
127  void strset(std::string const & valstring);
128 
129  //! Freeze/unfreeze this parameter, it becomes read-only and will not show up in the help message
130  void freeze(bool doit);
131 
132  //! Reset this parameter to its default value
133  void reset();
134 
135  //! Set the parameter's callback
136  /*! The callback function is called each time one tries to change the value of the parameter. It will also be
137  called one first time, with the current parameter value, as soon as the callback is set.
138 
139  The callback should examine the candidate value newval and (1) if it does not like it, throw and with a
140  descriptive message of why the value is rejected, (2) otherwise, it is assumed that the value is accepted and
141  the callback can then allocate resources or do other work with that value (the actual modification of the
142  Parameter object is handled upstream and the callback does not need to worry about it: if it returns without
143  throwing, the proposed value will become the new value of the Parameter). The Parameter is locked-up for
144  writing as long as the callback is running, to avoid destruction of the parameter and/or concurrent parameter
145  value changes by several different threads. Thus, callbacks should try to execute quickly, and should not call
146  set(), etc on the parameter as this will always deadlock (get() is allowed if your callback needs to know the
147  current value of the parameter). */
148  void setCallback(boost::python::object const & cb);
149 
150  private:
151  std::shared_ptr<jevois::python::PyParHelperBase> itsPyPar;
152  };
153 
154 
155 
156 } // namespace jevois
157 
158 // Include implementation details
159 #include <jevois/Core/details/PythonParameterImpl.H>
jevois::python::PyParHelperBase
Base helper class to allow creation of Parameter in python.
Definition: PythonParameter.H:28
jevois::python::PyParHelper::PyParHelper
PyParHelper(jevois::Component *comp, std::string const &name, std::string const &description, boost::python::object const &defaultValue, jevois::ParameterCategory const &category)
Create and add the parameter to the component.
jevois::python::PyParHelperBase::set
virtual void set(boost::python::object const &val)=0
Set the value from python object that should contain a value of the correct type.
jevois::python::PyParHelper::par
std::shared_ptr< jevois::ParameterBase > par() const override
Access the associated C++ base parameter, used to forward strget(), strset(), freeze(),...
jevois::PythonParameter::strget
const std::string strget() const
Get the value as a string.
Definition: PythonParameter.C:142
jevois::PythonParameter::set
void set(boost::python::object const &newVal)
Set the value of this Parameter.
Definition: PythonParameter.C:138
jevois::python::PyParHelperBase::PyParHelperBase
PyParHelperBase(jevois::Component *comp)
Constructor.
Definition: PythonParameter.C:23
jevois::PythonParameter::PythonParameter
PythonParameter(boost::python::object &pyinst, std::string const &name, std::string const &typ, std::string const &description, boost::python::object const &defaultValue, jevois::ParameterCategory const &category)
Constructor. Adds a dynamic parameter to the Component associated with pyinst.
Definition: PythonParameter.C:100
jevois::PythonParameter::name
const std::string & name() const
Get the parameter name.
Definition: PythonParameter.C:126
jevois::python::PyParHelper::setCallback
void setCallback(boost::python::object const &cb) override
Set the parameter's callback.
jevois::Component
A component of a model hierarchy.
Definition: Component.H:181
jevois::PythonParameter::freeze
void freeze(bool doit)
Freeze/unfreeze this parameter, it becomes read-only and will not show up in the help message.
Definition: PythonParameter.C:150
jevois::PythonParameter::~PythonParameter
~PythonParameter()
Destructor. Removes the dynamic parameter from the associated Component.
Definition: PythonParameter.C:122
jevois::python::PyParHelper::itsPyCallback
boost::python::object itsPyCallback
Definition: PythonParameter.H:88
jevois::ParameterCategory
A category to which multiple ParameterDef definitions can belong.
Definition: ParameterDef.H:33
jevois::python::PyParHelper::~PyParHelper
virtual ~PyParHelper()
Remove param from component.
jevois::PythonParameter::strset
void strset(std::string const &valstring)
Set the value from a string representation of it.
Definition: PythonParameter.C:146
jevois
Definition: Concepts.dox:1
Component.H
jevois::python::PyParHelperBase::comp
jevois::Component * comp() const
Access the associated C++ Component.
Definition: PythonParameter.C:31
jevois::PythonParameter::get
boost::python::object get() const
Get the value of this Parameter.
Definition: PythonParameter.C:134
jevois::PythonParameter::setCallback
void setCallback(boost::python::object const &cb)
Set the parameter's callback.
Definition: PythonParameter.C:158
jevois::python::PyParHelper::create
static std::shared_ptr< jevois::python::PyParHelperBase > create(jevois::Component *comp, std::string const &name, std::string const &description, boost::python::object const &defaultValue, jevois::ParameterCategory const &category)
Create and add the parameter to the component.
jevois::python::PyParHelperBase::get
virtual boost::python::object get()=0
Get the value, typed, then wrapped into python object.
jevois::PythonParameter::reset
void reset()
Reset this parameter to its default value.
Definition: PythonParameter.C:154
jevois::python::PyParHelper::itsParam
std::shared_ptr< jevois::DynamicParameter< T > > itsParam
Definition: PythonParameter.H:87
jevois::python::PyParHelperBase::setCallback
virtual void setCallback(boost::python::object const &cb)=0
Set the parameter's callback.
jevois::python::PyParHelperBase::~PyParHelperBase
virtual ~PyParHelperBase()
Remove param from component.
Definition: PythonParameter.C:27
jevois::python::PyParHelper::get
boost::python::object get() override
Get the value, typed, then wrapped into python object.
jevois::PythonParameter
Wrapper for jevois Parameter in python.
Definition: PythonParameter.H:97
jevois::python::PyParHelper::set
void set(boost::python::object const &val) override
Set the value from python object.
jevois::PythonParameter::descriptor
std::string descriptor() const
Get the parameter fully-qualified name, aka descriptor, including names of owning Component and all p...
Definition: PythonParameter.C:130
jevois::python::PyParHelper
Typed class to allow creation of Parameter in Python.
Definition: PythonParameter.H:59
jevois::python::PyParHelperBase::par
virtual std::shared_ptr< jevois::ParameterBase > par() const =0
Access the associated C++ base Parameter.