Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Polyline

A continuous line made from a series of straight segments. An array of points defines the corners of the polyline.

If the polyline's start and end point are the same, it is considered closed. This can be checked with isClosed. Some operations, such as contains, only work with closed polylines.

Example

import { Point, Polyline, Vector } from 'shapetypes'

// Create a new polyline
const triangle = new Polyline([new Point(0, 0), new Point(1, 1), new Point(2, 0)], true);

// Get properties of the polyline
console.log(triangle.area);
// => 1
console.log(triangle.length);
// => 4.82842712474619

// Check whether a point is inside the closed polyline
console.log(triangle.contains(new Point(1, 0.5)));
// => True

// Move the polyline and check whether the point is inside
const shifted = triangle.translate(new Vector(3, 4));
console.log(shifted.contains(new Point(1, 0.5)));
// => False

Hierarchy

Index

Constructors

constructor

  • new Polyline(points: keyof Point[], makeClosed?: boolean): Polyline
  • Creates a polyline from a set of corner points.

    note

    Doesn't verify that this is a valid polyline. It is possible to create a polyline with self-intersection or zero-length segments, which may cause problems in some functions.

    Parameters

    • points: keyof Point[]

      The points defining the corners of the polyline.

    • Default value makeClosed: boolean = false

      If true, checks whether the resulting polyline isClosed and if it isn't, adds another point ensuring the polyline ends the same place it starts.

    Returns Polyline

Accessors

area

  • get area(): number
  • Gets the area enclosed by the polyline. If the polyline isn't closed, returns 0.

    Returns number

boundingBox

count

  • get count(): number

from

isClosed

  • get isClosed(): boolean
  • Checks whether the polyline starts and ends in the same place (that from equals to). Returns true if it does.

    Returns boolean

length

  • get length(): number

points

  • get points(): keyof Point[]

segmentCount

  • get segmentCount(): number

segments

  • get segments(): keyof Line[]

to

Closed Methods

contains

  • Checks whether a point is inside, outside, or on the edge of a polyline.

    note

    This method only works with closed polylines. It will throw an error if applied to an open polyline.

    Parameters

    • point: Point

      The point to test for containment.

    • Default value tolerance: number = shapetypesSettings.absoluteTolerance

      The distance the point can be from the edge of the polyline and still considered coincident.

    Returns PointContainment

withOrientation

  • Returns a copy of the polyline with a given CurveOrientation. If the polyline already has that orientation, returns self.

    note

    This method only works with closed polylines. It may throw an error if applied to an open polyline.

    Parameters

    • goal: CurveOrientation

      The desired orientation of the new polyline.

    • Default value isYDown: boolean = false

    Returns Polyline

Create Methods

Static fromCoords

  • fromCoords(coordinates: Ring, makeClosed?: boolean): Polyline
  • Creates a polyline from a list of corner coordinates (in the GeoJSON format).

    Parameters

    • coordinates: Ring

      List of points in the format [[x1,y1],[x2,y2],[x3,y3],...]

    • Default value makeClosed: boolean = false

      If true, checks whether the resulting polyline isClosed and if it isn't, adds another point ensuring the polyline ends the same place it starts.

    Returns Polyline

Other Methods

asGeoJSON

  • asGeoJSON(): Ring
  • Gets the polyline in the GeoJSON format: [[x1,y1],[x2,y2],...].

    Returns Ring

center

closestIndex

  • closestIndex(testPoint: Point): number
  • Finds the closest point in the list of points and returns its index.

    Parameters

    • testPoint: Point

      The target to get closest to.

    Returns number

closestParameter

  • closestParameter(testPoint: Point): number
  • Finds the closest point on the polyline and returns the parameter for the point.

    Parameters

    • testPoint: Point

      The target to get closest to.

    Returns number

    The parameter of the closest point. Entering the parameter into pointAt will return the closest point.

closestPoint

  • closestPoint(testPoint: Point, includeInterior?: boolean): Point
  • Finds the closest point on the polyline and returns the point.

    Parameters

    • testPoint: Point

      Target to get closest to.

    • Default value includeInterior: boolean = false

      If false, the closest point must lie on a segment of the polyline. If true, the closest point can also be a point on the polyline's interior (if it is closed and has an interior).

    Returns Point

deleteShortSegments

  • deleteShortSegments(minimumSegmentSize?: number): Polyline
  • Creates a copy of the polyline with short segments removed. This is achieved by traveling along the polyline and removing any point closer to the previous point than minimumSegmentSize. Does not remove from or to points.

    Parameters

    • Default value minimumSegmentSize: number = shapetypesSettings.absoluteTolerance

      Shortest allowable segment.

    Returns Polyline

equals

  • equals(otherPolyline: Polyline, tolerance?: number): boolean
  • Checks whether another polyline has the same points. Returns true if it does.

    Parameters

    • otherPolyline: Polyline

      Polyline to compare against.

    • Default value tolerance: number = shapetypesSettings.absoluteTolerance

      The amount the points can differ and still be considered equal.

    Returns boolean

intersection

makeClosed

  • Returns a closed copy of the polyline. If the polyline is already closed, returns itself. If the polyline is open, closes it by adding a segment between to and from.

    Returns Polyline

mergeColinearSegments

  • mergeColinearSegments(angleTolerance?: number, includeSeam?: boolean): Polyline
  • Creates a copy of the polyline with colinear segments merged together. This is achieved by traveling along the polyline and merging any segments that travel in the same direction.

    Parameters

    • Default value angleTolerance: number = shapetypesSettings.angleTolerance

      The minimum angle at which segments are no longer colinear (in radians).

    • Default value includeSeam: boolean = true

      If true, it will also test seam on closed polylines for colinearity. If they are colinear, will move from and to points.

    Returns Polyline

normalAt

  • Calculates the normal to the polyline at a given parameter.

    If the polyline is closed, it will always return the normal that points towards the inside. If the polyline is open, the vector will be on the left side of the segment (which is the right side if the environment's y-axis points downwards).

    note

    At corners where two segments join, returns the normal to the segment with the smallest index.

    Parameters

    • u: number

      Position on the polyline to calculate the normal (see pointAt for explanation)

    Returns Vector

    A unit vector

orientation

  • Calculates whether a polyline is in a clockwise or counter-clockwise orientation and returns the result. If the polyline is not closed, it can't have an orientation, so the function returns CurveOrientation.undefined.

    Parameters

    • Default value isYDown: boolean = false

      The function assumes that the environment's y-axis points upwards. In environments where the y-axis points downwards, isYDown should be set to true. This inverts clockwise and counter-clockwise to ensure that they are in the correct orientation for how you're viewing them.

    Returns CurveOrientation

pointAt

  • pointAt(u: number): Point
  • Finds the point a normalized parameter along the polyline. Returns the point.

    Each segment of the polyline is parameterized from 0 to 1 (like Line.pointAt). So 0 is the start of the first segment, and 1 is the end. 0.5 is the mid point of the first segment, and 1.5 is the mid point of the second segment.

    Example

    const triangle = new Polyline([new Point(0, 0), new Point(1, 1), new Point(2, 0)], true);
    
    // The start of first segment
    console.log(triangle.pointAt(0).toString());
    // => (0,0)
    
    // Mid point of first segment
    console.log(triangle.pointAt(0.5).toString());
    // => (0.5,0.5)
    
    // The end of first segment / start of second segment
    console.log(triangle.pointAt(1).toString());
    // => (1,1)
    
    // Mid point of second segment
    console.log(triangle.pointAt(1.5).toString());
    // => (1.5,0.5)
    

    Parameters

    • u: number

      The normalized parameter.

    Returns Point

reverse

segmentAt

  • segmentAt(index: number): Line
  • Gets a segment of the polyline.

    Parameters

    • index: number

      The index of the segment.

    Returns Line

toString

  • toString(): string
  • Gets the polyline as a string in the format: [(x1,y1),(x2,y2),(x3,y3)].

    Returns string

trim

  • Extracts a section of the polyline. Returns the resulting polyline.

    Parameters

    • domain: IntervalSorted | Interval

      The section of the polyline to extract. The domain contains two numbers, the min, which is the parameter for the start of the new polyline. And the max, which will be the end. Everything between these two points is included in the new polyline. The position of the domain is calculated using the same method as pointAt.

    Returns Polyline

Transform Methods

changeBasis

  • changeBasis(planeFrom: Plane, planeTo: Plane): this
  • Translates the geometry from one coordinate system to another while keeping the geometry in the same position. In other words, if the geometry is currently described relative to planeFrom, after changeBasis, it will be in the same position but described relative to planeTo.

    see

    Transform.changeBasis.

    Parameters

    • planeFrom: Plane

      The coordinate system the geometry is currently described relative to.

    • planeTo: Plane

      The coordinate system to describe the geometry relative to.

    Returns this

    The geometry in the new coordinate system.

planeToPlane

  • planeToPlane(planeFrom: Plane, planeTo: Plane): this

rotate

  • rotate(angle: number): this
  • rotate(angle: number, pivot: Point): this
  • Rotates the geometry about (0,0).

    see

    Transform.rotate.

    Parameters

    • angle: number

      Angle to rotate the geometry (in radians). The direction is counter-clockwise.

    Returns this

  • Rotates the geometry about a point.

    see

    Transform.rotate.

    category

    Transform

    Parameters

    • angle: number

      Angle to rotate the geometry (in radians). If the environment's y-axis points upwards, the direction is counter-clockwise.

    • pivot: Point

      Point to pivot the geometry about.

    Returns this

scale

  • scale(amount: number): this
  • scale(x: number, y: number): this
  • scale(x: number, y: number, center: Point): this
  • Scales the geometry and returns the resized geometry. The geometry will be scaled about (0,0), meaning everything will shrink or expand away from this point.

    see

    Transform.scale.

    Parameters

    • amount: number

      Magnitude to scale in x- and y-direction. If less than 1, the object will shrink. If greater than 1, it will grow.

    Returns this

  • Scales the geometry and returns the resized geometry. The geometry will be scaled about (0,0), meaning everything will shrink or expand away from this point.

    see

    Transform.scale.

    category

    Transform

    Parameters

    • x: number

      Magnitude to scale in x-direction. If less than 1, the object will shrink. If greater than 1, it will grow.

    • y: number

      Magnitude to scale in y-direction. If less than 1, the object will shrink. If greater than 1, it will grow.

    Returns this

  • Scales the geometry about a point and returns the resized geometry.

    see

    Transform.scale.

    category

    Transform

    Parameters

    • x: number

      Magnitude to scale in x-direction. If less than 1, the object will shrink. If greater than 1, it will grow.

    • y: number

      Magnitude to scale in y-direction. If less than 1, the object will shrink. If greater than 1, it will grow.

    • center: Point

      Center of scaling. Everything will shrink or expand away from this point.

    Returns this

transform

  • Transforms the polyline by a transform matrix and returns the result.

    Example

    import { Point, Polyline. Transform, Vector } from 'shapetypes';
    
    // Create a new polyline
    const triangle = new Polyline([new Point(0, 0), new Point(1, 1), new Point(2, 0)], true);
    
    // Check start position of the polyline
    console.log(shifted.from.toString());
    // => (0,0)
    
    // Translate polyline using a transform matrix
    const matrix = Transform.translate(new Vector(3,4));
    const shifted = triangle.transform(matrix);
    console.log(shifted.from.toString());
    // => (3,4)
    
    // Translate polyline using the direct method
    const otherShifted = triangle.translate(new Vector(3, 4));
    console.log(otherShifted.from.toString());
    // => (3,4)
    note

    If you're applying the same transformation a lot of geometry, creating the Transform matrix once and calling this function is faster than using the direct methods.

    Parameters

    Returns this

translate

  • translate(move: Vector): this
  • translate(move: Vector, distance: number | undefined): this
  • Moves the geometry along a vector and returns the moved geometry. The translation is always linear.

    see

    Transform.translate.

    Parameters

    • move: Vector

      The direction and distance to move the geometry.

    Returns this

  • Moves the geometry along a vector and returns the moved geometry. The translation is always linear.

    see

    Transform.translate.

    category

    Transform

    Parameters

    • move: Vector

      The direction to move the geometry.

    • distance: number | undefined

      The distance to move the geometry.

    Returns this

Generated using TypeDoc