Interface OBJ_Polyline

Polyline shape options object that extends OBJ_Generic (without drawType) and OBJ_FigurePrimitive

A polyline is a series of lines that are connected end to end. It is defined by a series of points which are the ends and corners of the polyline.

The series of points is a zero width ideal polyline, and so to see it we must give it some width. This width can either be grown on one side of the ideal polyline or grown on both sides of it equally using widthIs.

A polyline can have a "positive" or "negative" side, and an "inside" or "outside".

If a line is defined from p1 to p2, then the positive side is the side where the line moves if it is rotated around p1 in the positive (counter clockwise) direction. Thus the order of the points that define the line defines which side is positive and negative. A polyline is made up of many lines end to end, and thus itself will have a positive and negative side dependent on the order of points.

Similarly we can define a line's side as either inside or outside. Each corner in the polyline will have an angle on the negative side of the line and a explementary angle on the positive side of the line. The inside side of the line is the same as the negative side if the sum of all the negative side angles is smaller than the sum of all positive side angles.

Both positive/negative and inside/outside are provided to define a line's side as different situations make different side definitions more intuitive. For instance, a closed, simple polygon has an obvious "inside" and "outside", but how the points are ordered would define if the "inside" is "positive" or "negative". In comparison, it would be more intuitive to use "positive" or "negative" for a polyline that has an overall trend in a single direction.

Therefore, the polyline width can be grown on either the 'positive', 'negative', 'inside', or 'outside' side of the line or around the middle of the line with 'mid'. In addition, a number between 0 and 1 can be used where 0 is the same as 'positive', 1 the same as 'negative' and 0.5 the same as 'mid'.

Each point, or line connection, creates a corner that will have an inside angle (<180º) and an outside angle (>180º or reflex angle).

Growing width on an outside corner can be challenging. As the corner becomes sharper, the outside width joins at a point further and further from the ideal corner. Eventually trucating the corner makes more visual sense and therefore, a minimum angle (minAutoCornerAngle) is used to specify when the corner should be drawn, and when it should be truncated.

By default, the border of the polyline is the line itself (border = 'line'). The border can also just be the points on the positive side of the line, or the negative side of the line. This is useful for capturing the hole shape of a closed polyline within a border. The border can also be the encompassing rectangle of the polyline (border = 'rect') or defined as a custom set of points.

The touch border can either be the same as the border ('border'), the encompassing rect ('rect'), a custom set of points, or the same as the line but with some buffer that effectively increases the width on both sides of the line.

points TypeParsablePoint[] | Point[]
width number — (0.01)
close boolean — close the polyline on itself (false)
simple boolean — simple and minimum computation polyline. Good for large numbers of points that need to be updated every animation frame. widthIs, dash, arrow and all corner and line primitive properties are not available when a polyline is simple. (false)
widthIs number | positive | negative | mid | outside | inside — defines how the width is grown from the polyline's points. Only "mid" is fully compatible with all options in cornerStyle and dash. ("mid")
drawBorder ("positive" | "negative" | "line" | TypeParsableBorder) & TypeParsableBorder — override OBJ_Generic drawBorder with 'line' to make the drawBorder just the line itself, 'positive' to make the drawBorder the positive side of the line, and 'negative' to make the drawBorder the negative side of the line. Use array definition for custom drawBorder ('line')
drawBorderBuffer (number | TypeParsableBorder) & TypeParsableBorder — override OBJ_Generic drawBorderBuffer with number to make the drawBorderBuffer the same as the line with additional number thickness on either side (0)
cornerStyle fill | none | radius | auto — "auto": sharp corners sharp when angle is less than minAutoCornerAngle, "none": no corners, "radius": curved corners, "fill": fills the gapes between the line ends, ("auto")
cornerSize number — only used when cornerStyle = radius (0.01)
cornerSides number — number of sides in curve - only used when cornerStyle = radius (10)
cornersOnly boolean — draw only the corners with size cornerSize (false)
cornerLength number — use only with cornersOnly = true - length of corner to draw (0.1)
minAutoCornerAngle number — see cornerStyle = auto (π/7)
dash TypeDash — leave empty for solid line - use array of numbers for dash line where first number is length of line, second number is length of gap and then the pattern repeats - can use more than one dash length and gap - e.g. [0.1, 0.01, 0.02, 0.01] produces a lines with a long dash, short gap, short dash, short gap and then repeats.
arrow OBJ_LineArrows | TypeArrowHead — either an object defining custom arrows or a string representing the name of an arrow head style can be used. If a string is used, then the line will have an arrow at both ends. Arrows are only available for close: false, widthIs: 'mid' and linePrimitives: false
linePrimitives boolean — Use WebGL line primitives instead of triangle primitives to draw the line (false)
lineNum number — Number of line primitives to use when linePrimitivs: true (2)

See

To test examples, append them to the boilerplate

Example

// Line
figure.add(
  {
    name: 'p',
    make: 'polyline',
    points: [[-0.5, -0.5], [-0.1, 0.5], [0.3, -0.2], [0.5, 0.5]],
    width: 0.05,
  },
);

Example

// Square with rounded corners and dot-dash line
figure.add(
  {
    name: 'p',
    make: 'polyline',
    points: [[-0.5, -0.5], [0.5, -0.5], [0.5, 0.5], [-0.5, 0.5]],
    width: 0.05,
    dash: [0.17, 0.05, 0.05, 0.05],
    close: true,
    cornerStyle: 'radius',
    cornerSize: 0.1,
  },
);

Example

// Corners only of a triangle
figure.add(
 {
   name: 'p',
   make: 'polyline',
   points: [[-0.5, -0.5], [0.5, -0.5], [0, 0.5]],
   width: 0.05,
   close: true,
   cornersOnly: true,
   cornerLength: 0.2,
 },
);

Example

// Zig zag with arrows
figure.add({
  name: 'arrowedLine',
  make: 'polyline',
  points: [[0, 0], [1, 0], [0, 0.7], [1, 0.7]],
  width: 0.05,
  cornerStyle: 'fill',
  arrow: {
    scale: 0.7,
    start: {
      head: 'triangle',
      reverse: true,
    },
    end: 'barb',
  },
});
@interface

Interface OBJ_Polyline

See

Example

Example

Example

Example

Settings