it.unibo.alchemist.model.geometry.ConvexPolygon.kt Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of alchemist-euclidean-geometry Show documentation
Alchemist geometric components for Euclidean spaces
There is a newer version: 35.0.3
Show newest version
/*
 * Copyright (C) 2010-2023, Danilo Pianini and contributors
 * listed, for each module, in the respective subproject's build.gradle.kts file.
 *
 * This file is part of Alchemist, and is distributed under the terms of the
 * GNU General Public License, with a linking exception,
 * as described in the file LICENSE in the Alchemist distribution's top directory.
 */

package it.unibo.alchemist.model.geometry

import it.unibo.alchemist.model.positions.Euclidean2DPosition
import java.awt.Shape

/**
 * A simple polygon (i.e. not self-intersecting and without holes) in which no
 * line segment between two points on the boundary ever goes outside the polygon.
 */
interface ConvexPolygon : Euclidean2DConvexShape, AwtShapeCompatible {

    /**
     * @returns the vertices of the polygon, sorted so that the polygon could
     * be obtained by connecting consecutive points in the list with a segment
     */
    fun vertices(): List

    /**
     * @returns the edges (= sides) of the polygon
     */
    fun edges(): List>

    /**
     * Depending on the implementation, this may be faster than [edges].get([index]).
     * @param index indicates which edge to get: edge i connects vertices i and i+1
     * (with respect to the ordering of vertices used in [vertices])
     * @returns the specified edge (= side) of the polygon
     */
    fun getEdge(index: Int): Segment2D

    /**
     * Checks if the polygon contains a vector (= a point). The definition of insideness
     * may vary depending on the implementation, this may affect the outcome for points
     * lying on the polygon's boundary. For accurate operations see [containsBoundaryIncluded]
     * and [containsBoundaryExcluded].
     * @param vector the vector (= point)
     * @returns true if the polygon contains the vector
     */
    override fun contains(vector: Euclidean2DPosition): Boolean

    /**
     * Checks if a vector (= a point) lies on the polygon's boundary.
     * @param vector the vector (= point)
     * @returns true if the vector lies on the polygon's boundary
     */
    fun liesOnBoundary(vector: Euclidean2DPosition): Boolean

    /**
     * Checks if a vector (= a point) is contained in the polygon or lies on its boundary.
     * @param vector the vector (= point)
     * @returns true if the vector is contained in the polygon or lies on its boundary
     */
    fun containsBoundaryIncluded(vector: Euclidean2DPosition): Boolean

    /**
     * Checks if a vector (= a point) is contained in the polygon, boundary excluded.
     * @param vector the vector (= point)
     * @returns true if the vector is contained in the interior of the polygon
     */
    fun containsBoundaryExcluded(vector: Euclidean2DPosition): Boolean

    /**
     * Checks if the polygon contains a polygonal [java.awt.Shape] (i.e. without curved
     * segments). A polygonal shape is contained in a polygon if all of its points are
     * contained in (or lie on the boundary of) the latter.
     * @param shape the polygonal shape
     * @returns true if the polygon contains the shape.
     */
    fun contains(shape: Shape): Boolean

    /**
     * Checks if a [java.awt.Shape] intersects the polygon, adjacent shapes are not
     * considered to be intersecting.
     * @param shape the shape
     * @returns true if the shape intersects with the polygon
     */
    fun intersects(shape: Shape): Boolean

    /**
     * A polygon is adjacent to another if any of its points lies on the boundary of the other.
     * @param other the other polygon
     * @returns true if the polygons are adjacent
     */
    fun isAdjacentTo(other: ConvexPolygon): Boolean

    /**
     * Checks if a segment intersects with the polygon, segments lying on the polygon's
     * boundary are not considered to be intersecting.
     * @param segment the segment
     * @returns true if the segment intersects the polygon
     */
    fun intersects(segment: Segment2D): Boolean

    /**
     * Finds the edge of the polygon closest to the provided [segment], i.e. the first one
     * that would collide (= intersect) with the segment in case the polygon extended on
     * each side.
     * @param segment the segment
     * @returns the edge of the polygon closest to the provided segment
     */
    fun closestEdgeTo(segment: Segment2D): Segment2D
}