RotatedRectangle.H

Go to the documentation of this file.

/*! @file
    @author Randolph Voorhies
    @copyright GNU Public License (GPL v3)
    @section License
    @verbatim
    // ////////////////////////////////////////////////////////////////////////
    //              The iLab Neuromorphic Robotics Toolkit (NRT)             //
    // Copyright 2010-2012 by the University of Southern California (USC)    //
    //                          and the iLab at USC.                         //
    //                                                                       //
    //                iLab - University of Southern California               //
    //                Hedco Neurociences Building, Room HNB-10               //
    //                    Los Angeles, Ca 90089-2520 - USA                   //
    //                                                                       //
    //      See http://ilab.usc.edu for information about this project.      //
    // ////////////////////////////////////////////////////////////////////////
    // This file is part of The iLab Neuromorphic Robotics Toolkit.          //
    //                                                                       //
    // The iLab Neuromorphic Robotics 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 3 of the License, or (at your option) any later version.      //
    //                                                                       //
    // The iLab Neuromorphic Robotics 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 Robotics Toolkit.  If not, see       //
    // <http://www.gnu.org/licenses/>.                                       //
    // ////////////////////////////////////////////////////////////////////////
    @endverbatim */


#ifndef INCLUDE_NRT_CORE_GEOMETRY_ROTATEDRECTANGLE_H
#define INCLUDE_NRT_CORE_GEOMETRY_ROTATEDRECTANGLE_H

#include <nrt/Core/Geometry/Dims.H>
#include <nrt/Core/Geometry/Polygon.H>
#include <nrt/External/cereal/access.hpp>

namespace nrt
{
  //! A 2D rotated rectangle containing a center point, dimensions, and an angle
  /*! \ingroup geometry */
  template <class T>
  class RotatedRectangle
  {
    public:
      //! Default constructor
      explicit RotatedRectangle() = default;

      //! Construct a RotatedRectangle from a center point, dimensions, and an angle (in radians)
      explicit RotatedRectangle(Point2D<T> const & center, Dims<T> const & dims, double const & angle);

      //! Copy Constructor
      RotatedRectangle(RotatedRectangle<T> const & other) = default;

      //! Move constructor
      RotatedRectangle(RotatedRectangle<T> && other) = default;

      //! Copy from a RotatedRectangle of a different datatype
      /*! This will internally use nrt::clamped_convert<T,U> on the center and dims */
      template <class U>
      explicit RotatedRectangle(RotatedRectangle<U> const & other);

      //! Assignment
      RotatedRectangle<T> & operator=(RotatedRectangle<T> const & other) = default;

      //! Move assignment
      RotatedRectangle<T> & operator=(RotatedRectangle<T> && other) = default;

      //! Get the center point
      Point2D<T> center() const;

      //! Get the dimensions
      Dims<T> dims() const;

      //! Get the angle (in radians)
      double angle() const;

      //! Compute the four vertices
      std::vector<Point2D<T> > vertices() const;

      //! Find the RotatedRectangle with the minimum area which encloses a convex Polygon
      /*! This method uses the algorithm outlined in "A Linear Time Algorithm for the Minimum Area Rectangle Enclosing a
          Convex Polygon" by Arnon & Gieselmann, 1983. The algorithm works by using the "Rotating Calipers" method,
          which exploits a proof showing that the minimum area enclosing rectangle will have one edge which meets an
          edge of the Polygon.

          The returned rectangle will have an angle between 0-pi, and it's width will always be at least as large as
          it's height.

          \note The given Polygon <i>must</i> be convex, otherwise the calculated RotatedRectangle will be incorrect. */
      static RotatedRectangle<T> minEnclosingRectangle(Polygon<T> const & convexPoly);

    private:
      Point2D<T> itsCenter;
      Dims<T> itsDims;
      double itsAngle;

      //! Serialization
      template <class Archive>
        void serialize(Archive& ar)
        {
          ar( itsCenter, itsDims, itsAngle );
        }
      friend class cereal::access;
  };


  //! Human-readable output to a stream: outputs [Center: xxx, Dims: xxx, Amgle: xxx]
  /*! \relates RotatedRectangle */
  template <class T>
  std::ostream& operator<<(std::ostream &out, RotatedRectangle<T> const & r);

  //! Return a scaled version of the source object
  /*! \note This does \e not have the same effect as the multiplication or division operators, which scale everything,
      while here we only scale the object size without scaling its center coordinates.
      \relates RotatedRectangle */
  template <class T>
  RotatedRectangle<T> scale(RotatedRectangle<T> const & src, double const factor);

  //! Return a rotated version of the source object, about its center by a given angle in radians
  /*! \relates RotatedRectangle */
  template <class T>
  RotatedRectangle<T> rotate(RotatedRectangle<T> const & src, double const angle);

  //! Return a rotated version of the source object, about the given point and by a given angle in radians
  /*! \relates RotatedRectangle */
  template <class T>
  RotatedRectangle<T> rotateAbout(RotatedRectangle<T> const & src, Point2D<T> const & p, double const angle);

  //! Operator overload for RotatedRectangle<T> == RotatedRectangle<T>
  /*! \relates RotatedRectangle */
  template <class T>
  bool operator==(RotatedRectangle<T> const & lhs, RotatedRectangle<T> const & rhs);

  //! Operator overload for RotatedRectangle<T> != RotatedRectangle<T>
  /*! \relates RotatedRectangle */
  template <class T>
  bool operator!=(RotatedRectangle<T> const & lhs, RotatedRectangle<T> const & rhs);

  //! Operator overload for RotatedRectangle<T> + Point2D<T>
  /*! \relates RotatedRectangle */
  template <class T>
  RotatedRectangle<T> operator+(RotatedRectangle<T> const & lhs, Point2D<T> const & rhs);

  //! Operator overload for Point2D<T> + RotatedRectangle<T>
  /*! \relates RotatedRectangle */
  template <class T>
  RotatedRectangle<T> operator+(Point2D<T> const & lhs, RotatedRectangle<T> const & rhs);

  //! Operator overload for RotatedRectangle<T> - Point2D<T>
  /*! \relates RotatedRectangle */
  template <class T>
  RotatedRectangle<T> operator-(RotatedRectangle<T> const & lhs, nrt::Point2D<T> const & rhs);

  //! Operator overload for Point2D<T> - RotatedRectangle<T>
  /*! \relates RotatedRectangle */
  template <class T>
  RotatedRectangle<T> operator-(Point2D<T> const & lhs, RotatedRectangle<T> const & rhs);

  //! Operator overload for RotatedRectangle<T> * double
  /*! \relates RotatedRectangle */
  template <class T>
  RotatedRectangle<T> operator*(RotatedRectangle<T> const & lhs, double const rhs);

  //! Operator overload for double * RotatedRectangle<T>
  /*! \relates RotatedRectangle */
  template <class T>
  RotatedRectangle<T> operator*(double const lhs, RotatedRectangle<T> const & rhs);

  //! Operator overload for RotatedRectangle<T> / double
  /*! \relates RotatedRectangle */
  template <class T>
  RotatedRectangle<T> operator/(RotatedRectangle<T> const & lhs, double const rhs);

  //! Operator overload for RotatedRectangle<T> *= double
  /*! \relates RotatedRectangle */
  template <class T>
  RotatedRectangle<T> & operator*=(RotatedRectangle<T> & lhs, double const rhs);

  //! Operator overload for RotatedRectangle<T> /= double
  /*! \relates RotatedRectangle */
  template <class T>
  RotatedRectangle<T> & operator/=(RotatedRectangle<T> & lhs, double const rhs);

  //! Operator overload for RotatedRectangle<T> += Point2D<T>
  /*! \relates RotatedRectangle */
  template <class T>
  RotatedRectangle<T> & operator+=(RotatedRectangle<T> & lhs, Point2D<T> const & rhs);

  //! Operator overload for RotatedRectangle<T> -= Point2D<T>
  /*! \relates RotatedRectangle */
  template <class T>
  RotatedRectangle<T> & operator-=(RotatedRectangle<T> & lhs, Point2D<T> const & rhs);

}

#include <nrt/Core/Geometry/details/RotatedRectangleImpl.H>

#endif // INCLUDE_NRT_CORE_GEOMETRY_ROTATEDRECTANGLE_H