plotboilerplate 1.23.2 → 1.24.0

package/src/esm/Polygon.d.ts

@@ -28,16 +28,26 @@
  * @modified 2023-09-25 Added the `Polygon.lineIntersections(Line,boolean)` function.
  * @modified 2023-09-29 Added the `Polygon.closestLineIntersection(Line,boolean)` function.
  * @modified 2023-11-24 Added the `Polygon.containsPolygon(Polygon)' function.
- * @version 1.12.0
+ * @modified 2024-10-12 Added the `getEdgeAt` method.
+ * @modified 2024-10-30 Added the `getEdges` method.
+ * @modified 2024-12-02 Added the `elimitateColinearEdges` method.
+ * @modified 2025-02-12 Added the `containsVerts` method to test multiple vertices for containment.
+ * @modified 2025-03-28 Added the `Polygon.utils.locateLineIntersecion` static helper method.
+ * @modified 2025-03-28 Added the `Polygon.lineIntersectionTangents` method.
+ * @modified 2025-04-09 Added the `Polygon.getCentroid` method.
+ * @modified 2025-05-16 Class `Polygon` now implements `IBounded`.
+ * @version 1.15.0
  *
  * @file Polygon
  * @public
  **/
 import { BezierPath } from "./BezierPath";
 import { Bounds } from "./Bounds";
+import { Line } from "./Line";
+import { Vector } from "./Vector";
 import { VertTuple } from "./VertTuple";
 import { Vertex } from "./Vertex";
-import { XYCoords, SVGSerializable, UID } from "./interfaces";
+import { XYCoords, SVGSerializable, UID, Intersectable, IBounded } from "./interfaces";
 /**
  * @classdesc A polygon class. Any polygon consists of an array of vertices; polygons can be open or closed.
  *
@@ -49,7 +59,7 @@ import { XYCoords, SVGSerializable, UID } from "./interfaces";
  * @requires Vertex
  * @requires XYCoords
  */
-export declare class Polygon implements SVGSerializable {
+export declare class Polygon implements IBounded, Intersectable, SVGSerializable {
     /**
      * Required to generate proper CSS classes and other class related IDs.
      **/
@@ -96,12 +106,66 @@ export declare class Polygon implements SVGSerializable {
     /**
      * Add a vertex to the end of the `vertices` array.
      *
-     * @method addVert
+     * @method addVertex
      * @param {Vertex} vert - The vertex to add.
      * @instance
      * @memberof Polygon
      **/
     addVertex(vert: Vertex): void;
+    /**
+     * Add a vertex at a particular position of the `vertices` array.
+     *
+     * @method addVertexAt
+     * @param {Vertex} vert - The vertex to add.
+     * @param {number} index - The position to add the vertex at. Will be handled modulo.
+     * @instance
+     * @memberof Polygon
+     **/
+    addVertexAt(vert: Vertex, index: number): void;
+    /**
+     * Get a new instance of the line at the given start index. The returned line will consist
+     * of the vertex at `vertIndex` and `vertIndex+1` (will be handled modulo).
+     *
+     * @method getEdgeAt
+     * @param {number} vertIndex - The vertex index of the line to start.
+     * @instance
+     * @memberof Polygon
+     * @return {Line}
+     **/
+    getEdgeAt(vertIndex: number): Line;
+    /**
+     * Converts this polygon into a sequence of lines. Please note that each time
+     * this method is called new lines are created. The underlying line vertices are no clones
+     * (instances).
+     *
+     * @method getEdges
+     * @instance
+     * @memberof Polygon
+     * @return {Array<Line>}
+     */
+    getEdges(): Array<Line>;
+    /**
+     * Checks if the angle at the given polygon vertex (index) is acute. Please not that this is
+     * only working for clockwise polygons. If this polygon is not clockwise please use the
+     * `isClockwise` method and reverse polygon vertices if needed.
+     *
+     * @method isAngleAcute
+     * @instance
+     * @memberof Polygon
+     * @param {number} vertIndex - The index of the polygon vertex to check.
+     * @returns {boolean} `true` is angle is acute, `false` is obtuse.
+     */
+    getInnerAngleAt(vertIndex: number): number;
+    /**
+     * Checks if the angle at the given polygon vertex (index) is acute.
+     *
+     * @method isAngleAcute
+     * @instance
+     * @memberof Polygon
+     * @param {number} vertIndex - The index of the polygon vertex to check.
+     * @returns {boolean} `true` is angle is acute, `false` is obtuse.
+     */
+    isAngleAcute(vertIndex: number): boolean;
     /**
      * Get the polygon vertex at the given position (index).
      *
@@ -112,7 +176,7 @@ export declare class Polygon implements SVGSerializable {
      *  - getVertexAt( vertices.length + k ) == getVertexAt( k )
      *  - getVertexAt( -k )                  == getVertexAt( vertices.length -k )
      *
-     * @metho getVertexAt
+     * @method getVertexAt
      * @param {number} index - The index of the desired vertex.
      * @instance
      * @memberof Polygon
@@ -136,12 +200,24 @@ export declare class Polygon implements SVGSerializable {
      *    https://stackoverflow.com/questions/22521982/check-if-point-inside-a-polygon
      *
      * @method containsVert
-     * @param {XYCoords} vert - The vertex to check. The new x-component.
+     * @param {XYCoords} vert - The vertex to check.
      * @return {boolean} True if the passed vertex is inside this polygon. The polygon is considered closed.
      * @instance
      * @memberof Polygon
      **/
     containsVert(vert: XYCoords): boolean;
+    /**
+     * Check if all given vertices are inside this polygon.<br>
+     * <br>
+     * This method just uses the `Polygon.containsVert` method.
+     *
+     * @method containsVerts
+     * @param {XYCoords[]} verts - The vertices to check.
+     * @return {boolean} True if all passed vertices are inside this polygon. The polygon is considered closed.
+     * @instance
+     * @memberof Polygon
+     **/
+    containsVerts(verts: XYCoords[]): boolean;
     /**
      * Check if the passed polygon is completly contained inside this polygon.
      *
@@ -218,9 +294,36 @@ export declare class Polygon implements SVGSerializable {
      * @return {Polygon} this, for chaining.
      **/
     rotate(angle: number, center: Vertex): Polygon;
+    /**
+     * Get the mean `center` of this polygon by calculating the mean value of all vertices.
+     *
+     * Mean: (v[0] + v[1] + ... v[n-1]) / n
+     *
+     * @method getMeanCenter
+     * @instance
+     * @memberof Polygon
+     * @return {Vertex|null} `null` is no vertices are available.
+     */
+    getMeanCenter(): Vertex | null;
+    /**
+     * Get centroid.
+     * Centroids define the barycenter of any non self-intersecting convex polygon.
+     *
+     * If the polygon is self intersecting or non konvex then the barycenter is not well defined.
+     *
+     * https://mathworld.wolfram.com/PolygonCentroid.html
+     *
+     * @method getCentroid
+     * @instance
+     * @memberof Polygon
+     * @returns {Vertex|null}
+     */
+    getCentroid(): Vertex | null;
     /**
      * Get all line intersections with this polygon.
      *
+     * This method returns all intersections (as vertices) with this shape. The returned array of vertices is in no specific order.
+     *
      * See demo `47-closest-vector-projection-on-polygon` for how it works.
      *
      * @param {VertTuple} line - The line to find intersections with.
@@ -228,6 +331,16 @@ export declare class Polygon implements SVGSerializable {
      * @returns {Array<Vertex>} - An array of all intersections within the polygon bounds.
      */
     lineIntersections(line: VertTuple<any>, inVectorBoundsOnly?: boolean): Array<Vertex>;
+    /**
+     * Get all line intersections of this polygon and their tangents along the shape.
+     *
+     * This method returns all intersection tangents (as vectors) with this shape. The returned array of vectors is in no specific order.
+     *
+     * @param line
+     * @param inVectorBoundsOnly
+     * @returns
+     */
+    lineIntersectionTangents(line: VertTuple<any>, inVectorBoundsOnly?: boolean): Array<Vector>;
     /**
      * Get the closest line-polygon-intersection point (closest the line point A).
      *
@@ -266,9 +379,29 @@ export declare class Polygon implements SVGSerializable {
     /**
      * Create a deep copy of this polygon.
      *
+     * @method clone
+     * @instance
+     * @memberof Polygon
      * @return {Polygon} The cloned polygon.
      */
     clone(): Polygon;
+    /**
+     * Create a new polygon without colinear adjacent edges. This method does not midify the current polygon
+     * but creates a new one.
+     *
+     * Please note that this method does NOT create deep clones of the vertices. Use Polygon.clone() if you need to.
+     *
+     * Please also note that the `tolerance` may become really large here, as the denominator of two closely
+     * parallel lines is usually pretty large. See the demo `57-eliminate-colinear-polygon-edges` to get
+     * an impression of how denominators work.
+     *
+     * @method elimitateColinearEdges
+     * @instance
+     * @memberof Polygon
+     * @param {number?} tolerance - (default is 1.0) The epsilon to detect co-linear edges.
+     * @return {Polygon} A new polygon without co-linear adjacent edges – respective the given epsilon.
+     */
+    elimitateColinearEdges(tolerance?: number): Polygon;
     /**
      * Convert this polygon to a sequence of quadratic Bézier curves.<br>
      * <br>
@@ -342,6 +475,7 @@ export declare class Polygon implements SVGSerializable {
          * @return {number}
          */
         area(vertices: Array<XYCoords>): number;
+        isClockwise(vertices: Array<XYCoords>): boolean;
         /**
          * Calulate the signed polyon area by interpreting the polygon as a matrix
          * and calculating its determinant.
@@ -350,5 +484,18 @@ export declare class Polygon implements SVGSerializable {
          * @return {number}
          */
         signedArea(vertices: Array<XYCoords>): number;
+        /**
+         * Find intersections of a line with a polygon (vertices).
+         *
+         * @param {VertTuple<any>} line - The line to find intersections with.
+         * @param {Array<Vertex>} vertices - The polygon's vertices.
+         * @param {boolean} isOpen - True if the polygon is open, false otherwise.
+         * @param {boolean} inVectorBoundsOnly - If only intersections in strict vector bounds should be returned.
+         * @returns
+         */
+        locateLineIntersecion(line: VertTuple<any>, vertices: Array<Vertex>, isOpen: boolean, inVectorBoundsOnly: boolean): Array<{
+            edgeIndex: number;
+            intersectionPoint: Vertex;
+        }>;
     };
 }