LoUtils.H

Go to the documentation of this file.

/**
   \file Robots/LoBot/misc/LoUtils.H

   \brief Various utility functions/classes.
*/

// //////////////////////////////////////////////////////////////////// //
// The iLab Neuromorphic Vision C++ Toolkit - Copyright (C) 2000-2005   //
// by the University of Southern California (USC) and the iLab at USC.  //
// See http://iLab.usc.edu for information about this project.          //
// //////////////////////////////////////////////////////////////////// //
// Major portions of the iLab Neuromorphic Vision Toolkit are protected //
// under the U.S. patent ``Computation of Intrinsic Perceptual Saliency //
// in Visual Environments, and Applications'' by Christof Koch and      //
// Laurent Itti, California Institute of Technology, 2001 (patent       //
// pending; application number 09/912,225 filed July 23, 2001; see      //
// http://pair.uspto.gov/cgi-bin/final/home.pl for current status).     //
// //////////////////////////////////////////////////////////////////// //
// This file is part of the iLab Neuromorphic Vision C++ Toolkit.       //
//                                                                      //
// The iLab Neuromorphic Vision C++ Toolkit is free software; you can   //
// redistribute it and/or modify it under the terms of the GNU General  //
// Public License as published by the Free Software Foundation; either  //
// version 2 of the License, or (at your option) any later version.     //
//                                                                      //
// The iLab Neuromorphic Vision C++ Toolkit is distributed in the hope  //
// that it will be useful, but WITHOUT ANY WARRANTY; without even the   //
// implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR      //
// PURPOSE.  See the GNU General Public License for more details.       //
//                                                                      //
// You should have received a copy of the GNU General Public License    //
// along with the iLab Neuromorphic Vision C++ Toolkit; if not, write   //
// to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,   //
// Boston, MA 02111-1307 USA.                                           //
// //////////////////////////////////////////////////////////////////// //
//
// Primary maintainer for this file: Manu Viswanathan <mviswana at usc dot edu>
// $HeadURL: svn://isvn.usc.edu/software/invt/trunk/saliency/src/Robots/LoBot/misc/LoUtils.H $
// $Id: LoUtils.H 12039 2009-11-17 05:36:44Z mviswana $
//

#ifndef LOBOT_UTILITIES_DOT_H
#define LOBOT_UTILITIES_DOT_H

//------------------------------ HEADERS --------------------------------

// lobot headers
#include "Robots/LoBot/misc/range.hh"

// INVT utilities
#include "Util/log.H"

// Standard C++ headers
#include <sstream>
#include <ostream>
#include <string>
#include <algorithm>
#include <list>
#include <vector>
#include <functional>
#include <iterator>
#include <limits>
#include <utility>

// Standard C headers
#include <math.h>

//----------------------------- NAMESPACE -------------------------------

namespace lobot {

//------------------------- NUMERIC FUNCTIONS ---------------------------

/// The sign of a number
template<typename T>
inline int sign(const T& t)
{
   return (t < 0) ? -1 : +1 ;
}

/// Absolute value for different numeric types
template<typename T>
inline T abs(const T& t)
{
   return (t < 0) ? -t : t ;
}

/// Clamp a given value to the specified range
template<typename T>
T clamp(const T& value, const T& min, const T& max)
{
   if (value < min)
      return min ;
   if (value > max)
      return max ;
   return value ;
}

/// Quick helper to clamp a given value to the specified range
template<typename T>
inline T clamp(const T& value, const range<T>& range)
{
   return clamp(value, range.min(), range.max()) ;
}

/// Quick helper to clamp a given angle to lie within 0 and 360 degrees
template<typename T>
T clamp_angle(const T& angle)
{
   T A = angle - 360 * static_cast<int>(angle/360) ;
   return (A < 0) ? 360 + A : A ;
}

/// Check if a floating-point number is near zero
template<typename T>
bool is_zero(const T& t)
{
   return t > -std::numeric_limits<T>::epsilon()
       && t <  std::numeric_limits<T>::epsilon() ;
}

/// Round a floating-point number to the nearest integer
template<typename T>
int round(const T& t)
{
   return static_cast<int>(t + T(0.5)) ;
}

/// Force the supplied number to be an odd number
template<typename T>
T force_odd(const T& t)
{
   return t | 1 ;
}

/// Force the supplied number to be an even number
template<typename T>
T force_even(const T& t)
{
   return t & T(~1) ;
}

/// Stuff two 16-bit ints into a long
inline unsigned long make_long(int a, int b)
{
   return (a << 16) | b ;
}

/// Extract the lower 16 bits of a long
inline int loword(unsigned long L)
{
   return static_cast<int>(L & 0xFFFF) ;
}

/// Extract the higher 16 bits of a long
inline int hiword(unsigned long L)
{
   return loword(L >> 16) ;
}

/// Trig functions for degrees rather than radians
//@{
inline float sin(float angle)
{
   return sinf(angle * 0.01745329f) ; // angle * PI/180
}

inline float cos(float angle)
{
   return cosf(angle * 0.01745329f) ; // angle * PI/180
}

inline double sin(double angle)
{
   return ::sin(angle * 0.0174532925199432) ; // angle * PI/180
}

inline double cos(double angle)
{
   return ::cos(angle * 0.0174532925199432) ; // angle * PI/180
}
//@}

/// Log functions for base 10
//@{
inline float log(float n)
{
   return log10f(n) ;
}

inline double log(double n)
{
   return log10(n) ;
}
//@}

/// Exponential functions
//@{
inline float exp(float n)
{
   return expf(n) ;
}

inline double exp(double n)
{
   return ::exp(n) ;
}
//@}

//------------------------ STRING MANIPULATION --------------------------

/// Convenient (but perhaps not the most efficient) helper to convert
/// various data types to strings.
///
/// DEVNOTE: Works as long as type T defines an operator << that writes
/// to an ostream.
template<typename T>
std::string to_string(const T& t)
{
   std::ostringstream str ;
   str << t ;
   return str.str() ;
}

/// Read from string. As above, works as long as type T defines an
/// operator >> that reads from an istream.
template<typename T>
T from_string(const std::string& s, const T& defval = T())
{
   T t(defval) ;
   std::istringstream str(s) ;
   str >> t ;
   return t ;
}

/// from_string() specialization for strings. If the client wants a
/// string from the input string, we just return the input string. If we
/// were to apply the default version of this template function, we would
/// end up parsing the input string as a whitespace separated string
/// stream and only return the first string from this stream.
template<>
std::string from_string(const std::string& s, const std::string&)
{
   return s ;
}

/// Converts a whitespace separated string of T into a vector of T
template<typename T>
std::vector<T> string_to_vector(const std::string& s)
{
   std::istringstream str(s) ;
   return std::vector<T>(std::istream_iterator<T>(str),
                         std::istream_iterator<T>()) ;
}

/// Converts a whitespace separated string of T into a list of T
template<typename T>
std::list<T> string_to_list(const std::string& s)
{
   std::istringstream str(s) ;
   return std::list<T>(std::istream_iterator<T>(str),
                       std::istream_iterator<T>()) ;
}

/// String case conversion
//@{
std::string upstring(std::string) ;
std::string downstring(std::string) ;
//@}

//---------------------------- STL HELPERS ------------------------------

/// Pointer deletion (useful in conjunction with STL algorithms and
/// containers).
///
/// WARNING: P must be a pointer type (e.g., int* rather than int).
template<typename P> void delete_ptr(P p) {delete p ;}

/// Pointer deletion when the pointer is part of an std::pair
//@{
template<typename P> void delete_first (P& p) {delete p.first ;}
template<typename P> void delete_second(P& p) {delete p.second ;}
//@}

/// Functions to retrieve the individual elements of a pair.
//@{
template<typename P>
typename P::first_type  get_first(const P& p)  {return p.first ;}

template<typename P>
typename P::second_type get_second(const P& p) {return p.second ;}
//@}

/// Releasing an STL container of pointers using a specific delete
/// function (useful in cases of std::maps).
///
/// C: container type
/// D: delete function object type
///
/// WARNING: C *must* be an STL container or *must* provide an equivalent
/// begin/end iterator interface.
///
/// This function would typically be used to clean-up maps. For example,
/// an std::map<int, int*>. In this case, we cannot use delete_ptr<int*>
/// directly because the map iterators point to std::pair objects whose
/// first member is the key (int in this case) and whose second member is
/// the value (int* in this case).
///
/// Thus, we need to supply an appropriate delete function. In this case,
/// that function would be delete_second<std::pair<int, int*>>.
template<typename C, typename D>
void purge_container(C& c, D delete_fn)
{
   std::for_each(c.begin(), c.end(), delete_fn) ;
}

/// Releasing an STL container of pointers using the delete_ptr function.
/// C: container type
///
/// WARNING: C *must* be an STL container or provide an equivalent
/// begin/end iterator interface and value_type typedef.
///
/// This function would typically be used to clean-up a containers such as
/// std::vector<int*> or other such containers of pointers. In this case,
/// value_type would be int*.
template<typename C>
void purge_container(C& c)
{
   typedef typename C::value_type P ;
   purge_container(c, delete_ptr<P>) ;
}

/// The STL already provides canned function objects for relational
/// operators. These two are for the min and max functions. They can be
/// used in conjunction with binders to quickly write calls to
/// std::transform(), etc. without having to create custom function
/// objects.
//@{
template<typename T>
struct min : std::binary_function<T, T, T> {
   T operator()(const T& a, const T& b) const {
      return std::min(a, b) ;
   }
} ;

template<typename T>
struct max : std::binary_function<T, T, T> {
   T operator()(const T& a, const T& b) const {
      return std::max(a, b) ;
   }
} ;
//@}

/// This function object is meant to be used in conjunction with the
/// std::accumulate algorithm and returns the sum of the squares of the
/// sequence to which the accumulate algorithm is applied.
template<typename T>
struct sum_of_squares : std::binary_function<T, T, T> {
   T operator()(const T& a, const T& b) const {
      return T(a + b*b) ;
   }
} ;

/// This function object is a predicate that returns true if the number
/// passed to its function call operator is out of the specified range.
template<typename T>
class out_of_range : public std::unary_function<T, bool> {
   range<T> m_range ;
public:
   out_of_range(const range<T>& R) : m_range(R) {}
   bool operator()(const T& t) const {return ! m_range.in(t) ;}
} ;

/// Quick helper to connect whatever is in the supplied container to the
/// specified target object using push_back(). (Thus, the target object
/// must supply a push_back() method and other necessary STL glue to make
/// this work.)
template<typename C, typename T>
static void connect(const C& container, T& target)
{
   std::copy(container.begin(), container.end(), std::back_inserter(target)) ;
}

//-------------------------- OPENGL HELPERS -----------------------------

/// Draw a text label in a GLUT window.
void draw_label(float x, float y, const char* label) ;

//--------------------------- DEBUG SUPPORT -----------------------------

/// Debugging support: dump an STL container using LERROR
///
/// DEVNOTE: Mostly suitable for small containers, e.g., vector of 10
/// numbers or something like that.
template<typename container>
void dump(const container& C, const std::string& caller,
          const std::string& container_name = "container")
{
   std::ostringstream str ;
   std::copy(C.begin(), C.end(),
             std::ostream_iterator<typename container::value_type>(str, " ")) ;
   LERROR("from %s ==> %s[0x%lx]: size = %d, contents = %s",
          caller.c_str(), container_name.c_str(),
          reinterpret_cast<long int>(&C), static_cast<int>(C.size()),
          str.str().c_str()) ;
}

/// Dump an array of type T given pointers to its first and last elements
template<typename T>
void dump(const T* begin, const T* end, const std::string& caller,
          const std::string& container_name = "array")
{
   std::vector<T> vec(begin, end) ;
   dump(vec, caller, container_name) ;
}

/// Function object to dump an std::pair to the given output stream
template<typename T1, typename T2>
class dump_pair {
   std::ostream& os ;
public:
   dump_pair(std::ostream& s) : os(s) {}
   void operator()(const std::pair<T1, T2>& p) const {
      os << '[' << p.first << ' ' << p.second << "] " ;
   }
} ;

/// The earlier version of the dump() function for dumping containers
/// will only work with containers of built-in/standard types such as
/// vector<int>, list<float>, etc. because it uses std::ostream_iterator,
/// which, annoyingly enough, doesn't work with user-defined types.
/// Therefore, the earlier dump() function won't dump std::map containers
/// (because their value type is an std::pair).
///
/// We work around this problem by providing this overloaded version of
/// dump() especially for std::maps.
template<typename key_type, typename value_type>
void dump(const std::map<key_type, value_type>& C,
          const std::string& caller,
          const std::string& container_name = "container")
{
   std::ostringstream str ;
   std::for_each(C.begin(), C.end(),
                 dump_pair<key_type, value_type>(str)) ;
   LERROR("from %s ==> %s[0x%lx]: size = %d, contents = %s",
          caller.c_str(), container_name.c_str(),
          reinterpret_cast<long int>(&C), static_cast<int>(C.size()),
          str.str().c_str()) ;
}

//-----------------------------------------------------------------------

} // end of namespace encapsulating this file's definitions

#endif

/* So things look consistent in everyone's emacs... */
/* Local Variables: */
/* indent-tabs-mode: nil */
/* End: */

---