JeVois  1.2
JeVois Smart Embedded Machine Vision Toolkit
Range.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 file has been modified / imported from the Neuromorphic Robotics Toolkit (NRT). Original copyright is:
19 
20 /* author Laurent Itti
21  // ////////////////////////////////////////////////////////////////////////
22  // The iLab Neuromorphic Robotics Toolkit (NRT) //
23  // Copyright 2010-2012 by the University of Southern California (USC) //
24  // and the iLab at USC. //
25  // //
26  // iLab - University of Southern California //
27  // Hedco Neurociences Building, Room HNB-10 //
28  // Los Angeles, Ca 90089-2520 - USA //
29  // //
30  // See http://ilab.usc.edu for information about this project. //
31  // ////////////////////////////////////////////////////////////////////////
32  // This file is part of The iLab Neuromorphic Robotics Toolkit. //
33  // //
34  // The iLab Neuromorphic Robotics Toolkit is free software: you can //
35  // redistribute it and/or modify it under the terms of the GNU General //
36  // Public License as published by the Free Software Foundation, either //
37  // version 3 of the License, or (at your option) any later version. //
38  // //
39  // The iLab Neuromorphic Robotics Toolkit is distributed in the hope //
40  // that it will be useful, but WITHOUT ANY WARRANTY; without even the //
41  // implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR //
42  // PURPOSE. See the GNU General Public License for more details. //
43  // //
44  // You should have received a copy of the GNU General Public License //
45  // along with The iLab Neuromorphic Robotics Toolkit. If not, see //
46  // <http://www.gnu.org/licenses/>. //
47  // ////////////////////////////////////////////////////////////////////////
48 */
49 
50 #pragma once
51 
52 #include <istream>
53 #include <ostream>
54 
55 namespace jevois
56 {
57  //! A generic range class
58  /*! The Range class is used to represent a range from [min .. max]
59 
60  Note that the operators of Range do not use type promotions. This is to minimize template burden and also possible
61  programmer confusion. For example, while in principle one could define Range<int> + float and return a
62  Range<float>, here we do not define such an operator. The same result can be achieved by first converting the
63  range and then adding the constant:
64 
65  @code
66  jevois::Range<int> r1(0, 100);
67  // NOT ALLOWED: jevois::Range<float> r2 = r1 + 1.23F;
68  jevois::Range<float> r2 = jevois::Range<float>(r1) + 1.23F; // OK, no hidden conversions, easy to read, explicit
69  @endcode
70 
71  Operators on Range use range checking and clamping internally. Thus, be careful if using Range<byte>. For
72  example:
73  @code
74  jevois::Range<jevois::byte> r(jevois::byte(0), jevois::byte(250));
75  r += jevois::byte(100); // new range is 100-255
76  @endcode
77 
78  \ingroup types */
79  template <typename T>
80  class Range
81  {
82  public:
83  //! Default constructor, range is [0 .. 0]
84  explicit Range();
85 
86  //! Constructor
87  explicit Range(T const mini, T const maxi);
88 
89  //! Copy constructor
90  Range(Range<T> const & other) = default;
91 
92  //! Move constructor
93  Range(Range<T> && other) = default;
94 
95  //! Copy-conversion constructor, uses jevois::clamped_convert<T,U> internally
96  /*! Note that this constructor is \e explicit, i.e., you need to explicitly mention it. This is to avoid
97  conversions to happen without a programmer being aware of it. For example:
98  @code
99  void myFunc(jevois::Range<float> const & rng) { ... }
100  jevois::Range<int> r1(0, 100);
101  jevois::Range<float> r2(r1); // ok, explicit constructor call
102  myFunc(r2); // ok, no conversion necessary
103  //myFunc(r1) // NO: passing Range<int> to function that takes a Range<float> arg fails to compile
104  myFunc(jevois::Range<float>(r1)); // ok, nice and explicit; and you can think about whether r1 should
105  // have been a Range<float> in the first place so you don't waste CPU
106  // doing this conversion (as opposed to just not being aware of the wasting)
107  @endcode */
108  template <typename U>
109  explicit Range(Range<U> const & other);
110 
111  //! Assignment
112  Range<T> & operator=(Range<T> const & other) = default;
113 
114  //! Move assignment
115  Range<T> & operator=(Range<T> && other) = default;
116 
117  //! Return the minimum value
118  T const & min() const;
119 
120  //! Return the maximum value
121  T const & max() const;
122 
123  //! Return whether min() == max()
124  bool empty() const;
125 
126  //! Extend the range, if needed, so that it includes val
127  void extend(T const val);
128 
129  //! Return true if val is within [min ... max]
130  bool contains(T const & val) const;
131 
132  private:
133  T itsMin;
134  T itsMax;
135  };
136 
137  // ######################################################################
138  // Free functions for Range<T>
139  // ######################################################################
140 
141  //! Merge two ranges
142  /*! \relates jevois::Range */
143  template <typename T>
144  Range<T> merge(Range<T> const & r1, Range<T> const & r2);
145 
146  //! Stream out as "[min ... max]"
147  /*! \relates jevois::Range */
148  template <typename T>
149  std::ostream & operator<<(std::ostream & out, Range<T> const & r);
150 
151  //! Stream in as "[min ... max]"
152  /*! \relates jevois::Range */
153  template <typename T>
154  std::istream & operator>>(std::istream & in, Range<T> & r);
155 
156  //! Machine-readable output to a string, for use in jevois::Parameter: outputs \c min...max (e.g., 0...100)
157  /*! \relates jevois::Range */
158  template <class T>
159  void paramValToString(Range<T> const & val, std::string & result);
160 
161  //! Machine-readable input from a string, for use in jevois::Parameter: reads \c min...max (e.g., 0...100)
162  /*! \relates jevois::Range */
163  template <class T>
164  void paramStringToVal(std::string const & valstring, Range<T> & result);
165 
166  //! Equality test: Range<T> == Range<T>
167  /*! \relates jevois::Range */
168  template <typename T>
169  bool operator==(Range<T> const & range1, Range<T> const & range2);
170 
171  //! Inequality test: Range<T> != Range<T>
172  /*! \relates jevois::Range */
173  template <typename T>
174  bool operator!=(Range<T> const & range1, Range<T> const & range2);
175 
176  //! Add constant to both ends of a range: Range<T> + T
177  /*! \relates jevois::Range */
178  template <typename T>
179  Range<T> operator+(Range<T> const & range, T const & scalar);
180 
181  //! Add constant to both ends of a range: T + Range<T>
182  /*! \relates jevois::Range */
183  template <typename T>
184  Range<T> operator+(T const & scalar, Range<T> const & range);
185 
186  //! Subtract constant from both ends of a range: Range<T> - T
187  /*! \relates jevois::Range */
188  template <typename T>
189  Range<T> operator-(Range<T> const & range, T const & scalar);
190 
191  //! Subtract constant from both ends of a range: T - Range<T>
192  /*! \relates jevois::Range */
193  template <typename T>
194  Range<T> operator-(T const & scalar, Range<T> const & range);
195 
196  //! Divide both ends of a range by a factor: Range<T> / T
197  /*! \relates jevois::Range */
198  template <typename T>
199  Range<T> operator/(Range<T> const & range, T const & scalar);
200 
201  //! Divide a factor by both ends of a range: T / Range<T>
202  /*! \relates jevois::Range */
203  template <typename T>
204  Range<T> operator/(T const & scalar, Range<T> const & range);
205 
206  //! Multiply both ends of a range by a factor: Range<T> * T
207  /*! \relates jevois::Range */
208  template <typename T>
209  Range<T> operator*(Range<T> const & range, T const & scalar);
210 
211  //! Multiply a factor by both ends of a range: T * Range<T>
212  /*! \relates jevois::Range */
213  template <typename T>
214  Range<T> operator*(T const & scalar, Range<T> const & range);
215 
216  //! Add constant to both ends of a range: Range<T> += T
217  /*! \relates jevois::Range */
218  template <typename T>
219  Range<T> & operator+=(Range<T> & range, T const & scalar);
220 
221  //! Subtract constant from both ends of a range: Range<T> -= T
222  /*! \relates jevois::Range */
223  template <typename T>
224  Range<T> & operator-=(Range<T> & range, T const & scalar);
225 
226  //! Multiply both ends of a range by a factor: Range<T> *= T
227  /*! \relates jevois::Range */
228  template <typename T>
229  Range<T> & operator*=(Range<T> & range, T const & scalar);
230 
231  //! Divide both ends of a range by a factor: Range<T> /= T
232  /*! \relates jevois::Range */
233  template <typename T>
234  Range<T> & operator/=(Range<T> & range, T const & scalar);
235 
236 } // namespace jevois
237 
238 // Include inlined implementation details that are of no interest to the end user
void paramStringToVal(std::string const &valstring, T &result)
Machine-readable conversion from string to T, for use in jevois::Parameter.
bool empty() const
Return whether min() == max()
Definition: RangeImpl.H:90
T const & max() const
Return the maximum value.
Definition: RangeImpl.H:85
void paramValToString(T const &val, std::string &result)
Machine-readable conversion of T to a string, for use in jevois::Parameter.
bool contains(T const &val) const
Return true if val is within [min ... max].
Definition: RangeImpl.H:104
Range()
Default constructor, range is [0 .. 0].
Definition: RangeImpl.H:59
Range< T > & operator=(Range< T > const &other)=default
Assignment.
A generic range class.
Definition: Range.H:80
void extend(T const val)
Extend the range, if needed, so that it includes val.
Definition: RangeImpl.H:96
T const & min() const
Return the minimum value.
Definition: RangeImpl.H:80