Merge pull request #8206 from dotCooCoo/feat/packaging-fold-preview

Packaging Tools: Fold Preview folds the blank in 3D with the printed art on its panels
This commit is contained in:
BFlat
2026-11-18 10:30:50 +07:00
committed by GitHub
51 changed files with 3423 additions and 31 deletions
+52 -4
View File
@@ -13694,10 +13694,10 @@ there is no step. → `{symbols: [name…], ids: [instance id…], skipped: [{la
## Packaging Tools add-on
Packaging Tools is a built-in add-on for the dielines of boxes and other folded packaging. Its commands are
`addon.packaging.setRole`, `addon.packaging.roles`, `addon.packaging.setRoleSwatch` and `addon.packaging.check`. In the
desktop app, Object › Plug-ins › Packaging Tools › Fold Lines opens the Fold Lines panel, Make Cut Line, Make Crease Line,
Make Partial Cut Line and Make Perforation Line run `addon.packaging.setRole` on the selection, and Check Fold Lines runs
`addon.packaging.check`.
`addon.packaging.setRole`, `addon.packaging.roles`, `addon.packaging.setRoleSwatch`, `addon.packaging.check` and
`addon.packaging.fold`. In the desktop app, Object › Plug-ins › Packaging Tools › Fold Lines opens the Fold Lines panel,
Make Cut Line, Make Crease Line, Make Partial Cut Line and Make Perforation Line run `addon.packaging.setRole` on the
selection, Check Fold Lines runs `addon.packaging.check`, and Fold Preview runs `ui.foldPreview`.
### Fold line roles
@@ -13793,6 +13793,54 @@ The list is shown until the document changes.
{"name":"run_command","arguments":{"command":"addon.packaging.check","params":{"tolerance":0.5,"select":true}}}
```
### Fold Preview
`addon.packaging.fold` (`{ids?, base?: [x, y], amount?: 1, tolerance?: 0.1}`) folds a blank into its 3D shape. It reads
the fold lines as `addon.packaging.check` does, and folds the blank that holds the base panel: the panel under `base`, or
the largest panel of all the blanks. The base panel stays in place. Every other panel turns about the hinges that join it
to the base, each by its angle times `amount` (0 is flat, 1 is folded): a Crease or a Perforation folds 90° away from
the printed side, so the print ends up outside, and a Partial Cut folds 90° toward it. A hinge that closes a loop of
panels is not turned about; `gap` says how far apart its two placements end up when every hinge is folded all the way,
whatever `amount` is, and it `closes` when that is within `tolerance` or 0.5% of its length. A panel that no chain of
hinges joins to the base stays flat where it is. `amount` must be from 0 to 1 and `base` a point in a panel; anything
else is an error. The command does not change the document.
Result: `{ok, blank, blanks, base, panels: [{outline, frame: {x, y, z, origin}, parent, depth}], hinges: [{a, b,
angle, kind, closes, gap}], collisions: [[a, b]], issues}`. `outline` is the panel's SVG path data in document
coordinates. `frame` gives where the flat blank's x and y directions, its printed side and its origin end up, in points,
with x to the right, y up and z toward the printed side of the flat blank. `kind` is `tree` for the hinges the panels
turn about and `closing` for the others. `collisions` lists the panels that pass through each other; panels stacked in
one plane, such as the top flaps of a closed box, are not listed. Without a blank (`ok` false), `blank` and `base` are
null and the lists are empty; `issues` are those of `addon.packaging.check`.
The Fold Preview window (Object › Plug-ins › Packaging Tools › Fold Preview, or the Fold Lines panel's Fold Preview
button) shows the blank that the document's shown fold lines make, folded, with the document's printed art on the
outside of each panel and the board's inside color on the back. The print leaves out the fold lines, unless Show Fold
Lines is on, and the layers that do not print. Under the view, the Fold slider sets the amount and the Zoom slider the
zoom; a status line gives the panels and hinges and says when a joint does not close, when two panels pass through each
other, when other blanks are not shown and when the fold lines have an error. Dragging in the view turns it, a
Shift-drag keeps to one axis, a middle-drag or a Space-drag moves it, the wheel zooms, a double-click on a panel makes it
the base, and the arrow keys turn the view by 5° when it has the keyboard focus. The view is drawn at the display's
pixel density up to 2,097,152 pixels (2,048 × 1,024) and 4,096 pixels along a side, and at a lower density past either,
and the print is a raster whose longest side is 2,048 pixels, rendered again when the document changes.
`ui.foldPreview` (`{amount?, view?: front|back|left|right|top|bottom|threeQuarter, rotateX?, rotateY?, zoom?,
perspective?, inside?, showFoldLines?, base?}`) sets the window, shows it and draws it again. A second run leaves the
window open. `rotateX` (-180 to 180) tips the top toward the viewer and `rotateY` (-180 to 180) turns the right side
toward the viewer, in degrees; `zoom` is 0.1 to 8, where 1 fits the folded blank; `perspective` is the field of view, 0 to
160 degrees, 0 for none; `inside` is the name of a swatch with a plain color, or else `#rrggbb`, or `""` for white; `base` is a point in a panel
of the document's blanks, or null for the largest panel. With perspective, the zoom of 1 keeps the eye at least twice
the folded blank's radius from its middle. A value of the wrong kind or out of range is an error and sets nothing.
VectorCraft's own defaults are a Three-Quarter view (`rotateX` 25, `rotateY` 35), no perspective, a white inside and the
fold lines hidden. Saved settings out of range are brought into range when the window is drawn. Result: the window's
settings, and `frame`: the last frame's `{width, height}` in pixels and how long the fold and the drawing took (`foldMs`,
`drawMs`), or null before the first frame. The view is folded and drawn again only when the document, the settings or
the window's size change.
```json
{"name":"run_command","arguments":{"command":"ui.foldPreview","params":{"amount":0.5,"view":"threeQuarter","perspective":30}}}
```
## Image Tools add-on
Image Tools is a built-in add-on for placed images: its commands are `addon.image.removeBackground`,