PPK Dieline Editor

A Next.js proof of concept for turning packaging dielines into editable 2D layouts and live Three.js folding previews.

Current project progress

The current implementation has two editor surfaces:

• Parametric Dieline Editor — the default route. Generates a folding carton from dimensions and model parameters, validates the result, previews it in 2D/3D, and exports JSON or SVG.
• Dieline-to-3D Editor — loads fixed template JSON files or imports annotated SVGs, then renders the same 2D canvas texture onto a foldable 3D preview.

Requirements

• Node.js compatible with the installed Next.js 16 dependency. Node 20.19+, 22.12+, or newer is recommended based on the dependency lockfile.
• npm

Run locally

npm install
npm run dev

Open the local Next.js URL shown in the terminal, usually:

• http://localhost:3000

The home route redirects to /editors/parametric-dieline.

Available routes

Route	Purpose
/	Redirects to the parametric editor.
/editors/parametric-dieline	Interactive parametric folding-carton editor.
/editors/dieline-to-3d	Fixed-template and SVG-import dieline-to-3D editor.
/api/templates/[templateId]	Serves bundled template JSON fixtures.

Bundled template IDs currently served by the API:

• mailer-box-300-200
• mailer-box-315x202x62
• two-panel-fold
• cardbox-60x30x90

What is implemented

Parametric folding carton

The default editor uses the card-box-basic model to generate a structured dieline from:

• base dimensions: length, width, height
• closure parameters: top/bottom closing flaps, tuck flaps, and closure type
• dust flap parameters: size, radius, slant, step-in, and flat top width
• glue flap parameters: size and top/bottom angles
• material and print-area parameters: material thickness, fold allowance, bleed, safe area, and cut gap

The generated card box includes stable panel IDs, cut lines, fold lines, bleed paths, safe-area paths, validation issues, and a compiled shape that the existing 2D/3D renderer can preview.

Editor features:

• unit switching for length inputs (mm, cm, in)
• debounced regeneration while editing fields
• validation messages for invalid model inputs
• 2D pan/zoom/fit controls
• configurable guide visibility and colors
• live 3D fold preview with open/close controls and fold slider
• JSON export for the structured template shape
• SVG export with annotated dieline layers

Fixed-template and SVG-import editor

The /editors/dieline-to-3d route can:

• load bundled template fixtures from /api/templates/[templateId]
• import browser-uploaded SVG files
• preserve annotated panels and folds when SVG metadata is present
• infer a basic panel/fold layout from cut and fold geometry when possible
• download the imported or selected template as JSON

The SVG importer recognizes common dieline line classes/metadata for cut, fold/crease, bleed, safe-area, dimension, construction, and glue-area lines.

2D/3D renderer

The shared renderer pipeline provides:

• canvas-based 2D rendering of trim, crease, bleed, safe-area, dimensions, panels, and simple demo artwork
• texture-canvas generation for the 3D material
• Three.js panel meshes with UVs and material thickness
• fold graph construction and ordered fold progress
• optional panel labels and debug helpers
• viewport controls for pan, zoom, fit, and keyboard navigation

Project structure

src/app/                         Next.js App Router pages and template API
src/components/                  Shared editor layout and canvas UI
src/editors/                     Client-side editor orchestration
src/core/models/                 Parametric model registry and field definitions
src/core/parameters/             Parameter and dimension helpers
src/core/structure/              Fold graph and structural validation
src/core/template/               Template compiler, schema, serializers, SVG importer
src/core/units/                  Unit conversion utilities
src/render2d/                    Canvas renderer, hit testing, viewport, SVG export
src/render3d/                    Three.js scene builder, preview, fold animation
templates/                       Bundled template fixtures and controlled SVG sources
test/core/                       Node test suite for core geometry/rendering behavior
scripts/                         Template extraction and local utility scripts

Templates

Parametric model

• src/templates/cardbox/ — implemented folding-carton/card-box model, geometry generator, validation, and compiled-renderer adapter.

Bundled fixtures

• templates/mailer-box-315x202x62/template.json — reconstructed 315 × 202 × 62 mm mailer-box template.
• templates/mailer-box-315x202x62/dieline.svg — controlled annotated SVG source for the same mailer box.
• templates/mailer-box-300-200/template.json — compact mailer-box fixture.
• templates/cardbox/template.json — imported cardbox fixture.
• templates/two-panel-fold/template.json — small two-panel feasibility fixture.

The MVP assumes controlled/annotated SVG templates for reliable conversion. Arbitrary SVG import is best-effort and may fall back to a flat or inferred layout when structural panel/fold metadata is missing.

Scripts

npm run dev              # Start the Next.js development server
npm run build            # Build the Next.js app
npm run start            # Start a production build
npm test                 # Run the node:test suite
npm run extract:mailer   # Rebuild the mailer-box fixture from its controlled SVG

Additional one-off utility scripts exist under scripts/, but only extract:mailer is wired as an npm script.

Testing

Run all tests with:

npm test

The test suite covers the parameter engine, unit conversion, card-box geometry and export behavior, template/schema handling, fold graph and structural validation, 2D rendering helpers, SVG import heuristics, and 3D scene/fold construction.

Current limitations

• The parametric editor currently exposes one registered model: card-box-basic.
• The 3D preview is an MVP renderer, not a production manufacturing simulator.
• SVG import is deterministic for controlled/annotated SVGs and best-effort for arbitrary SVGs.
• Some fixed fixtures use simplified rectangular 3D panel approximations while preserving richer 2D guide paths.
• Production-grade CAD operations, artwork persistence, and multi-format export are still future work.