VSinerva/freesewing
1
0
Fork 0
Code Activity

Update snap pct option documentation.

Browse source
This commit is contained in:
Nick Dower 2022-01-21 09:56:53 +01:00
parent ec19ee87ea
commit a18f8a6b35
1 changed files with 43 additions and 37 deletions
Download patch file Download diff file Expand all files Collapse all files

80
markdown/dev/reference/api/config/options/percentage/en.md
View file

@ -6,7 +6,7 @@ Percentage options are the bread and butter of freesewing.
Almost all your options will most likely be percentage options as Almost all your options will most likely be percentage options as
they ensure that your pattern will scale regardless of size. they ensure that your pattern will scale regardless of size.
Percentage come in two varieties: Percentage options come in two varieties:
- Plain percentage options - Plain percentage options
- Snapped percentage options - Snapped percentage options
@ -18,24 +18,27 @@ For both varieties, the following is good to keep in mind:
###### Percentage options will be divided by 100 when loaded ###### Percentage options will be divided by 100 when loaded
You specify percentages in your config file. For example, `50` means 50%. You specify percentages in your config file. For example, `50` means 50%.
When your configuration is loaded, those percentages will by divided by 100. When your configuration is loaded, those percentages will be divided by 100.
So a percentage of `50` in your config file will be `0.5` when you read out that option in your pattern. So a percentage of `50` in your config file will be `0.5` when you read out that option in your pattern.
###### Percentage options are not limited to the range 0-100 ###### Percentage options are not limited to the range 0-100
The minimum and maximum (and default) values are not restricted to the range from `0%` to `100%`. The minimum and maximum (and default) percentages are not restricted to the range from `0%` to `100%`.
A percentage option that spans from `-25%` to `135%` is just as valid. A percentage option that spans from `-25%` to `135%` is just as valid.
</Note> </Note>
## Plain percentage options ## Plain percentage options
A plain percentage option allows a user to specify a relative value (a percentage) which is
then used to produce an absolute value in mm based on one or more measurements.
A plain percentage option should be an object with these properties: A plain percentage option should be an object with these properties:
- `pct` : The percentage - `pct` : The default percentage
- `min` : The minimum that's allowed - `min` : The minimum percentage that's allowed
- `max` : The maximum that's allowed - `max` : The maximum percentage that's allowed
```js ```js
options: { options: {
@ -51,9 +54,9 @@ options: {
A snapped percentage option should be an object with these properties: A snapped percentage option should be an object with these properties:
- `pct` : The percentage - `pct` : The default percentage
- `min` : The minimum that's allowed - `min` : The minimum percentage that's allowed
- `max` : The maximum that's allowed - `max` : The maximum percentage that's allowed
- `snap`: See below - `snap`: See below
- `toAbs`: See below - `toAbs`: See below
@ -71,14 +74,14 @@ options: {
### How snapped percentage options work ### How snapped percentage options work
In a so-called _snapped percentage option_ the value of the option is snapped to In a so-called _snapped percentage option_ the absolute (i.e. not relative) value
absolute values (think millimeter). To make that happen, the following happens of the option is snapped to discreet values ("snap points"). To make that happen,
under the hood: the following happens under the hood:
- Use `toAbs()` to calculate the absolute value of the option - Use `toAbs()` to calculate an absolute value for the option
- See whether that approaches one of the absolute values provided by `snap` - See whether that approaches one of the absolute values provided by `snap`
- If so, set the absolute option to the snapped value - If so, use the snapped value
- If not, set the absolute option to whatever the absolute option is - If not, use the absolute value unchanged
If you're head's spinning, here's an image that will hopefully clarify things a bit: If you're head's spinning, here's an image that will hopefully clarify things a bit:
@ -87,30 +90,31 @@ If you're head's spinning, here's an image that will hopefully clarify things a
The gradient box represents the range of any given measurement, The gradient box represents the range of any given measurement,
from dolls all the way on the left, to giants all the way on the right. from dolls all the way on the left, to giants all the way on the right.
The sort of middle green-colored region is what the designer had in mind The sort of middle green-colored region is what the designer had in mind
when designing the pattern, and they have setup snap points for values when designing the pattern, and they have set up snap points for values
that they feel make sense. that they feel make sense.
The region of influence of any given snap point will extend 50% towards its The region of influence of any given snap point will extend 50% towards its
neighbor, on both sides (indicated by the dashed lines).This means that the neighbor on both sides (indicated by the dashed lines).This means that the
region of snap points is continuous, once you're in, you're going to be region of snap points is continuous, once you're in, you're going to be
snapped to a given absolute value. snapped to one of the snap points.
However, when you venture out into the area where the designer did not However, when you venture out into the area where the designer did not
configure any snap points, your input will be used as-is. configure any snap points, the absolute value will be used as-is, without
snapping, just as it would in a normal percentage option.
This system results in a best of both words: This system results in the best of both worlds:
- Things like elastic widths and so on can be configured to be fixed values, - Things like elastic widths and so on can be configured to be fixed values,
of common elastic widths for example of common elastic widths for example
- The default value will still scale up and down, but merely snap to the closest - The absolute value will still scale up and down, but will snap to the closest
fixed value fixed value when appropriate.
- When the input measurements go somewhere the designer did not anticipate, - When the input measurements go somewhere the designer did not anticipate,
the option will just behave as a regular `pct` option the option will just behave as a regular `pct` option
### What does it take? ### What does it take?
To make all this work, we need to clarify we want to happen. To make all this work, we need to clarify what we want to happen.
Specifically, we need to: Specifically, we need to:
- Configure the `snap` property to define what values to snap to - Configure the `snap` property to define what values to snap to
@ -143,14 +147,14 @@ The absolute value of this option will be set to a multiple of `7`
In a case like this, the value will **always** be snapped, In a case like this, the value will **always** be snapped,
because the snap points will be distributed equally across the entire range because the snap points will be distributed equally across the entire range
of all possible input. of all possible inputs.
</Note> </Note>
##### snap is an array of numbers ##### snap is an array of numbers
This will snap the **absolute value** of the option to any of the numbers in the This will snap the **absolute value** of the option to one of the numbers in the
array/list. array/list if it is in the region of influence.
An example: An example:
@ -163,12 +167,13 @@ myOption: {
} }
``` ```
This will snap the **absolute value** of the option to the number of the list, In this case, if the absolute value returned by `toAbs` is in the region of influence (in
if it approaches it. this example between 4.5 and 69.5), the nearest snap point will be used. If instead it is
outside the region of influence, it will be used unchanged.
##### snap is an object with `metric` and `imperial` properties that each hold an array of numbers ##### snap is an object with `metric` and `imperial` properties that each hold an array of numbers
This will work the same as an array numbers, but it allows you to supply a This will work the same as an array of numbers, but it allows you to supply a
different array/list for users drawing metric, or imperial patterns. different array/list for users drawing metric, or imperial patterns.
An example config: An example config:
@ -185,13 +190,14 @@ myOption: {
} }
``` ```
This will snap the **absolute value** of the option to the number of the list, In this case, the value of [settings.units](/api/settings/units) will determine which
if it approaches it. list of snap points to use. If the absolute value returned by `toAbs` is in the region of
What list is used will depend on the value of [settings.units](/api/settings/units). influence, the nearest snap point will be used. If instead it is outside the region of
influence, it will be used unchanged.
#### Pass a method to the `toAbs` property that will calculate the absolute value of the option #### Pass a method to the `toAbs` property that will calculate the absolute value of the option
Our snap configuration depends on the **absulute value** of the option. Our snap configuration depends on the **absolute value** of the option.
But we only receive the percentage value as input. It's up to us to come up But we only receive the percentage value as input. It's up to us to come up
with the logic to turn that into its absolute value. with the logic to turn that into its absolute value.
@ -203,8 +209,8 @@ function toAbs(pctValue, settings) {
// return absolute value here // return absolute value here
} }
``` ```
The first parameter is the value of the option provided by the user The first parameter is the percentage value provided by the user (for example
(as a percentage, so for example `0.5` for `50%`), `0.5` for `50%`),
the second is the pattern's settings object which (among other things) the second is the pattern's settings object which (among other things)
holds the measurements. holds the measurements.
@ -250,13 +256,13 @@ method that does the inverse: return the `pct` value required to achieve a certa
absolute value. absolute value.
This ability to set a percentage option to whatever is required for a given absolute This ability to set a percentage option to whatever is required for a given absolute
value in on our roadmap, so by using this method you are future-proving your code. value is on our roadmap, so by using this method you are future-proofing your code.
</Note> </Note>
### How to use this in your pattern code ### How to use this in your pattern code
This is all good and well, but how do you use this? This is all well and good, but how do you use this?
Well, just like you can get the `options` object from our shorthand call, Well, just like you can get the `options` object from our shorthand call,
you can now get the `absoluteOptions` object that holds absolute values you can now get the `absoluteOptions` object that holds absolute values