From 1f7ba79f8123f66a96a34ad3219350584ea8d78c Mon Sep 17 00:00:00 2001 From: Joost De Cock Date: Tue, 20 Sep 2022 18:09:28 +0200 Subject: [PATCH] chore(markdown): Working on v3 docs --- markdown/dev/guides/v3/en.md | 6 + markdown/dev/reference/api/design/en.md | 57 +++++---- markdown/dev/reference/api/en.md | 83 +++++++++---- markdown/dev/reference/api/part/en.md | 113 ++++++++++++++++-- .../dev/reference/api/pattern/addpart/en.md | 44 +++++++ .../dev/reference/api/pattern/draft/en.md | 11 +- markdown/dev/reference/api/pattern/en.md | 73 ++++++++--- .../dev/reference/api/pattern/getconfig/en.md | 32 +++++ .../reference/api/pattern/getcutlist/en.md | 47 -------- .../api/pattern/getrenderprops/en.md | 54 ++++----- markdown/dev/reference/api/pattern/on/en.md | 4 +- .../dev/reference/api/pattern/render/en.md | 17 ++- .../dev/reference/api/pattern/sample/en.md | 58 +++------ .../api/pattern/samplemeasurement/en.md | 26 ++-- .../reference/api/pattern/samplemodels/en.md | 27 ++--- .../reference/api/pattern/sampleoption/en.md | 33 ++--- markdown/dev/reference/api/pattern/use/en.md | 20 ++-- 17 files changed, 433 insertions(+), 272 deletions(-) create mode 100644 markdown/dev/guides/v3/en.md create mode 100644 markdown/dev/reference/api/pattern/addpart/en.md create mode 100644 markdown/dev/reference/api/pattern/getconfig/en.md delete mode 100644 markdown/dev/reference/api/pattern/getcutlist/en.md diff --git a/markdown/dev/guides/v3/en.md b/markdown/dev/guides/v3/en.md new file mode 100644 index 00000000000..ddd273a56d2 --- /dev/null +++ b/markdown/dev/guides/v3/en.md @@ -0,0 +1,6 @@ +--- +title: Migration guide +--- + +- named exports +- ESM only diff --git a/markdown/dev/reference/api/design/en.md b/markdown/dev/reference/api/design/en.md index bd2cc38421b..7922913be70 100644 --- a/markdown/dev/reference/api/design/en.md +++ b/markdown/dev/reference/api/design/en.md @@ -3,42 +3,55 @@ title: Design order: 10 --- -The `Design` object in FreeSewing's core library serves a single purpose: -To instantiate new pattern designs. +The `Design` named export in FreeSewing's core library serves a single purpose: +To create new pattern designs. ## Design constructor ```js -function freesewing.Design( - object config, - object|array plugins, // optional - object|array conditionalPlugins // optional -) +import { Design } from "@freesewing/core" + +const Sorcha = new Design({ + // design configuration here +}) ``` This constructor creates a new pattern design. -It takes the following arguments: +It takes a single argument, an object holding the design's configuration. -- `config` : The pattern configuration -- `plugins` : Either a [plugin object](/guides/plugins/), or an array of plugin objects -- `conditionalPlugins` : Either a [conditional plugin object](/guides/plugins/conditionally-loading-build-time-plugins/), or an array - of conditional plugin objects to (conditionally) load in your pattern +## Design configuration + + +Since a design's configuration is managed at the part level, +the Design constructor only expects a `parts` attribute that should +hold an array of parts to include in the Design. ```js -import freesewing from "@freesewing/core" -import plugins from "@freesewing/plugin-bundle" -import config from "../config" +const Sorcha = new Design({ + parts: [ front, back, sleeve ], +}) +``` -// Create new design -const Sorcha = new freesewing.Design(config, plugins) +A Design in FreeSewing is little more than a container for various Parts + +Optionally, you can also pass it a `data` attrbute +to hold any custom data you'd like to add to your Design. + +Any `data` you add to the Design constructor will be added +to [the Store](/reference/api/store). + +```js +const Sorcha = new Design({ + parts: [ front, back, sleeve ], + data: { + // Your custom data here + } +}) ``` -This method is a _super-constructor_. It will return a constructor -method that will become the default export of your design and -should be called to instantiate your pattern. - -See [creating a new pattern design](/howtos/code/create-new-design) for a complete example. +This Design constructor is a _super-constructor_. +It will return a constructor method that will a pattern based on your design. diff --git a/markdown/dev/reference/api/en.md b/markdown/dev/reference/api/en.md index 0b5711d4953..6d413a8586c 100644 --- a/markdown/dev/reference/api/en.md +++ b/markdown/dev/reference/api/en.md @@ -6,37 +6,80 @@ This is the documentation for FreeSewing's core library, published as `@freesewi It's a complete toolbox for parametric design with a primary focus on sewing patterns, but can be utilized for a variety of similar 2D design tasks. -## Getting started - -To get started, import the library: - -```js -import freesewing from '@freesewing/core' -``` - -This is the reference documentation. For a more hands-on walkthrough, -please refer to our [pattern design tutorial](/tutorials/pattern-design/) +##### Looking to get started? + +You are currently browsing the reference documentation. +Please refer to [the quick start guide](/guides/quick) to get started. -## Properties +## Named exports -The `@freesewing/core` default export is a single object with the following properties: + -- `Design`: The [Design constructor](/reference/api/design/) to create a new design +Ever since version 3 of FreeSewing, we use only named exports, and no default exports. + +Refer to [the migration guide](/guides/v3) for more details. + + + +The `@freesewing/core` package provides the following named exports: + + +| Named export | Description | +| ------------ | ------------| +| version | The version of `@freesewing/core` | +| Bezier | A re-export of [the bezier-js dependency](https://www.npmjs.com/package/bezier-js) | + +The following named exports are **constructors**: You will typically use the `Design()` constructor. -The other constructors and utilities below are exported to facilitate unit testing. +The other constructors and utilities below are exported to +facilitate unit testing and other specific use cases. -- `Path`: The [Path constructor](/reference/api/path) to create a new path -- `Pattern`: The [Pattern constructor](/reference/api/pattern) to create a new pattern -- `Point`: The [Point constructor](/reference/api/point) to create a new point -- `Snippet`: The [Snippet constructor](/reference/api/snippet) to create a new snippet -- `utils`: A collection of [utilities](/reference/api/utils) -- `version`: A string containing the `@freesewing/core` version number +| Named export | Description | +| ------------ | ------------| +| `Design` | The [Design](/reference/api/design) constructor | +| `Attributes` | The [Attributes](/reference/api/attributes) constructor | +| `Pattern` | The [Pattern](/reference/api/pattern) constructor | +| `Point` | The [Point](/reference/api/point) constructor | +| `Path` | The [Path](/reference/api/path) constructor | +| `Part` | The [Part](/reference/api/part) constructor | +| `Snippet` | The [Snippet](/reference/api/snippet) constructor | +| `Store` | The [Store](/reference/api/store) constructor | + + +The following named exports are **uitility methods**: + +| Named export | Description | +| ------------ | ------------| +| `beamIntersectsCircle` | See the [beamIntersectsCircle](/reference/api/utils/beamintersectsCircle) documentation | +| `beamIntersectsX` | See the [beamIntersectsX](/reference/api/utils/beamintersectsX) documentation | +| `beamIntersectsY` | See the [beamIntersectsY](/reference/api/utils/) documentation | +| `beamsIntersect` | See the [beamsIntersect](/reference/api/utils/beamsintersect) documentation | +| `capitalize` | See the [capitalize](/reference/api/utils/capitalize) documentation | +| `circlesIntersect` | See the [circlesIntersect](/reference/api/utils/circlesintersect) documentation | +| `curveEdge` | See the [curveEdge](/reference/api/utils/curveedge) documentation | +| `curveIntersectsX` | See the [curveIntersectsX](/reference/api/utils/curveintersectsX) documentation | +| `curveIntersectsY` | See the [curveIntersectsY](/reference/api/utils/curveintersectsY) documentation | +| `curvesIntersect` | See the [curvesIntersect](/reference/api/utils/curvesintersect) documentation | +| `deg2rad` | See the [deg2rad](/reference/api/utils/deg2rad) documentation | +| `generateStackTransform` | see the [generateStackTransform](/reference/api/utils/generateStackTransform) documentation | +| `lineIntersectsCircle` | See the [lineIntersectsCircle](/reference/api/utils/lineintersectsCircle) documentation | +| `lineIntersectsCurve` | See the [lineIntersectsCurve](/reference/api/utils/lineintersectsCurve) documentation | +| `linesIntersect` | See the [linesIntersect](/reference/api/utils/linesintersect) documentation | +| `pctBasedOn` | See the [pctBasedOn](/reference/api/utils/pctbasedon) documentation | +| `pointOnBeam` | See the [pointOnBeam](/reference/api/utils/pointonbeam) documentation | +| `pointOnCurve` | See the [pointOnCurve](/reference/api/utils/pointoncurve) documentation | +| `pointOnLine` | See the [pointOnLine](/reference/api/utils/pointonline) documentation | +| `rad2deg` | See the [rad2deg](/reference/api/utils/rad2deg) documentation | +| `splitCurve` | See the [splitCurve](/reference/api/utils/splitcurve) documentation | +| `stretchToScale` | See the [stretchToScale](/reference/api/utils/stretchtoscale) documentation | +| `units` | See the [units](/reference/api/utils/units) documentation | + diff --git a/markdown/dev/reference/api/part/en.md b/markdown/dev/reference/api/part/en.md index 9c630826ea0..f229c07988d 100644 --- a/markdown/dev/reference/api/part/en.md +++ b/markdown/dev/reference/api/part/en.md @@ -1,22 +1,111 @@ --- title: Part -order: 20 +order: 15 --- -The `Part` object in FreeSewing's core library holds all data and logic of a pattern part. -A pattern part is what holds the actual information about points and paths, -and multiple parts together typically make up a pattern. +A `Part` in FreeSewing holds all data, logic, and configuration of a Design. +Parts truly are the building blocks of FreeSewing as they not only provide +the configurarion, but also a `draft()` method that does the actual work +of drafting a parametric design. -## Part properties +## Part structure + +A part is an object with the following properties: + +| Property | Description | +| -------- | ----------- | +| `draft` | The method that will draft the part (__required__) | +| `measurements` | An array of required measurements | +| `optionalMeasurements` | An array of optional measurements | +| `options` | An object of options | +| `plugins` | A plugin or array of plugins | + +## A part's `draft()` method + +Each part **must** have a `draft` property that holds a method that will draft the part. +The method's signature is as follows: + +```js +function draft({ + Path, + Point, + Snippet, + absoluteOptions, + complete, + hide, + log, + macro, + measurements, + paperless, + part, + paths, + points, + scale, + snippets, + options, + sa, + store, + units, + unhide, + utils, +}) +``` + +The method received a single parameter, an object which you can _destructure_ to +access the following properties: + +### Provided constructors | Property | Description | | --------:| ----------- | -| `attributes` | An [Attributes](/reference/api/attributes) instance holding the part's attributes | -| `paths` | A plain object to store your paths in | -| `points` | A plain object to store your points in | -| `render` | A flag that controls whether to include the part in the render output | -| `snippets` | A plain object to store your snippets in | +| `Path` | A [Path constructor](/reference/api/path) | +| `Point` | A [Point constructor](/reference/api/point) | +| `Snippet` | A [Snippet constructor](/reference/api/snippet) | -## Part methods +### Provided settings - +| Property | Description | +| --------:| ----------- | +| `absoluteOptions` | FIXME | +| `complete` | Holds `settings.complete` | +| `measurements` | Holds `settings.measurements` | +| `paperless` | Holds `settings.paperless` | +| `scale` | Holds `settings.scale` | +| `options` | Holds `settings.options` | +| `sa` | Holds `settings.sa` | + +### Provided containers + +| Property | Description | +| --------:| ----------- | +| `paths` | The part's paths container | +| `points` | The part's points container | +| `snippets` | The part's snippets container | +| `store` | Holds the [Store](/reference/api/store) instance that is shared across parts | +| `utils` | A [Utils](/reference/api/utils) instance with utility methods | + + +### Provided methods + +| Property | Description | +| --------:| ----------- | +| `hide` | Call `hide()` to hide this part | +| `units` | A context-aware version of `utils.units` | +| `unhide` | A context-aware version of `utils.units` | + + +### Other provided properties + +| Property | Description | +| --------:| ----------- | +| `log` | The default logging object from the store (FIXME) | +| `macro` | The macro runner. See [the macros documentation](/reference/macros/) | +| `part` | The part container itself. **You must return this** | +| `store` | Holds the [Store](/reference/api/store) instance that is shared across parts | +| `utils` | A [Utils](/reference/api/utils) instance with utility methods | + + +## A part's `measurements` list +## A part's `optionalMeasurements` list +## A part's `options` list +## A part's `plugin` list diff --git a/markdown/dev/reference/api/pattern/addpart/en.md b/markdown/dev/reference/api/pattern/addpart/en.md new file mode 100644 index 00000000000..0ca66da0abe --- /dev/null +++ b/markdown/dev/reference/api/pattern/addpart/en.md @@ -0,0 +1,44 @@ +--- +title: Pattern.addPart() +--- + +The `Pattern.addPart()` method allows you to add a part to a pattern. +It has the same effect as passing a part to the Design constructor. + +This method is chainable as it returns the Pattern object + +## Pattern.addPart() signature + +```js +Pattern pattern.addPart(object part) +``` + +## Pattern.addPart() example + +```js +import { Aaron } from "@freesewing/aaron" +import { cisFemaleAdult34 } from "@freesewing/models" + +const extra = { + name: 'aaron.extra', + draft: ({ points, Point, paths, Path, part }) => { + points.msg = new Point(50,15) + .attr('data-text', "I am an extra part") + paths.box = new Path() + .move(new Point(0,0)) + .line(new Point(0,30)) + .line(new Point(100,30)) + .line(new Point(100,0)) + .close(new Point(100,0)) + .addClass('note') + + return part + } +} + +const pattern = new Aaron({ + measurements: cisFemaleAdult34 +}).addPart(extra) + +const svg = pattern.draft().render() +``` diff --git a/markdown/dev/reference/api/pattern/draft/en.md b/markdown/dev/reference/api/pattern/draft/en.md index 933f90eefe3..4e5a34d142c 100644 --- a/markdown/dev/reference/api/pattern/draft/en.md +++ b/markdown/dev/reference/api/pattern/draft/en.md @@ -2,7 +2,7 @@ title: Pattern.draft() --- -A pattern's `draft()` method will draft all the different pattern parts +A pattern's `draft()` method will draft the different pattern parts making sure to do so in the right order, handle dependencies, resolve options to their absolute values and a number of other housekeeping things that are required for the pattern to be drafted. @@ -18,14 +18,11 @@ Pattern pattern.draft() ## Pattern.draft() example ```js -import Aaron from "@freesewing/aaron" -import models from "@freesewing/models" +import { Aaron } from "@freesewing/aaron" +import { cisFemaleAdult34 } from "@freesewing/models" const pattern = new Aaron({ - settings: { - embed: true, - }, - measurements: models.manSize38 + measurements: cisFemaleAdult34 }) const svg = pattern.draft().render() diff --git a/markdown/dev/reference/api/pattern/en.md b/markdown/dev/reference/api/pattern/en.md index bcd9d12b3e9..2ca95bf690e 100644 --- a/markdown/dev/reference/api/pattern/en.md +++ b/markdown/dev/reference/api/pattern/en.md @@ -1,33 +1,72 @@ --- title: Pattern -order: 15 +order: 20 --- The `Pattern` object in FreeSewing's core library holds all data and logic of a pattern. -It is the parametric blueprint that when instantiated with a user's measurements and -objects will generate a made-to-measure pattern. +It is the parametric blueprint that when instantiated with a user's settings +can draft a made-to-measure sewing pattern. -## Pattern constructor +## Creating a Pattern + +A Pattern in FreeSewing is an instantiated Design: ```js -function freesewing.Pattern(object settings) +import { Florence } from "@freesewing/florence" + +const pattern = new Florence() ``` -A pattern is instantiated by passing a [settings object](/reference/api/settings/) to the pattern constructor. +You probably want to create a pattern using your own [settings](/reference/api/settings): -This settings objects holds, amongst other things, the measurements and options chosen by the user. -Refer to the [settings documentation](/reference/api/settings/) for an exhaustive list. +```js +import { Florence } from "@freesewing/florence" -## Pattern properties +const pattern = new Florence({ + paperless: true, + measurements: { + head: 390, + } +}) +``` -- `settings` : The settings as set by the user -- `options` : the options as set by the user -- `config` : The pattern configuration -- `parts` : A plain object to hold your parts -- `Part` : The [Part](/reference/api/part) constructor -- `store` : A [Store](/reference/api/store) instance -- `svg` : An [Svg](/reference/api/svg) instance -- `is` : A string that will be set to `draft` or `sample` when you respectively draft or sample a pattern. This allows plugins that hook into your pattern to determine what to do in a given scenario. +## Multisets in FreeSewing + +You can pass the Pattern constructor an array of multiple settings objects: + +```js +import { Florence } from "@freesewing/florence" + +const pattern = new Florence([ + { + measurements: { + head: 390, + } + }, + { + measurements: { + head: 420, + } + }, +]) +``` + +We refer to these *multiple sets of settings* as **multisets**. +It is what powers FreeSewing's [sampling capabilities](/reference/api/pattern/sample) but +it also allows you to draft some pattern parts with one set of measurements, and other parts +with another set. For example if you have an asymetric model to fit. + + + +##### Core always keeps a set of settings + +Multisets is an advanced feature of FreeSewing, and for the most part you can forget about it +until the day you want to use it. + +However, it's good to keep in mind that under the hood, FreeSewing will always use a set of settings. +It just so happens that in most cases, there will be only one settings object in the set. + + ## Pattern methods diff --git a/markdown/dev/reference/api/pattern/getconfig/en.md b/markdown/dev/reference/api/pattern/getconfig/en.md new file mode 100644 index 00000000000..fa4ebcd3804 --- /dev/null +++ b/markdown/dev/reference/api/pattern/getconfig/en.md @@ -0,0 +1,32 @@ +--- +title: Pattern.getConfig() +--- + +You can call `Pattern.getConfig()` to retrieve a pattern's runtime configuration. + +Doing so will resolve all dependencies, load all the plugins, and do all other +housekeeping tasks that are typically done behind the scenes when you call +`Pattern.draft()`. But it will stop short of drafting the pattern, and instead +return a Pattern's internal configuration. + +You can use this to see what options a pattern provides, what +measurments it requires, and so on. + +## Pattern.getConfig() signature + +```js +object pattern.getConfig() +``` + +## Pattern.getConfig() example + +```js +import { Aaron } from "@freesewing/aaron" +import { cisFemaleAdult34 } from "@freesewing/models" + +const pattern = new Aaron({ + measurements: cisFemaleAdult34 +}) + +const config = pattern.getConfig() +``` diff --git a/markdown/dev/reference/api/pattern/getcutlist/en.md b/markdown/dev/reference/api/pattern/getcutlist/en.md deleted file mode 100644 index 4dddc3d8083..00000000000 --- a/markdown/dev/reference/api/pattern/getcutlist/en.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Pattern.getCutList() ---- - -This method will return the cut list, which means the `cut` property of -all parts that were included in the most recent call to `Pattern.draft()`. - -This relies on the pattern designers properly setting the cut property -in each part. - -This method is chainable as it returns the Pattern object - -## Pattern.getCutList() signature - -```js -Object pattern.getCutList() -``` - -## Pattern.getCutList() example - -```js -import Aaron from "@freesewing/aaron" -import models from "@freesewing/models" - -const pattern = new Aaron({ - settings: { - embed: true, - }, - measurements: models.manSize38 -}) - -const cutList = pattern.draft().getCutList() -``` -## Cut list format - -The object returned by `Pattern.getCutList()` is a plain object -with a property for each part that will be included in the pattern's output. - -The value of these properties is the `cut` property of the part in question. - - -Refer to [part.addCut()](/reference/api/part/addcut) for details on the -format of a part's `cut` property - - - - diff --git a/markdown/dev/reference/api/pattern/getrenderprops/en.md b/markdown/dev/reference/api/pattern/getrenderprops/en.md index f0b785c6f33..5d60c429c15 100644 --- a/markdown/dev/reference/api/pattern/getrenderprops/en.md +++ b/markdown/dev/reference/api/pattern/getrenderprops/en.md @@ -2,8 +2,8 @@ title: Pattern.getRenderProps() --- -A pattern's `getRenderProps()` method will return a set of properties -that allow the pattern to be rendered be an external renderer such as +The `Pattern.getRenderProps()` method will return an object that +facilitates rendered the pattern by an external renderer such as a React component. It should only be called after calling `Pattern.draft()`. ## Pattern.getRenderProps() signature @@ -12,35 +12,31 @@ a React component. It should only be called after calling `Pattern.draft()`. Object pattern.getRenderProps() ``` -The object returned by this method contains the following properties: +## Pattern.getRenderProps() example + +```js +import { Aaron } from "@freesewing/aaron" +import { cisFemaleAdult34 } from "@freesewing/models" + +const pattern = new Aaron({ + measurements: cisFemaleAdult34 +}) + +const props = pattern.draft().getRenderProps() +``` + +## Pattern.getRenderProps() returned object + +The `Pattern.getRenderProps()` method returns an object with +the following properties: | Property | Description | | --------:| ----------- | +| `autoLayout` | An object describing the (automated) pattern layout | +| `height` | Height of the drafted pattern in `mm` | +| `logs` | The logs generated by the pattern | +| `parts` | A plain object holding the drafted parts | +| `settings` | The (sets of) settings used to draft the pattern | +| `stacks` | A plain object holding the drafted stacks | | `svg` | An [Svg Object](/reference/api/svg/) object with the `preRender` hook applied | | `width` | Widht of the drafted pattern in `mm` | -| `height` | Height of the drafted pattern in `mm` | -| `settings` | The settings used to draft the pattern | -| `events` | An object with properties `debug`, `info`, `warning`, and `error` holding events of that type that were generated during the draft of the pattern | -| `parts` | A plain object holding the drafted parts | - - - -See [the Draft React component](/reference/packages/components/draft/) for more info. - - - -## Pattern.getRenderProps() example - -```jsx -import React from 'react -import Aaron from "@freesewing/aaron" -import Draft from "@freesewing/components/Draft" - -const MyReactComponent = ({ measurements }) => { - const pattern = new Aaron({ measurements }) - - return -} - -export default MyReactComponent -``` diff --git a/markdown/dev/reference/api/pattern/on/en.md b/markdown/dev/reference/api/pattern/on/en.md index a271574500e..b911a7aa42c 100644 --- a/markdown/dev/reference/api/pattern/on/en.md +++ b/markdown/dev/reference/api/pattern/on/en.md @@ -2,12 +2,12 @@ title: Pattern.on() --- -A pattern's `on()` method allows you to attach a function to one of the +The `Pattern.on()` method allows you to attach a function to one of the pattern's [lifecycle hooks](/reference/hooks/). It takes the lifecycle hook's name as the first argument and the function as the second. This method will then be triggered by the lifecycle hook. -Since FreeSewing v2.19, this method is chainable as it returns the Pattern object +This method is chainable as it returns the Pattern object ## Pattern.on() signature diff --git a/markdown/dev/reference/api/pattern/render/en.md b/markdown/dev/reference/api/pattern/render/en.md index ea83f28109f..b03faa5ad83 100644 --- a/markdown/dev/reference/api/pattern/render/en.md +++ b/markdown/dev/reference/api/pattern/render/en.md @@ -2,27 +2,24 @@ title: Pattern.render() --- -A pattern's `render()` method will render the pattern to SVG and return -the SVG as a string. It should only ever be called after calling +The `Pattern.render()` method will render the pattern to SVG and return +that SVG as a string. It should only be called after calling [Pattern.draft()](/reference/api/pattern/draft/) first. -# Pattern.render() signature +## Pattern.render() signature ```js string pattern.render() ``` -# Pattern.render() example +## Pattern.render() example ```js -import Aaron from "@freesewing/aaron" -import models from "@freesewing/models" +import { Aaron } from "@freesewing/aaron" +import { cisFemaleAdult34 } from "@freesewing/models" const pattern = new Aaron({ - settings: { - embed: true, - }, - measurements: models.manSize38 + measurements: cisFemaleAdult34 }) const svg = pattern.draft().render() diff --git a/markdown/dev/reference/api/pattern/sample/en.md b/markdown/dev/reference/api/pattern/sample/en.md index cfe7aea8d0b..6aacc496939 100644 --- a/markdown/dev/reference/api/pattern/sample/en.md +++ b/markdown/dev/reference/api/pattern/sample/en.md @@ -2,24 +2,28 @@ title: Pattern.sample() --- -A pattern's `sample()` method will _sample_ the pattern which means -to draft it in different iterations while adjusting the input settings. +The `Pattern.sample()` method will _sample_ the pattern which means +to draft multiple variants of the same pattern, and stack them on +top of each other. + +This method is chainable as it returns the Pattern object + Under the hood, this method will call one of [Pattern.sampleOption()](/reference/apu/pattern/sampleoption), [Pattern.sampleMeasurement()](/reference/apu/pattern/sampleoption), or [Pattern.sampleModels()](/reference/apu/pattern/sampleoption) to sample -an option, a measurement, or a set of measurements respectively. +an option, a measurement, or different models respectively. Unlike those three methods where you pass the relevant info to to the method, -this `Pattern.sample()` will instead read the `pattern.settings.sample` -object to determine what to do. +this `Pattern.sample()` method will instead read the `settings.sample` +object to determine what needs to be done. -The possiblities are: +The `settings.sample` object can hold the following properties: - **type**: One of `option`, `measurement`, or `models` - **option**: An option name as defined in the pattern config file (only used when `type` is option). - **measurement**: A measurement name as defined in the pattern config file (only used when `type` is measurement). -- **models**: An array of models with the required measurements for this pattern (only used when `type` is models). +- **models**: A plain object of different models where the key is the model name and the value an object with the required measurements. See the specific sample methods below for more details: @@ -27,35 +31,6 @@ See the specific sample methods below for more details: - [Pattern.sampleMeasurement()](/reference/apu/pattern/sampleoption) - [Pattern.sampleModels()](/reference/apu/pattern/sampleoption) -From a lifecycle point of view, the `Pattern.sample()` method is a substitute for -`Pattern.draft()`. So you call it after instantiating the pattern, prior to -calling `Pattern.render()`. - - - -###### Anchor your samples - -If you add a point named `anchor` to your pattern part, the different samples -will be anchored on this point. - -In other words, for each sample, the anchor point will be kept in the same location. - - - -This method is chainable as it returns the Pattern object - - - -##### FreeSewing v3 breaking changes - -This method does some juggling under the hood, essentially cramming -different versions of a pattern into a single Pattern object. - -This behavior is likely to change in FreeSewing v3. Refer to [the -roadmap](https://github.com/freesewing/freesewing/discussions/1278) for details. - - - ## Pattern.sample() signature ```js @@ -65,14 +40,13 @@ Pattern pattern.sample() ## Pattern.sample() example ```js -import Aaron from "@freesewing/aaron" -import models from "@freesewing/models" +import { Aaron } from "@freesewing/aaron" +import { cisFemaleAdult } from "@freesewing/models" const pattern = new Aaron({ - settings: { - embed: true, - }, - measurements: models.manSize38 + sample: { + models: cisFemaleAdult + } }) const svg = pattern.sample().render() diff --git a/markdown/dev/reference/api/pattern/samplemeasurement/en.md b/markdown/dev/reference/api/pattern/samplemeasurement/en.md index e1e09f0336f..f79fc4556ce 100644 --- a/markdown/dev/reference/api/pattern/samplemeasurement/en.md +++ b/markdown/dev/reference/api/pattern/samplemeasurement/en.md @@ -2,11 +2,12 @@ title: Pattern.sampleMeasurement() --- -A pattern's `sampleMeasurement()` method will _sample_ a given measurement, -which means to draft it in different iterations while adjusting the input value -of the given measurement. -In practice, it will draft 10 iterations of the pattern -while adapting the measurement between 90% and 110% of its original value. +The `Pattern.sampleMeasurement()` method will _sample_ the pattern which means +to draft multiple variants of the same pattern, and stack them on +top of each other. + +In this particular case, it will draft 10 variants of the pattern that vary +the measurement of your choice between 90% and 110% if the value in the settings. The goal of measurement sampling is to understand the impact of a given measurement on a pattern. @@ -14,11 +15,6 @@ The goal of measurement sampling is to understand the impact of a given measurem This method is chainable as it returns the Pattern object - -The goal of option sampling is to verify the impact of an option on the pattern, and verify that -its min and max boundaries are correct and its default value is sensible. - - ## Pattern.sampleMeasurement() signature ```js @@ -28,10 +24,12 @@ Pattern pattern.sampleMeasurement(string measurement) ## Pattern.sampleMeasurement() example ```js -import Aaron from "@freesewing/aaron" -import models from "@freesewing/models" +import { Aaron } from "@freesewing/aaron" +import { cisFemaleAdult34 } from "@freesewing/models" -const pattern = new Aaron({ measurements: models.manSize38 }) +const pattern = new Aaron({ + measurements: cisFemaleAdult34 +}) -const svg = pattern.sampleMeasurement("chest").render() +const svg = pattern.draft().sampleMeasurement('chest') ``` diff --git a/markdown/dev/reference/api/pattern/samplemodels/en.md b/markdown/dev/reference/api/pattern/samplemodels/en.md index 9eac3be9e17..2d507046bfe 100644 --- a/markdown/dev/reference/api/pattern/samplemodels/en.md +++ b/markdown/dev/reference/api/pattern/samplemodels/en.md @@ -2,9 +2,11 @@ title: Pattern.sampleModels() --- -A pattern's `sampleModels()` method will _sample_ a pattern for a list of -models you pass to it. It will draft different iterations of the pattern, -using the measurements for each model you pass to it. +The `Pattern.sampleModels()` method will _sample_ the pattern which means +to draft multiple variants of the same pattern, and stack them on +top of each other. + +In this particular case, it will draft a variants for each of the models you pass it. The goal of model sampling is to verify that a pattern grades correctly up and down as sizes change. @@ -12,24 +14,13 @@ The goal of model sampling is to verify that a pattern grades correctly up and d This method is chainable as it returns the Pattern object - - -###### Anchor your samples - -If you add a point named `anchor` to your pattern part, the different samples -will be anchored on this point. - -In other words, for each sample, the anchor point will be kept in the same location. - - - ## Pattern.sampleModels() signature ```js Pattern pattern.sampleModels(object models, string focus) ``` -The models object you pass as the first parameter should be structured as such: +The `models` object you pass as the first parameter should be structured as such: ```js { @@ -61,10 +52,10 @@ identifying your model in the models object. ## Pattern.sampleModels() example ```js -import Aaron from "@freesewing/aaron" -import models from "@freesewing/models" +import { Aaron } from "@freesewing/aaron" +import { cisFemaleAdult } from "@freesewing/models" const Aaron = new Aaron() -const svg = aaron.sampleModels(models, "manSize38").render() +const svg = aaron.sampleModels(cisFemaleAdult, "34').render() ``` diff --git a/markdown/dev/reference/api/pattern/sampleoption/en.md b/markdown/dev/reference/api/pattern/sampleoption/en.md index 94d1a027cbb..74a728df157 100644 --- a/markdown/dev/reference/api/pattern/sampleoption/en.md +++ b/markdown/dev/reference/api/pattern/sampleoption/en.md @@ -2,15 +2,19 @@ title: Pattern.sampleOption() --- -A pattern's `sampleOption()` method will _sample_ a given option, -which means to draft it in different iterations while adjusting the input value -of the given option. -The practical implementation varies based on [the type of option](/config/options/): +The `Pattern.sampleOption()` method will _sample_ the pattern which means +to draft multiple variants of the same pattern, and stack them on +top of each other. + +In this particular case, the variants it drafts depend + on [the type of option](/config/options/): - For options that are an object with a **min** and **max** property, 10 steps will be sampled, between min and max - For options that are a numeric value (**constants**), 10 steps will be sampled between 90% and 110% of the value - For options with a **list** of options, each option in the list will be sampled +Handle other option types + The goal of option sampling is to verify the impact of an option on the pattern, and verify that its min and max boundaries are correct and its default value is sensible. @@ -18,17 +22,6 @@ its min and max boundaries are correct and its default value is sensible. This method is chainable as it returns the Pattern object - - -###### Anchor your samples - -If you add a point named `anchor` to your pattern part, the different samples -will be anchored on this point. - -In other words, for each sample, the anchor point will be kept in the same location. - - - ## Pattern.sampleOption() signature ```js @@ -38,12 +31,12 @@ Pattern pattern.sampleOption(string option) ## Pattern.sampleOption() example ```js -import Aaron from "@freesewing/aaron" -import models from "@freesewing/models" +import { Aaron } from "@freesewing/aaron" +import { cisFemaleAdult34 } from "@freesewing/models" -const pattern = new aaron({ - measurements: models.manSize38 +const pattern = new Aaron({ + measurements: cisFemaleAdult34 }) -const svg = pattern.sampleOption("necklineDrop").render() +const svg = pattern.draft().sampleMeasurement('chest') ``` diff --git a/markdown/dev/reference/api/pattern/use/en.md b/markdown/dev/reference/api/pattern/use/en.md index 7a3bb6869c1..8b78334b578 100644 --- a/markdown/dev/reference/api/pattern/use/en.md +++ b/markdown/dev/reference/api/pattern/use/en.md @@ -2,10 +2,9 @@ title: Pattern.use() --- -A pattern's `use()` method will load a FreeSewing plugin. -Plugins are a way to extend a pattern's functionality, and can be -loaded both at build-time and at run-time. This method only applies -to run-time plugins. For more details, refer to [the plugin guide](/guides/plugins/). +The `Pattern.use()` method will load a FreeSewing plugin. +Plugins are a way to extend a pattern's functionality. +For more details, refer to [the plugin guide](/guides/plugins/). This method is chainable as it returns the Pattern object @@ -21,16 +20,13 @@ you plugin object. ## Pattern.use() example ```js -import Aaron from "@freesewing/aaron" -import models from "@freesewing/models" -import theme from "@freesewing/theme" +import { Aaron } from "@freesewing/aaron" +import { cisFemaleAdult34 } from "@freesewing/models" +import { pluginTheme } from "@freesewing/plugin-theme" const pattern = new Aaron({ - settings: { - embed: true, - }, - measurements: models.manSize38 -}).use(theme) + measurements: cisFemaleAdult34 +}).use(pluginTheme) const svg = pattern.draft().render() ```