3cca4a2350
M001: Kerf Engine (pipeline, API, presets, Docker) — 3 slices, 10 tasks M002: Kerf App (Import UI, Canvas, Text system) — 3 slices (planned, not detailed) M003: Export, Docker Compose, Embed Mode — 3 slices (planned, not detailed) 25 requirements extracted from GSD-INITIATE.md 7 architectural decisions recorded Human checkpoints gate M001→M002→M003 transitions
43 lines
5 KiB
Markdown
43 lines
5 KiB
Markdown
# Requirements — Kerf
|
|
|
|
> Auto-generated from GSD-INITIATE.md. Canonical source: `.gsd/gsd.db`
|
|
|
|
## Engine Requirements
|
|
|
|
| ID | Description | Status | Primary Owner | Validation |
|
|
|----|-------------|--------|---------------|------------|
|
|
| R001 | Engine accepts raster images (PNG, JPG, BMP, TIFF, WebP) and returns clean vector output (SVG, DXF, JSON) | active | M001/S01 | POST /engine/trace returns valid SVG/DXF/JSON for each format |
|
|
| R002 | Engine accepts existing SVG input for simplification passes via /engine/simplify | active | M001/S02 | Node count drops, shape preserved on complex SVG input |
|
|
| R003 | Preprocessing pipeline: grayscale, denoise (bilateral), CLAHE contrast, Otsu threshold, optional Canny edge, dilation/erosion — all tunable | active | M001/S01 | Each preprocessing param produces measurable output difference |
|
|
| R004 | Mode A vectorization via Potrace with tunable params (turdsize, alphamax, opticurve, opttolerance) | active | M001/S01 | Potrace params affect output; clean SVG from high-contrast logo |
|
|
| R005 | Mode B vectorization via VTracer with tunable params (colormode, hierarchical, filter_speckle, etc.) | active | M001/S01 | VTracer produces better output on noisy/photographic inputs |
|
|
| R006 | Post-processing: RDP path simplification (epsilon tunable), island detection, open path detection/repair, node count reporting | active | M001/S02 | Simplification reduces nodes; islands flagged; open paths detected |
|
|
| R007 | DXF output AC1015+ compatible, openable in Inkscape/LightBurn with clean geometry | active | M001/S02 | DXF opens in target apps with closed paths, no errors |
|
|
| R008 | Preset system: sign, patch, stencil, detailed, custom — stored as JSON in /engine/presets/ | active | M001/S03 | GET /engine/presets returns all; each preset produces distinct output |
|
|
| R009 | Engine API is stateless, REST over HTTP, JSON responses with metadata | active | M001/S01 | Concurrent requests succeed; no server-side session state |
|
|
| R010 | Output metadata includes format, path_count, node_count_total, open_paths, warnings, processing_ms | active | M001/S02 | Metadata fields present and accurate in all responses |
|
|
|
|
## App Requirements
|
|
|
|
| ID | Description | Status | Primary Owner | Validation |
|
|
|----|-------------|--------|---------------|------------|
|
|
| R011 | React SPA with three views: Import & Convert → Design Canvas → Export | active | M002 | Navigation between views works, state carries forward |
|
|
| R012 | View 1: Upload raster/vector, select preset, tune sliders with live preview, accept output | active | M002/S01 | Slider changes produce visible preview updates within 300ms debounce |
|
|
| R013 | View 2: Konva.js 2D canvas with artboard shapes (rect, square, circle, oval, shield, pennant, custom) | active | M002/S02 | Each artboard shape renders at correct real-world proportions |
|
|
| R014 | Canvas text objects: font picker from fonts.json manifest, opentype.js rendering, convert-to-paths | active | M002/S03 | Text renders with loaded font; path conversion produces matching vectors |
|
|
| R015 | Canvas shape objects: rectangle, circle, ellipse, line (solid/dashed/dotted/double/centerline), stroke/fill | active | M002/S02 | Each shape type renders and is selectable/moveable/resizable |
|
|
| R016 | Object panel: layer stack, reorder via drag, visibility toggle, lock toggle per object | active | M002/S02 | Layer order affects rendering; visibility/lock toggles work |
|
|
| R017 | Alignment tools: align left/center/right/top/middle/bottom, distribute H/V, center on artboard | active | M002/S02 | Selected objects align correctly relative to artboard or selection |
|
|
| R018 | Undo/redo with full history stack | active | M002/S02 | Actions reversible; redo restores after undo |
|
|
| R019 | View 3: Export as DXF/SVG/PNG; DXF layer assignment; text-to-paths enforcement; pre-export validation | active | M003/S01 | Export produces valid files; validation catches open paths and unconverted text |
|
|
| R020 | DXF export at real-world scale with correct units (inches/mm) | active | M003/S01 | DXF dimensions match artboard size in target application |
|
|
|
|
## Deployment & Integration Requirements
|
|
|
|
| ID | Description | Status | Primary Owner | Validation |
|
|
|----|-------------|--------|---------------|------------|
|
|
| R021 | Docker Compose deployment: kerf-engine, kerf-app, kerf-server as separate services | active | M003/S02 | docker-compose up starts all services healthy |
|
|
| R022 | kerf-engine deployable independently for API-only consumers | active | M003/S02 | Engine container starts alone, API responds |
|
|
| R023 | Embed mode: script tag + div, Shadow DOM scoped styles, postMessage events | active | M003/S03 | Component renders in host page; no style bleed; download works |
|
|
| R024 | Font system: local .otf files + fonts.json manifest, volume-mounted | active | M002/S03 | Fonts load from volume; adding new font = drop file + update manifest |
|
|
| R025 | Engine and App architecturally decoupled — App consumes Engine via HTTP API | active | M001 | Engine has zero imports from App; App calls Engine only via HTTP |
|