55 lines
2.5 KiB
Markdown
55 lines
2.5 KiB
Markdown
# De-rasterizing an image into an editable diagram
|
|
|
|
Goal: turn a whiteboard photo, a legacy PNG export, or a Visio screenshot
|
|
into an EDITABLE `.drawio` file. Claude's own vision does the extraction;
|
|
`scripts/raster2drawio.py` only turns the extracted JSON into XML.
|
|
|
|
## Workflow
|
|
|
|
1. **Look at the image.** Read it with your normal vision — no OCR tool
|
|
needed. For every box/shape in the picture, note:
|
|
- `id` — any short stable slug (`n1`, `api-gw`, …)
|
|
- `label` — the text verbatim, exactly as written (fix obvious typos only
|
|
if the source is clearly a typo, not a stylistic choice)
|
|
- `x`, `y` — estimate the pixel position of the shape's top-left corner
|
|
from the image (a rough grid read is fine; exact pixel-matching isn't
|
|
the goal)
|
|
- `w`, `h` — estimate width/height in pixels (defaults to 120x60 if you
|
|
can't tell)
|
|
- `shape` — classify: `rect`, `rounded`, `ellipse`, `rhombus`/`diamond`,
|
|
`cylinder`, `parallelogram`, `cloud`, `hexagon`
|
|
- `fill`, `stroke` — sample the approximate fill/border color as a hex
|
|
value (skip if the source is plain black-and-white)
|
|
|
|
For every arrow/line, note `source`, `target`, the label text if any
|
|
(e.g. "Yes"/"No" on a decision arrow), whether it's `dashed`, and whether
|
|
it has a visible `arrow` head (false for a plain connecting line).
|
|
|
|
2. **Write the JSON** to a file:
|
|
```json
|
|
{"nodes": [{"id": "n1", "label": "API Gateway", "x": 120, "y": 60,
|
|
"w": 160, "h": 60, "shape": "rect",
|
|
"fill": "#dae8fc", "stroke": "#6c8ebf"}],
|
|
"edges": [{"source": "n1", "target": "n2", "label": "HTTPS",
|
|
"dashed": false, "arrow": true}]}
|
|
```
|
|
|
|
3. **Convert it**:
|
|
```bash
|
|
python3 scripts/raster2drawio.py graph.json -o out.drawio
|
|
```
|
|
If any node is missing `x`/`y`, don't guess coordinates by hand — leave
|
|
them out and the script auto-places the whole graph via `autolayout.py`
|
|
(Graphviz `dot` required), noting this on stderr.
|
|
|
|
4. **Continue the standard workflow**: `validate.py` for structural issues,
|
|
export a preview PNG, then a vision self-check — compare the rendered
|
|
PNG side-by-side against the ORIGINAL image and look for missed shapes,
|
|
wrong labels, or misrouted edges. Fix and re-run as needed.
|
|
|
|
## Honest limitation
|
|
|
|
Hand sketches with ambiguous, crossing, or arrowhead-less connections are
|
|
genuinely ambiguous — expect one review round where you correct a
|
|
misattributed edge after seeing the first render next to the original.
|