iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Point.H
Go to the documentation of this file.
1 /*! @file
2  @author Unknown
3  @copyright GNU Public License (GPL v3)
4  @section License
5  @verbatim
6  // ////////////////////////////////////////////////////////////////////////
7  // The iLab Neuromorphic Robotics Toolkit (NRT) //
8  // Copyright 2010-2012 by the University of Southern California (USC) //
9  // and the iLab at USC. //
10  // //
11  // iLab - University of Southern California //
12  // Hedco Neurociences Building, Room HNB-10 //
13  // Los Angeles, Ca 90089-2520 - USA //
14  // //
15  // See http://ilab.usc.edu for information about this project. //
16  // ////////////////////////////////////////////////////////////////////////
17  // This file is part of The iLab Neuromorphic Robotics Toolkit. //
18  // //
19  // The iLab Neuromorphic Robotics Toolkit is free software: you can //
20  // redistribute it and/or modify it under the terms of the GNU General //
21  // Public License as published by the Free Software Foundation, either //
22  // version 3 of the License, or (at your option) any later version. //
23  // //
24  // The iLab Neuromorphic Robotics Toolkit is distributed in the hope //
25  // that it will be useful, but WITHOUT ANY WARRANTY; without even the //
26  // implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR //
27  // PURPOSE. See the GNU General Public License for more details. //
28  // //
29  // You should have received a copy of the GNU General Public License //
30  // along with The iLab Neuromorphic Robotics Toolkit. If not, see //
31  // <http://www.gnu.org/licenses/>. //
32  // ////////////////////////////////////////////////////////////////////////
33  @endverbatim */
34 
35 #ifndef INCLUDE_NRT_CORE_GEOMETRY_POINT_H
36 #define INCLUDE_NRT_CORE_GEOMETRY_POINT_H
37 
44 #include <nrt/External/cereal/types/array.hpp>
45 
46 #include <boost/lexical_cast.hpp>
47 #include <algorithm>
48 #include <array>
49 #include <functional>
50 #include <iostream>
51 #include <math.h>
52 
53 namespace nrt
54 {
55  class PointBase {};
56 
57  // ######################################################################
58  //! A N-Dimensional Point Class
59  /*! The nrt::Point class is a general container useful for representing points in N-Dimentional space. Most users will
60  just want to use the specialized Point2D and Point3D classes.
61 
62  \ingroup geometry */
63  template <class T, size_t Dimensions>
64  class Point : public PointBase
65  {
66  public:
67  //! Construct an uninitialized point
68  explicit Point();
69 
70  //! Construct a Point by specifying the value of each Dimension.
71  /*! e.g. Point<float, 3> p(1.0F, 2.0F, 3.0F); */
72  template <typename ... S>
73  explicit Point(S... args);
74 
75  //! Construct a point from an std::array
76  explicit Point(std::array<T, Dimensions> const & init);
77 
78  //! Copy constructor
79  Point(Point<T, Dimensions> const & other) = default;
80 
81  //! Move constructor
82  Point(Point<T, Dimensions> && other) = default;
83 
84  //! Conversion copy constructor, uses nrt::clamped_convert<T,U> internally
85  template <class U>
86  explicit Point(Point<U, Dimensions> const & other);
87 
88  //! Assignment
89  Point<T, Dimensions> & operator=(Point<T, Dimensions> const & other) = default;
90 
91  //! Move assignment
93 
94  //! Access a single dimension of the Point
95  T & operator[](size_t index);
96 
97  //! Access a single dimension of the Point - const version
98  T const & operator[](size_t index) const;
99 
100  //! Compute the Euclidian distance to another point
101  template <class U>
102  double distanceTo(Point<U, Dimensions> const & other) const;
103 
104  //! Compute the squared Euclidian distance to another point
105  template <class U>
106  double squaredDistanceTo(Point<U, Dimensions> const & other) const;
107 
108  //! Compute the magnitude (the Euclidian distance from the origin)
109  double magnitude() const;
110 
111  //! Compute the Manhattan distance to another point
112  template <class U>
113  double manhattanDistanceTo(Point<U, Dimensions> const & other) const;
114 
115  //! Access the beginning of the underlying array
116  T* begin();
117 
118  //! Access the end of the underlying array
119  T* end();
120 
121  //! Access the beginning of the underlying array - const version
122  T const * begin() const;
123 
124  //! Access the end of the underlying array - const version
125  T const * end() const;
126 
127  protected:
128  std::array<T, Dimensions> itsData;
129 
130  friend class cereal::access;
131 
132  //! Serialization
133  template <class Archive>
134  void serialize(Archive & ar)
135  {
136  ar( itsData );
137  }
138 
139  private:
140  template <typename Head, typename... Tail>
141  void VariadicConstructorHelper(size_t idx, Head head, Tail... tail);
142 
143  template <typename Head>
144  void VariadicConstructorHelper(size_t idx, Head h);
145  };
146 
147  // ######################################################################
148  //! A 2-Dimensional Point Class
149  /*! \see Point
150  \ingroup geometry */
151  template <class T>
152  class Point2D : public Point<T, 2>
153  {
154  public:
155  //! Construct an uninitialized Point
156  explicit Point2D();
157 
158  //! Construct a Point by specifying the x,y dimensions
159  explicit Point2D(T x, T y);
160 
161  //! Construct a Point from an std::array.
162  explicit Point2D(std::array<T,2> const & init);
163 
164  //! Copy constructor
165  Point2D(Point<T, 2> const & other);
166 
167  //! Move constructor
168  Point2D(Point<T, 2> && other);
169 
170  //! Conversion copy constructor, uses nrt::clamped_convert<T,U> internally
171  template <class U>
172  explicit Point2D(Point<U, 2> const & other);
173 
174  //! Access the first dimension of this Point
175  T & x();
176 
177  //! Access the first dimension of this Point - const version
178  T const & x() const;
179 
180  //! Access the second dimension of this Point
181  T & y();
182 
183  //! Access the second dimension of this Point - const version
184  T const & y() const;
185  };
186 
187  // ######################################################################
188  //! A 3-Dimensional Point Class
189  /*! \see Point
190  \ingroup geometry */
191  template <class T>
192  class Point3D : public Point<T, 3>
193  {
194  public:
195  //! Construct an uninitialized Point
196  explicit Point3D();
197 
198  //! Construct a Point by specifying the x,y,z dimensions
199  explicit Point3D(T x, T y, T z);
200 
201  //! Construct a Point from an std::array.
202  explicit Point3D(std::array<T,3> const & init);
203 
204  //! Copy constructor
205  Point3D(Point<T,3> const & other);
206 
207  //! Move constructor
208  Point3D(Point<T,3> && other);
209 
210  //! Conversion copy constructor
211  template <class U>
212  explicit Point3D(Point<U, 3> const & other);
213 
214  //! Access the first dimension of this Point
215  T & x();
216 
217  //! Access the first dimension of this Point - const version
218  T const & x() const;
219 
220  //! Access the second dimension of this Point
221  T & y();
222 
223  //! Access the second dimension of this Point - const version
224  T const & y() const;
225 
226  //! Access the third dimension of this Point
227  T & z();
228 
229  //! Access the third dimension of this Point - const version
230  T const & z() const;
231  };
232 
233  // ######################################################################
234  // Free functions for Point<T, S>
235  // ######################################################################
236 
237  //! Human-readable output to a stream: outputs x1,x2,x3,...,xN
238  /* \relates Point */
239  template <class T, size_t S>
240  std::ostream& operator<<(std::ostream & out, nrt::Point<T, S> const & p);
241 
242  //! Human-readable input from a stream: reads x1,x2,x3,...,xN
243  /*! @throws nrt::exception::Exception if input is malformed
244  \relates Point */
245  template <class T, size_t S>
246  std::istream& operator>>(std::istream & in, nrt::Point<T, S> & p);
247 
248  //! Machine-readable output to a string, for use in nrt::Parameter: outputs x1,x2,x3,...,xN
249  /*! This is an overload for Point<T,S> of the function template in
250  nrt/Core/Model/ParameterStringConversion.H.
251  \relates Point */
252  template <class T, size_t S>
253  void paramValToString(Point<T, S> const & val, std::string & result);
254 
255  //! Machine-readable input from a string, for use in nrt::Parameter: reads x1,x2,x3,...,xN
256  /*! @throws nrt::exception::Exception if input is malformed.
257  This is an overload for Dims<T> of the function template in nrt/Core/Model/ParameterStringConversion.H.
258  \relates Point */
259  template <class T, size_t S>
260  void paramStringToVal(std::string const & valstring, Point<T, S> & result);
261 
262  //! Return a scaled version of the source object
263  /*! \note For a Point, scale() is a no-op. This does \e not have the same effect as the multiplication or division
264  operators, which scale everything, while here we only scale the object size (and that size is zero for a point)
265  without scaling its center coordinates. \relates Point */
266  template <class T, size_t S>
267  Point<T, S> scale(Point<T, S> const & src, double const factor);
268 
269  //! Return a rotated version of the source object, about its center by a given angle in radians
270  /*! \relates Point2D */
271  template <class T>
272  Point2D<T> rotate(Point2D<T> const & src, double const angle);
273 
274  //! Return a rotated version of the source object, about the given point and by a given angle in radians
275  /*! \relates Point2D */
276  template <class T>
277  Point2D<T> rotateAbout(Point2D<T> const & src, Point2D<T> const & p, double const angle);
278 
279  //! Operator overload for Point<T, S> == Point<T, S>
280  /*! \relates Point */
281  template <class T, size_t S>
282  bool operator==(Point<T, S> const & lhs, Point<T, S> const & rhs);
283 
284  //! Operator overload for Point<T, S> != Point<T, S>
285  /*! \relates Point */
286  template <class T, size_t S>
287  bool operator!=(Point<T, S> const & lhs, Point<T, S> const & rhs);
288 
289  //! Operator overload for Point2D<T> + Point<T, S>
290  /*! \relates Point */
291  template <class T, size_t S>
292  Point<T, S> operator+(Point<T, S> const & lhs, Point<T, S> const & rhs);
293 
294  //! Operator overload for Point2D<T> - Point<T, S>
295  /*! \relates Point */
296  template <class T, size_t S>
297  Point<T, S> operator-(Point<T, S> const & lhs, Point<T, S> const & rhs);
298 
299  //! Operator overload for Point<T, S> * double
300  /*! \relates Point */
301  template <class T, size_t S>
302  Point<T, S> operator*(Point<T, S> const & lhs, double const rhs);
303 
304  //! Operator overload for double * Point<T, S>
305  /*! \relates Point */
306  template <class T, size_t S>
307  Point<T, S> operator*(double const lhs, Point<T, S> const & rhs);
308 
309  //! Operator overload for Point<T, S> / double
310  /*! \relates Point */
311  template <class T, size_t S>
312  Point<T, S> operator/(Point<T, S> const & lhs, double const rhs);
313 
314  //! Operator overload for Point<T, S> *= double
315  /*! \relates Point */
316  template <class T, size_t S>
317  Point<T, S> & operator*=(Point<T, S> & lhs, double const rhs);
318 
319  //! Operator overload for Point<T, S> /= double
320  /*! \relates Point */
321  template <class T, size_t S>
322  Point<T, S> & operator/=(Point<T, S> & lhs, double const rhs);
323 
324  //! Operator overload for Point<T, S> += Point<T, S>
325  /*! \relates Point */
326  template <class T, size_t S>
327  Point<T, S> & operator+=(Point<T, S> & lhs, Point<T, S> const & rhs);
328 
329  //! Operator overload for Point<T, S> -= Point<T, S>
330  /*! \relates Point */
331  template <class T, size_t S>
332  Point<T, S> & operator-=(Point<T, S> & lhs, Point<T, S> const & rhs);
333 
334  //! Operator overload for Point2D<T> * Point<T, S>
335  /*! \relates Point \deprecated */
336  template <class T, size_t S>
337  Point<T, S> operator*(Point<T, S> const & lhs, Point<T, S> const & rhs);
338 
339  //! Operator overload for Point2D<T> / Point<T, S>
340  /*! \relates Point \deprecated */
341  template <class T, size_t S>
342  Point<T, S> operator/(Point<T, S> const & lhs, Point<T, S> const & rhs);
343 }
344 
345 // Include implementation details that are of no interest to the end user
347 
348 // Include explicit instantiations that are of no interest to the end user
350 
351 #endif // INCLUDE_NRT_CORE_GEOMETRY_POINT_H
352