Puzzle specifications

From Valentina Project's Wiki
Jump to navigation Jump to search

seInfo[edit | edit source]

This page is the document to define the specifications of "Puzzle" app before implementing it. It is not a final document until said so and it is subject to be changed a lot in the coming weeks / months.

See the Trello-Board for the management of the coding: https://trello.com/b/1aUNbdcQ/puzzle

Introduction[edit | edit source]

Creating a layout is a very important part of the pattern making process. It consists in arranging the pattern pieces on a surface of defined size in order to be later printed on paper, exported or direct sent to a fabric cutting machine. The placement of the pieces has to be very compact to save paper / fabric, or in the case of tiled PDF (printed on A4 paper) to later minimize the assembling by the user.

There are two different approaches to resolving this task:

  • Automated layout
  • Manual layout

Currently, Valentina supports only automated layout generation without the possibility to modify the position of the pieces. The algorithm itself is not perfect and doesn't produce optimal results in many cases. Thus it cannot be considered as a replacement for commercial marker generators. Valentina users need more flexibility to create a layout manually. Because there is no known solution to cover this need we have decided to implement the feature as an addition to the already existing automated layout.

Additionally to the "classic" approach described above. We also recognize a need for a gradation card -- a sequence of pieces that "mutates" from input data to input data. Such an approach may serve different purposes: allow a pattern maker to see the gradation process, create layouts with gradations. Such layouts allow very compactly nest pattern pieces on one sheet, reprint them on a sheet of paper with pattern wheel, and cut. Such a format is very popular among magazines.

New App "Puzzle"[edit | edit source]

Puzzle is the name of the new application to create manual layouts. Similar to "Tape", it is an application that is separated from Valentina and work on it's own, but is a part of the Valentina package and work closely together with Valentina.

Icon[edit | edit source]

The first icon-proposition is the following:

Icon of Puzzle

Possible workflows[edit | edit source]

Example 1, The user

  1. has created a valentina pattern with several details, saved in mypattern.val
  2. with Valentina menu Create Manual Layout opens Puzzle. (In the background, Valentina passes Raw Layout Data to Puzzle)
  3. All pieces from the RLD file added to unplaced list.
  4. select a sheet list
    1. if this is a new sheet list a user will be asked to define the settings of the sheet list (e.g. roll paper of width 84,1 cm, length 200cm, margin 1cm)
    2. if there is another opened sheet list a user can select to insert pieces there or create a new sheet list
  5. drag piece from the pending carousel on the sheet list to add it on layout scene
  6. moves the pieces around with drag and drop, alternatively rotate pieces
  7. while doing so, he zooms in and out of layout to see how close some pieces are
  8. realizes, that he needs the pieces' orientation to follow their grainlines
  9. changes the layout option for active sheet which forces pieces with grainline to rotate
  10. sees that the layout doesn't have enough length, he adds 50cm to it
  11. moves the pieces a little bit more around
  12. is happy with the result
  13. removes the unused layout length via a button
  14. exports the layout to a PDF file, he chooses where the file will be saved and how it's called.

Example 2, The user

  1. opens an existing layout
  2. opens an existing Valentina pattern and prepare Raw Layout Data
  3. selects a Raw Layout Data to import some more details from
  4. enables the tile preview, the resulting tile-grid is added as a layer to the layout (see wireframe bellow)
  5. changes the orientation of the tiles from portrait to landscape, it updates the tile-grid on the layout
  6. changes the margins of the tiles in order to fit its printer requirements
  7. adds some pieces from pending list
  8. rotates some pieces and move them around
  9. is happy with the result
  10. exports the layout to a tiled pdf, he chooses where the file will be saved and how it's called.

Example 3, The user

  1. received a layout-file per mail, in which there are saved pieces and half made layout
  2. can still open the layout in puzzle, the pieces that were added to the layout are still there and can be moved, etc.
  3. can link a new Raw Layout Data file that he owns and adds some details to the layout
  4. can export the layout

Example 4, The user

  1. has created a valentina pattern with several details, saved in mypattern.val
  2. with Valentina menu Create Gradation preparing data to be passed to Puzzle
  3. Set gradation index to determine sorting order
  4. Pieces passed to Puzzle
  5. All pieces from the RLD file added to unplaced list.
  6. Save the layout file.
  7. Return to Valentina and prepare another set.
  8. with Valentina menu Update Gradation select the layout file to update in Puzzle
  9. Set another gradation index to determine sorting order
  10. Create gradation by placing pieces on a layout sheet
  11. Save layout

Example 5, The user

  1. Open Puzzle
  2. with Puzzle menu Create Gradation select several RLD files containing a gradation indexes.
  3. Create gradation by placing gradation pieces on a layout sheet
  4. Save layout

Use Cases[edit | edit source]

Valentina and Puzzle could be used for the following use cases. The list of use cases should help us know wich functionalities are needed.

Level Type of use Final product Size Type Description Functions needed
Hobby Own use Paper pattern in Big format (e.g. A0) Single When printing in a copy shop Export in pdf / svg / png to print later
Paper pattern posterized/tiled (e.g A4) Single When printing at home Export in tiled pdf / print directly
Professional Own use Paper pattern in roll format (e.g. A0-width) Single For instance in a tailor's shop, the pattern are printed for themselves.
Selling to hobby sewist Paper pattern in Big format - single size Single Multiple size is burda-like, when several sizes are on top on each other, each size with a special marking.

The final product can be branded (e.g. logo of the designer / pattern maker, water mark).

Need for instructions for the hobby sewist :

arrows, texts, supplementary informations that are in AND/OR outside of the pieces.

Information for who the pattern is (e.g. "This pattern by only be used by Max Mustermann")

Export in pdf/svg/png, tiled pdf

Add other elements than only pieces

Fancy tiles guide

Digital pattern in Big format (e.g. A0) Single
Digital pattern posterized/tiled (e.g. A4) Single
Selling to industry ?
Cutting machine Digital file with cutting instructions Single In the final file, there will be online the onlines to be cut.

No need for fancy layouts.

Export in *.dxf Format

Core Features / Core Specifications[edit | edit source]

This Features / specifications will be part of the first release and are essential to build an MVP (minimum viable product).

Priority Status Name Description Notes / questions
MVP New Manual Layout File Format We need a new file format to save a layout. For instance .vlt (Valentina LayoutT). See "Layout manual data"
MVP Create / Open / Close Layout Standard open/save/close functions The informations are saved in pixels in the file, so the unit can be changed on the fly.
MVP Import/export the raw layout We need an exchange format between Valentina and Puzzle. Raw Layout Data (.rld)

For the implementation, see "Raw Layout Data"

Valentina -> export function, Puzzle import function

Base for this already present in Valentina.
MVP Load Raw Layout Data In Valentina, in the Detail View, there is a new function "create/add to a manual layout". (no need to first create an automatically generated layout)

The selected details are converted in a Raw-Layout file that is automaticaly "sent" to Puzzle.

The user himself doesn't have to deal with this Raw-Layout-file, it all happens in the background.

Puzzle opens / gets in the focus.

The user chooses to add the pieces to a new layout, the curently opened layout or another existing layout

  • then there are a few possible scenarios:
    • we add the pieces to a piece carousel of unplaced pieces
    • We add a new list of pieces (sheet)
    • We append the pieces to an existing list (sheey)
    • We update pieces in existing layout
    • We add pieces to new layer
Through this abstraction and the fact that the pieces are not dependant from the valentina file anymore, it automatically means that we have the possibility to Create a combined layout.

(Layout with pieces coming from different val files).

MVP Layout properties In the layout properties, we can edit central properties for the whole layout (for the various sheets)
  • name of the layout
  • description
  • unit
  • controls
    • Checkbox for "Warning when superposition of pieces" (e.g. pieces get red)"
    • Checkbox for "Warning when pieces out of bound"
  • later
    • central gradation informations
    • bulk export
MVP Sheet A sheet is a white surface, its size is defined in the sheet properties.

It's where the pieces are placed and adjusted (position / orientation).

It displays the layout margins (e.g. in a blue line) and optionally the tile grid (see tile properties)

MVP Sheet properties The following sheet properties should be editable:

- margins (top, right, bottom, left)

- Width of the sheet (margin included), with standard sizes (TODO) and the possibility to define a custom width

- Length (no standard size, as we want to work with paper rolls, the length can be whatever, but not bigger than Qt scene max value)

- Orientation : Landscape / Portrait. (landscape is default)

- Checkbox "follow grain line"

- Layout gap - min distance between pieces allowed

- Button "removed unused length" - removes the unsued lengtht he bottom of the sheet

- Drop Down of file types + Button to export the sheet.

Orientation is now a separate property, meaning when changing the orientation, it doesn't switch width and length anymore.

Only Rolling paper (defined width, variable length). No DIN Ax format with several sheets

RLT: 23.05.2020 : is that still true?

RLT: 23.05.2020 : instead of "remove unused length", maybe "adapt length" (it would add or remove length as necessary).

MVP Export the layout A layout can be exported. Following formats are available:

*.svg, *.pdf, *.ps, *.eps, lots of *.dxf

-> Same formats as supported by Valentina formats. Expect PNG, to not limit the size of a sheet. PNG can be created by any third party application that supports base export formats.

MVP Zoom in and out of the sheet Zoom in and out of the sheet

- with "Mouse-Wheel + Ctrl"

- using the drop-down / input in the bottom left of the screen

-> Support all zoom features of Valentina

MVP Piece Carrousel It's a list of pieces, represented by previews. The piece carrousel can be placed on the top, left, right or bottom of Puzzle.

The piece carrousel has a drop down to navigate between the various piece lists : unplaced pieces, piece of sheet #1, piece of sheet #2 ...

MVP Add pieces to a sheet Dragging a piece adds it to the current sheet in place of mouse release. Each piece can be added only one time. Use option in Valentina to specify number of pieces need for layout.

If the piece doesn't fit the layout, we place it anyway and is marked as invalid (depending on the layout properties the piece will the get red or not.)

MVP Move a piece in a sheet A pattern piece can be moved around
  • with the mouse (drag & drop)
  • with the arrow keys of the keyboard when the piece is selected
MVP Rotate a piece in a sheet A piece can rotated when: (posibilites, tbd)
  • clicking in one of the corner of the surrounding box of a piece and then moving the mouse.
  • keyboard shortcut + mouse, for instance instance Alt + clicking and moving the mouse rotates the piece.
  • keyboard shortcut if piece is selected, for stance Alt + arrow top or arrow bottom rotates the piece.

If the piece has the option "follow" grainline, it can only be rotated only based on grainline potions.

MVP Behaviour by superposition of pieces (see Edit the Layout properties) it is possibile to choose if we accept pieces superposing.

If pieces are superposing, they both get red

MVP Behaviour by pieces getting out of the layout limit / margin like for the superposition behaviour, when piece gets out of the margin limit, it becomes red
MVP Piece properties - Name (read only, set in valentina)

- Checkbox "Show seamline"

- Dropdown "Cutting line type" (list of several line types, for instance dots, rounds etc.)

- Dropdown "Cutting line color" (list of possible colors, or maybe a color picker with a list of user-defined colors?)

- Checkbox "Mirror the piece" (mirrores the piece. The position of the text boxes should be mirrored as well but not their content)

Some of the properties are only suitable for certain export formats.

Further Features / Specifications[edit | edit source]

This features / specifications will be implemented, but won't be part of the first release.

Priority Status Name Description Notes / questions
List of sheets Each layout can have one or several sheet.

Way to switch between sheet: a combo box similar to pattern piece in Valentina.

in MVP version, only one sheet, but we already include the list-possibility in the file format etc.
Sticky edges Sticking to edge of a sheet and other pieces on a layout Sticky edge must has a radius of activation. It main purpose to help improve speed of creation of layout. If piece is in radius of activation of the sticky edge it moves automatically to that edge. Use can move it out only if move far than radius of activation of the feature.
Move several pieces at once in a sheet When several pieces are selected at the same time, it is possible to move them together.
MVP Remove piece from a sheet It removes the piece from the sheet it's placed on back to the list of unplaced pieces
Delete a piece from the layout When a piece is in "unplaced pieces", we can delete it for good from the layout
Tiles properties - Dropdown "Tile size" (standard sizes like A4, A3, ...) maybe also custom sizes?

- Margins (top, right, bottom, left) - margins have to be defined for the printers. bigger margins means a smaller usable surface of the tile.

- Dropdown "orientation" (portrait, landscape)

- Checkbox "show tiles on the layout" - displays a grid on the layout. It allows better placement for pattern that are distributed as tiled-pattern. The grid displays the surface usable of the tiles, the margins are not included.

- Drop-Down "Matching mark types" (for now we don't have specific matching marks, that could be a nice feature)

- Button "Export Tiled Layout"

RLT: 23.05.2020 : I think it should be possible to edit the tiles properties differently for each sheet.

For instance, for 1 sheet orientation landscape of the tiles would be more efficient and for the second one, portrait would be better.

Export to tiled PDF The layout is cut down in tiles and exported in as PDF Format, as defined in the "Tiles properties".

It allows a big layout to be printed on a home printer, then assembled / glue together.

Watermark The watermark function was added to valentina. We probably want it here as well.
Check/stripe nesting There are few special types of nesting: check and stripe. For supporting this type of nesting user must be able to define vertical and horizontal position rules for a piece. And additionally define a fabric struct: distance between horizontal and vertical lines.
"Gradation map" mode A lot of pattern maker sellers practice selling gradation maps. It is not a layout in common understanding, but rather an image with pieces in different sizes.


  • Disabling piece intersection checks.
  • Some sort of axis line or point which can help to organize pieces in butch.
  • Support for layers. For example, each size will be in a separate layer.
  • Export layers in PDF and SVG.

TODO: add the examples hier from the issue.

First make sure if it's ok to have these pattern hier.

Automated layout generation The New automated generation of the layout is not perfect, but still more than a very good start to then adjust the pieces manually.

We could let the user first add its pieces to the layout a bit randomly and if he wishes let him first have the pieces be placed automatically.

Then the person can do the rest manually.

Update pieces on a Layout For example, after reloading raw layout.
  • Update all pieces at once
  • Update one piece at a time
  • possibility to disabled Pieces Update for chosen pieces.
To be able to provide this feature each piece must have a unique stable id. This way we can link a piece from Raw Layout Data file to a piece on layout.
Gradation card Special layout mode to allow creation and nesting combined pieces containing several iterations based on different input data. The process of combining must be automated and based on gradation index, piece uuid and gradation center point provided by user.

Most likely in this mode piece intersection check will be disabled. Each piece must contain information about each gradation index. User must be able to remove the index from a layout data for all pieces. Combined piece like like one item with many sea allowances and internal paths.

Feature candidates / Optional features[edit | edit source]

This functionalities are propositions that need to be discussed. Depending on their usefulness / importance, they might be implemented as a core feature or

Priority Name Description Notes / questions
Copy/ clone a piece of the layout It copies an existing piece.

When a layout is exported for cutting, it makes sense to have several time the same piece.

Nice to have depending if users need it. We can do this in valentina.

You can specify this in Valentina. Export Raw Layout Data just must follow the option.

Wireframes / UI - Version 3[edit | edit source]

Current Piece Tab with a simple piece[edit | edit source]

Current piece Tab with a multisize piece (gradation)[edit | edit source]

Sheet tab[edit | edit source]

Tiles tab[edit | edit source]

[edit | edit source]

Layout Tab[edit | edit source]

New tab that we didn't have before and that can hold central properties or actions

Data definition[edit | edit source]

This section describes requirements for the Puzzle app formats.

For work Puzzle requires to major formats: data format for exchange data with Valentina and data format for saving process of creating manual layout.

Raw Layout Data[edit | edit source]

Raw layout data is a format for exchanging data with Valentina. Main goal of the format is to provide cheap and fast way of exchanging data between to applications. Because both applications based on the same codebase and are tightly bound we will use format based on QDataStream class.

Using QDataStream has its cons and pros.


  • Cheap to develop and start using.
  • Good solution for exchanging data between applications.


  • Binary format.
  • Hard to maintain backward compatibility.
  • Hard to fix.
  • No support for conversion.

Considering all the pros and cons basing format on QDataStream class is a good decision. Main purpose of the Raw Layout Data format is to provide exchange format between Valentina and Puzzle. Such exchange in most cases will be done without user interference. The RLD format is short lived files. There is no need to provide great level of compatability with old the format versions. This is one way exchange without need of modifying file. Easy write on one side and easy read on another. Perfect for our needs.

Specification[edit | edit source]

  • Class "VRawLayout" to read and write the raw layout data.
  • To be used other classes we will add to VRawLayoutData struct must support serialization/de-serialization with QDataStream class.
  • It seems to support update for piece shapes we must distinguish between them. The best way to achieve this is to provide a unique UUID value for each piece

Manual Layout Data[edit | edit source]

In contrary to the RLD format the MLD has different nature. The following list of features must be supported:

  • Easy to fix.
  • Exchange format.
  • Write/Read/Modify.
  • Great backward compatibility.
  • Support conversion from older format versions.
  • Text-based.
  • Support manual layout creation progress.
  • Validation.
  • Easy implementation of undo/redo operations.

Based on the list of requirements the best choice for us is the same we use for VAL pattern format -- XML. It is text-based format that easy to fix and save VCS systems. It has validation, good conversion support, etc.

Specification[edit | edit source]

See vlt Format specifications

Classes definition[edit | edit source]

16.05.2020 - we need a bit of refactoring. We have a new structure and also we want the classes and file to follow the same name convention.

Possible Prefix: VP for ValentinaPuzzle, but we can use something else.

I propose the following:

Class name before Class name after
PuzzleApplication VPApplication
PuzzleCommands VPCommands
PuzzleMainwindow VPMainWindow
Stable VPStable
Version VPVersion
VPuzzleCommandLine VPCommandLine
VPuzzleLayout VPLayout
- VPSheet
VPuzzleLayer VPPieceList
VPuzzlePiece VPPiece
VPieceCarrousel VPCarrousel
VPieceCarrouselLayer VPCarrouselPieceList
VPieceCarrouselPiece VPCarrouselPiece
VPieceCarrouselPiecePreview VPCarrouselPiecePreview
VPuzzleMimeDataPiece VPMimeDataPiece
VPuzzleMainGraphicsView VPMainGraphicsView
VPuzzleMainGraphicsScene VPMainGraphicsScene
VPuzzleGraphicsLayout VPGraphicsSheet
VPuzzleGraphicsPiece VPGraphicsPiece
DialogAboutPuzzle VPDialogAbout
layoutliterals vplayoutliterals
VPuzzleLayoutFileReader VPLayoutFileReader
VPuzzleLayoutFileWriter VPLayoutFileWriter

Useful links[edit | edit source]

Notes[edit | edit source]

  • Here is a space for notes and ideas, that can be added later on in the tables / wireframes above

use watermark in pattern[edit | edit source]