# from-raster

Workflow per conversione raster -> SVG con fallback espliciti.

## Quando usarlo

Usa questo workflow quando il task richiede vettorializzazione a partire da input raster (`.png`, `.jpg`, `.jpeg`, `.bmp`, `.tiff`, `.webp`).

## Input minimo

- `input_path`: path assoluto o relativo al file raster.
- `output_svg_path`: path file SVG di destinazione.
- `mode` opzionale: `color` oppure `bw`.

Se `mode` non e' indicato:
- tratta come `color` quando il logo/asset contiene gradazioni o piu' tinte;
- tratta come `bw` solo su input chiaramente monocromatico.

## Obiettivo predefinito

Per questo workflow, il default e' **replicare il raster nel modo piu' fedele possibile**.

- Ottimizzazione del markup e semplificazione geometrica vengono dopo la fedelta' visiva.
- Una ricostruzione manuale della forma e' ammessa solo se:
  - il trace automatico fallisce o degrada la forma; oppure
  - il task chiede esplicitamente restyling, ricostruzione o pulizia geometrica.
- Se si usa una ricostruzione manuale, il report finale deve dichiararlo esplicitamente come output `approximate` o `restyled`, non `faithful`.

## Classificazione iniziale consigliata

Prima di scegliere il tool, classifica l'input in una di queste categorie:

1. `high-contrast flat shape`
   - poche tinte nette, bordo/riempimento ben separato dallo sfondo;
   - preferisci `potrace` se basta una maschera monocromatica.
2. `low-contrast flat shape`
   - forma piatta ma molto vicina al bianco o al colore di sfondo;
   - evita `vtracer` come default;
   - preferisci estrazione maschera/threshold + `potrace`.
3. `multi-color soft gradients`
   - piu' colori, sfumature o transizioni morbide;
   - prova `vtracer` come prima scelta.
4. `simple geometric logo/icon`
   - ammette ricostruzione manuale solo con confronto obbligatorio col raster prima della consegna.

## Decision tree tool

1. Se l'asset e' `low-contrast flat shape`:
   - estrai una maschera binaria o applica threshold preliminare;
   - usa `potrace` sulla maschera come scelta primaria.
2. Se `mode=color` e l'asset contiene davvero piu' tinte o gradienti:
   - usa `vtracer` come scelta primaria.
3. Se `mode=bw` o l'asset e' una forma piatta monocromatica:
   - usa `potrace` come scelta primaria.
4. Se il tool primario manca/fallisce -> tenta fallback:
   - da `vtracer` a pre-processing + `potrace` se l'asset e' in realta' quasi monocromatico;
   - da `vtracer` a `inkscape` (trace bitmap) solo come fallback operativo;
   - da `potrace` a `inkscape` (trace bitmap) solo come fallback operativo.
5. Se anche fallback non disponibile/fallisce -> termina con errore esplicito.

Nota: `potrace` richiede normalmente input bitmap monocromatico; se serve conversione preliminare, dichiararla nel report operativo.

## Pipeline B/N consolidata (potrace)

Per i casi B/N, usa questa pipeline standard:

1. input in formato supportato `potrace` (`.bmp`, `.pbm`, `.pgm`, `.ppm`, `.pnm`);
2. pre-processing con `mkbitmap` quando disponibile (threshold + cleanup);
3. trace con `potrace` su output preprocessato.

Script operativo cross-platform:

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

Parametri utili (opzionali):

```bash
node skills/svg/tools/trace-bw-potrace.js \
  --input <input.bmp> \
  --output <out.svg> \
  --threshold 0.45 \
  --turdsize 2 \
  --alphamax 1 \
  --opttolerance 0.2
```

Se l'input e' PNG/JPG e non c'e' conversione automatica disponibile, non forzare `potrace`:
- usa `vtracer` (anche in mode `bw`) oppure
- converti esplicitamente a BMP/PNM prima del trace e dichiaralo nel report.

## Differenze decisionali per host (obbligatorie)

Usa queste regole per scegliere in modo coerente col runtime:

### Windows

1. chain primaria `vtracer -> potrace -> inkscape`;
2. se `vtracer` e' disponibile ed e' input colore/gradiente, partire da `vtracer`;
3. se input e' B/N o shape piatta ad alto contrasto, privilegiare `potrace`;
4. usare `inkscape` solo come fallback operativo finale.

### Ubuntu

1. chain primaria `vtracer -> potrace -> inkscape`;
2. in setup base Ubuntu, `vtracer` puo' non essere installato automaticamente:
   - se manca `vtracer`, non bloccare il workflow;
   - passa a `potrace` (se input binarizzabile) oppure `inkscape` fallback;
3. se il risultato non e' fedele, iterare pre-processing/threshold prima della consegna.

Regola trasversale:
- l'ordine host-specifico vale come default tecnico;
- qualsiasi deviazione dalla chain va motivata nel report finale.

## Verifica obbligatoria di fedelta'

Prima di chiudere il task:

1. esporta un PNG dall'SVG generato;
2. confronta visivamente l'export con il raster originale;
3. verifica almeno:
   - posizione dell'apertura/taglio;
   - forma e orientamento dei terminali;
   - proporzioni globali;
   - offset e posizionamento nel canvas;
   - eventuale perdita di parti dovuta a basso contrasto.

Se il confronto evidenzia differenze visive evidenti, non consegnare il file come risultato finale: torna alla fase di scelta tool o di pre-processing.

## Output atteso

- SVG generato nel path richiesto.
- Report operativo sintetico con:
  - tool selezionato;
  - classificazione iniziale dell'asset;
  - eventuale pre-processing applicato (mask/threshold/invert/campionamento colore);
  - fallback tentati;
  - esito della verifica di fedelta' (`faithful`, `approximate`, `restyled`);
  - eventuali warning di qualita' (nodi eccessivi, perdita dettaglio).

## Error handling (no fail silenziosi)

- Input raster mancante/non leggibile -> errore bloccante con path e causa.
- Tool non nel PATH -> errore esplicito con elenco tool richiesti e fallback tentati.
- Conversione fallita -> errore esplicito con ultimo comando/log utile.
- Trace completato ma non fedele al raster -> non trattarlo come successo; riporta il mismatch e il punto di rottura della verifica.

## Boundary

- Nessuna integrazione con asset libraries o submodule.
- Nessuna pipeline compositiva multi-sorgente.
- Nessuna post-produzione automatica avanzata oltre la conversione base.