join

The join macro joins multiple paths together.

Unlike the core Path.join() function, the join macro can extend line ends to meet in a sharp corner and will automatically trim useless path ends when adjacent paths in the array are intersecting.

note

Not a core-plugins macro

The join macro is not provided by the core plugins, so you need to load the path-utils plugin explicitly if you want to use it.

Signature

Path macro('join', {
  Array paths,
  number limit,
  string mode
})

Example

Preview

Code

({ Point, points, Path, paths, macro, part }) => {
  paths.a = new Path().move(new Point(10, 10)).line(new Point(10, 20))

  paths.b = new Path().move(new Point(25, 30)).line(new Point(55, 30))

  paths.c = new Path().move(new Point(40, 20)).line(new Point(40, 50))

  paths.d = new Path().move(new Point(50, 60)).line(new Point(60, 60))

  paths.e = new Path()
    .move(new Point(70, 40))
    .curve(new Point(55, 15), new Point(55, 15), new Point(30, 0))

  paths.join = macro('join', {
    paths: ['a', 'b', 'c', null, 'd', 'e'],
  }).setClass('stroke-sm mark dotted')

  return part
}

X-Ray

An example of the join macro

Configuration

Property	Default	Type	Description
paths		array	An array of pathnames, the names of Paths in the paths array to join (you can also reference Path objects directly, or insert null elements to create gaps)
mode	'corner'	string	Mode for joining paths. Either 'corner' or 'cut'. 'cut' will join the paths directly without extending them (like Path.join()).
limit	null	number	Allows limiting the length of corners in 'corner' mode. Prevents overly long joins on very sharp angles. Ignored if null or false.

Notes

The join macro accepts an array of Path objects (either names in the paths array or direct references to Path objects). This array can contain null values or hidden paths (created with Path.hide()) to create gaps.

warning

Since hidden paths will create gaps in the resulting paths, make sure that all the paths you want to include in the join are visible before calling the macro.

You can hide them afterwards again, if needed.

By default, the join macro will join the paths in a circular fashion, joining the end of the last path in the array to the start of the first path, creating a full outline. If this is not desired, insert a null element between paths where you want the gap (or at the end of the paths parameter).

Note that a null value will create a basic gap in the output. If you instead include a hidden path, this method will still create sharp corners as if the path were present, but the actual path will be skipped in the output.