VSinerva/freesewing
1
0
Fork 0
Code Activity

chore(markdown): Updated utils docs for v3

Browse source
This commit is contained in:
Joost De Cock 2022-10-01 22:20:43 +02:00
parent acf1b72c4c
commit bc3b0cd770
23 changed files with 782 additions and 622 deletions
Download patch file Download diff file Expand all files Collapse all files

116
markdown/dev/reference/api/utils/beamintersectscircle/en.md
View file

@ -1,20 +1,23 @@
---
title: beamIntersectsCircle()
title: utils.beamIntersectsCircle()
---
The `utils.beamIntersectsCircle()` function finds the intersection between an
endless line through points `point1` and `point2` and a circle with its center
at point `center` and a radius of `radius` mm.
## Signature
```js
array | false utils.beamIntersectsCircle(
Point center,
float radius,
Point point1,
Point point1,
string sort = 'x'
string sort=x
)
```
Finds the intersection between an endless line through points `point1` and `point2`
and a circle with its center at point `center` and a radius of `radius` mm.
The 5th and last parameter controls the _sorting_ of the found intersections.
This will (almost) always return 2 intersections, and you can choose how
they are ordered in the returned array:
@ -24,59 +27,54 @@ Set sort to:
- `x` : The point with the lowest X-coordinate will go first (left to right)
- `y` : The point with the lowest Y-coordinate will go first (top to bottom)
<Example part="utils_beamintersectscircle">
A Utils.beamIntersectsCircle() example
## Example
<Example caption="A utils.beamIntersectsCircle() example">
```js
({ Point, points, Path, paths, Snippet, snippets, utils, part }) => {
points.A = new Point(45, 45)
.addCircle(35, "Fabric")
points.B = new Point(5, 50);
points.C = new Point(25, 30);
points.D = new Point(5, 65);
points.E = new Point(65, 5);
points.F = new Point(15, 75);
points.G = new Point(75, 15);
paths.line1 = new Path().move(points.B).line(points.C);
paths.line2 = new Path().move(points.D).line(points.E);
paths.line3 = new Path().move(points.F).line(points.G);
let intersections1 = utils.beamIntersectsCircle(
points.A,
points.A.attributes.get("data-circle"),
points.B,
points.C
);
let intersections2 = utils.beamIntersectsCircle(
points.A,
points.A.attributes.get("data-circle"),
points.D,
points.E,
"y"
);
let intersections3 = utils.beamIntersectsCircle(
points.A,
points.A.attributes.get("data-circle"),
points.F,
points.G
);
snippets.first1 = new Snippet("bnotch", intersections1[0]);
snippets.second1 = new Snippet("notch", intersections1[1]);
snippets.first2 = new Snippet("bnotch", intersections2[0]);
snippets.second2 = new Snippet("notch", intersections2[1]);
snippets.first3 = new Snippet("bnotch", intersections3[0]);
snippets.second3 = new Snippet("notch", intersections3[1]);
return part
}
```
</Example>
```js
let {
Point,
points,
Path,
paths,
Snippet,
snippets,
utils
} = part.shorthand();
points.A = new Point(45, 45)
.attr("data-circle", 35)
.attr("data-circle-class", "fabric");
points.B = new Point(5, 50);
points.C = new Point(25, 30);
points.D = new Point(5, 65);
points.E = new Point(65, 5);
points.F = new Point(15, 75);
points.G = new Point(75, 15);
paths.line1 = new Path().move(points.B).line(points.C);
paths.line2 = new Path().move(points.D).line(points.E);
paths.line3 = new Path().move(points.F).line(points.G);
let intersections1 = utils.beamIntersectsCircle(
points.A,
points.A.attributes.get("data-circle"),
points.B,
points.C
);
let intersections2 = utils.beamIntersectsCircle(
points.A,
points.A.attributes.get("data-circle"),
points.D,
points.E,
"y"
);
let intersections3 = utils.beamIntersectsCircle(
points.A,
points.A.attributes.get("data-circle"),
points.F,
points.G
);
snippets.first1 = new Snippet("bnotch", intersections1[0]);
snippets.second1 = new Snippet("notch", intersections1[1]);
snippets.first2 = new Snippet("bnotch", intersections2[0]);
snippets.second2 = new Snippet("notch", intersections2[1]);
snippets.first3 = new Snippet("bnotch", intersections3[0]);
snippets.second3 = new Snippet("notch", intersections3[1]);
```

44
markdown/dev/reference/api/utils/beamintersectsx/en.md
View file

@ -1,38 +1,40 @@
---
title: beamIntersectsX()
title: utils.beamIntersectsX()
---
The `utils.beamIntersectsX()` function finds the intersection between an endless
line and a given X-value. Returns a [Point](/reference/api/point) object for
the intersection, or `false` there is no intersection.
## Signature
```js
Point | false utils.beamIntersectsX(Point A, Point B, float X)
```
Finds the intersection between an endless line and a given X-value. Returns a [Point](/reference/api/point) object
for the intersection, or `false` there is no intersection.
<Example part="utils_beamintersectsx">
A Utils.beamIntersectsX() example
</Example>
## Example
<Example caption="A Utils.beamIntersectsX() example">
```js
let {
Point,
points,
Path,
paths,
Snippet,
snippets,
utils
} = part.shorthand();
({ Point, points, Path, paths, Snippet, snippets, utils, part }) => {
points.A = new Point(10, 10);
points.B = new Point(90, 30);
points.A = new Point(10, 10)
points.B = new Point(90, 30)
paths.AB = new Path().move(points.A).line(points.B);
paths.AB = new Path().move(points.A).line(points.B)
snippets.x = new Snippet("notch", utils.beamIntersectsX(points.A, points.B, 40));
snippets.x = new Snippet(
"notch",
utils.beamIntersectsX(points.A, points.B, 40)
)
paths.help = new Path()
.move(new Point(40, 5))
.line(new Point(40, 35))
.attr("class", "note dashed");
.addClass("note dashed")
return part
}
```
</Example>

58
markdown/dev/reference/api/utils/beamintersectsy/en.md
View file

@ -1,38 +1,40 @@
---
title: beamIntersectsY()
title: utils.beamIntersectsY()
---
The `utils.beamIntersectsY()` function finds the intersection between an endless
line and a given Y-value. Returns a [Point](/reference/api/point) object for
the intersection, or `false` there is no intersection.
## Signature
```js
Point | false utils.beamIntersectsY(Point A, Point B, float Y)
```
Finds the intersection between an endless line and a given Y-value. Returns a [Point](/reference/api/point) object
for the intersection, or `false` there is no intersection.
## Example
<Example part="utils_beamintersectsy">
A Utils.beamIntersectsY() example
<Example caption="A Utils.beamIntersectsY() example">
```js
({ Point, points, Path, paths, Snippet, snippets, utils, part }) => {
points.A = new Point(10, 10)
points.B = new Point(50, 40)
paths.AB = new Path().move(points.A).line(points.B)
snippets.x = new Snippet(
"notch",
utils.beamIntersectsY(points.A, points.B, 30)
)
paths.help = new Path()
.move(new Point(0, 30))
.line(new Point(50, 30))
.attr("class", "note dashed")
return part
}
```
</Example>
```js
let {
Point,
points,
Path,
paths,
Snippet,
snippets,
utils
} = part.shorthand();
points.A = new Point(10, 10);
points.B = new Point(50, 40);
paths.AB = new Path().move(points.A).line(points.B);
snippets.x = new Snippet("notch", utils.beamIntersectsY(points.A, points.B, 30));
paths.help = new Path()
.move(new Point(0, 30))
.line(new Point(50, 30))
.attr("class", "note dashed");
```

57
markdown/dev/reference/api/utils/beamsintersect/en.md
View file

@ -1,7 +1,13 @@
---
title: beamsIntersect()
title: uils.beamsIntersect()
---
The `utils.beamsIntersect()` function finds the intersection between two endless
lines (beams). Returns a [Point](/reference/api/point) object for the
intersection, or `false` if the lines don't intersect.
## Signature
```js
Point | false utils.beamsIntersect(
Point A,
@ -11,34 +17,27 @@ Point | false utils.beamsIntersect(
)
```
Finds the intersection between two endless lines (beams). Returns a [Point](/reference/api/point) object
for the intersection, or `false` if the lines don't intersect.
## Example
<Example part="utils_beamsintersect">
A Utils.beamIntersect() example
<Example caption="A Utils.beamIntersect() example">
```js
({ Point, points, Path, paths, Snippet, snippets, utils, part }) => {
points.A = new Point(10, 10)
points.B = new Point(50, 40)
points.C = new Point(45, 20)
points.D = new Point(60, 15)
paths.AB = new Path().move(points.A).line(points.B)
paths.CD = new Path().move(points.C).line(points.D)
snippets.x = new Snippet(
"notch",
utils.beamsIntersect(points.A, points.B, points.C, points.D)
)
return part
}
```
</Example>
```js
let {
Point,
points,
Path,
paths,
Snippet,
snippets,
utils
} = part.shorthand();
points.A = new Point(10, 10);
points.B = new Point(50, 40);
points.C = new Point(45, 20);
points.D = new Point(60, 15);
paths.AB = new Path().move(points.A).line(points.B);
paths.CD = new Path().move(points.C).line(points.D);
snippets.x = new Snippet(
"notch",
utils.beamsIntersect(points.A, points.B, points.C, points.D)
);
```

19
markdown/dev/reference/api/utils/capitalize/en.md Normal file
View file

@ -0,0 +1,19 @@
---
title: utils.capitalize()
---
The `utils.capitalize()` function returns the string you pass it with its first
letter turned into uppercase.
## Signature
```js
String utils.capitalize(String input)
```
## Example
```js
capitalize('hello') // returns 'Hello')
capitalize('hello there') // returns 'Hello there'
```

83
markdown/dev/reference/api/utils/circlesintersect/en.md
View file

@ -1,7 +1,12 @@
---
title: circlesIntersect()
title: utils.circlesIntersect()
---
The `utils.circlesIntersect()` function finds the intersections between two
circles described by their center point and radius.
## Signature
```js
array | false utils.circlesIntersect(
Point centerA,
@ -12,8 +17,6 @@ array | false utils.circlesIntersect(
)
```
Finds the intersections between two circles described by their center point and radius.
The 5th and last parameter controls the _sorting_ of the found intersections.
When this returns 2 intersections, you can choose how they are ordered in the returned array:
@ -22,42 +25,42 @@ Set sort to:
- `x` : The point with the lowest X-coordinate will go first (left to right)
- `y` : The point with the lowest Y-coordinate will go first (top to bottom)
<Example part="utils_circlesintersect">
A Utils.circlesIntersect() example
## Example
<Example caption="A Utils.circlesIntersect() example">
```js
({ Point, points, Snippet, snippets, utils, part }) => {
points.A = new Point(10, 10)
.addCircle(15, "fabric")
points.B = new Point(30, 30)
.addCircle(35, "fabric")
points.C = new Point(90, 10)
.addCircle(15, "various")
points.D = new Point(110, 30)
.addCircle(35, "various")
const intersections1 = utils.circlesIntersect(
points.A,
points.A.attributes.get("data-circle"),
points.B,
points.B.attributes.get("data-circle")
)
const intersections2 = utils.circlesIntersect(
points.C,
points.C.attributes.get("data-circle"),
points.D,
points.D.attributes.get("data-circle"),
"y"
)
snippets.first1 = new Snippet("bnotch", intersections1[0])
snippets.second1 = new Snippet("notch", intersections1[1])
snippets.first2 = new Snippet("bnotch", intersections2[0])
snippets.second2 = new Snippet("notch", intersections2[1])
return part
}
```
</Example>
```js
let { Point, points, Snippet, snippets, utils } = part.shorthand();
points.A = new Point(10, 10)
.attr("data-circle", 15)
.attr("data-circle-class", "fabric");
points.B = new Point(30, 30)
.attr("data-circle", 35)
.attr("data-circle-class", "fabric");
points.C = new Point(90, 10)
.attr("data-circle", 15)
.attr("data-circle-class", "various");
points.D = new Point(110, 30)
.attr("data-circle", 35)
.attr("data-circle-class", "various");
let intersections1 = utils.circlesIntersect(
points.A,
points.A.attributes.get("data-circle"),
points.B,
points.B.attributes.get("data-circle")
);
let intersections2 = utils.circlesIntersect(
points.C,
points.C.attributes.get("data-circle"),
points.D,
points.D.attributes.get("data-circle"),
"y"
);
snippets.first1 = new Snippet("bnotch", intersections1[0]);
snippets.second1 = new Snippet("notch", intersections1[1]);
snippets.first2 = new Snippet("bnotch", intersections2[0]);
snippets.second2 = new Snippet("notch", intersections2[1]);
```

98
markdown/dev/reference/api/utils/curveintersectsx/en.md
View file

@ -1,7 +1,12 @@
---
title: curveIntersectsX()
title: utils.curveIntersectsX()
---
The `utils.curveIntersectsX()` function finds the point(s) where a curve
intersects a given X-value.
## Signature
```js
array | Point | false utils.curveIntersectsX(
Point start,
@ -11,61 +16,60 @@ array | Point | false utils.curveIntersectsX(
float x)
```
Finds the point(s) where a curve intersects a given X-value.
This is a low-level variant
of [`Path.intersectsX()`](/reference/api/path/intersectsx).
Instead of a path, you describe a single curve by passing the four
points that describes it.
This returns `false` if no intersections are found,
a [Point](/reference/api/point) object if
a single intersection is found, and an array
of [Point](/reference/api/point) objects if
multiple intersections are found.
<Example part="utils_curveintersectsx">A Utils.curveIntersectX() example</Example>
## Example
<Example caption="A Utils.curveIntersectX() example">
```js
let {
Point,
points,
Path,
paths,
utils,
snippets,
Snippet
} = part.shorthand();
({ Point, points, Path, paths, Snippet, snippets, utils, part }) => {
points.start = new Point(10, 15);
points.cp1 = new Point(80, 10);
points.cp2 = new Point(-50, 80);
points.end = new Point(110, 70);
points.start = new Point(10, 15)
points.cp1 = new Point(80, 10)
points.cp2 = new Point(-50, 80)
points.end = new Point(110, 70)
paths.curve = new Path()
.move(points.start)
.curve(points.cp1, points.cp2, points.end)
for (let x of [30, 40]) {
points["from" + x] = new Point(x, 10)
points["to" + x] = new Point(x, 80)
paths["line" + x] = new Path()
.move(points["from" + x])
.line(points["to" + x])
.addClass("lining dashed")
}
snippets.i40 = new Snippet(
"notch",
utils.curveIntersectsX(points.start, points.cp1, points.cp2, points.end, 40)
)
for (let p of utils.curveIntersectsX(
points.start,
points.cp1,
points.cp2,
points.end,
30
))
snippets[p.y] = new Snippet("notch", p)
paths.curve = new Path()
.move(points.start)
.curve(points.cp1, points.cp2, points.end);
for (let x of [30, 40]) {
points["from" + x] = new Point(x, 10);
points["to" + x] = new Point(x, 80);
paths["line" + x] = new Path()
.move(points["from" + x])
.line(points["to" + x])
.attr("class", "lining dashed");
return part
}
snippets.i40 = new Snippet(
"notch",
utils.curveIntersectsX(points.start, points.cp1, points.cp2, points.end, 40)
);
for (let p of utils.curveIntersectsX(
points.start,
points.cp1,
points.cp2,
points.end,
30
))
snippets[p.y] = new Snippet("notch", p);
```
</Example>
## Notes
This is a low-level (and faster) variant
of [`Path.intersectsX()`](/reference/api/path/intersectsx).
Instead of a path, you describe a single curve by passing the four
points that describes it.

98
markdown/dev/reference/api/utils/curveintersectsy/en.md
View file

@ -1,7 +1,12 @@
---
title: curveIntersectsY()
title: utils.curveIntersectsY()
---
The `utils.curveIntersectsX()` function finds the point(s) where a curve
intersects a given Y-value.
## Signature
```js
array | Point | false utils.curveIntersectsY(
Point start,
@ -11,61 +16,60 @@ array | Point | false utils.curveIntersectsY(
float y)
```
Finds the point(s) where a curve intersects a given Y-value.
This is a low-level variant
of [`Path.intersectsY()`](/reference/api/path/intersectsy).
Instead of a path, you describe a single curve by passing the four
points that describes it.
This returns `false` if no intersections are found,
a [Point](/reference/api/point/) object if
a single intersection is found, and an array
of [Point](/reference/api/point/) objects if
multiple intersections are found.
<Example part="utils_curveintersectsy">A Utils.curveIntersectY() example</Example>
## Example
<Example caption="A Utils.curveIntersectY() example">
```js
let {
Point,
points,
Path,
paths,
utils,
snippets,
Snippet
} = part.shorthand();
({ Point, points, Path, paths, Snippet, snippets, utils, part }) => {
points.start = new Point(10, 45);
points.cp1 = new Point(50, 10);
points.cp2 = new Point(0, 80);
points.end = new Point(110, 70);
points.start = new Point(10, 45)
points.cp1 = new Point(50, 10)
points.cp2 = new Point(0, 80)
points.end = new Point(110, 70)
paths.curve = new Path()
.move(points.start)
.curve(points.cp1, points.cp2, points.end)
for (let y of [40, 50]) {
points["from" + y] = new Point(10, y)
points["to" + y] = new Point(110, y)
paths["line" + y] = new Path()
.move(points["from" + y])
.line(points["to" + y])
.addClass("lining dashed")
}
snippets.i50 = new Snippet(
"notch",
utils.curveIntersectsY(points.start, points.cp1, points.cp2, points.end, 50)
)
for (let p of utils.curveIntersectsY(
points.start,
points.cp1,
points.cp2,
points.end,
40
))
snippets[p.x] = new Snippet("notch", p)
paths.curve = new Path()
.move(points.start)
.curve(points.cp1, points.cp2, points.end);
for (let y of [40, 50]) {
points["from" + y] = new Point(10, y);
points["to" + y] = new Point(110, y);
paths["line" + y] = new Path()
.move(points["from" + y])
.line(points["to" + y])
.attr("class", "lining dashed");
return part
}
snippets.i50 = new Snippet(
"notch",
utils.curveIntersectsY(points.start, points.cp1, points.cp2, points.end, 50)
);
for (let p of utils.curveIntersectsY(
points.start,
points.cp1,
points.cp2,
points.end,
40
))
snippets[p.x] = new Snippet("notch", p);
```
</Example>
## Notes
This is a low-level (and faster) variant
of [`Path.intersectsY()`](/reference/api/path/intersectsy).
Instead of a path, you describe a single curve by passing the four
points that describes it.

81
markdown/dev/reference/api/utils/curvesintersect/en.md
View file

@ -1,7 +1,12 @@
---
title: curvesIntersect()
title: utils.curvesIntersect()
---
The `utils.curvesIntersect()` function finds the intersections between two curves
described by 4 points each.
## Signature
```js
array | false utils.curvesIntersect(
Point startA,
@ -14,49 +19,43 @@ array | false utils.curvesIntersect(
Point endB)
```
Finds the intersections between two curves described by 4 points each.
<Example part="utils_curvesintersect">
A Utils.curvesIntersect() example
</Example>
## Example
<Example caption="A Utils.curvesIntersect() example">
```js
let {
Point,
points,
Path,
paths,
Snippet,
snippets,
utils
} = part.shorthand();
({ Point, points, Path, paths, Snippet, snippets, utils, getId, part }) => {
points.A = new Point(10, 10);
points.Acp = new Point(310, 40);
points.B = new Point(110, 70);
points.Bcp = new Point(-210, 40);
points.A = new Point(10, 10)
points.Acp = new Point(310, 40)
points.B = new Point(110, 70)
points.Bcp = new Point(-210, 40)
points.C = new Point(20, -5)
points.Ccp = new Point(60, 300)
points.D = new Point(100, 85)
points.Dcp = new Point(70, -220)
paths.curveA = new Path()
.move(points.A)
.curve(points.Acp, points.Bcp, points.B)
paths.curveB = new Path()
.move(points.C)
.curve(points.Ccp, points.Dcp, points.D)
for (const p of utils.curvesIntersect(
points.A,
points.Acp,
points.Bcp,
points.B,
points.C,
points.Ccp,
points.Dcp,
points.D
)) {
snippets[getId()] = new Snippet("notch", p)
}
points.C = new Point(20, -5);
points.Ccp = new Point(60, 300);
points.D = new Point(100, 85);
points.Dcp = new Point(70, -220);
paths.curveA = new Path()
.move(points.A)
.curve(points.Acp, points.Bcp, points.B);
paths.curveB = new Path()
.move(points.C)
.curve(points.Ccp, points.Dcp, points.D);
for (let p of utils.curvesIntersect(
points.A,
points.Acp,
points.Bcp,
points.B,
points.C,
points.Ccp,
points.Dcp,
points.D
)) {
snippets[part.getId()] = new Snippet("notch", p);
return part
}
```
</Example>

10
markdown/dev/reference/api/utils/deg2rad/en.md
View file

@ -1,12 +1,16 @@
---
title: deg2rad()
title: utils.deg2rad()
---
The `utils.deg2read()` function returns the degrees you pass to it as radians.
## Signature
```js
float deg2rad(float degrees)
```
Returns the degrees you pass to it as radians.
## Notes
This is useful for when you use methods like `Math.cos()` that expects a corner
This is useful for when you use functions like `Math.cos()` that expect a corner
in radians, when we typically use degrees.

7
markdown/dev/reference/api/utils/en.md
View file

@ -1,7 +1,10 @@
---
title: Utils
title: utils
---
The `Utils` object provides the following utility methods to facilitate your work:
The `utils` object is a plain object that bundles utility functions to
facilitate parametric design.
The following functions are provided by the `utils` object:
<ReadMore list />

112
markdown/dev/reference/api/utils/lineintersectscircle/en.md
View file

@ -1,7 +1,13 @@
---
title: lineIntersectsCircle()
title: utils.lineIntersectsCircle()
---
The `utils.lineIntersectsCircle()` function finds the intersection between a line
segment from point `from` to point `to` and a circle with its center at point
`center` and a radius of `radius` mm.
## Signature
```js
array | false utils.lineIntersectsCircle(
Point center,
@ -12,9 +18,6 @@ array | false utils.lineIntersectsCircle(
)
```
Finds the intersection between a line segment from point `from` to point `to`
and a circle with its center at point `center` and a radius of `radius` mm.
The 5th and last parameter controls the _sorting_ of the found intersections.
When this returns 2 intersections, you can choose how they are ordered in the returned array:
@ -23,58 +26,53 @@ Set sort to:
- `x` : The point with the lowest X-coordinate will go first (left to right)
- `y` : The point with the lowest Y-coordinate will go first (top to bottom)
<Example part="utils_lineintersectscircle">
A Utils.lineIntersectsCircle() example
## Example
<Example caption="A Utils.lineIntersectsCircle() example">
```js
({ Point, points, Path, paths, Snippet, snippets, utils, part }) => {
points.A = new Point(95, 45)
.addCircle(35, "fabric")
points.B = new Point(55, 50)
points.C = new Point(75, 30)
points.D = new Point(55, 65)
points.E = new Point(115, 5)
points.F = new Point(65, 75)
points.G = new Point(125, 15)
paths.line1 = new Path().move(points.B).line(points.C)
paths.line2 = new Path().move(points.D).line(points.E)
paths.line3 = new Path().move(points.F).line(points.G)
const intersections1 = utils.lineIntersectsCircle(
points.A,
points.A.attributes.get("data-circle"),
points.B,
points.C
)
const intersections2 = utils.lineIntersectsCircle(
points.A,
points.A.attributes.get("data-circle"),
points.D,
points.E,
"y"
)
const intersections3 = utils.lineIntersectsCircle(
points.A,
points.A.attributes.get("data-circle"),
points.F,
points.G
)
snippets.first1 = new Snippet("bnotch", intersections1[0])
snippets.first2 = new Snippet("bnotch", intersections2[0])
snippets.second2 = new Snippet("notch", intersections2[1])
snippets.first3 = new Snippet("bnotch", intersections3[0])
snippets.second3 = new Snippet("notch", intersections3[1])
return part
}
```
</Example>
```js
let {
Point,
points,
Path,
paths,
Snippet,
snippets,
utils
} = part.shorthand();
points.A = new Point(95, 45)
.attr("data-circle", 35)
.attr("data-circle-class", "fabric");
points.B = new Point(55, 50);
points.C = new Point(75, 30);
points.D = new Point(55, 65);
points.E = new Point(115, 5);
points.F = new Point(65, 75);
points.G = new Point(125, 15);
paths.line1 = new Path().move(points.B).line(points.C);
paths.line2 = new Path().move(points.D).line(points.E);
paths.line3 = new Path().move(points.F).line(points.G);
let intersections1 = utils.lineIntersectsCircle(
points.A,
points.A.attributes.get("data-circle"),
points.B,
points.C
);
let intersections2 = utils.lineIntersectsCircle(
points.A,
points.A.attributes.get("data-circle"),
points.D,
points.E,
"y"
);
let intersections3 = utils.lineIntersectsCircle(
points.A,
points.A.attributes.get("data-circle"),
points.F,
points.G
);
snippets.first1 = new Snippet("bnotch", intersections1[0]);
snippets.first2 = new Snippet("bnotch", intersections2[0]);
snippets.second2 = new Snippet("notch", intersections2[1]);
snippets.first3 = new Snippet("bnotch", intersections3[0]);
snippets.second3 = new Snippet("notch", intersections3[1]);
```

69
markdown/dev/reference/api/utils/lineintersectscurve/en.md
View file

@ -1,7 +1,13 @@
---
title: lineIntersectsCurve()
title: utils.lineIntersectsCurve()
---
The `utils.lineIntersectsCurve()` function finds the intersection between a line
segment from point `from` to point `to` and a curve described by points
`start`, `cp1`, `cp2, and `end\`.
## Signature
```js
array | false utils.lineIntersectsCurve(
Point from,
@ -13,43 +19,36 @@ array | false utils.lineIntersectsCurve(
)
```
Finds the intersection between a line segment from point `from` to point `to`
and a curve described by points `start`, `cp1`, `cp2, and `end\`.
<Example part="utils_lineintersectscurve">
A Utils.lineIntersectsCurve() example
</Example>
## Example
<Example caption="A Utils.lineIntersectsCurve() example">
```js
let {
Point,
points,
Path,
paths,
Snippet,
snippets,
utils
} = part.shorthand();
({ Point, points, Path, paths, Snippet, snippets, getId, utils, part }) => {
points.A = new Point(10, 10);
points.Acp = new Point(310, 40);
points.B = new Point(110, 70);
points.Bcp = new Point(-210, 40);
points.E = new Point(20, -5);
points.D = new Point(100, 85);
paths.curve = new Path()
.move(points.A)
.curve(points.Acp, points.Bcp, points.B);
paths.line = new Path().move(points.E).line(points.D);
points.A = new Point(10, 10)
points.Acp = new Point(310, 40)
points.B = new Point(110, 70)
points.Bcp = new Point(-210, 40)
points.E = new Point(20, -5)
points.D = new Point(100, 85)
paths.curve = new Path()
.move(points.A)
.curve(points.Acp, points.Bcp, points.B)
paths.line = new Path().move(points.E).line(points.D)
for (let p of utils.lineIntersectsCurve(
points.D,
points.E,
points.A,
points.Acp,
points.Bcp,
points.B
)) {
snippets[getId()] = new Snippet("notch", p)
}
for (let p of utils.lineIntersectsCurve(
points.D,
points.E,
points.A,
points.Acp,
points.Bcp,
points.B
)) {
snippets[part.getId()] = new Snippet("notch", p);
return part
}
```
</Example>

57
markdown/dev/reference/api/utils/linesintersect/en.md
View file

@ -1,7 +1,13 @@
---
title: linesIntersect()
title: utils.linesIntersect()
---
The `utils.linesInersect()` function finds the intersection between two line
segments. Returns a [Point](../point) object for the intersection, or `false`
if the lines don't intersect.
## Signature
```js
Point | false utils.linesIntersect(
Point A,
@ -11,34 +17,27 @@ Point | false utils.linesIntersect(
)
```
Finds the intersection between two line segments. Returns a [Point](../point) object
for the intersection, or `false` if the lines don't intersect.
## Example
<Example part="utils_linesintersect">
A Utils.linesIntersect() example
<Example caption="A Utils.linesIntersect() example">
```js
({ Point, points, Path, paths, Snippet, snippets, utils, part }) => {
points.A = new Point(10, 10)
points.B = new Point(50, 40)
points.C = new Point(15, 30)
points.D = new Point(60, 15)
paths.AB = new Path().move(points.A).line(points.B)
paths.CD = new Path().move(points.C).line(points.D)
snippets.X = new Snippet(
"notch",
utils.linesIntersect(points.A, points.B, points.C, points.D)
)
return part
}
```
</Example>
```js
let {
Point,
points,
Path,
paths,
Snippet,
snippets,
utils
} = part.shorthand();
points.A = new Point(10, 10);
points.B = new Point(50, 40);
points.C = new Point(15, 30);
points.D = new Point(60, 15);
paths.AB = new Path().move(points.A).line(points.B);
paths.CD = new Path().move(points.C).line(points.D);
snippets.X = new Snippet(
"notch",
utils.linesIntersect(points.A, points.B, points.C, points.D)
);
```

35
markdown/dev/reference/api/utils/pctbasedon/en.md Normal file
View file

@ -0,0 +1,35 @@
---
title: utils.pctBasedOn()
---
The `utils.pctBasedOn()` function is a helper function to be used when
configuring [snapped percentage
options](/reference/api/part/config/options/pct/snap).
## Signature
```js
object utils.pctBasedOn(String measurement)
```
## Example
```js
const options = {
example: {
pct: 12,
min: 5,
max: 18,
snap: 3,
...pctBasedOn('chest')
}
}
```
## Notes
This will return an object with `toAbs` and `fromAbs` properties that calculate
the option's absolute and relative values based on a measurment. Refer to
[snapped percentage options](/reference/api/part/config/options/pct/snap) for
more details.

125
markdown/dev/reference/api/utils/pointonbeam/en.md
View file

@ -1,7 +1,13 @@
---
title: pointOnBeam()
title: utils.pointOnBeam()
---
The `utils.pointOnBeam()` function returns `true` if the point `check` lies on
the endless line that goes through `point1` and `point2`.
## Signature
```js
bool utils.pointOnBeam(
Point point1,
@ -11,73 +17,64 @@ bool utils.pointOnBeam(
)
```
Returns `true` if the point `check` lies on the endless line that goes through `point1` and `point2`.
The fourth parameter controls the precision. Lower numbers make the check less precise.
<Note>
## Example
###### Tweak precision only when needed
<Example caption="A Utils.pointOnBeam() example">
```js
({ Point, points, Path, paths, Snippet, snippets, getId, utils, part }) => {
Typically, you don't need to worry about precision. But occasionally, you may get
unexpected results because of floating point errors, rounding errors, or
points.from1 = new Point(10, 10)
points.to1 = new Point(90, 60)
points.from2 = new Point(10, 30)
points.to2 = new Point(90, 80)
points.b1 = new Point(170, 110)
points.b2 = new Point(170, 130)
const scatter = []
for (let i = 1; i < 36; i++) {
for (let j = 1; j < 27; j++) {
scatter.push(new Point(i * 10, j * 10))
}
}
let snippet
for (let point of scatter) {
if (utils.pointOnBeam(points.from1, points.to1, point)) snippet = "notch"
else snippet = "bnotch"
snippets[getId()] = new Snippet(snippet, point)
if (utils.pointOnBeam(points.from2, points.to2, point, 0.01)) {
snippet = "notch"
} else snippet = "bnotch"
snippets[getId()] = new Snippet(snippet, point)
}
paths.line1 = new Path()
.move(points.from1)
.line(points.to1)
.addClass("fabric stroke-lg")
paths.lne1 = new Path()
.move(points.to1)
.line(points.b1)
.addClass("fabric dashed")
paths.line2 = new Path()
.move(points.from2)
.line(points.to2)
.addClass("fabric stroke-lg")
paths.lne2 = new Path()
.move(points.to2)
.line(points.b2)
.addClass("fabric dashed")
return part
}
```
</Example>
## Notes
Typically, you don't need to worry about precision. But occasionally, you may
get unexpected results because of floating point errors, rounding errors, or
cubic bezier juggling.
When that happens, you can lower the precision so you get what you expect.
</Note>
<Example part="utils_pointonbeam">
A Utils.pointOnBeam() example
</Example>
```js
let {
Point,
points,
Path,
paths,
Snippet,
snippets,
utils
} = part.shorthand();
points.from1 = new Point(10, 10);
points.to1 = new Point(90, 60);
points.from2 = new Point(10, 30);
points.to2 = new Point(90, 80);
points.b1 = new Point(170, 110);
points.b2 = new Point(170, 130);
let scatter = [];
for (let i = 1; i < 36; i++) {
for (let j = 1; j < 27; j++) {
scatter.push(new Point(i * 10, j * 10));
}
}
let snippet;
for (let point of scatter) {
if (utils.pointOnBeam(points.from1, points.to1, point)) snippet = "notch";
else snippet = "bnotch";
snippets[part.getId()] = new Snippet(snippet, point);
if (utils.pointOnBeam(points.from2, points.to2, point, 0.01)) {
snippet = "notch";
} else snippet = "bnotch";
snippets[part.getId()] = new Snippet(snippet, point);
}
paths.line1 = new Path()
.move(points.from1)
.line(points.to1)
.attr("class", "fabric stroke-lg");
paths.lne1 = new Path()
.move(points.to1)
.line(points.b1)
.attr("class", "fabric dashed");
paths.line2 = new Path()
.move(points.from2)
.line(points.to2)
.attr("class", "fabric stroke-lg");
paths.lne2 = new Path()
.move(points.to2)
.line(points.b2)
.attr("class", "fabric dashed");
```

93
markdown/dev/reference/api/utils/pointoncurve/en.md
View file

@ -1,7 +1,12 @@
---
title: pointOnCurve()
title: utils.pointOnCurve()
---
The `utils.pointOnCurve()` function returns `true` if the point `check` lies on a
curve described by points `start`, `cp1`, `cp2`, and `end`.
## Signature
```js
bool utils.pointOnCurve(
Point start,
@ -12,57 +17,49 @@ bool utils.pointOnCurve(
)
```
Returns `true` if the point `check` lies on a curve described by points `start`, `cp1`, `cp2`, and `end`.
## Example
<Note>
<Example caption="A Utils.pointOnCurve() example">
```js
({ Point, points, Path, paths, Snippet, snippets, getId, utils, part }) => {
Keep in mind that calculations with Bezier curves are often aproximations.
points.start = new Point(10, 10)
points.cp1 = new Point(90, 10)
points.cp2 = new Point(10, 60)
points.end = new Point(90, 60)
const scatter = []
for (let i = 1; i < 19; i++) {
for (let j = 1; j < 14; j++) {
scatter.push(new Point(i * 10, j * 10))
}
}
let snippet
for (let point of scatter) {
if (
utils.pointOnCurve(
points.start,
points.cp1,
points.cp2,
points.end,
point
)
) {
snippet = "notch"
} else snippet = "bnotch"
snippets[getId()] = new Snippet(snippet, point)
}
paths.curve = new Path()
.move(points.start)
.curve(points.cp1, points.cp2, points.end)
.addClass("fabric stroke-lg")
</Note>
<Example part="utils_pointoncurve">
A Utils.pointOnCurve() example
return part
}
```
</Example>
```js
let {
Point,
points,
Path,
paths,
Snippet,
snippets,
utils
} = part.shorthand();
points.start = new Point(10, 10);
points.cp1 = new Point(90, 10);
points.cp2 = new Point(10, 60);
points.end = new Point(90, 60);
## Notes
let scatter = [];
for (let i = 1; i < 19; i++) {
for (let j = 1; j < 14; j++) {
scatter.push(new Point(i * 10, j * 10));
}
}
let snippet;
for (let point of scatter) {
if (
utils.pointOnCurve(
points.start,
points.cp1,
points.cp2,
points.end,
point
)
) {
snippet = "notch";
} else snippet = "bnotch";
snippets[part.getId()] = new Snippet(snippet, point);
}
paths.curve = new Path()
.move(points.start)
.curve(points.cp1, points.cp2, points.end)
.attr("class", "fabric stroke-lg");
```
Keep in mind that calculations with Bezier curves are often aproximations.

112
markdown/dev/reference/api/utils/pointonline/en.md
View file

@ -1,7 +1,12 @@
---
title: pointOnLine()
title: utils.pointOnLine()
---
The `utils.pointOnLine()` function returns `true` if the point `check` lies on a
line segment from point `from` to point `to`.
## Signature
```js
bool utils.pointOnLine(
Point from,
@ -11,62 +16,57 @@ bool utils.pointOnLine(
)
```
Returns `true` if the point `check` lies on a line segment from point `from` to point `to`.
The fourth parameter controls the precision.
See [pointOnBeam](/reference/api/utils/pointonbeam).
The fourth parameter controls the precision. See [pointOnBeam](/reference/api/utils/pointonbeam).
## Example
<Example part="utils_pointonline">
A Utils.pointOnLine() example
<Example caption="A Utils.pointOnLine() example">
```js
({ Point, points, Path, paths, Snippet, snippets, getId, utils, part }) => {
points.from1 = new Point(10, 10)
points.to1 = new Point(90, 60)
points.from2 = new Point(10, 30)
points.to2 = new Point(90, 80)
points.b1 = new Point(170, 110)
points.b2 = new Point(170, 130)
const scatter = []
for (let i = 1; i < 36; i++) {
for (let j = 1; j < 27; j++) {
scatter.push(new Point(i * 10, j * 10))
}
}
let snippet
for (let point of scatter) {
if (utils.pointOnLine(points.from1, points.to1, point)) snippet = "notch"
else snippet = "bnotch"
snippets[getId()] = new Snippet(snippet, point)
if (utils.pointOnLine(points.from2, points.to2, point, 0.01)) {
snippet = "notch"
} else snippet = "bnotch"
snippets[getId()] = new Snippet(snippet, point)
}
paths.line1 = new Path()
.move(points.from1)
.line(points.to1)
.addClass("fabric stroke-lg")
paths.lne1 = new Path()
.move(points.to1)
.line(points.b1)
.addClass("fabric dashed")
paths.line2 = new Path()
.move(points.from2)
.line(points.to2)
.addClass("fabric stroke-lg")
paths.lne2 = new Path()
.move(points.to2)
.line(points.b2)
.addClass("fabric dashed")
return part
}
```
</Example>
```js
let {
Point,
points,
Path,
paths,
Snippet,
snippets,
utils
} = part.shorthand();
points.from1 = new Point(10, 10);
points.to1 = new Point(90, 60);
points.from2 = new Point(10, 30);
points.to2 = new Point(90, 80);
points.b1 = new Point(170, 110);
points.b2 = new Point(170, 130);
let scatter = [];
for (let i = 1; i < 36; i++) {
for (let j = 1; j < 27; j++) {
scatter.push(new Point(i * 10, j * 10));
}
}
let snippet;
for (let point of scatter) {
if (utils.pointOnLine(points.from1, points.to1, point)) snippet = "notch";
else snippet = "bnotch";
snippets[part.getId()] = new Snippet(snippet, point);
if (utils.pointOnLine(points.from2, points.to2, point, 0.01)) {
snippet = "notch";
} else snippet = "bnotch";
snippets[part.getId()] = new Snippet(snippet, point);
}
paths.line1 = new Path()
.move(points.from1)
.line(points.to1)
.attr("class", "fabric stroke-lg");
paths.lne1 = new Path()
.move(points.to1)
.line(points.b1)
.attr("class", "fabric dashed");
paths.line2 = new Path()
.move(points.from2)
.line(points.to2)
.attr("class", "fabric stroke-lg");
paths.lne2 = new Path()
.move(points.to2)
.line(points.b2)
.attr("class", "fabric dashed");
```

7
markdown/dev/reference/api/utils/rad2deg/en.md
View file

@ -1,9 +1,12 @@
---
title: rad2deg()
title: utils.rad2deg()
---
The `utils.rad2dag()` function returns the radians you pass to it as degrees.
## Signature
```js
float rad2deg(float radians)
```
Returns the radians you pass to it as degrees.

14
markdown/dev/reference/api/utils/round/en.md
View file

@ -1,12 +1,18 @@
---
title: round()
title: utils.round()
---
The `utils.round()` function rounds a value to two decimals.
## Signature
```js
float utils.round(float value)
```
Rounds a value to two decimals. For example:
## Example
- 0.1234 becomes 0.12
- 5.6789 becomes 5.68
```js
utils.round(0.1234) // 0.12
utils.round(5.6789) // 5.68
```

81
markdown/dev/reference/api/utils/splitcurve/en.md Normal file
View file

@ -0,0 +1,81 @@
---
title: utils.splitCurve()
---
The `utils.splitCurve()` function splits a curve defined by 4 points `start`,
`cp1`, `cp2`, and `end` on the point `split` and returns an array holding both
halves.
## Signature
```js
array utils.splitCurve(
Point start,
Point cp1,
Point cp2,
Point end,
Point check,
)
```
## Example
<Example caption="A Utils.splitCurve() example">
```js
({ Point, points, Path, paths, utils, part }) => {
points.start = new Point(10, 10)
points.cp1 = new Point(100, 80)
points.cp2 = new Point(100, 0)
points.end = new Point(10, 50)
paths.example = new Path()
.move(points.start)
.curve(points.cp1, points.cp2, points.end)
.addClass('dotted stroke-xs')
points.split = paths.example.shiftFractionAlong(0.4)
const halves = utils.splitCurve(
points.start,
points.cp1,
points.cp2,
points.end,
points.split
)
for (let i=0; i<2; i++) {
const { start, cp1, cp2, end } = halves[i]
console.log({start, cp1, cp2,end})
paths[`segment${i}`] = new Path()
.move(start)
.curve(cp1, cp2, end)
.addClass('stroke-xl')
.attr('style', 'stroke-opacity: 0.5;')
}
paths.segment0.addClass('note')
paths.segment1.addClass('lining')
return part
}
```
</Example>
## Notes
The returned object has this signature:
```js
[
{
start: Point,
cp1: Point,
cp2: Point,
end: Point,
},
{
start: Point,
cp1: Point,
cp2: Point,
end: Point,
},
]

11
markdown/dev/reference/api/utils/stretchtoscale/en.md
View file

@ -1,17 +1,24 @@
---
title: stretchToScale()
title: utils.stretchToScale()
---
The `utils.stretchToScale()` function calculates the scale for a given amount of
stretch.
## Signature
```js
float utils.stretchToScale(float stretch)
```
## Notes
The way people measure stretch intuitively is different from the way we handle stretch in code.
When people say _25% stretch_ they mean that 10cm fabric gets stretched to 12.5cm fabric.
In code and on our patterns, that means we need to scale things by 80%.
This method does that by returning:
This function does that by returning:
```js
1 / (1 + parseFloat(stretch));

17
markdown/dev/reference/api/utils/units/en.md
View file

@ -1,18 +1,19 @@
---
title: units()
title: utils.units()
---
The `utils.units()` function converts the units `value` you pass it into a
formatted string for the `format` you pass it.
## Signature
```js
string utils.units(float value, string format = 'metric')
```
Converts the units `value` you pass it into a formatted string for the `format` you pass it.
Format must be either `imperial` or `metric` (the default).
<Tip>
## Notes
The [Part.shorthand](/reference/api/part/shorthand/) call provides a context-aware
`unit()` method that will call this method and pass it the units requested by the user.
</Tip>
A [part's `draft()` function](/reference/api/part/draft) receives a context-aware
`unit()` function that will call this function and pass it the units requested by the user.