VSinerva/freesewing
1
0
Fork 0
Code Activity

feat(core): Added Path.combine and related changes, closes #5976

Browse source 
The discussion in #5976 is whether `Path.join()` should use a line
segment to close any gaps in the path caused by move operations, or by
differences in the end and start points of paths being joined.

The answer is yes, that is the intended behaviour, but people who read
_join_ might expect differently.

So I have made a few changes to clarify this:

- The new `Path.combine()` method combines multiple path instances into
  a single instance without making any changes to the drawing operations
- Since `Path.combine()` is variadic, I have also updated `Path.join()`
  to be variadic too, since that is more consistent.
- The old way of calling `Path.join(path, bool)` is deprecated and will
  log a warning. Calling `Path.join()` this way will be removed in v4.
- Related to this change is how `Path.length()` should behave when there
  are gaps in the path. Currently, it skips those. So I've added a
  parameter that when set to `true` will include them.
- Added documentation for `Path.combine()`
- Updated documentation for `Path.join()`
- Updated documentation for `Path.length()`
This commit is contained in:
joostdecock 2024-02-10 15:40:41 +01:00
parent 323d8d5bd7
commit a30b08371c
8 changed files with 200 additions and 61 deletions
Download patch file Download diff file Expand all files Collapse all files

58
markdown/dev/reference/api/path/combine/en.md Normal file
View file

@ -0,0 +1,58 @@
---
title: Path.combine()
---
The `Path.combines()` method combines this path with one or more other paths
into a single Path instance.
Any gaps in the path (caused by move operations) will be left as-is, rather
than joined with a line. If that's not what you want, you should use
[`Path.join()`](/reference/api/path/join) instead.
## Signature
```js
Path path.combine(path other)
```
## Examples
<Example caption="Example of the Path.combine() method">
```js
({ Point, points, Path, paths, part }) => {
points.A1 = new Point(0, 0)
points.A2 = new Point(60, 0)
points.B1 = new Point(0, 10)
points.B2 = new Point(60, 10)
points.C1 = new Point(0, 20)
points.C2 = new Point(60, 20)
paths.path1 = new Path()
.move(points.A1)
.line(points.A2)
.setClass("various")
paths.path2 = new Path()
.move(points.B1)
.line(points.B2)
.setClass("note")
paths.path3 = new Path()
.move(points.C1)
.line(points.C2)
.setClass("canvas")
paths.combo = paths.path1
.combine(paths.path2, paths.path3)
.setClass("lining dotted")
return part
}
```
</Example>
## Notes
`Path.combine()` method is _variadic_, so you can pass multiple paths to join

35
markdown/dev/reference/api/path/join/en.md
View file

@ -2,7 +2,11 @@
title: Path.join()
---
The `Path.join()` method joins this path with another path.
The `Path.join()` method joins this path with one or more other paths.
Any gaps in the path (caused by move operations) will be filled-in with a line.
If that's not what you want, you should use
[`Path.combine()`](/reference/api/path/combine) instead.
## Signature
@ -17,24 +21,30 @@ Path path.join(path other)
```js
({ Point, points, Path, paths, part }) => {
points.A = new Point(45, 60)
points.B = new Point(10, 30)
points.BCp2 = new Point(40, 20)
points.C = new Point(90, 30)
points.CCp1 = new Point(50, -30)
points.A1 = new Point(0, 0)
points.A2 = new Point(60, 0)
points.B1 = new Point(0, 10)
points.B2 = new Point(60, 10)
points.C1 = new Point(0, 20)
points.C2 = new Point(60, 20)
paths.path1 = new Path()
.move(points.A)
.line(points.B)
.move(points.A1)
.line(points.A2)
.setClass("various")
paths.path2 = new Path()
.move(points.B)
.curve(points.BCp2, points.CCp1, points.C)
.move(points.B1)
.line(points.B2)
.setClass("note")
paths.path3 = new Path()
.move(points.C1)
.line(points.C2)
.setClass("canvas")
paths.joint = paths.path1
.join(paths.path2)
.join(paths.path2, paths.path3)
.setClass("lining dotted")
return part
@ -45,4 +55,5 @@ Path path.join(path other)
## Notes
You cannot join a closed path to another path
- `Path.join()` is _variadic_, so you can pass multiple paths to join
- You cannot join a closed path to another path

57
markdown/dev/reference/api/path/length/en.md
View file

@ -7,50 +7,43 @@ The `Path.length()` method returns the length of the path.
## Signature
```js
float path.length()
float path.length(bool withMoves = false)
```
## Example
<Example caption="Example of the Path.length() method">
```js
({ Point, points, Path, paths, macro, utils, units, part }) => {
({ Point, points, Path, paths, units, part }) => {
points.A = new Point(45, 60)
points.B = new Point(10, 30)
points.BCp2 = new Point(40, 20)
points.C = new Point(90, 30)
points.CCp1 = new Point(50, -30)
points.A1 = new Point(0, 0)
points.A2 = new Point(160, 0)
points.B1 = new Point(0, 10)
points.B2 = new Point(160, 10)
points.C1 = new Point(0, 20)
points.C2 = new Point(160, 20)
paths.AB = new Path()
.move(points.A)
.line(points.B)
paths.path1 = new Path()
.move(points.A1)
.line(points.A2)
.move(points.B1)
.line(points.B2)
.move(points.C1)
.line(points.C2)
.setClass("various")
paths.BC = new Path()
.move(points.B)
.curve(points.BCp2, points.CCp1, points.C)
points.label1 = new Point(25, 8).addText('Total length = ' + units(paths.path1.length()))
points.label2 = new Point(25, 18).addText('Total length with moves = ' + units(paths.path1.length(true)))
const lengthABC = paths.AB.length() + paths.BC.length()
macro("pd", {
path: new Path().move(points.B).line(points.A),
d: 10
})
macro("pd", {
path: new Path().move(points.B).curve(points.BCp2, points.CCp1, points.C),
d: -10
})
points.label = new Point(25, 40)
.addText('Total length = ' + units(lengthABC))
// Set a path to prevent clipping
paths.noclip = new Path()
.move(new Point(10, -15))
.move(new Point(90, 60))
return part
}
```
</Example>
## Notes
By default, `Path.length()` will measure the combined length of all drawing operations in the Path, but skip
over gaps in the path (caused by move operations).
If you want the full length of the Path, including move operations, pass `true` to `Path.length()`.