pdm/README.md

# creoparams

Estrae parametri e proprietà dai file nativi Creo Parametric (`.prt`, `.asm`,
`.drw`) **senza avviare Creo** e senza SDK commerciali. Solo Python 3, nessuna
dipendenza esterna.

## Uso

Un file alla volta — è il caso d'uso principale:

```bash
python3 -m creoparams 9258400201.prt.12               # tabella a video
python3 -m creoparams 9258400201.prt.12 --quiet -o -  # JSON su stdout
python3 -m creoparams 9258400201.prt.12 -o scheda.json
```

Con un solo file l'output JSON è un **oggetto**; con più file una **lista**.
`-o -` scrive su stdout, quindi il comando si può mettere in pipe.

Un file indicato esplicitamente viene sempre elaborato così com'è: la scelta
automatica dell'ultima versione riguarda solo l'esplorazione di una cartella.

In lotto, quando serve:

```bash
python3 -m creoparams . --csv metadati.csv            # cartella corrente
python3 -m creoparams /rete/archivio -r --csv indice.csv
```

Opzioni principali:

| Opzione | Effetto |
|---|---|
| `-o`, `--json FILE` | scrive il JSON su file, oppure su stdout con `-` |
| `--csv FILE` | tabella riepilogativa CSV (Excel, separatore `;`) |
| `-r`, `--recursive` | esplora le sottocartelle |
| `--all-versions` | elabora tutte le versioni (`.prt.1`, `.prt.2`, …) invece della sola più recente |
| `--features` | include i parametri delle feature (fori, lavorazioni) oltre a quelli di modello |
| `--system` | include i parametri generati da Creo (`PTC_*`, `SMT_*`) |
| `--quiet` | non stampa la tabella |

Codici di uscita: `0` estrazione riuscita, `1` nessun file trovato, `2` nessun
file elaborabile (file mancante o non nativo Creo). I messaggi diagnostici
vanno su stderr, così stdout resta pulito per le pipe.

Nella tabella a video, il marcatore a inizio riga indica l'affidabilità:
spazio = confermato in due rappresentazioni indipendenti, `?` = trovato una
volta sola, `~` = valore binario non decodificato, `!` = valori discordanti,
`-` = parametro atteso ma assente.

## Come funziona

Un file nativo Creo è un container con header ASCII in chiaro, un indice delle
sezioni (`UGC_TOC`) e un corpo binario. La maggior parte delle sezioni **non è
compressa**, e la tabella dei parametri è leggibile direttamente.

Ogni parametro è presente in due rappresentazioni indipendenti:

- la **tabella estesa** (sezione `LargeText`), che contiene i parametri di modello;
- la **copia neutra** (sezione `NeuPrtSld`), che contiene anche quelli delle feature.

Il lettore percorre entrambe e confronta i risultati. Da qui derivano due
informazioni che finiscono nell'output:

- `owner`: `model` se il parametro compare nella tabella estesa, `feature` se
  vive solo nella copia neutra (è un parametro di un foro, non del pezzo);
- `confidence`: `0.99` se le due rappresentazioni concordano, valori più bassi
  se il dato compare una volta sola o se le copie divergono (`status: conflict`).

## Formato di output

```json
{
  "schema_version": 1,
  "file": { "name": "9258400201.prt.12", "sha256": "994dd3a8…", "size": 450797 },
  "model": { "name": "9258400201", "kind": "PART", "creo_version": "9.0.3.0" },
  "extraction": { "method": "ugc_native_reader", "holds_model_parameters": true },
  "parameters": {
    "DENOMINAZIONE": {
      "type": "string", "owner": "model", "scope": "user",
      "value": "Carter lato destro", "status": "found", "confidence": 0.99,
      "sections": ["LargeText", "NeuPrtSld"]
    },
    "PESO": {
      "type": "real", "status": "encoded_not_decoded",
      "raw": "90f8382356ca2d", "driven_by": "value(d_val)"
    }
  }
}
```

L'`sha256` permette di verificare in seguito se un record estratto corrisponde
ancora al file da cui proviene.

## Limiti noti

**Parametri numerici non decodificati.** `PESO` e `DENSITA` usano una codifica
binaria a lunghezza variabile (7–8 byte osservati) che non è un double IEEE
lineare. Non vengono inventati valori: lo stato è `encoded_not_decoded` e i byte
grezzi sono conservati in `raw`, così da poter essere interpretati in seguito
senza rileggere l'archivio. Per decifrare la codifica servono alcuni valori di
riferimento letti da Creo.

**Disegni.** I `.drw` vengono riconosciuti e ne viene letto l'header, ma non
contengono la tabella parametri del modello: espongono note e cartiglio, con una
struttura diversa non ancora implementata. Il campo `holds_model_parameters`
lo dichiara esplicitamente.

**Copertura verificata.** Il lettore è stato validato su file `PART` e
`PART/SHEETMETAL` scritti da **Creo 9.0.3.0**. Non è stato provato su assiemi,
family table, né su file di versioni Creo precedenti. Prima di usarlo
sull'archivio storico, va verificato su un campione di file più vecchi.

**Family table.** Le istanze non hanno un file proprio: vivono nel generic. Su
un generic con family table il lettore restituirebbe i valori del generic, non
quelli dell'istanza. Nei file campione la sezione `FamilyInf` è vuota, quindi
il caso non è mai stato esercitato.

## Test

```bash
python3 -m unittest test_regression -v
```

I test girano sui `.prt` presenti nella cartella e verificano che i parametri
aziendali obbligatori siano letti con confidenza alta. `KNOWN` in
`test_regression.py` contiene i valori verificati a mano: **è la rete di
sicurezza vera del progetto** e va estesa ogni volta che si confronta un nuovo
file con Creo.

## Struttura

| File | Contenuto |
|---|---|
| [creoparams/ugc.py](creoparams/ugc.py) | header e indice delle sezioni del container |
| [creoparams/params.py](creoparams/params.py) | riconoscimento dei record parametro nel binario |
| [creoparams/extract.py](creoparams/extract.py) | aggregazione, confidenza, record di output |
| [creoparams/cli.py](creoparams/cli.py) | riga di comando ed esportazioni |