VSinerva/freesewing
1
0
Fork 0
Code Activity

[plugin-path-utils] feat: Add path-utils plug-in (#236)

Browse source 
This plug-in helps with creating seam allowance and hem paths.

Rebased v4 version for #99, see the linked issue for screenshots/details.

Reviewed-on: https://codeberg.org/freesewing/freesewing/pulls/236
Reviewed-by: Joost De Cock <joostdecock@noreply.codeberg.org>
Co-authored-by: Jonathan Haas <haasjona@gmail.com>
Co-committed-by: Jonathan Haas <haasjona@gmail.com>
This commit is contained in:
Jonathan Haas 2025-04-13 08:58:45 +00:00 • committed by Joost De Cock
parent 36da79afb6
commit 04a0b4b099
14 changed files with 1971 additions and 436 deletions
Download patch file Download diff file Expand all files Collapse all files

131
sites/dev/docs/reference/macros/hem/readme.mdx Normal file
View file

@ -0,0 +1,131 @@
---
title: hem
---
The `hem` macro drafts a hem allowance with fold lines.
## Signature
```js
Path macro('hem', {
Path|string path1,
Path|string path2,
number offset1 = null,
number offset2 = null,
number hemAllowance,
number lastHemAllowance = null,
number folds = 2,
number prefix = 'hemMacro',
number cssClass = 'fabric'
})
```
## Example
<Example caption="An example of the hem macro">
```js
;({ Point, points, Path, paths, macro, part }) => {
paths.inseam = new Path().move(new Point(150, 0)).line(new Point(200, 200)).hide()
paths.outseam = new Path()
.move(new Point(300, 200))
.curve(new Point(350, 100), new Point(350, 50), new Point(350, 0))
.hide()
paths.fabric = paths.inseam.clone().join(paths.outseam)
paths.hem = macro('hem', {
class: 'fabric',
path1: 'inseam',
path2: 'outseam',
hemWidth: 30,
offset1: 10,
offset2: 10,
})
// show helper mirror paths
paths.hemMacroMirror1.unhide().addClass('various sa')
paths.hemMacroMirror2.unhide().addClass('various sa')
return part
}
```
</Example>
## Configuration
| Property | Default | Type | Description |
| --------------: | ---------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `path1` | | `Path` or `string` | The path before the hem (when the part is seen anticlockwise), for example the inseam on a pants pattern when construction a leg hole. You can reference a Path object directly or give a name of an existing path in the `paths` array. |
| `path2` | | `Path` or `string` | The path after the hem, for example the outseam on a pants pattern when constructing a leg hole. |
| `offset1` | (seam allowance) | `number` | The seam allowance of `path1`, defaults to used seam allowance (`sa`), if not given. |
| `offset2` | (seam allowance) | `number` | The seam allowance of `path2`, defaults to used seam allowance (`sa`), if not given. |
| `hemWidth` | | `number` | The width of the hem in millimeters. |
| `lastFoldWidth` | (seam allowance) | `number` | The width of the last fold, defaults to used seam allowance (`sa`), if not given. |
| `folds` | 2 | `number` | The number of folds for the hem. `2` creates a normal double folded hem. `1` would create a single fold for hems that are overlocked or made from knit fabric. Values below 1 are invalid. |
| `prefix` | `'hemMacro'` | `number` | The name prefix used for paths created by this macro. |
| `cssClass` | `'fabric'` | `number` | The CSS class added to the fold lines and the hem outline. Should usually match the CSS class for the part outline |
## Detailed Description
This macro will create the following paths (assuming the default `'hemMacro'` prefix is used):
- `hemMacroMirror1`: The part of the offset `path1` that is used to construct the starting edge of the hem line (by repeatedly mirroring it)
- `hemMacroMirror2`: The part of the offset `path2` that is used to construct the closing edge of the hem line (by repeatedly mirroring it)
- `hemMacroFold1`, `hemMacroFold2`, ...: The dot-dashed lines that mark the fold lines (one less than the `fold` parameter)
The Paths `hemMacroMirror1` and `hemMacroMirror2` are hidden by default, but you could use them to e.g. mark where the folded part would end up.
The macro call will _return_ the outline path of the hem, so you need to do something like
```js
paths.hem = macro('hem', {
...
});
```
to get and use the actual hem path. You probably want to embed the hem path into the seam allowance path, the following example code shows how to do this using the `sa` macro.
:::note
The hem path already includes the seam allowance, so it doesn't need any additional offset.
:::
<Example caption="Embedding the hem macro in the seam allowance path">
```js
;({ Point, points, Path, paths, macro, part }) => {
paths.inseam = new Path().move(new Point(150, 0)).line(new Point(200, 200)).hide()
paths.outseam = new Path()
.move(new Point(300, 200))
.curve(new Point(350, 100), new Point(350, 50), new Point(350, 0))
.hide()
paths.fabric = paths.inseam.clone().join(paths.outseam)
paths.hem = macro('hem', {
class: 'fabric',
path1: 'inseam',
path2: 'outseam',
hemWidth: 30,
offset1: 10,
offset2: 10,
}).hide()
paths.sa = macro('sa', {
paths: ['inseam', { p: 'hem', offset: 0 }, 'outseam', null],
sa: 10,
}).setClass('fabric sa')
return part
}
```
</Example>
:::note
When copying the example code for your design, you can probably omit the `sa`, `offset1` and `offset2` parameters.
They're only needed here as there is no default seam allowance in this preview window.
:::

76
sites/dev/docs/reference/macros/join/readme.mdx Normal file
View file

@ -0,0 +1,76 @@
---
title: 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.
The join function 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.
## Signature
```js
Path macro('join', {
Array paths,
number limit,
string mode
})
```
## Example
<Example caption="An example of the join macro">
```js
;({ 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
}
```
</Example>
## 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`. |

84
sites/dev/docs/reference/macros/offset/readme.mdx Normal file
View file

@ -0,0 +1,84 @@
---
title: offset
---
The `offset` macro will offset and join paths.
Unlike the core `path.join(...)` and `path.offset(...)` functions, the `offset` 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.
The offset macro accepts an array of `Path` objects with their offset, like `{p: 'somePath', offset: 30}` or `{p: ['path1', 'path2'], offset: sa * 3, hidden: true}`.
For the paths in the `p` attribute, you can reference either names in the `paths` array or insert direct references to `Path` objects.
The array can contain `null` values to create gaps (e.g., for cuts on the fold or for other sections that don't need seam allowance).
By default, the `offset` macro will offset 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 `null` elements where you want to create gaps.
You can use `offset: 0` to include paths which don't need an additional offset.
You can use `hidden: true` to omit path segments from the output, but still build corner joins as if they were there.
This can be used for cut-on-fold lines, where no seam allowance is needed.
:::note
To create a seam allowance, prefer the `sa` macro instead of the `offset` macro. It does pretty much the same,
but the `sa` macro defaults to offsetting paths by the user defined seam allowance.
:::
## Signature
```js
Path macro('offset', {
Array paths,
number limit,
string mode,
string class
})
```
## Example
<Example caption="An example of the offset macro">
```js
;({ Point, points, Path, paths, macro, part }) => {
paths.outline = new Path()
.move(new Point(10, 30))
.line(new Point(30, 30))
.line(new Point(30, 50))
.line(new Point(50, 50))
.line(new Point(50, 70))
.line(new Point(70, 70))
.curve(new Point(55, 15), new Point(55, 15), new Point(30, 0))
paths.outline2 = new Path().move(new Point(30, 0)).line(new Point(10, 30))
paths.offset = macro('offset', {
paths: [
{ p: 'outline', offset: 10 },
{ p: 'outline2', offset: 30 },
],
}).setClass('stroke-sm mark dotted')
paths.halfCircle = new Path().move(new Point(100, 0)).circleSegment(37, new Point(200, 0)).hide()
paths.halfCircleClosed = paths.halfCircle.clone().line(new Point(200, 0)).unhide().close()
paths.halfCircleSa = macro('offset', {
paths: [{ p: 'halfCircle', offset: 10 }, null],
}).setClass('stroke-sm mark dotted')
return part
}
```
</Example>
## Configuration
| Property | Default | Type | Description |
| -------: | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `paths` | | `array` | An array of paths with their offset and visibility. You can use path names in the `paths` array or 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 (like `path.join(...)`) without extending the corners. |
| `limit` | `null` | `number` | Allows limiting the length of extended path corners in `'corner'` mode. Prevents overly long joins on very sharp angles. Ignored if `null` or `false`. |
| `class` | `'offset'` | `string` | CSS class that is automatically applied to the resulting path. |

82
sites/dev/docs/reference/macros/sa/readme.mdx Normal file
View file

@ -0,0 +1,82 @@
---
title: sa
---
The `sa` macro will create seam allowance paths.
Unlike the core `path.join(...)` and `path.offset(...)` functions, the `sa` 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.
The sa 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 to create gaps (e.g. for cuts on the fold or for other sections that don't need seam allowance).
By default, the `sa` macro will sa 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 `null` elements where you want to create gaps.
You can optionally override the offset and invisibility for individual paths.
To do so, insert an object literal like `{p: 'somePath', offset: 30}` or `{p: ['path1', 'path2'], offset: sa * 3, hidden: true}` into the `paths` array.
You can use `offset: 0` to include paths which have already build-in the seam allowance (e.g. the result of the `hem` macro).
You can use `hidden: true` to hide path segments from the output, but still build corner joins as if they were there.
This can be used for cut-on-fold lines, where no seam allowance is needed.
## Signature
```js
macro('sa', {
Array paths,
number limit,
string mode,
string class
})
```
## Example
<Example caption="An example of the sa macro">
```js
;({ Point, points, Path, paths, macro, part }) => {
paths.outline = new Path()
.move(new Point(10, 30))
.line(new Point(30, 30))
.line(new Point(30, 50))
.line(new Point(50, 50))
.line(new Point(50, 70))
.line(new Point(70, 70))
.curve(new Point(55, 15), new Point(55, 15), new Point(30, 0))
paths.outline2 = new Path().move(new Point(30, 0)).line(new Point(10, 30))
paths.sa = macro('sa', {
paths: ['outline', { p: 'outline2', offset: 30 }],
sa: 10,
}).setClass('stroke-sm mark dotted')
paths.halfCircle = new Path().move(new Point(100, 0)).circleSegment(37, new Point(200, 0)).hide()
paths.halfCircleClosed = paths.halfCircle.clone().line(new Point(200, 0)).unhide().close()
paths.halfCircleSa = macro('sa', {
paths: ['halfCircle', null],
sa: 10,
}).setClass('stroke-sm mark dotted')
return part
}
```
</Example>
## Configuration
| Property | Default | Type | Description |
| -------: | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `paths` | | `array` | An array of paths. You can use path names in the `paths` array or reference `Path` objects directly, or insert `null` elements to create gaps. You can also override offset and visibility for individual paths in the same way as with the `offset` macro. |
| `mode` | `'corner'` | `string` | Mode for joining paths. Either `'corner'` or `'cut'`. `'cut'` will join the paths directly (like `path.join(...)`) without extending the corners. |
| `limit` | `null` | `number` | Allows limiting the length of extended path corners in `'corner'` mode. Prevents overly long joins on very sharp angles. Ignored if `null` or `false`. |
| `sa` | (seam allowance) | `number` | Allows you to override the seam allowance used for this macro. Defaults to the standard seam allowance (`sa` parameter in draft function). |
| `class` | `'sa'` | `string` | CSS class that is automatically applied to the resulting path. |

34
sites/dev/docs/reference/plugins/path-utils/readme.mdx Normal file
View file

@ -0,0 +1,34 @@
---
title: plugin-path-utils
---
Published as [@freesewing/plugin-path-utils][1], this plugin provides the [hem](/reference/macros/hem), [sa](/reference/macros/sa), [offset](/reference/macros/offset) and [sa](/reference/macros/join) macros,
whose main purpose is to make it easier to construct seam allowance paths.
## Installation
```sh
npm install @freesewing/plugin-path-utils
```
## Usage
Either [add it as a part plugins](/reference/api/part/config/plugins) in your
design, or [add it to a pattern instance with
Pattern.use()](/reference/api/pattern/use).
To import the plugin for use:
```js
import { pathUtilsPlugin } from '@freesewing/plugin-path-utils'
// or
import { pluginPathUtils } from '@freesewing/plugin-path-utils'
```
## Notes
This plugin is part of the [core-plugins bundle](/reference/plugins/core),
so there is no need to install or import it manually unless you wish to forego
loading of core plugins yet still want to load this plugin.
[1]: https://www.npmjs.com/package/@freesewing/plugin-path-utils