Visual Servoing Platform  version 3.5.1 under development (2022-05-22)
vpPolygon Class Reference

#include <visp3/core/vpPolygon.h>

Public Types

enum  PointInPolygonMethod { PnPolySegmentIntersection, PnPolyRayCasting }
 

Public Member Functions

 vpPolygon ()
 
 vpPolygon (const std::vector< vpImagePoint > &corners)
 
 vpPolygon (const std::list< vpImagePoint > &corners)
 
 vpPolygon (const vpPolygon &poly)
 
virtual ~vpPolygon ()
 
vpPolygonoperator= (const vpPolygon &poly)
 
void buildFrom (const std::vector< vpImagePoint > &corners, const bool create_convex_hull=false)
 
void buildFrom (const std::list< vpImagePoint > &corners, const bool create_convex_hull=false)
 
void buildFrom (const std::vector< vpPoint > &corners, const vpCameraParameters &cam, const bool create_convex_hull=false)
 
unsigned int getSize () const
 
void initClick (const vpImage< unsigned char > &I, unsigned int size=5, const vpColor &color=vpColor::red, unsigned int thickness=1)
 
void initClick (const vpImage< vpRGBa > &I, unsigned int size=5, const vpColor &color=vpColor::red, unsigned int thickness=1)
 
bool isInside (const vpImagePoint &iP, const PointInPolygonMethod &method=PnPolyRayCasting) const
 
void display (const vpImage< unsigned char > &I, const vpColor &color, unsigned int thickness=1) const
 
const std::vector< vpImagePoint > & getCorners () const
 
double getArea () const
 
vpImagePoint getCenter () const
 
vpRect getBoundingBox () const
 

Static Public Member Functions

static bool isInside (const std::vector< vpImagePoint > &roi, const double &i, const double &j, const PointInPolygonMethod &method=PnPolyRayCasting)
 

Protected Member Functions

void init (const std::vector< vpImagePoint > &corners)
 
void init (const std::list< vpImagePoint > &corners)
 
void updateArea ()
 
void updateCenter ()
 
void updateBoundingBox ()
 

Protected Attributes

std::vector< vpImagePoint_corners
 
vpImagePoint _center
 
double _area
 
bool _goodPoly
 
vpRect _bbox
 

Detailed Description

Defines a generic 2D polygon.

A polygon is internally represented by N 2D points.

By default three coordinates in the $ (i,j) $ frame (see vpImagePoint class documentation for more details about the frame) are used $ (0,0) $, $ (1,0) $ and $ (0,1) $.

The code bellow shows how to manipulate a polygon.

#include <iostream>
#include <visp3/core/vpPolygon.h>
int main()
{
std::vector<vpImagePoint> corners;
// Initialize the corners vector with 4 points
corners.push_back( vpImagePoint( 50, 100) );
corners.push_back( vpImagePoint( 50, 300) );
corners.push_back( vpImagePoint(200, 300) );
corners.push_back( vpImagePoint(200, 100) );
// Initialize a polygon with the corners
vpPolygon polygon(corners);
// Get the polygon bounding box
vpRect bbox = polygon.getBoundingBox();
std::cout << "Bounding box: " << bbox.getTopLeft() << " to "
<< bbox.getBottomRight() << std::endl;
// Get the polygon surface and center
std::cout << "Area: " << polygon.getArea() << std::endl;
std::cout << "Center: " << polygon.getCenter() << std::endl;
// Check if a point is inside the polygon
vpImagePoint ip(550, 200);
std::cout << "The point " << ip << " is "
<< (polygon.isInside(ip) ? "inside":"outside")
<< " the polygon" << std::endl;
return 0;
}
Examples:
mbot-apriltag-2D-half-vs.cpp, testDisplayPolygonLines.cpp, testPolygon2.cpp, tutorial-flood-fill.cpp, and tutorial-pose-from-planar-object.cpp.

Definition at line 105 of file vpPolygon.h.

Member Enumeration Documentation

◆ PointInPolygonMethod

Enumerator
PnPolySegmentIntersection 

Legacy Point In Polygon test.

PnPolyRayCasting 

Point In Polygon test using ray casting method (faster).

Definition at line 122 of file vpPolygon.h.

Constructor & Destructor Documentation

◆ vpPolygon() [1/4]

vpPolygon::vpPolygon ( )

Default constructor that creates an empty polygon.

Definition at line 117 of file vpPolygon.cpp.

◆ vpPolygon() [2/4]

vpPolygon::vpPolygon ( const std::vector< vpImagePoint > &  corners)
explicit

Constructor which initialises the polygon thanks to the given corners.

Warning
the corners must be ordered (either clockwise or counter clockwise).
Parameters
corners: The Points defining the corners.

Definition at line 130 of file vpPolygon.cpp.

References _goodPoly, and init().

◆ vpPolygon() [3/4]

vpPolygon::vpPolygon ( const std::list< vpImagePoint > &  corners)
explicit

Constructor which initialises the polygon thanks to the given corners.

Warning
the corners must be ordered (either clockwise or counter clockwise).
Parameters
corners: The Points defining the corners.

Definition at line 147 of file vpPolygon.cpp.

References _goodPoly, and init().

◆ vpPolygon() [4/4]

vpPolygon::vpPolygon ( const vpPolygon poly)

Copy constructor

Parameters
poly: The polygon used for the initialisation.

Definition at line 161 of file vpPolygon.cpp.

◆ ~vpPolygon()

vpPolygon::~vpPolygon ( )
virtual

Basic destructor

Definition at line 170 of file vpPolygon.cpp.

Member Function Documentation

◆ buildFrom() [1/3]

void vpPolygon::buildFrom ( const std::vector< vpImagePoint > &  corners,
const bool  create_convex_hull = false 
)

Initialises the triangle thanks to the collection of 2D points (in pixel).

Warning
the corners must be ordered (either clockwise or counter clockwise).
Parameters
corners: The corners of the polyon.
create_convex_hullCreate a convex hull from the given corners.
Examples:
testPolygon2.cpp, and tutorial-pose-from-planar-object.cpp.

Definition at line 198 of file vpPolygon.cpp.

References init(), and vpException::notImplementedError.

Referenced by buildFrom(), initClick(), Model::keypoints(), vpMbtDistanceKltCylinder::updateMask(), and vpMbtDistanceKltPoints::updateMask().

◆ buildFrom() [2/3]

void vpPolygon::buildFrom ( const std::list< vpImagePoint > &  corners,
const bool  create_convex_hull = false 
)

Initialises the polygon thanks to the collection of 2D points (in pixel).

Warning
the corners must be ordered (either clockwise or counter clockwise).
Parameters
corners: The corners of the polyon.
create_convex_hullCreate a convex hull from the given corners.

Definition at line 220 of file vpPolygon.cpp.

References init(), and vpException::notImplementedError.

◆ buildFrom() [3/3]

void vpPolygon::buildFrom ( const std::vector< vpPoint > &  corners,
const vpCameraParameters cam,
const bool  create_convex_hull = false 
)

Initialises the triangle thanks to the collection of 2D points (in meter). The fields x and y are used to compute the corresponding coordinates in pixel thanks to the camera parameters cam.

Warning
the corners must be ordered (either clockwise or counter clockwise).
Parameters
corners: The corners of the polyon.
cam: The camera parameters used to convert the coordinates from meter to pixel.
create_convex_hullCreate a convex hull from the given corners.

Definition at line 246 of file vpPolygon.cpp.

References buildFrom(), and vpMeterPixelConversion::convertPoint().

◆ display()

void vpPolygon::display ( const vpImage< unsigned char > &  I,
const vpColor color,
unsigned int  thickness = 1 
) const

Display the polygon in the image (overlay, so the image is not modified). A call to the flush() method is necessary.

Parameters
I: The image where the polygon is displayed.
color: The color of the polygon's lines.
thickness: The thickness of the polygon's lines.

Definition at line 607 of file vpPolygon.cpp.

References _corners, and vpDisplay::displayLine().

◆ getArea()

double vpPolygon::getArea ( ) const
inline

Return the area of the polygon. The area is computed when the polygon is built from the corners.

Returns
The area of the polygon.

Definition at line 164 of file vpPolygon.h.

Referenced by vpPose::computePlanarObjectPoseFromRGBD(), vpMbtPolygon::isVisible(), vpMbtDistanceKltCylinder::updateMask(), and vpMbtDistanceKltPoints::updateMask().

◆ getBoundingBox()

vpRect vpPolygon::getBoundingBox ( ) const
inline

Return the bounding box. The bounding box is the smallest rectangle containing all the polygon.

Returns
The bounding box of the polygon.

Definition at line 180 of file vpPolygon.h.

Referenced by vpMbtFaceDepthDense::computeDesiredFeatures(), vpMbtFaceDepthNormal::computeDesiredFeatures(), vpPose::computePlanarObjectPoseFromRGBD(), vpPlaneEstimation::estimatePlane(), and vpKeyPoint::matchPointAndDetect().

◆ getCenter()

vpImagePoint vpPolygon::getCenter ( ) const
inline

Return the center of the polygon. The center is computed when the polygon is built from the corners.

Returns
The area of the polygon.

Definition at line 172 of file vpPolygon.h.

◆ getCorners()

const std::vector<vpImagePoint>& vpPolygon::getCorners ( ) const
inline

Get the corners of the polygon.

Returns
A reference to the corners.
Examples:
testDisplayPolygonLines.cpp, testPolygon2.cpp, and tutorial-flood-fill.cpp.

Definition at line 156 of file vpPolygon.h.

Referenced by vpPlaneEstimation::estimatePlane().

◆ getSize()

unsigned int vpPolygon::getSize ( ) const

Return number of corners belonging to the polygon.

Definition at line 636 of file vpPolygon.cpp.

References _corners.

◆ init() [1/2]

void vpPolygon::init ( const std::vector< vpImagePoint > &  corners)
protected

Intialises the polygon using the collection of image points. This method computes some internal variables such as center, area, ...

Warning
the corners must be ordered (either clockwise or counter clockwise).
Parameters
corners: The corners of the polygon.

Definition at line 323 of file vpPolygon.cpp.

References _corners, updateArea(), updateBoundingBox(), and updateCenter().

Referenced by buildFrom(), and vpPolygon().

◆ init() [2/2]

void vpPolygon::init ( const std::list< vpImagePoint > &  corners)
protected

Intialises the polygon using the collection of image points. This method computes some internal variables such as center, area, ...

Warning
the corners must be ordered (either clockwise or counter clockwise).
Parameters
corners: The corners of the polygon.

Definition at line 343 of file vpPolygon.cpp.

References _corners, vpException::divideByZeroError, vpImagePoint::get_i(), vpImagePoint::get_j(), updateArea(), updateBoundingBox(), and updateCenter().

◆ initClick() [1/2]

void vpPolygon::initClick ( const vpImage< unsigned char > &  I,
unsigned int  size = 5,
const vpColor color = vpColor::red,
unsigned int  thickness = 1 
)

Initialises the polygon by (left-)clicking to add a corners to the polygon. A right click is used to stop the addition of new corners.

Parameters
I: The image where to click to initialise the corners.
size: Cross size in terms of number of pixels that is displayed over a polygon corner.
color: Color used to display the cross over the polygon corner.
thickness: Thickness used to display the cross.
Examples:
testDisplayPolygonLines.cpp, and tutorial-flood-fill.cpp.

Definition at line 265 of file vpPolygon.cpp.

References buildFrom(), vpMouseButton::button1, vpDisplay::displayCross(), vpDisplay::flush(), and vpDisplay::getClick().

◆ initClick() [2/2]

void vpPolygon::initClick ( const vpImage< vpRGBa > &  I,
unsigned int  size = 5,
const vpColor color = vpColor::red,
unsigned int  thickness = 1 
)

Initialises the polygon by (left-)clicking to add a corners to the polygon. A right click is used to stop the addition of new corners.

Parameters
I: The image where to click to initialise the corners.
size: Size of the cross in terms of number of pixels that is displayed over a polygon corner.
color: Color used to display the cross over the polygon corner.
thickness: Thickness used to display the cross.

Definition at line 295 of file vpPolygon.cpp.

References buildFrom(), vpMouseButton::button1, vpDisplay::displayCross(), vpDisplay::flush(), and vpDisplay::getClick().

◆ isInside() [1/2]

◆ isInside() [2/2]

bool vpPolygon::isInside ( const std::vector< vpImagePoint > &  roi,
const double &  i,
const double &  j,
const PointInPolygonMethod method = PnPolyRayCasting 
)
static

Test if an image point is inside a 2D polygon.

Parameters
roi: List of the polygon corners.
i: i-coordinate of the image point to test.
j: j-coordinate of the image point to test.
method: Method to use for Point In Polygon test.
Returns
True if the point defined by (i,j) is inside the polygon, False otherwise.

Definition at line 626 of file vpPolygon.cpp.

References isInside().

◆ operator=()

vpPolygon & vpPolygon::operator= ( const vpPolygon poly)

Equal operator.

Assign poly to this polygon and return a reference to it.

Definition at line 177 of file vpPolygon.cpp.

References _area, _bbox, _center, _corners, and _goodPoly.

◆ updateArea()

void vpPolygon::updateArea ( )
protected

Update the _area attribute of the polygon using the corners.

The area is computed using the formula:

\[ A = \frac{1}{2} \sum_{i=0}^{n-1} (x_1 y_{i+1} - x_{i+1} y_{i}) \]

Definition at line 497 of file vpPolygon.cpp.

References _area, _corners, and _goodPoly.

Referenced by init().

◆ updateBoundingBox()

void vpPolygon::updateBoundingBox ( )
protected

Update bounding box of the polygon.

See also
getBoundingBox()

Definition at line 570 of file vpPolygon.cpp.

References _bbox, _corners, _goodPoly, vpRect::setBottomRight(), and vpRect::setTopLeft().

Referenced by init().

◆ updateCenter()

void vpPolygon::updateCenter ( )
protected

Update the _center attribute of the polygon using the corners.

The i coordinate is computed using:

\[ i = \frac{1}{6{area}} \sum_{i=0}^{n-1} (i_i + i_{i+1})(i_{i+1} j_i - j_{i+1} i_i) \]

The computation of the j coordinate is similar.

Definition at line 528 of file vpPolygon.cpp.

References _area, _center, _corners, _goodPoly, vpImagePoint::set_i(), and vpImagePoint::set_j().

Referenced by init().

Member Data Documentation

◆ _area

double vpPolygon::_area
protected

Area of the polygon.

Definition at line 114 of file vpPolygon.h.

Referenced by operator=(), updateArea(), and updateCenter().

◆ _bbox

vpRect vpPolygon::_bbox
protected

Bounding box containing the polygon.

Definition at line 119 of file vpPolygon.h.

Referenced by operator=(), and updateBoundingBox().

◆ _center

vpImagePoint vpPolygon::_center
protected

Center of the polygon. It is automatically computed when the corners are set.

Definition at line 112 of file vpPolygon.h.

Referenced by operator=(), and updateCenter().

◆ _corners

std::vector<vpImagePoint> vpPolygon::_corners
protected

Collection of image points containing the corners.

Definition at line 109 of file vpPolygon.h.

Referenced by display(), getSize(), init(), isInside(), operator=(), updateArea(), updateBoundingBox(), and updateCenter().

◆ _goodPoly

bool vpPolygon::_goodPoly
protected

Flag set to true when the polygon is a good polygon (ie. it has more than two corners) or false otherwise.

Definition at line 117 of file vpPolygon.h.

Referenced by operator=(), updateArea(), updateBoundingBox(), updateCenter(), and vpPolygon().