168 lines
8.0 KiB
Markdown
168 lines
8.0 KiB
Markdown
# Scrap Tracer — Design
|
||
|
||
## Purpose
|
||
|
||
Makerspace Delft keeps a bucket of leftover laser-cut material. To reuse it, members need a
|
||
1:1 vector outline of a scrap piece (including holes where parts were already cut out) that
|
||
they can import into their laser software to check whether their design fits.
|
||
|
||
Scrap Tracer turns a phone photo of a scrap piece into a correctly scaled DXF/SVG outline.
|
||
|
||
**Success:** a member photographs a piece, sets the scale with a couple of clicks, downloads a
|
||
file, and imports it into the laser software where it matches the real piece within a few mm.
|
||
|
||
## Scope
|
||
|
||
In scope (v1):
|
||
- Load a photo, set scale from one known length, detect the outline automatically, with a
|
||
manual polygon fallback, apply a safety margin, export DXF and SVG.
|
||
|
||
Out of scope (v1):
|
||
- Perspective correction (photos are assumed roughly top-down; see Future).
|
||
- Inventory/catalogue of scrap pieces; nothing is persisted.
|
||
- Point-by-point editing of detected contours.
|
||
- Desktop packaging (Tauri) and browser end-to-end tests.
|
||
|
||
## Users and environment
|
||
|
||
- Makerspace members, low friction is essential.
|
||
- Photos are taken on a phone; the tool is used on a computer (typically the laser PC).
|
||
- The recommended laser software is RDWorks; others (LightBurn, Inkscape) may be used.
|
||
RDWorks imports DXF reliably but not SVG, so **DXF is the primary export**, SVG secondary.
|
||
- Accuracy target: a few mm. The safety margin absorbs the rest.
|
||
|
||
## Tech stack
|
||
|
||
- Svelte 5 + TypeScript on Vite (plain Svelte, not SvelteKit). Single page, no backend.
|
||
- OpenCV.js (`@techstark/opencv-js`) for image processing, running fully client-side.
|
||
- Vitest for tests.
|
||
- Deployed as static files on Cloudflare Pages. The build output can later be wrapped with
|
||
Tauri without changes to the app.
|
||
|
||
## User flow
|
||
|
||
One screen: a zoomable/pannable image canvas, with a sidebar listing the steps.
|
||
|
||
1. **Load photo.** Drag-drop or file picker. The image is downscaled to about 2000 px on the
|
||
long side for processing.
|
||
2. **Set scale.** The user clicks two points on a feature of known length and enters the
|
||
length in mm. The reference line and label stay visible, and px/mm is displayed.
|
||
3. **Detect outline.** Detection runs automatically once the photo loads and reruns when a
|
||
control changes. The result is drawn over the photo.
|
||
- Threshold slider. The initial value comes from Otsu's method.
|
||
- Invert toggle, for when the piece is darker than the background.
|
||
- Click to pick the piece. Only the connected region under the click (the seed point) is
|
||
kept, including its holes. If there is no seed, the largest region that does not touch
|
||
the image border is used.
|
||
- Draw manually: click polygon points for the outer edge, then optionally add hole
|
||
polygons. This replaces the automatic result.
|
||
4. **Safety margin.** Slider from −10 to +5 mm, default −2 mm, with a live preview. Negative
|
||
values shrink usable area: the outer edge moves inward and holes grow. It requires the
|
||
scale to be set.
|
||
5. **Export.** "Download DXF" (primary) and "Download SVG". The file contains outlines only,
|
||
in mm, with the bounding box's top-left at (0,0). The filename includes the size, e.g.
|
||
`scrap-412x287mm.dxf`.
|
||
|
||
The overlay always shows exactly what will be exported.
|
||
|
||
## Architecture
|
||
|
||
Thin Svelte UI on top of small pure TypeScript modules:
|
||
|
||
| Module | Responsibility | Depends on |
|
||
|---|---|---|
|
||
| `src/lib/scale.ts` | two points + length in mm → px/mm | nothing |
|
||
| `src/lib/detect.ts` | image + params → contours in px | OpenCV (injected) |
|
||
| `src/lib/margin.ts` | polygons in px + margin_px → contours in px (for manual mode) | OpenCV (injected), `detect.ts` helpers |
|
||
| `src/lib/geometry.ts` | px contours → mm polygons: scale, simplify, normalise to origin, bounding box | nothing |
|
||
| `src/lib/export-dxf.ts` | mm polygons → DXF text | nothing |
|
||
| `src/lib/export-svg.ts` | mm polygons → SVG text | nothing |
|
||
| `src/lib/opencv-loader.ts` | load OpenCV.js once, async | OpenCV.js |
|
||
| `src/components/ImageCanvas.svelte` | display, zoom/pan, overlays, click handling | — |
|
||
| `src/components/Sidebar.svelte` | step controls | — |
|
||
| `src/App.svelte` | owns app state, wires modules together | all of the above |
|
||
|
||
### Shared types
|
||
|
||
```ts
|
||
type Point = { x: number; y: number };
|
||
type Shape = { outer: Point[]; holes: Point[][] }; // px or mm depending on stage
|
||
type RasterImage = { width: number; height: number; data: Uint8ClampedArray }; // RGBA, ImageData-compatible
|
||
type DetectParams = {
|
||
threshold: number; // 0–255
|
||
invert: boolean;
|
||
seed: Point | null; // px; null = largest non-border region
|
||
marginPx: number; // negative shrinks the piece
|
||
};
|
||
```
|
||
|
||
### Detection pipeline (`detect(cv, image: RasterImage, params): Shape | null`)
|
||
|
||
1. Convert to grayscale, apply a light blur, threshold (inverted if requested) → binary mask.
|
||
2. Morphological open/close with a small kernel to remove speckle.
|
||
3. Connected components. Keep the component under `seed`, or else the largest component that
|
||
doesn't touch the border.
|
||
4. Apply the margin: erode (negative) or dilate (positive) the mask by |marginPx| using an
|
||
elliptical kernel. Holes then grow or shrink as well.
|
||
5. `findContours` with `RETR_CCOMP`. Take the outer contour of the largest remaining
|
||
component and its child holes.
|
||
6. Return `null` if nothing remains.
|
||
|
||
`detect.ts` also exports `otsuThreshold(cv, image): number` for the initial slider value.
|
||
|
||
Simplification (`approxPolyDP`-style, Douglas–Peucker in `geometry.ts`) uses a tolerance of
|
||
about 0.5 mm and runs after conversion to mm, so it's independent of photo resolution.
|
||
|
||
### Manual mode
|
||
|
||
The user's clicked polygons are rasterised into a mask (`fillPoly`, with holes drawn as
|
||
background). That mask then goes through steps 4–5 of the same pipeline, so there is one
|
||
margin implementation.
|
||
|
||
### Exports
|
||
|
||
- **DXF:** a minimal ASCII DXF (R12-compatible) with one closed `LWPOLYLINE`/`POLYLINE` per
|
||
contour, `$INSUNITS = 4` (mm). The Y axis is flipped so the piece isn't mirrored. It must
|
||
import in RDWorks.
|
||
- **SVG:** `width`/`height` in `mm` with a matching `viewBox`, so 1 user unit = 1 mm. One
|
||
`<path>` with `fill-rule="evenodd"`, stroke only.
|
||
|
||
### State
|
||
|
||
A single Svelte `$state` object in `App.svelte`: image, scale points, length in mm, detection
|
||
params, manual polygons, mode (`auto` | `manual`), result shape. Derived values (px/mm, mm
|
||
shape, export enabled) use `$derived`. Nothing is persisted.
|
||
|
||
## Error handling
|
||
|
||
- OpenCV fails to load: show an error with a reload button.
|
||
- No region found, or the region is the whole image: show "Nothing detected, try adjusting
|
||
the threshold or invert, or draw manually."
|
||
- A margin that removes the piece entirely: show the same warning, and keep export disabled.
|
||
- Export is disabled until the scale is set and a non-empty shape exists.
|
||
- A zero-length scale line or non-positive mm value: reject the input with an inline message.
|
||
|
||
## Testing
|
||
|
||
Vitest, run in Node.
|
||
|
||
- **`detect.ts`.** Since it takes a plain `RasterImage` and an injected `cv`, tests load
|
||
`@techstark/opencv-js` headless.
|
||
- Synthetic images are generated in the test. They check that the outer bounding box and
|
||
area are within about 2 px, that the hole count is correct, that a stray blob is ignored
|
||
when the seed is on the piece, that invert works, and that a margin of ±N px moves the
|
||
outer edge and hole edges by about N px.
|
||
- Real photo fixtures in `tests/fixtures/` (to be supplied: 3–5 photos of plywood, MDF and
|
||
acrylic), each with expected size and hole count, checked with loose tolerances.
|
||
- **`scale.ts`, `geometry.ts`.** Unit tests for scale maths, simplification, origin
|
||
normalisation and the bounding box.
|
||
- **`export-dxf.ts` / `export-svg.ts`.** Check structure (sections, closed polylines, units),
|
||
that coordinates are in mm, and the Y flip in DXF.
|
||
- **UI.** Manual check, plus one manual import test of an exported DXF in RDWorks.
|
||
|
||
## Future (not v1)
|
||
|
||
- Perspective correction from a reference rectangle (e.g. an A4 sheet) via `warpPerspective`.
|
||
- Contour point editing.
|
||
- Tauri desktop packaging.
|