dlib C++ Library - polygon_abstract.h

// Copyright (C) 2022 Davis E. King (davis@dlib.net), Adrià Arrufat
// License: Boost Software License See LICENSE.txt for the full license.
#undef DLIB_POLYGOn_ABSTRACT_H_
#ifdef DLIB_POLYGOn_ABSTRACT_H_
#include "rectangle.h"
#include "vector.h"
namespace dlib
{
 class polygon
 {
 /*!
 WHAT THIS OBJECT REPRESENTS
 This object represents a polygon inside a Cartesian coordinate system.
 It is just a wrapper class for a std::vector<point> with some added
 methods.
 Note that the origin of the coordinate system, i.e. (0,0), is located
 at the upper left corner. That is, points such as (1,1) or (3,5)
 represent locations that are below and to the right of the origin.
 Moreover, the polygon is the area enclosed by the lines defined by all
 pairwise lines between adjacent points in this object. That is, if
 you drew lines between all pairs of points polygon[i] and polygon[(i+1)%polygon.size()]
 for all valid i, then the area enclosed by those lines is the polygon in 
 question.
 !*/
 public:
 using size_type = std::vector<point>::size_type;
 polygon(std::vector<point> points);
 /*!
 ensures
 - #*this represents a polygon defined by points.
 !*/
 size_type size() const;
 /*!
 ensures
 - returns the number of points in the polygon.
 !*/
 point& operator[](const size_type idx);
 /*!
 requires
 - idx < size()
 ensures
 - returns the point of the polygon at index idx.
 !*/
 const point& operator[](const size_type idx) const;
 /*!
 requires
 - idx < size()
 ensures
 - returns the point of the polygon at index idx.
 !*/
 const point& at(const size_type idx) const;
 /*!
 ensures
 - returns the point of the polygon at index idx.
 throws
 - std::out_of_range if idx >= size()
 !*/
 rectangle get_rect() const;
 /*!
 ensures
 - returns smallest rectangle that contains all points in the polygon.
 !*/
 double area() const;
 /*!
 ensures
 - If you walk the points of #*this in order to make a closed polygon, what is its
 area? This function returns that area. It uses the shoelace formula to
 compute the result and so works for general non-self-intersecting polygons.
 !*/
 template <typename alloc>
 void get_left_and_right_bounds (
 const long top,
 const long bottom,
 std::vector<double, alloc>& left_boundary,
 std::vector<double, alloc>& right_boundary
 ) const;
 /*! 
 requires 
 - 0 <= top <= bottom 
 ensures 
 - Finds the left and right edges of the polygon for all y coordinate values in the
 range [top, bottom].
 - #left_boundary.size() == bottom-top+1 
 - #right_boundary.size() == bottom-top+1 
 - for all top <= y <= bottom: 
 - #left_boundary[y-top] == the x coordinate for the left most side of 
 the polygon at coordinate y. 
 - #right_boundary[y-top] == the x coordinate for the right most side of
 the polygon at coordinate y. 
 !*/
 private:
 std::vector<point> points;
 };
}
#endif // DLIB_POLYGOn_ABSTRACT_H_