# SVG Tools

Questa cartella contiene helper Node locali e deterministici usati dalla skill SVG
per calcoli geometrici/parametrici che richiedono precisione ripetibile.

Principi operativi:

- la skill resta il control plane;
- i tool fanno solo execution helper su parti numeriche;
- niente dipendenze esterne non necessarie;
- output machine-readable e errori espliciti.

Per aggiungere o modificare helper, seguire:

- `docs/svg/svg-skill-maintenance-guide.md`
- `skills/svg/references/helper-first.md`

## Tool disponibili

Per discovery rapida da parte dell'agente, leggere prima `catalog.json`.
Questo README contiene i dettagli umani dei parametri e dei limiti.

| Intento | Tool | Esempio rapido |
| --- | --- | --- |
| superellipse/supercerchio | `superellipse.js` | `--width 256 --height 256 --n 4 --samples 128` |
| punti su arco | `arc-points.js` | `--cx 50 --cy 50 --radius 20 --start-deg 0 --end-deg 90 --points 5` |
| distribuzione polare | `polar-distribute.js` | `--cx 0 --cy 0 --radius 10 --count 8` |
| handle cubic Bezier | `bezier-handles.js` | `--x1 0 --y1 0 --x2 100 --y2 0` |
| viewBox da bounds | `fit-viewbox.js` | `--x 10 --y 20 --width 200 --height 100 --padding 5` |
| rettangolo arrotondato | `rounded-corners.js` | `--width 120 --height 80 --rx 8 --ry 8` |
| ricerca asset locali | `search-assets.js` | `--query "save icon" --kind icons --limit 5` |
| trace raster B/N | `trace-bw-potrace.js` | `--input input.bmp --output out.svg` |

### superellipse.js

Genera un path SVG per superellipse/supercerchio con sampling deterministico.

Uso base:

```bash
node skills/svg/tools/superellipse.js --width 256 --height 256 --n 4 --samples 128
```

Parametri principali:

- `--width` (required, > 0)
- `--height` (required, > 0)
- `--n` (required, > 0)
- `--samples` (required, intero >= 8)
- `--cx` (optional, default `width/2`)
- `--cy` (optional, default `height/2`)
- `--precision` (optional, intero 0..12, default `4`)
- `--format` (optional, `json|svg`, default `json`)
- `--out` (optional, path file output)

Output `json` (default):

```json
{
  "result": "ok",
  "shape": "superellipse",
  "width": 256,
  "height": 256,
  "n": 4,
  "samples": 128,
  "path_d": "M ... Z"
}
```

Error handling:

- input invalido -> exit code `1` con messaggio esplicito su `stderr`;
- `--out` non scrivibile -> exit code `1` con causa.

Limiti noti:

- il tool genera solo geometria path; non applica stile/palette;
- non sostituisce `optimize` o `validate`;
- non esegue composizione multi-asset.

### arc-points.js

Genera punti e path lineare lungo un arco tra due angoli.

Uso base:

```bash
node skills/svg/tools/arc-points.js --cx 50 --cy 50 --radius 20 --start-deg 0 --end-deg 90 --points 5
```

Output: JSON con `points[]` e `path_d`.

### polar-distribute.js

Distribuisce punti in coordinate polari su cerchio/arco.

Uso base:

```bash
node skills/svg/tools/polar-distribute.js --cx 0 --cy 0 --radius 10 --count 8
```

Output: JSON con punti indicizzati e angoli calcolati.

### bezier-handles.js

Calcola handle cubic Bezier deterministici tra due punti usando `tension` e `curvature`.

Uso base:

```bash
node skills/svg/tools/bezier-handles.js --x1 0 --y1 0 --x2 100 --y2 0 --tension 0.33 --curvature 0.1
```

Output: JSON con `c1`, `c2` e `cubic_command`.

### fit-viewbox.js

Calcola un `viewBox` a partire da bounds noti, con padding opzionale.

Uso base:

```bash
node skills/svg/tools/fit-viewbox.js --x 10 --y 20 --width 200 --height 100 --padding 5
```

Output: JSON con `viewbox` e `viewBox_string`.

### rounded-corners.js

Genera un path SVG di rettangolo con angoli arrotondati (raggio clampato).

Uso base:

```bash
node skills/svg/tools/rounded-corners.js --width 120 --height 80 --rx 8 --ry 8
```

Output: JSON con `path_d`.

### search-assets.js

Cerca icone e illustrazioni nell'indice asset bundled della skill. Risolve
`assets/index.json` rispetto alla directory della skill, quindi funziona anche
quando l'agente opera in un workspace esterno al repo tecnico.

Uso base:

```bash
node skills/svg/tools/search-assets.js --query "save icon" --kind icons --limit 5
```

Filtri:

- `--query`: termini liberi;
- `--library`: `lucide` oppure `open-peeps`;
- `--kind`: `icons` oppure `illustrations`;
- `--limit`: numero massimo risultati.

Output: JSON con `matches[]`, `skill_relative_path`, `absolute_path`, `exists`,
`license`, `attribution` e `score`.

### trace-bw-potrace.js

Wrapper locale per pipeline raster B/N -> SVG tramite `potrace`, con
pre-processing `mkbitmap` quando disponibile.

Uso base:

```bash
node skills/svg/tools/trace-bw-potrace.js --input input.bmp --output out.svg
```

Input supportati: `.bmp`, `.pbm`, `.pgm`, `.ppm`, `.pnm`.

Output: JSON con `trace_bw`, `input`, `output`, `preprocessing` e parametri
usati. Richiede `potrace` nel PATH; se manca, fallisce esplicitamente.