76 lines
4.4 KiB
Markdown
76 lines
4.4 KiB
Markdown
# Shop Packet Plan
|
|
|
|
A living plan for turning the BOM into a **shop-packet generator**. Adjust as we go.
|
|
|
|
## Guiding principle
|
|
The **math layer is deterministic and inspectable**; AI is used **only for narrative**
|
|
(instruction wording, jig explanations). Cut lengths, kerf, counts, layouts, jig
|
|
dimensions, validation, and warnings all come from code — the AI never invents a number.
|
|
|
|
UI language: say **"Optimize" / "Find better layout"**, never "optimal" (woodworking
|
|
wants explainable good layouts, not slow provably-perfect ones).
|
|
|
|
## Data flow
|
|
```
|
|
Scene → CutItems → StockInventory → CutPlan → ShopPacket(view)
|
|
```
|
|
|
|
## The keystone: `CutPlan` (cutplan.py)
|
|
Dataclasses, JSON-friendly, **stable IDs everywhere** (`CutItem.id`, `StockPiece.id`,
|
|
`Placement.id`) — never rely on list position. Serializable from day one
|
|
(`to_dict`/`from_dict`) so we can save manual layouts, compare strategies, export, debug.
|
|
|
|
- `ShopSettings` — kerf, stick/sheet sizes, offcut-usable thresholds, plywood rotation
|
|
allowed, grain direction (future), tolerances (mortise/tenon clearance, sanding
|
|
allowance, reveal). Defaults present from day one even before they're in the UI.
|
|
- `CutItem` — a required piece (part id, stock, length, width, is_sheet, note e.g. "incl. tenon").
|
|
- `StockPiece` — a physical stick/sheet with its `placements` and `waste` regions.
|
|
- `Placement` — a cut item on a stock piece: position (x[,y]), rotated?, locked?.
|
|
- `WasteRegion` — leftover, with a `reusable` flag (≥ threshold).
|
|
- `CutPlan` — settings, items, stock_pieces, unplaced, strategy, **score**, warnings.
|
|
- `score = {stock_count, waste_area, reusable_offcuts, warnings, strategy_name}` —
|
|
detailed, so the UI can explain *why* one layout beats another.
|
|
- `build_cut_plan(scene, settings=None, strategy="decreasing") -> CutPlan`.
|
|
- `validate_cut_plan(plan) -> [problems]` — no piece outside stock, no overlaps, kerf
|
|
respected, every item placed-or-warned, stock dims respected, rotations legal.
|
|
|
|
`ShopPacket` stays thin (a view/composition over cut rows + shopping rows + cut plan +
|
|
warnings) until `CutPlan` is solid.
|
|
|
|
## Phases (commit after each)
|
|
|
|
**Phase 0 — CutPlan + ShopSettings (keystone).**
|
|
New `cutplan.py` with the model + `build_cut_plan` + `validate_cut_plan`. Port the current
|
|
FFD (lumber) / shelf (plywood) packers behind it. **Keep old APIs** (`layout.nest_lumber/
|
|
nest_plywood/stock_counts/waste_summary`, `cutlist.shopping/waste_summary`) as thin wrappers
|
|
over `build_cut_plan` so existing tests/UI keep working. BOM window renders from `CutPlan`.
|
|
Tests: lumber, plywood, kerf, tenon extra length, unplaced/oversize warnings, JSON roundtrip.
|
|
|
|
**Phase 1 — smart auto-layout.** Strategies behind the buttons: FFD, BFD, bounded exact
|
|
(small jobs, capped), random restarts / best-of-N for big jobs; objective "minimize stock,
|
|
then maximize useful offcuts (bonus for common 12/24/36″)". Plywood: per-panel rotation;
|
|
shelf/guillotine/maxrects; score by sheet count, waste area, reusable-offcut size. Buttons:
|
|
**Optimize · Try Alternative · Best of N**; surface warnings.
|
|
|
|
**Phase 2 — structured instructions.** Deterministic ordered steps from CutPlan + scene
|
|
(buy → cut per plan → mark joinery → repeated cuts/jigs → cut/drill features → dry-fit →
|
|
assemble → finish); **then** AI polishes wording (numbers stay from code). Instructions tab.
|
|
|
|
**Phase 3 — jig suggestions (rule-based → AI explanation).** Detect patterns (identical
|
|
crosscuts, repeated end-offsets, repeated mortises/holes, mirrored L/R, repeated angles,
|
|
repeated panel widths) → candidates with **computed dims** (stop block, spacer, drill
|
|
template, story stick, mortise template, angle sled). AI explains build/use. Jigs are
|
|
**shop aids** kept separate from project parts — optional, opt-in before any jig material
|
|
enters the BOM. Jigs tab.
|
|
|
|
**Phase 4 — constrained manual layout editing.** Drag in the layout view as a *constrained
|
|
planner*: snap to stock edges / kerf / neighbors; invalid = red; move pieces between
|
|
sticks/sheets; rotate plywood (if grain allows); **lock** a piece so re-optimization works
|
|
around it; live "valid / invalid / saves a stick / wastes more" feedback. Builds on
|
|
`CutPlan.locked` + `validate_cut_plan`.
|
|
|
|
## Deterministic vs AI
|
|
| Code (deterministic) | AI (narrative only) |
|
|
|---|---|
|
|
| lengths, kerf, counts, layouts, scores, jig dims, validation, warnings | instruction wording, jig build/use explanations, summaries |
|