EasyGeometry::D2::Polygon

A two-dimensional polygon.

.new(*args)

Description

A simple polygon in space can be constructed from a sequence of points.

Polygons are treated as closed paths rather than 2D areas so some calculations can be be negative or positive (e.g., area) based on the orientation of the points.

Any consecutive identical points are reduced to a single point and any points collinear and between two points will be removed unless they are needed to define an explicit intersection (see specs).

Must be at least 3 points.

Signature

Parameters:
    args - sequence of 
                EasyGeometry::D2::Point 
                or Array of Numeric(coordinates)

Returns:
    EasyGeometry::D2::Polygon
    
Errors:
    raise TypeError if args is not sequence of Points or Arrays of coordinates
    raise ArgumentError if args.length < 3 

Example

EasyGeometry::D2::Polygon.new([0, 0], [1, 0], [5, 1], [0, 1])

.is_right?(a, b, c)

Description

Return True/False for cw/ccw orientation.

Signature

Parameters:
    a, b, c - EasyGeometry::D2::Point or Array of Numeric(coordinates)

Returns:
    boolean (true or false)
    
Errors:
    raise TypeError if a or b or c is not a Point

Example

EasyGeometry::D2::Polygon.is_right?([0, 0], [1, 1], [1, 0]) # true

#==(other)

Description

Returns True if self and otherare the same mathematical entities.

Signature

Parameters:
    other - GeometryEntity(Point, Line etc.)
    
Returns:
    boolean (true or false)
    
Errors:

Example

poly1 =  EasyGeometry::D2::Polygon.new([0, 0], [3, -1], [6, 0], [4, 5], [2, 3], [0, 3])
poly2 =  EasyGeometry::D2::Polygon.new([6, 0], [3, -1], [0, 0], [0, 3], [2, 3], [4, 5])

poly1 == poly1     # true
poly1 == poly2     # true

#area

Description

The area of the polygon.

The area calculation can be positive or negative based on the orientation of the points. If any side of the polygon crosses any other side, there will be areas having opposite signs.

Signature

Parameters:
    
Returns:
    Numeric
    
Errors:

Example

poly1 =  EasyGeometry::D2::Polygon.new([0, 0], [3, -1], [6, 0], [4, 5], [2, 3], [0, 3])

poly1.area     # 22

#perimeter

Description

The perimeter of the polygon.

Signature

Parameters:
    
Returns:
    Numeric
    
Errors:

Example

poly1 =  EasyGeometry::D2::Polygon.new([0, 0], [0, 1], [1, 1], [1, 0])

poly1.perimeter     # 4

#centroid

Description

The centroid of the polygon.

Signature

Parameters:
    
Returns:
    EasyGeometry::D2::Point
    
Errors:

Example

poly1 =  EasyGeometry::D2::Polygon.new([0, 0], [0, 1], [1, 1], [1, 0])

poly1.centroid     # Point(0.5, 0.5)

#sides

Description

The directed line segments that form the sides of the polygon.

Signature

Parameters:
    
Returns:
    Array of EasyGeometry::D2::Segment
    
Errors:

Example

poly1 =  EasyGeometry::D2::Polygon.new([0, 0], [0, 1], [1, 1], [1, 0])

poly1.sides # [Segment([0, 0], [0, 1]), Segment([0, 1], [1, 1]), Segment([1, 1], [1, 0]), Segment([1, 0], [0, 0])]

#bounds

Description

Return an array (xmin, ymin, xmax, ymax) representing the bounding rectangle for the geometric figure.

Signature

Parameters:
    
Returns:
    Array of Numeric
    
Errors:

Example

poly1 =  EasyGeometry::D2::Polygon.new([0, 0], [0, 1], [1, 1], [1, 0])

poly1.bounds # [0, 0, 1, 1]

#is_convex?

Description

Is the polygon convex?

A polygon is convex if all its interior angles are less than 180 degrees and there are no intersections between sides.

Signature

Parameters:
    
Returns:
    boolean (true or false)
    
Errors:

Example

poly1 =  EasyGeometry::D2::Polygon.new([0, 0], [5, 0], [0, 5])
poly2 =  EasyGeometry::D2::Polygon.new([0, 0], [3, -1], [6, 0], [4, 5], [2, 3], [0, 3])

poly1.is_convex? # true
poly2.is_convex? # false

#is_encloses_point?(point)

Description

Return True if p is enclosed by (is inside of) self, False otherwise.

Being on the border of self is considered False.

http://paulbourke.net/geometry/polygonmesh/#insidepoly

Signature

Parameters:
    point - EasyGeometry::D2::Point or Array of Numeric(coordinates)
  
Returns:
    boolean (true or false)
    
Errors:

Example

poly1 =  EasyGeometry::D2::Polygon.new([0, 0], [4, 4], [0, 4])

poly1.is_encloses_point?([2, 2]) # false
poly1.is_encloses_point?([1, 3]) # true

#intersection?(entity)

Description

The intersection of polygon and geometry entity.

The intersection may be empty and can contain individual Points and complete Line Segments.

Signature

Parameters:
    entity - GeometryEntity(Point, Line etc.)

Returns:
    Array of Points and Segments
    
Errors:

Example

polygon1 =  EasyGeometry::D2::Polygon.new([0, 0], [1, 0], [0, 1])
polygon2 =  EasyGeometry::D2::Polygon.new([0, 1], [-5, 0], [0, -4], [0, 1/5r], [1/2r, -0.1], [1, 0], [0, 1])

polygon1.intersection(EasyGeometry::D2::Point.new(0, 0)) # [Point.new(0, 0)]
polygon1.intersection(polygon2) # [Point(1/3r, 0), Segment([0, 1/5r], [0, 0]), Segment([1, 0], [0, 1])]

#distance(other)

Description

Returns the shortest distance between self and other.

If other is a point, then self does not need to be convex.

If other is another polygon self and other must be convex.

Signature

Parameters:
    other - EasyGeometry::D2::Point 
            or Array of Numeric(coordinates)
            or EasyGeometry::D2::Polygon

Returns:
    Numeric
    
Errors:
    raise TypeError if point is not Point or valid Array or convex EasyGeometry::D2::Polygon

Example

poly1 = EasyGeometry::D2::Polygon.new([0, 0], [1, 0], [1, 1], [0, 1])
poly2 = EasyGeometry::D2::Polygon.new([0, 5/4r], [1, 5/4r], [1, 9/4r], [0, 9/4r])

poly1.distance([1/2r, 1/2r])   # 0.5
poly1.distance(poly2)          # 0.25