iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
nrt::Rectangle< T > Class Template Reference

#include <nrt/Core/Geometry/Rectangle.H>

template<class T>
class nrt::Rectangle< T >

A basic rectangle class.

  This is a shorthand class to represent a 2D rectangle, as defined by top, left, bottom and right coordinates.  The
goal of this object is not to have to check if left < right, etc...  for each function using a Rectangle. The object
checks for that at its creation, and is always internally coherent.  Image convention: top < bottom, left < right.

There is often some ambiguity about how to represent the left-right and top-bottom ranges involved in a
rectangle. Imagine a pixel grid like this:
    +---+---+---+---+
    |   |   |   |   |
    |   |   |   |   |
    +---+---+---+---+
    |   |   |   |   |
    |   |   |   |   |
    +---+---+---+---+
    |   |   |   |   |
    |   |   |   |   |
    +---+---+---+---+
    |   |   |   |   |
    |   |   |   |   |
    +---+---+---+---+
If we want a Rectangle that covers this whole 4x4 grid, how should we represent the coordinates? Clearly the upper
left corner is (0,0), but what about the bottom right corner? One answer would be that the lower right corner is
(4,4), in which we imagine the coordinate numbers falling between the cracks of the pixels:
    . 0...1...2...3...4
    0 +---+---+---+---+
    . |   |   |   |   |
    . |   |   |   |   |
    1 +---+---+---+---+
    . |   |   |   |   |
    . |   |   |   |   |
    2 +---+---+---+---+
    . |   |   |   |   |
    . |   |   |   |   |
    3 +---+---+---+---+
    . |   |   |   |   |
    . |   |   |   |   |
    4 +---+---+---+---+
Another answer is that the lower right corner should be labeled as (3,3), if we envision the coordinate numbers
labeling the pixel centers, and this approach is more natural if we want to draw a line just inside the border of
the rectangle as shown by the '*' here:
    . ..0...1...2...3..
    . +---+---+---+---+
    0 |***|***|***|***|
    . |***|***|***|***|
    . +---+---+---+---+
    1 |***|   |   |***|
    . |***|   |   |***|
    . +---+---+---+---+
    2 |***|   |   |***|
    . |***|   |   |***|
    . +---+---+---+---+
    3 |***|***|***|***|
    . |***|***|***|***|
    . +---+---+---+---+
In the Rectangle class we support both approaches; the (4,4) coords are called 'outer' coordinates and corresponding
functions have a 'O' suffix (bottomO(), rightO(), and tlbrO()), while the (3,3) coords are called 'inner'
coordinates and corresponding functions have an 'I' suffix (bottomI(), rightI(), and tlbrI()).

The internal representation of Rectangle is based on outer coordinates, but this has no effect on users of the class
who are free to user whichever of inner or outer coords are more convenient for their purposes.

Outer coordinates are more natural for uniformly scaling a rectangle up or down by a factor. For example, if we want
to scale the 4x4 rect up by a factor of 2 giving an 8x8 rect, then in outer coords we just do newright=right*2=4*2=8
and newbottom=bottom*2=4*2=8. But with inner coords we can't just multiply by 2: the inner bottom-right coords are
(3,3), and if we scale those by 2 we get (6,6) which represents a 7x7 rectangle rather than the correct 8x8
result.
Examples:
tests/test-Geometry.C, and tests/test-Image.C.

Definition at line 127 of file Rectangle.H.

Public Member Functions

 Rectangle ()
 Uninitialized constructor, topleft = (0,0) and bottom-right=(0,0)
 
 Rectangle (Point2D< T > const &topLeft, Dims< T > const &dims)
 Build a Rectangle from a top-left corner and some dims.
 
 Rectangle (Point2D< T > const &topLeft, Point2D< T > const &bottomRight)
 Build a Rectangle from the top left and bottom right corners.
 
 Rectangle (Rectangle< T > const &rect)=default
 Copy constructor.
 
 Rectangle (Rectangle< T > &&rect)=default
 Move constructor.
 
template<class U >
 Rectangle (Rectangle< U > const &rect)
 Conversion copy constructor, uses nrt::clamped_convert<T,U> internally.
 
Rectangle< T > & operator= (Rectangle< T > const &other)=default
 Assignment.
 
Rectangle< T > & operator= (Rectangle< T > &&other)=default
 Move assignment.
 
Dims< T > dims () const
 Get the Rectangle's dims. More...
 
width () const
 Get the Rectangle's width.
 
height () const
 Get the Rectangle's height.
 
area () const
 Get the Rectangle's area.
 
float aspectRatio () const
 Get the Rectangle's aspect ratio (width/height)
 
Point2D< T > center () const
 Get the Rectangle's center.
 
template<class PointClass = nrt::Point2D<typename nrt::promote<T, float>::type>>
void getGridOfPoints (T const margin, T const nx, T const ny, std::vector< PointClass > &points) const
 Get a grid of points uniformly distributed inside the rectangle. More...
 
template<class U >
bool contains (Point2D< U > const &p) const
 Is this the Point contained in the Rectangle? More...
 
template<class U >
bool contains (Rectangle< U > const &r) const
 check if this Rectangle contains another More...
 
template<class U >
bool inside (Dims< U > const &dims) const
 Check that rectangle entirely fits inside the specified Dims. More...
 
top () const
 Get (inner) top coordinate.
 
bottomI () const
 Get inner bottom coordinate (=top+height-1)
 
bottomO () const
 Get outer bottom coordinate (=top+height)
 
left () const
 Get (inner) left coordinate.
 
rightI () const
 Get inner right coordinate (=left+width-1)
 
rightO () const
 Get outer right coordinate (=left+width)
 
Point2D< T > topLeft () const
 Get (outer) top left corner point.
 
Point2D< T > topRight () const
 Get (outer) top right corner point.
 
Point2D< T > bottomLeft () const
 Get (outer) bottom left corner point.
 
Point2D< T > bottomRight () const
 Get (outer) bottom right corner point.
 
Point2D< T > topRightI () const
 Get (inner) top right corner point.
 
Point2D< T > bottomLeftI () const
 Get (inner) bottom left corner point.
 
Point2D< T > bottomRightI () const
 Get (inner) bottom right corner point.
 
void intersect (Rectangle< T > const &rect)
 Set this rectangle as the intersection of itself and another Rectangle.
 
Rectangle< T > intersected (Rectangle< T > const &rect) const
 Return the intersection of this Rectangle and another Rectangle. More...
 
void unite (Rectangle< T > const &rect)
 Set this rectangle as the union of itself and another Rectangle (note: "union" is a reserved word)
 
Rectangle< T > united (Rectangle< T > const &rect) const
 Return the union of this Rectangle and another Rectangle. More...
 
double overlapRatio (Rectangle< T > const &rect) const
 Compute the overlap as (the area of the intersection) / (the area of the union)
 
std::vector< Point2D< T > > vertices () const
 Return vector of vertices of this Rectangle (convention is clockwise from top-left)
 
Line< T > clip (Line< T > const &line) const
 Clip the line so that it is contained within the Rectangle. More...
 

Static Public Member Functions

static Rectangle< T > centerDims (Point2D< T > const &center, Dims< T > const &dims)
 Build a Rectangle from a center point and some dims.
 
static Rectangle< T > tlbrI (T tt, T ll, T bb, T rr)
 Build a Rectangle from 4 coordinates (top, left, inner-bottom, inner-right)
 
static Rectangle< T > tlbrO (T tt, T ll, T bb, T rr)
 Build a Rectangle from 4 coordinates (top, left, outer-bottom, outer-right)
 
static Rectangle< T > bounds (std::vector< Point2D< T > > const &points)
 Build a Rectangle which defines the smallest bounding box around the given group of points. More...
 

Protected Member Functions

template<class Archive >
void serialize (Archive &ar)
 

Friends

class cereal::access
 

Related Functions

(Note that these are not member functions.)

template<class T >
std::ostream & operator<< (std::ostream &out, Rectangle< T > const &r)
 Human-readable output to a stream: outputs [TopLeft: xxx, Dims: xxx]. More...
 
template<class T >
Rectangle< T > scale (Rectangle< T > const &src, double const factor)
 Return a scaled version of the source object. More...
 
template<class T >
bool operator== (Rectangle< T > const &lhs, Rectangle< T > const &rhs)
 Return a rotated version of the source object, about its center by a given angle in radians. More...
 
template<class T >
bool operator!= (Rectangle< T > const &lhs, Rectangle< T > const &rhs)
 Operator overload for Rectangle<T> != Rectangle<T> More...
 
template<class T >
Rectangle< T > operator+ (Rectangle< T > const &lhs, Point2D< T > const &rhs)
 Operator overload for Rectangle<T> + Point2D<T> More...
 
template<class T >
Rectangle< T > operator+ (Point2D< T > const &lhs, Rectangle< T > const &rhs)
 Operator overload for Point2D<T> + Rectangle<T> More...
 
template<class T >
Rectangle< T > operator- (Rectangle< T > const &lhs, nrt::Point2D< T > const &rhs)
 Operator overload for Rectangle<T> - Point2D<T> More...
 
template<class T >
Rectangle< T > operator- (Point2D< T > const &lhs, Rectangle< T > const &rhs)
 Operator overload for Point2D<T> - Rectangle<T> More...
 
template<class T >
Rectangle< T > operator* (Rectangle< T > const &lhs, double const rhs)
 Operator overload for Rectangle<T> * double. More...
 
template<class T >
Rectangle< T > operator* (double const lhs, Rectangle< T > const &rhs)
 Operator overload for double * Rectangle<T> More...
 
template<class T >
Rectangle< T > operator/ (Rectangle< T > const &lhs, double const rhs)
 Operator overload for Rectangle<T> / double. More...
 
template<class T >
Rectangle< T > & operator*= (Rectangle< T > &lhs, double const rhs)
 Operator overload for Rectangle<T> *= double. More...
 
template<class T >
Rectangle< T > & operator/= (Rectangle< T > &lhs, double const rhs)
 Operator overload for Rectangle<T> /= double. More...
 
template<class T >
Rectangle< T > & operator+= (Rectangle< T > &lhs, Point2D< T > const &rhs)
 Operator overload for Rectangle<T> += Point2D<T> More...
 
template<class T >
Rectangle< T > & operator-= (Rectangle< T > &lhs, Point2D< T > const &rhs)
 Operator overload for Rectangle<T> -= Point2D<T> More...
 

Member Function Documentation

template<class T >
nrt::Rectangle< T > nrt::Rectangle< T >::bounds ( std::vector< Point2D< T > > const &  points)
inlinestatic

Build a Rectangle which defines the smallest bounding box around the given group of points.

Note
The returned Rectangle contains the extremal points on its borders (see dims() for more)

Definition at line 92 of file RectangleImpl.H.

References nrt::Rectangle< T >::tlbrO().

Referenced by nrt::Polygon< T >::boundingRect().

template<class T >
nrt::Dims< T > nrt::Rectangle< T >::dims ( ) const
inline

Get the Rectangle's dims.

The dimensions returned by this method are such that the bottomRight corner lies on the border. This means that if you want to allocate e.g. an Image to contain this Rectangle, the Image's dimensions should be 1 larger than the Rectangle.

Definition at line 124 of file RectangleImpl.H.

template<class T >
template<class PointClass >
void nrt::Rectangle< T >::getGridOfPoints ( T const  margin,
T const  nx,
T const  ny,
std::vector< PointClass > &  points 
) const
inline

Get a grid of points uniformly distributed inside the rectangle.

PointClass must have a constructor that takes two arguments of type nrt::promote<T, float>::type for x and y. For example, nrt::Point2D<typename nrt::promote<T, float>::type>

Definition at line 180 of file RectangleImpl.H.

template<class T >
template<class U >
bool nrt::Rectangle< T >::contains ( nrt::Point2D< U > const &  p) const
inline

Is this the Point contained in the Rectangle?

Note
Boundaries are included in this check

Definition at line 166 of file RectangleImpl.H.

References nrt::Point2D< T >::x(), and nrt::Point2D< T >::y().

template<class T >
template<class U >
bool nrt::Rectangle< T >::contains ( nrt::Rectangle< U > const &  r) const
inline

check if this Rectangle contains another

Note
The boundaries are allowed to coincide, such that by this definition a rectangle "contains" itself.

Definition at line 201 of file RectangleImpl.H.

References nrt::Rectangle< T >::bottomO(), nrt::Rectangle< T >::left(), nrt::Rectangle< T >::rightO(), and nrt::Rectangle< T >::top().

template<class T >
template<class U >
bool nrt::Rectangle< T >::inside ( Dims< U > const &  dims) const
inline

Check that rectangle entirely fits inside the specified Dims.

This is the same as checking that the intersection of our rectangls with a rectangle of top-left at (0,0) and the given dims is our rectangle itself. Useful to check whether a Rectangle is fully inside an Image.

Definition at line 173 of file RectangleImpl.H.

References nrt::Dims< T >::height(), and nrt::Dims< T >::width().

template<class T >
nrt::Rectangle< T > nrt::Rectangle< T >::intersected ( nrt::Rectangle< T > const &  rect) const
inline

Return the intersection of this Rectangle and another Rectangle.

See Also
intersect()

Definition at line 287 of file RectangleImpl.H.

References nrt::Rectangle< T >::intersect().

template<class T >
nrt::Rectangle< T > nrt::Rectangle< T >::united ( nrt::Rectangle< T > const &  rect) const
inline

Return the union of this Rectangle and another Rectangle.

See Also
unite()

Definition at line 306 of file RectangleImpl.H.

References nrt::Rectangle< T >::unite().

template<class T >
nrt::Line< T > nrt::Rectangle< T >::clip ( nrt::Line< T > const &  line) const

Clip the line so that it is contained within the Rectangle.

Todo:
Implement one of the many very fast line-rectangle clipping algorithms around

Definition at line 338 of file RectangleImpl.H.

References nrt::Line< T >::p1(), and nrt::Line< T >::p2().

Friends And Related Function Documentation

template<class T >
std::ostream & operator<< ( std::ostream &  out,
Rectangle< T > const &  r 
)
related

Human-readable output to a stream: outputs [TopLeft: xxx, Dims: xxx].

template<class T >
Rectangle< T > scale ( Rectangle< T > const &  src,
double const  factor 
)
related

Return a scaled version of the source object.

Note
This does 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.
template<class T >
bool operator== ( Rectangle< T > const &  lhs,
Rectangle< T > const &  rhs 
)
related

Return a rotated version of the source object, about its center by a given angle in radians.

Return a rotated version of the source object, about the given point and by a given angle in radians Operator overload for Rectangle<T> == Rectangle<T>

template<class T >
bool operator!= ( Rectangle< T > const &  lhs,
Rectangle< T > const &  rhs 
)
related

Operator overload for Rectangle<T> != Rectangle<T>

template<class T >
Rectangle< T > operator+ ( Rectangle< T > const &  lhs,
Point2D< T > const &  rhs 
)
related

Operator overload for Rectangle<T> + Point2D<T>

template<class T >
Rectangle< T > operator+ ( Point2D< T > const &  lhs,
Rectangle< T > const &  rhs 
)
related

Operator overload for Point2D<T> + Rectangle<T>

template<class T >
Rectangle< T > operator- ( Rectangle< T > const &  lhs,
nrt::Point2D< T > const &  rhs 
)
related

Operator overload for Rectangle<T> - Point2D<T>

template<class T >
Rectangle< T > operator- ( Point2D< T > const &  lhs,
Rectangle< T > const &  rhs 
)
related

Operator overload for Point2D<T> - Rectangle<T>

template<class T >
Rectangle< T > operator* ( Rectangle< T > const &  lhs,
double const  rhs 
)
related

Operator overload for Rectangle<T> * double.

template<class T >
Rectangle< T > operator* ( double const  lhs,
Rectangle< T > const &  rhs 
)
related

Operator overload for double * Rectangle<T>

template<class T >
Rectangle< T > operator/ ( Rectangle< T > const &  lhs,
double const  rhs 
)
related

Operator overload for Rectangle<T> / double.

template<class T >
Rectangle< T > & operator*= ( Rectangle< T > &  lhs,
double const  rhs 
)
related

Operator overload for Rectangle<T> *= double.

template<class T >
Rectangle< T > & operator/= ( Rectangle< T > &  lhs,
double const  rhs 
)
related

Operator overload for Rectangle<T> /= double.

template<class T >
Rectangle< T > & operator+= ( Rectangle< T > &  lhs,
Point2D< T > const &  rhs 
)
related

Operator overload for Rectangle<T> += Point2D<T>

template<class T >
Rectangle< T > & operator-= ( Rectangle< T > &  lhs,
Point2D< T > const &  rhs 
)
related

Operator overload for Rectangle<T> -= Point2D<T>


The documentation for this class was generated from the following files: