Visual Servoing Platform  version 3.6.1 under development (2024-10-14)
vpPolygon Class Reference

#include <visp3/core/vpPolygon.h>

Public Types

enum  PointInPolygonMethod { PnPolySegmentIntersection , PnPolyRayCasting }
 

Public Member Functions

 vpPolygon ()
 
VP_EXPLICIT vpPolygon (const std::vector< vpImagePoint > &corners)
 
VP_EXPLICIT vpPolygon (const std::list< vpImagePoint > &corners)
 
 vpPolygon (const vpPolygon &poly)
 
virtual ~vpPolygon ()
 
vpPolygonoperator= (const vpPolygon &poly)
 
vpPolygonbuildFrom (const std::vector< vpImagePoint > &corners, const bool &create_convex_hull=false)
 
vpPolygonbuildFrom (const std::list< vpImagePoint > &corners, const bool &create_convex_hull=false)
 
vpPolygonbuildFrom (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>
#ifdef ENABLE_VISP_NAMESPACE
using namespace VISP_NAMESPACE_NAME;
#endif
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;
}
Class that defines a 2D point in an image. This class is useful for image processing and stores only ...
Definition: vpImagePoint.h:82
Defines a generic 2D polygon.
Definition: vpPolygon.h:103
Defines a rectangle in the plane.
Definition: vpRect.h:79
vpImagePoint getTopLeft() const
Definition: vpRect.h:199
vpImagePoint getBottomRight() const
Definition: vpRect.h:117
Examples
catchPolygon2.cpp, mbot-apriltag-2D-half-vs.cpp, testDisplayPolygonLines.cpp, testDisplays.cpp, testPolygon.cpp, tutorial-flood-fill.cpp, and tutorial-pose-from-planar-object.cpp.

Definition at line 102 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 105 of file vpPolygon.h.

Constructor & Destructor Documentation

◆ vpPolygon() [1/4]

BEGIN_VISP_NAMESPACE vpPolygon::vpPolygon ( )

Default constructor that creates an empty polygon.

Definition at line 114 of file vpPolygon.cpp.

◆ vpPolygon() [2/4]

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

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 126 of file vpPolygon.cpp.

References _goodPoly, and init().

◆ vpPolygon() [3/4]

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

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 143 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 157 of file vpPolygon.cpp.

◆ ~vpPolygon()

vpPolygon::~vpPolygon ( )
virtual

Basic destructor

Definition at line 165 of file vpPolygon.cpp.

Member Function Documentation

◆ buildFrom() [1/3]

vpPolygon & 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 polygon.
create_convex_hullCreate a convex hull from the given corners.

Definition at line 217 of file vpPolygon.cpp.

References init(), and vpException::notImplementedError.

◆ buildFrom() [2/3]

vpPolygon & 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 polygon.
create_convex_hullCreate a convex hull from the given corners.
Examples
catchPolygon2.cpp, testPolygon.cpp, and tutorial-pose-from-planar-object.cpp.

Definition at line 193 of file vpPolygon.cpp.

References init(), and vpException::notImplementedError.

Referenced by buildFrom(), and initClick().

◆ buildFrom() [3/3]

vpPolygon & 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 polygon.
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 244 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.
Examples
testPolygon.cpp.

Definition at line 610 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.
Examples
mbot-apriltag-2D-half-vs.cpp, and testPolygon.cpp.

Definition at line 148 of file vpPolygon.h.

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

◆ 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.
Examples
testPolygon.cpp.

Definition at line 164 of file vpPolygon.h.

Referenced by vpMbtFaceDepthDense::computeDesiredFeatures(), vpMbtFaceDepthNormal::computeDesiredFeatures(), vpPose::computePlanarObjectPoseFromRGBD(), 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.
Examples
testPolygon.cpp.

Definition at line 156 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, testPolygon.cpp, and tutorial-flood-fill.cpp.

Definition at line 140 of file vpPolygon.h.

◆ getSize()

unsigned int vpPolygon::getSize ( ) const

Return number of corners belonging to the polygon.

Definition at line 639 of file vpPolygon.cpp.

References _corners.

◆ init() [1/2]

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

Initialises 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 342 of file vpPolygon.cpp.

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

◆ init() [2/2]

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

Initialises 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 322 of file vpPolygon.cpp.

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

Referenced by buildFrom(), and vpPolygon().

◆ 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, testPolygon.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 294 of file vpPolygon.cpp.

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

◆ isInside() [1/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 629 of file vpPolygon.cpp.

References isInside().

◆ isInside() [2/2]

bool vpPolygon::isInside ( const vpImagePoint ip,
const PointInPolygonMethod method = PnPolyRayCasting 
) const

Check if the 2D point $ ip $ is inside the polygon.

Parameters
ip: The point which have to be tested.
method: Method to use for Point In Polygon test.
Returns
Returns true if the point is inside the polygon, false otherwise.
Examples
testPolygon.cpp.

Definition at line 400 of file vpPolygon.cpp.

References _corners, vpImagePoint::get_i(), vpImagePoint::get_j(), vpImagePoint::get_u(), vpImagePoint::get_v(), PnPolySegmentIntersection, vpImagePoint::set_i(), and vpImagePoint::set_j().

Referenced by vpKeyPoint::compute3DForPointsOnCylinders(), vpMbtFaceDepthDense::computeDesiredFeatures(), vpMbtFaceDepthNormal::computeDesiredFeatures(), vpPose::computePlanarObjectPoseFromRGBD(), and isInside().

◆ operator=()

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

Equal operator.

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

Definition at line 172 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 505 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 572 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 537 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 186 of file vpPolygon.h.

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

◆ _bbox

vpRect vpPolygon::_bbox
protected

Bounding box containing the polygon.

Definition at line 191 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 184 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 181 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 189 of file vpPolygon.h.

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