Placement Patterns

Placement Patterns

A placement pattern tells the layout engine how pieces from a material should tile a surface. Each project has its own pattern library so the same pattern (e.g. "1/3 running bond, vertical") can be re-used on many surfaces.

Feature line from the README: 🔁 Placement patterns (stacked, running bond, custom offsets, …).

What a pattern controls

A pattern is described by six independent dimensions:

Field	Choices	Effect
Type	Stacked, Vertical, Bond 1/2, Bond 1/3, Custom offset, Diagonal	The base joint topology.
Orientation	Horizontal, Vertical, Custom angle	How the material's long side is oriented.
Origin	Center, Top-left, Bottom-left, Custom point	Where the first piece starts on the surface.
Direction	Left → Right, Right → Left, Top → Bottom, Bottom → Top	Which way the grid grows.
Symmetry	None, Vertical, Horizontal, Custom axis	Optional mirroring around an axis.
Row offset	mm or % of unit width	Lateral shift between adjacent rows (only when the type permits it).

Some Type values lock the row offset:

• Stacked and Vertical Stacked force zero offset.
• Bond 1/2 forces 50 %.
• Bond 1/3 forces ≈ 33 %.
• Diagonal is rotated and has no row offset concept.
• Custom offset exposes the row-offset field for free editing.

When a surface with a material is the context (contextMaterialId), the row-offset field switches between mm and % of unit width with an automatic conversion.

Type catalogue

Type	Description
Stacked	Aligned grid; all joints line up vertically.
Vertical	Tall units stacked aligned in columns; zero offset.
Bond 1/2	Running bond — each row offset by 50 % of the unit width.
Bond 1/3	Running bond — each row offset by 33 % of the unit width.
Custom offset	Specify a custom row offset (in mm or % of unit width).
Diagonal	Units rotated 45° forming a diagonal layout.

Each option in the editor is illustrated by a small preview (PatternVisuals) that updates live as you change settings.

Managing patterns

The bottom panel contains the Pattern List:

• Add pattern — creates a new pattern with sensible defaults and opens the standalone editor dialog.
• Edit — opens the editor for the selected pattern.
• Delete — protected against deleting a pattern that is in use; you must first un-assign it from every surface and layout that references it.

Assigning a pattern to a surface

The Surface Properties panel has an Assign pattern control. Selecting a pattern there:

1. Stores surface.placementPatternId.
2. Opens an in-place Pattern settings section so you can tweak the pattern without leaving the surface context.

Optimisation priorities

Every pattern carries an OptimizationPriority block that biases the layout engine when it generates pieces. Each priority can be Low, Medium or High (mapped internally to weights 1 / 2 / 4):

Priority	What it favours
Waste	Layouts with the smallest amount of unusable cut-offs.
Symmetry	Visually symmetric distributions, especially around openings.
Cut count	Fewer pieces of cut material at edges.
Small pieces	Avoids producing pieces below the material's minimum size.

Plus two extra knobs:

• Joint alignment — Off, Selected surfaces or Connected group. Tells the engine whether joints should line up across selected surfaces or all surfaces in the same connection cluster.
• Lock manual offset — when on, the engine never auto-shifts the pattern origin; whatever you dragged with the Pattern origin tool is preserved.

Pattern origin tool (M)

While the Pattern origin tool is active, every patterned surface shows a handle representing its computed origin. Dragging the handle:

• Snaps to whole-piece increments while the snap modifier is on.
• Live-updates the pattern values shown in the placement panel.
• Persists as a manual offset on the pattern instance.

Where this lives in the codebase

• Pattern catalogue & metadata — src/features/placementPatterns/patternMeta.ts, PatternVisuals.tsx
• Pattern UI — PatternList.tsx, PlacementPatternPanel.tsx, PlacementPatternEditorDialog.tsx, AssignPatternControl.tsx
• Optimisation knobs — OptimizationPanel.tsx
• Pattern-origin canvas tooling — src/features/materialLayout/PatternOriginLayer.tsx
• Domain helpers — src/domain/placementPatterns/

Related pages

• Material Library
• Surfaces, Openings and Connections
• Auto-generated Cut Lists and Layouts