commit 591399495cf3af7636a702a3d9aab3684ee9d97d Author: Sven Date: Fri May 1 19:36:18 2026 +0200 Dateien nach "/" hochladen diff --git a/project_scope.md b/project_scope.md new file mode 100644 index 0000000..e52e30b --- /dev/null +++ b/project_scope.md @@ -0,0 +1,1044 @@ +# Project Scope: Calibrated Trace CAD + +## 1. Purpose + +This document defines the initial product scope, technical architecture, development priorities, and implementation rules for a desktop application that converts manually traced real-world outlines into clean, scale-accurate 2D CAD geometry and DXF exports. + +The application is not an AI-based image-to-vector tool. It is a deterministic, user-controlled 2D tracing and sketching application that uses a calibrated printed sheet and photo reference as a scale-accurate background layer. The user manually reconstructs clean CAD geometry over the reference image using lines, arcs, circles, and assisted fitting tools. + +The goal is to produce technically valid 2D DXF drawings suitable for laser cutting, CNC routing, milling preparation, or further editing in CAD software. + +--- + +## 2. Product Concept + +The product should allow a user to: + +1. Print a calibrated marker sheet. +2. Place or trace a real object on the sheet using a pencil, fineliner, or marker. +3. Photograph or scan the sheet. +4. Import the image into the application. +5. Let the software detect the sheet, correct perspective, and establish a real-world millimetre coordinate system. +6. Manually trace the visible sketch using precise CAD-style tools. +7. Optionally refine the geometry with dimensions or constraints. +8. Export a clean DXF file using real CAD entities. + +The standard workflow must not require manual dimensioning. Dimensioning and constraints are optional advanced features. + +The core UX principle is: + +> The physical sheet provides scale. The photo provides visual reference. The user creates clean geometry manually. + +--- + +## 3. Non-Goals + +The application must not be designed as: + +- A fully automatic AI image-to-DXF converter. +- A raster autotracing tool that blindly converts pixels into vector paths. +- A general-purpose 3D CAD application. +- A parametric CAD clone in the first MVP. +- A web-only prototype. +- A Python application. + +Automatic detection of pencil lines may be added later as an assistive feature, but it must never become the source of final geometry without explicit user confirmation. + +--- + +## 4. Target Platform and Technology Stack + +### 4.1 Primary Stack + +Use: + +- Language: C# +- Runtime: .NET 8 or newer +- UI framework: Avalonia UI +- Rendering: Avalonia custom controls / SkiaSharp where useful +- Computer vision: OpenCvSharp / OpenCV +- DXF export: netDxf initially, with an abstraction layer to allow replacement later +- Project format: custom JSON +- Unit tests: xUnit + +### 4.2 Release Target + +The first release target is: + +- Windows x64 +- Portable executable or portable application folder +- No forced installer +- No Python runtime dependency +- No external CAD dependency + +Preferred initial packaging: + +```bash +# Portable folder build, preferred while native OpenCV DLLs are involved +dotnet publish src/TraceCad.App \ + -c Release \ + -r win-x64 \ + --self-contained true +``` + +Single-file publishing may be evaluated later: + +```bash +dotnet publish src/TraceCad.App \ + -c Release \ + -r win-x64 \ + --self-contained true \ + /p:PublishSingleFile=true \ + /p:IncludeNativeLibrariesForSelfExtract=true +``` + +### 4.3 Future Platforms + +The architecture should not block later builds for: + +- Linux x64 +- macOS x64 +- macOS arm64 + +However, Windows x64 is the first-class MVP target. + +--- + +## 5. Recommended Solution Structure + +Use a clean multi-project .NET solution. + +```text +TraceCad/ + src/ + TraceCad.App/ # Avalonia UI application + TraceCad.Core/ # Geometry, document model, tools, snapping, validation + TraceCad.Dxf/ # DXF export/import abstraction + TraceCad.Vision/ # OpenCV, marker detection, homography, calibration + tests/ + TraceCad.Tests/ # Unit tests for geometry, export, transforms, validation + docs/ + project_scope.md + architecture.md + mvp.md + dxf-export.md + samples/ + reference-images/ + exports/ +``` + +### 5.1 Dependency Rules + +The dependencies must flow in one direction: + +```text +TraceCad.App + -> TraceCad.Core + -> TraceCad.Dxf + -> TraceCad.Vision + +TraceCad.Dxf + -> TraceCad.Core + +TraceCad.Vision + -> TraceCad.Core where needed for coordinate data only + +TraceCad.Core + -> no UI framework dependency + -> no Avalonia dependency + -> no OpenCV dependency + -> no DXF library dependency +``` + +The `TraceCad.Core` project must remain UI-independent and testable. + +--- + +## 6. Core Design Principles + +### 6.1 Millimetres as Internal Units + +All model-space geometry must be stored in millimetres. + +Pixels may only be used in the view/rendering layer. + +Required coordinate spaces: + +```text +Model Space real geometry in mm +View Space screen pixels +Reference Space calibrated image/background +Export Space DXF coordinate output in mm +``` + +Never store final CAD geometry in pixels. + +### 6.2 Deterministic Geometry + +Final geometry must consist of explicit CAD entities: + +- Lines +- Circles +- Arcs +- Polylines where appropriate +- Optional dimensions later +- Optional construction entities + +Do not export raw traced raster contours as the main workflow. + +### 6.3 Reference Image Is Not Geometry + +The imported photo or scan is a locked background/reference layer. + +It provides: + +- visual guidance +- scale +- orientation +- real-world coordinate alignment + +It does not directly define final CAD geometry unless the user explicitly creates geometry from it. + +### 6.4 Optional Precision, Low Friction by Default + +The default workflow should require no manual bemaßung/dimensioning. + +Advanced users may later add: + +- exact length +- exact radius/diameter +- exact angle +- horizontal/vertical constraints +- parallel/perpendicular constraints +- tangency +- equality constraints + +But the primary workflow is visual tracing over a scale-accurate reference. + +--- + +## 7. User Workflow + +### 7.1 Standard Workflow + +1. Start new project. +2. Import a photo/scan of a traced calibration sheet. +3. The application detects the printed sheet and sets the document scale. +4. The reference image is displayed on the canvas as a locked, semi-transparent layer. +5. The user manually traces the outline with CAD tools. +6. The application displays endpoint snaps, grid, and geometry previews. +7. The user validates the sketch. +8. The application exports a clean DXF. + +### 7.2 Early MVP Workflow Before Marker Detection + +For MVP staging, marker detection may be delayed. + +Initial workflow: + +1. Start app. +2. Work on an empty millimetre canvas. +3. Draw lines, circles, and arcs. +4. Export DXF. + +Then add: + +1. Import reference image. +2. Manually scale/position the reference image. +3. Trace over it. + +Then add: + +1. Marker sheet detection. +2. Automatic calibration. + +--- + +## 8. MVP Phases + +### 8.1 Version 0.1 — Editor Core + +Goal: prove that the application can create clean 2D CAD geometry and export valid DXF. + +Required features: + +- Avalonia desktop app starts reliably. +- Custom drawing canvas. +- Model-space coordinate system in mm. +- Pan and zoom. +- Grid display. +- Basic snapping to existing endpoints. +- Draw line. +- Draw circle through 3 points. +- Draw arc through 3 points. +- Select entity. +- Delete selected entity. +- Undo/redo. +- Save/load custom JSON project file. +- Export DXF containing LINE, CIRCLE, and ARC entities. + +Not required in 0.1: + +- OpenCV +- marker detection +- camera input +- real-time calibration +- constraints +- automatic image tracing +- dimensions + +### 8.2 Version 0.2 — Reference Image Layer + +Goal: allow manual tracing over an imported background image. + +Required features: + +- Import image as reference. +- Display reference below CAD entities. +- Adjust image opacity. +- Lock/unlock reference image. +- Move/scale/rotate reference image manually if needed. +- Continue drawing geometry over image. + +### 8.3 Version 0.3 — Calibration Sheet + +Goal: automatically convert a photographed sheet into a scale-accurate reference layer. + +Required features: + +- Generate printable A4 calibration sheet. +- Sheet contains machine-readable markers and known geometry. +- Detect markers in imported photo. +- Compute perspective transform/homography. +- Warp image into orthographic top-down view. +- Place image into model space using millimetres. +- Show calibration status. + +Preferred marker types: + +- ArUco +- ChArUco +- AprilTag if practical + +### 8.4 Version 0.4 — Assisted Tracing + +Goal: make manual tracing faster and cleaner without automatic black-box vectorisation. + +Required features: + +- Fit line from multiple user-selected points. +- Fit circle from multiple user-selected points. +- Fit arc from multiple user-selected points. +- Snap endpoints together. +- Close contour command. +- Highlight open endpoints. +- Detect duplicate or near-duplicate segments. +- Detect very short unwanted segments. + +### 8.5 Version 0.5 — Optional Precision and Export Profiles + +Goal: add CAD-like refinement and production checks. + +Required features: + +- Optional length correction. +- Optional radius/diameter correction. +- Optional angle correction. +- Horizontal/vertical constraints. +- Parallel/perpendicular constraints. +- Simple layer system UI. +- Export profiles for CAD and laser/CAM. +- Export validation report. + +--- + +## 9. Calibration Sheet Requirements + +The printed sheet should be designed for reliable detection and practical tracing. + +### 9.1 Initial Sheet Size + +Start with: + +- A4 portrait +- Units: millimetres +- Printed at 100 percent scale + +Future options: + +- A3 +- Letter +- custom sheet sizes + +### 9.2 Sheet Elements + +The sheet should include: + +- Four corner markers outside the main drawing area. +- Known marker positions in millimetres. +- A visible outer reference frame. +- A light drawing grid, e.g. 5 mm or 10 mm. +- A 100 mm printed control line. +- Template ID/version. +- Instruction text: print at 100 percent / actual size / no scaling. + +### 9.3 Drawing Area + +Markers must not overlap with the main tracing area. + +The drawing area should be visually clean and not interfere with pencil lines. + +Recommended: + +- light grey grid +- high contrast markers +- dark outer frame +- reserved margins for markers + +--- + +## 10. Geometry Model + +### 10.1 Required Primitive Types + +The core model must support at least: + +- Point2 +- Vector2 +- LineEntity +- CircleEntity +- ArcEntity +- PolylineEntity later +- Layer +- SketchDocument +- ReferenceImage + +Example conceptual model: + +```csharp +public readonly record struct Point2(double X, double Y); + +public abstract record Entity(Guid Id, string Layer); + +public record LineEntity( + Guid Id, + string Layer, + Point2 Start, + Point2 End +) : Entity(Id, Layer); + +public record CircleEntity( + Guid Id, + string Layer, + Point2 Center, + double Radius +) : Entity(Id, Layer); + +public record ArcEntity( + Guid Id, + string Layer, + Point2 Center, + double Radius, + double StartAngleDeg, + double EndAngleDeg +) : Entity(Id, Layer); +``` + +### 10.2 Three-Point Circle + +The application must allow a circle to be defined by three user-selected points on its circumference. + +Implementation must compute: + +- centre point +- radius +- validity check for collinear or near-collinear points + +### 10.3 Three-Point Arc + +The application must allow an arc to be defined by: + +- start point +- point on arc +- end point + +Implementation must compute: + +- centre point +- radius +- start angle +- end angle +- direction/orientation +- validity check for collinear or near-collinear points + +### 10.4 Entity Editing + +At minimum: + +- select +- delete +- move later +- edit via properties later + +Do not overbuild editing in the first iteration. + +--- + +## 11. Tool System + +The canvas must use a tool-state model. Do not hard-code all interactions into the canvas control. + +Recommended interface concept: + +```csharp +public interface ISketchTool +{ + string Name { get; } + void PointerDown(ToolContext context, Point2 modelPoint); + void PointerMove(ToolContext context, Point2 modelPoint); + void PointerUp(ToolContext context, Point2 modelPoint); + void KeyDown(ToolContext context, Key key); + void RenderOverlay(DrawingContext context, ToolRenderContext renderContext); +} +``` + +Initial tools: + +- SelectTool +- LineTool +- Circle3PointTool +- Arc3PointTool +- PanTool or integrated middle-mouse pan +- Delete command + +Later tools: + +- CircleCenterRadiusTool +- PolylineTool +- FitLineTool +- FitCircleTool +- FitArcTool +- TrimTool +- OffsetTool +- FilletTool +- DimensionTool + +--- + +## 12. Snapping + +### 12.1 MVP Snaps + +Required initially: + +- snap to entity endpoints +- snap to grid optionally + +### 12.2 Later Snaps + +Add later: + +- midpoint +- circle centre +- arc centre +- intersection +- tangent +- perpendicular foot +- nearest point on entity +- reference-image assisted snap, if implemented + +### 12.3 Snap Behaviour + +Snapping must happen in model space. + +The view may display snap indicators in screen space, but the resulting point must be stored in millimetres. + +--- + +## 13. Rendering Requirements + +The custom canvas should render: + +- background +- grid +- reference image +- geometry entities +- selected entities +- hover highlights +- snap indicators +- active tool preview +- optional axes/origin + +The canvas must support: + +- zoom around cursor +- pan by middle mouse button or equivalent +- smooth redraw +- precise hit testing + +Rendering must not mutate the document model. + +--- + +## 14. Project File Format + +Use a custom JSON format as the native document format. + +DXF is an export format, not the internal source of truth. + +Example conceptual structure: + +```json +{ + "version": 1, + "units": "mm", + "document": { + "width": 210.0, + "height": 297.0 + }, + "reference": { + "imagePath": "reference.png", + "opacity": 0.55, + "locked": true, + "transform": { + "originX": 0.0, + "originY": 0.0, + "scaleX": 1.0, + "scaleY": 1.0, + "rotationDeg": 0.0 + } + }, + "layers": [ + { "name": "CUT", "visible": true, "locked": false }, + { "name": "CONSTRUCTION", "visible": true, "locked": false }, + { "name": "DIMENSIONS", "visible": true, "locked": false } + ], + "entities": [ + { + "type": "line", + "id": "00000000-0000-0000-0000-000000000001", + "layer": "CUT", + "start": [10.0, 20.0], + "end": [80.0, 20.0] + } + ] +} +``` + +--- + +## 15. Layer Model + +Initial layers: + +- CUT +- CONSTRUCTION +- REFERENCE +- DIMENSIONS +- DEBUG + +### 15.1 CUT + +Final production geometry intended for DXF export. + +### 15.2 CONSTRUCTION + +Helper geometry. Should not be exported by default. + +### 15.3 REFERENCE + +Imported or calibrated reference information. + +### 15.4 DIMENSIONS + +Optional dimension annotations later. + +### 15.5 DEBUG + +Internal generated geometry or diagnostics. Hidden by default in production builds unless debug mode is enabled. + +--- + +## 16. DXF Export Requirements + +### 16.1 General + +The DXF export must use millimetres. + +Final entities should export as native CAD geometry where possible: + +| Internal Entity | DXF Entity | +|---|---| +| LineEntity | LINE | +| CircleEntity | CIRCLE | +| ArcEntity | ARC | +| PolylineEntity | LWPOLYLINE | + +### 16.2 Export Profiles + +Support at least two conceptual profiles eventually. + +#### CAD Profile + +- Preserve LINE, CIRCLE, ARC. +- Use real geometry. +- Keep layers. +- Suitable for FreeCAD, Fusion, AutoCAD-like systems. + +#### Laser/CAM Profile + +- Prefer closed contours. +- Optionally preserve arcs. +- Optionally flatten arcs/circles to polylines. +- Configurable tolerance, e.g. 0.05 mm. +- Avoid duplicate line cuts. + +### 16.3 Validation Before Export + +The app should eventually report: + +- open endpoints +- duplicate segments +- very short segments +- self-intersections +- invalid arcs +- zero-length lines +- non-mm units + +For MVP 0.1, basic DXF export without full validation is acceptable, but the architecture must leave room for validation. + +--- + +## 17. Validation and Quality Checks + +The application should later include a “drawing health” check. + +Important checks: + +- outer contour closed +- inner contours closed +- no duplicate segments +- no tiny accidental segments below tolerance +- no self-intersections +- arcs have valid radius +- circles have positive radius +- all exportable geometry is on exportable layers + +Validation results should be user-facing but not block saving. + +Export may warn before writing problematic DXF files. + +--- + +## 18. Computer Vision Scope + +### 18.1 Responsibility + +The vision module is responsible for: + +- marker detection +- perspective correction +- coordinate calibration +- optional lens/camera calibration later +- generating a corrected reference image + +The vision module is not responsible for producing final CAD entities. + +### 18.2 Initial Marker Workflow + +1. Load image. +2. Detect marker corners. +3. Match detected marker IDs to template definition. +4. Compute homography from image points to sheet mm points. +5. Warp image to orthographic top-down sheet view. +6. Store corrected image as reference. +7. Attach image to document at known mm dimensions. + +### 18.3 Calibration Result + +The result should include: + +- success/failure +- detected marker count +- template ID +- sheet size in mm +- homography matrix +- warped image +- quality score later + +### 18.4 Quality Feedback Later + +The UI should later show: + +- sheet detected: yes/no +- marker count +- blur/sharpness estimate +- perspective severity +- estimated calibration quality +- warning if image is too skewed or low resolution + +--- + +## 19. User Interface Requirements + +### 19.1 Main Window Layout + +Recommended layout: + +```text +┌──────────────────────────────────────────────┐ +│ Menu / Toolbar │ +├────────────┬───────────────────────┬─────────┤ +│ Tools │ Canvas │ Props │ +│ │ │ Panel │ +├────────────┴───────────────────────┴─────────┤ +│ Status bar / command hints │ +└──────────────────────────────────────────────┘ +``` + +### 19.2 Main Toolbar + +Initial buttons: + +- New +- Open +- Save +- Import Reference +- Export DXF +- Select +- Line +- Circle 3P +- Arc 3P +- Undo +- Redo + +### 19.3 Canvas UX + +The canvas should feel closer to a lightweight CAD/sketch tool than a paint program. + +Required controls: + +- left click for tool actions +- mouse wheel zoom +- middle mouse drag pan +- Esc cancels current operation +- Delete deletes selection +- Ctrl+Z undo +- Ctrl+Y or Ctrl+Shift+Z redo +- Ctrl+S save + +### 19.4 Status Bar + +Show context-specific prompts, e.g.: + +```text +Line Tool: choose start point +Line Tool: choose end point +Circle 3P: choose first point on circle +Arc 3P: choose point on arc +``` + +This reduces the need for documentation. + +--- + +## 20. Undo/Redo + +Implement undo/redo early. + +Preferred model: + +- command pattern +- each document change is a command +- commands can apply and revert + +Initial commands: + +- AddEntityCommand +- DeleteEntityCommand +- AddLayerCommand later +- SetReferenceImageCommand later + +Avoid editing the document directly from tools without command tracking. + +--- + +## 21. Testing Requirements + +### 21.1 Geometry Tests + +Test: + +- line length +- circle from three points +- arc from three points +- collinear failure cases +- angle normalization +- coordinate transforms + +### 21.2 DXF Tests + +Test: + +- export line +- export circle +- export arc +- units are mm +- layer names preserved + +### 21.3 Document Tests + +Test: + +- save/load JSON roundtrip +- entity IDs preserved +- layers preserved +- document version handled + +### 21.4 Vision Tests Later + +Use sample images for: + +- marker detection +- homography +- failed detection +- distorted/skewed sheet + +--- + +## 22. Implementation Priorities + +### Highest Priority + +1. Clean Core model. +2. Custom canvas with model/view transform. +3. Tool system. +4. Line/Circle/Arc creation. +5. DXF export. +6. JSON project file. +7. Undo/redo. + +### Medium Priority + +1. Reference image layer. +2. Manual scaling/rotation of reference image. +3. Layers UI. +4. Basic validation. +5. Export profiles. + +### Later Priority + +1. Marker sheet generation. +2. OpenCV marker detection. +3. Homography correction. +4. Fit tools. +5. Optional dimensions. +6. Optional constraints. +7. Camera live mode. + +--- + +## 23. Development Rules for the Agent + +When implementing, follow these rules: + +1. Do not implement automatic AI tracing as a core feature. +2. Do not store geometry in pixels. +3. Do not put CAD logic inside Avalonia UI controls. +4. Do not make DXF the internal document format. +5. Do not build a monolithic canvas class containing all tools. +6. Do not add OpenCV before the basic editor and DXF export work. +7. Keep `TraceCad.Core` independent from Avalonia and OpenCV. +8. Prefer small testable geometry functions. +9. Use explicit entity classes instead of generic loosely typed objects. +10. Keep the first MVP narrow and working. +11. Implement robust error handling for invalid circle/arc definitions. +12. Maintain millimetre units across the model and export layers. +13. Every tool should have clear interaction state. +14. Every document mutation should eventually go through undoable commands. + +--- + +## 24. First Development Task + +Create the initial .NET solution with this structure: + +```text +TraceCad/ + src/ + TraceCad.App/ + TraceCad.Core/ + TraceCad.Dxf/ + TraceCad.Vision/ + tests/ + TraceCad.Tests/ +``` + +Then implement MVP 0.1 skeleton: + +1. `TraceCad.Core` + - `Point2` + - `Vector2` + - `Entity` + - `LineEntity` + - `CircleEntity` + - `ArcEntity` + - `SketchDocument` + - `Layer` + - basic geometry helpers + +2. `TraceCad.App` + - Avalonia main window + - custom canvas control + - pan/zoom view transform + - grid rendering + - render lines/circles/arcs from document + - toolbar for select/line/circle3p/arc3p + +3. `TraceCad.Dxf` + - exporter interface + - initial netDxf-based exporter + - export LINE/CIRCLE/ARC in mm + +4. `TraceCad.Tests` + - circle from 3 points tests + - arc from 3 points tests + - JSON document roundtrip test + - basic DXF export smoke test + +Do not implement marker detection yet. + +--- + +## 25. Acceptance Criteria for MVP 0.1 + +MVP 0.1 is acceptable when: + +1. The app launches as a Windows desktop application. +2. The user can pan and zoom the canvas. +3. The user can draw a line by clicking two points. +4. The user can create a circle from three clicked points. +5. The user can create an arc from three clicked points. +6. The user can select and delete entities. +7. The user can save and reload a project file. +8. The user can export a DXF. +9. The exported DXF opens in at least one external CAD/CAM program with correct millimetre scale. +10. The core geometry calculations are covered by unit tests. + +--- + +## 26. Product Positioning Summary + +The application should be developed as: + +> A calibrated 2D tracing CAD tool that helps users turn real-world traced outlines into clean, scale-accurate DXF geometry without forcing them into traditional CAD dimensioning workflows. + +Primary value: + +- approachable workflow +- real-world scale from printed sheet +- deterministic geometry +- clean CAD export +- no AI/autotrace slop +- optional precision tools for advanced users +