# DPAC T2 Generator Il **AerariumChain DPAC T2 Generator** è un'applicazione desktop (macOS e Windows) che AerariumChain mette a disposizione, su licenza, dei fornitori di digitalizzazione e della Digital Library. Costruisce i **pacchetti di aggiornamento T2** per gli oggetti 3D e per i gigapixel, li verifica prima dello ZIP, li scrive su un disco esterno e rilascia un **certificato di verifica** con il registro di tutti i controlli e i documenti dei paradati allegati. Un pacchetto T2 è un *delta* sul pacchetto T1 già ingerito da DPAC: contiene il METS aggiornato (`RECORDSTATUS="UPDATE_3D"`, ID dell'header uguale all'UUID della risorsa assegnato da DPAC), la cartella dei **paradati** (la relazione di setup dell'acquisizione e la relazione di elaborazione) e la cartella **RAW_3D** con i dati grezzi di acquisizione. Le immagini già nel T1 (il thumbnail e le viste di rendering) vengono rimesse anche nel T2, copiate byte per byte dal pacchetto T1 e verificate con i checksum del METS; master e derivato restano riferimenti (opzione: solo immagini, tutti i file del T1, nessuno). Lo strumento ha due parti: un **builder** (una procedura guidata) e un **verificatore** (l'interfaccia di controllo con i pannelli dei pacchetti generati e falliti). Tutto ciò che fa la finestra si può pilotare anche da un'**API HTTP locale**, così che un fornitore possa integrare il packager nel proprio sistema e tenere l'interfaccia per il lavoro manuale sul PC. ## Installazione, accesso e licenza L'app si usa solo con un **account dell'Hub AerariumChain** e una **licenza attiva**. Il referente della licenza (per la Digital Library, AerariumChain) indica quali account possono usarla e su quanti computer. **Scaricare l'installer.** Sull'Hub, nel menu **DPAC → DPAC T2 Generator**, la pagina mostra la licenza dell'account e i pulsanti per macOS (Apple Silicon o Intel) e Windows. Il download è registrato a nome dell'account. Senza licenza attiva i pulsanti sono disattivati. **macOS.** Aprire il file `.dmg` e trascinare l'app nella cartella Applicazioni. L'app è firmata e notarizzata da Apple: si apre senza avvisi. Se macOS mostrasse comunque un messaggio di app non verificata (per esempio con un file copiato da una chiavetta), aprire **Impostazioni di Sistema → Privacy e sicurezza** e scegliere **Apri comunque**, oppure fare clic destro sull'app → **Apri**. **Windows.** Eseguire `AerariumChain DPAC T2 Generator Setup .exe` e seguire l'installazione (si può scegliere la cartella). Finché l'installer non è firmato con il certificato di firma del codice Windows, può comparire uno di questi messaggi: | Messaggio | Che cosa fare | |---|---| | **"Windows ha protetto il PC"** (Microsoft Defender SmartScreen) | fare clic su **Ulteriori informazioni**, verificare che l'app sia "AerariumChain DPAC T2 Generator", poi **Esegui comunque** | | Il browser segnala il file come **"non scaricato comunemente"** | nella lista dei download scegliere **Mantieni** (Edge: … → Mantieni → Mostra altro → Mantieni comunque) | | **"Smart App Control ha bloccato un'app"** | con Smart App Control attivo Windows non permette di aprire app non firmate: [contattateci](https://aerariumchain.com/it/contact/) per la versione firmata. Lo stato si vede in **Sicurezza di Windows → Controllo app e browser → Smart App Control** | | L'antivirus aziendale mette in quarantena il file | chiedere all'amministratore IT di consentire l'installer e la cartella dell'app | **Primo avvio.** L'app mostra il **contratto di licenza** (EULA) da accettare, poi chiede l'accesso con l'account dell'Hub: la stessa sessione serve per leggere i dati dell'Hub, senza un secondo login. In alto compaiono il codice della licenza, il titolare e la scadenza; lo stesso codice è riportato sul certificato e nel pacchetto di verifica di ogni pacchetto creato. **Licenza.** Ogni computer su cui si accede occupa un'installazione della licenza (riaprire l'app sullo stesso computer non ne consuma altre). La licenza si rinnova online ogni 30 minuti; senza rete l'app funziona fino a 72 ore. Alla scadenza, o se la licenza viene sospesa, l'app si blocca e indica a chi rivolgersi. **Aggiornamenti.** Le versioni nuove si scaricano da sole e si installano al riavvio (vedi più sotto). ## Che cosa produce Per ogni pacchetto il disco di destinazione riceve una cartella con il nome della consegna, così l'elenco si legge una riga per opera: ``` /CANTIERE_LOTTO_PK_T2/ CANTIERE_LOTTO_PK_T2.zip la consegna per la Digital Library CANTIERE_LOTTO_PK_T2_CERTIFICATO.pdf certificato di verifica CANTIERE_LOTTO_PK_T2_VERIFICA.zip il pacchetto di verifica per il quality check (vedi sotto) CANTIERE_LOTTO_PK_T2/ la consegna non zippata, con lo stesso nome dello ZIP (su cui girano i controlli) .xml METS T2 (UPDATE_3D, UUID DPAC, SIZE e MD5 reali) _PARADATA_3D/ relazione di setup / scheda di rilievo e relazione di elaborazione (PDF) _RAW_3D/ dati grezzi: export Artec (PLY + foto), file, contenitore .acraw o progetto originale _Thumbnail_3D/ thumbnail già nel T1, rimesso nel T2 _6ViewImages_3D/ viste di rendering già nel T1, rimesse nel T2 CANTIERE_LOTTO_PK_T2_VERIFICA/ il pacchetto di verifica non zippato, con lo stesso nome dello ZIP ``` Lo ZIP di consegna contiene solo il contenuto della cartella `CANTIERE_LOTTO_PK_T2/`. Tutto il resto resta fuori dalla consegna. Per un **gigapixel** (materiale HQ di D.PaC) il T2 ha la stessa forma: il METS del T1 gigapixel con lo stato di aggiornamento (`UPDATE_HQ`, oppure `UPDATE_2D` se la Digital Library lo richiede: si sceglie in Impostazioni), le cartelle `_PARADATA_HQ` e `_RAW_HQ`, e come dati grezzi le **immagini di input del fotomosaico in RAW DNG** con almeno uno scatto con il **ColorChecker**, come chiesto dal MiC. La relazione di elaborazione descrive stitching, allineamento, calibrazione del colore e l'immagine master. La struttura del pacchetto, la trasformazione del METS e le regole sui checksum sono le stesse della pipeline dell'Hub AerariumChain: un pacchetto costruito con lo strumento è identico a uno prodotto dall'Hub. ![La vista di verifica: il pacchetto in esame, i pacchetti generati e quelli falliti con i problemi](/downloads/dpac-t2-verifica.png) ## Creare un pacchetto a mano La sezione **Crea pacchetto T2** è una procedura in cinque passi. 1. **METS T1**: il METS esatto ingerito con il T1, da file locale, da URL, oppure letto direttamente dall'**Hub AerariumChain** (accesso con le credenziali dell'Hub, scelta della hive e dell'opera: lo strumento scarica il METS T1, l'UUID DPAC, la scheda di rilievo del Site Manager e lo stato del derivato). Con il T1 arriva anche il suo pacchetto (dall'hub vengono lette solo le voci necessarie), da cui thumbnail e viste di rendering sono rimessi nel T2. 2. **Identificazione**: codice cantiere, codice lotto e PK (danno il nome allo ZIP), il prefisso del pacchetto (dà il nome al METS e alle cartelle), l'**UUID della risorsa assegnato da DPAC** dopo l'ingestione del T1, titolo e numero di inventario. 3. **Paradati**: le due relazioni possono essere generate dai moduli (lo strumento riproduce i modelli MiC) oppure allegate come PDF già pronti; si possono aggiungere altri documenti. 4. **RAW 3D**: i dati grezzi di acquisizione in una di quattro forme: - l'**export dal progetto Artec Studio** con la CLI `aec_artecViewer`, lo stesso strumento che usa il nodo GPU AerariumChain: una PLY grezza per scansione (ogni frame come registrato) più le **foto delle scansioni** (le immagini della camera texture, PNG lossless, `_RAW_NN_INP_NNNN.png`) elencate nel METS come immagini di input. I filtri sono quelli della CLI (`kind`, `scan-geometry`, `target-total`, `max-size`, `on-oversize`): una scansione esclusa o rifiutata per dimensione non lascia né PLY né foto, un file fuso o incompleto fa fallire l'export (gate di provenienza del server DPAC). Il progetto può essere una cartella o uno ZIP locale, oppure quello registrato sull'hub, scaricato prima dell'export; - **file grezzi** (un PLY per scansione, immagini, E57 ...), copiati e sottoposti a hash; - il **formato aperto `.acraw`** (AerariumChain Raw): invece dei file sciolti, un unico contenitore con manifest, SHA-256 di ogni file e root hash, verificabile da chiunque senza software proprietario; si applica sia ai file grezzi selezionati sia all'export Artec (PLY per scansione + foto); specifica su [github.com/aerariumchain/acraw-spec](https://github.com/aerariumchain/acraw-spec); - il **formato originale** del software di acquisizione: la cartella del progetto zippata senza ricompressione, oppure un archivio copiato byte per byte. 5. **Destinazione**: il disco esterno (volumi montati e spazio libero sono elencati), verifica automatica, ZIP (ZIP64 quando serve) e certificato. ![Il passo RAW 3D: export dal progetto Artec con la CLI integrata (PLY per scansione + foto), filtri della CLI](/downloads/dpac-t2-raw.png) Dall'Hub, lo strumento può anche chiedere all'**Hub stesso** di costruire il T2: i PLY grezzi sono esportati dal progetto dello scanner su un nodo GPU e il pacchetto è assemblato lì. ![La procedura guidata: METS T1 dall'Hub, identificazione, paradati, RAW 3D, destinazione](/downloads/dpac-t2-crea.png) ## Verificare un pacchetto La sezione **Verifica pacchetti** accetta la cartella del pacchetto (prima dello ZIP) oppure uno ZIP già creato. I controlli riguardano: - il METS: XML ben formato, `PROFILE`, `OBJID`, header (`RECORDSTATUS`, UUID, `CREATEDATE`, agenti), sezioni descrittiva e amministrativa, i campi obbligatori dei metadati tecnici 3D, gli identificativi duplicati; - la sezione dei file: vocabolario `USE`, il gruppo `FG_3D` del T1, i gruppi `STORAGE` e `RAW_3D`, i nomi dei documenti dei paradati; - ogni file dichiarato nei gruppi del T2: presenza, `SIZE`, `MD5`, `MIMETYPE`, `CREATED`, `ADMID`; la firma dei PDF; l'header dei PLY; i contenitori `.acraw` (regole del contenitore, manifest, hash, root hash, struttura); - la semantica del delta: nessun file del T1 nel pacchetto, nessun file non dichiarato; - il confronto con il METS T1, quando è fornito; - a scelta, il validatore pubblico METS ECO-MiC di ICDP. Due pannelli tengono la storia: **pacchetti generati** (verifica superata) e **pacchetti falliti**, ciascuno con i problemi riscontrati. Ogni regola ha un identificativo stabile (`HDR-ID`, `FSEC-STORAGE`, `FILE-MD5` ...) che compare anche nel certificato e nelle risposte dell'API. ## Il pacchetto di verifica per il quality check Accanto a ogni consegna lo strumento scrive un **pacchetto di verifica**: la cartella `CANTIERE_LOTTO_PK_T2_VERIFICA/` e la sua copia `CANTIERE_LOTTO_PK_T2_VERIFICA.zip` (le cartelle non zippate si possono disattivare nelle impostazioni). Serve al quality check della Digital Library: chi riceve lo ZIP di consegna può controllare che sia arrivato intatto, leggere il registro dei controlli e risalire a come è stato costruito, senza aprire il pacchetto. Per il pacchetto `3D03CE01_LDIG013_PK0000002_T2` contiene: | File | Che cos'è e a cosa serve | |---|---| | `3D03CE01_LDIG013_PK0000002_T2_CERTIFICATO.pdf` | il certificato di verifica (vedi sotto), copia di quello accanto allo ZIP | | `3D03CE01_LDIG013_PK0000002_T2.zip.md5` | l'impronta MD5 dello ZIP di consegna, nel formato di `md5sum`: l'hash, due spazi, il nome del file. Dalla cartella in cui sta lo ZIP: `md5sum -c 3D03CE01_LDIG013_PK0000002_T2.zip.md5` (Linux), `md5 -r 3D03CE01_LDIG013_PK0000002_T2.zip` (macOS), `certutil -hashfile 3D03CE01_LDIG013_PK0000002_T2.zip MD5` (Windows). Se l'hash coincide, lo ZIP arrivato è byte per byte quello prodotto | | `3D03CE01_LDIG013_PK0000002_T2.zip.sha256` | la stessa impronta con SHA-256 (`sha256sum -c …` su Linux, `shasum -a 256 -c …` su macOS): più robusta dell'MD5, è quella riportata anche nel certificato | | `rapporto.json` | il registro completo dei controlli, leggibile da macchina: `ok`, `errors`, `warnings`, l'elenco `items[]` (ogni controllo ha un `id` stabile come `HDR-ID`, `FSEC-STORAGE`, `FILE-MD5`, `T1-FILES`, un `level` `error|warn|info|ok`, il messaggio e il file interessato) e `summary` (tipo, OBJID, UUID DPAC, RECORDSTATUS, conteggi, inventario con MD5) | | `build.json` | come è stato costruito il pacchetto: la specifica di build (identificativi, sorgente del T1, paradati, modalità RAW, opzioni), da dove viene il T1, i file prodotti con dimensione e MD5, lo strumento di export e la sua versione | | `t1.xml` | il METS T1 ingerito da DPAC da cui deriva il T2: serve per rifare il confronto delta (ogni file del T1 citato nel T2 deve avere gli stessi SIZE e CHECKSUM) e l'app lo riusa da sola quando qualcuno verifica lo ZIP | | `METS_.xml` | copia del METS T2 consegnato | | `METS__RELAZIONE_SETUP-ACQUISIZIONE.pdf`, `METS__RELAZIONE_ELABORAZIONE.pdf` | copie dei documenti dei paradati, per leggerli senza aprire il pacchetto | | `artec-manifest.json` | (modalità Artec) il manifest della CLI: per ogni PLY grezzo la scansione d'origine, frame totali e usati, HD/SD, MD5, e l'elenco delle foto | | `inventario.txt` | una riga per file del pacchetto: MD5, dimensione, gruppo METS (STORAGE, RAW_3D, LOW, PREVIEW…), percorso | | `LEGGIMI.txt` | che cos'è la cartella, esito e identificativi del pacchetto, i problemi rilevati e l'elenco qui sopra | Un errore blocca lo ZIP; un avviso no. Il pacchetto di verifica viene prodotto anche quando un pacchetto viene solo verificato (una cartella o uno ZIP ricevuto da un fornitore), accanto al file controllato. ## Il certificato di verifica Quando un pacchetto supera la verifica, lo strumento scrive un PDF **fuori dal pacchetto**: l'identità del pacchetto, SHA-256 e MD5 del METS e dello ZIP, il registro completo dei controlli con il loro esito, l'inventario dei file con i loro hash. I PDF dei paradati non sono allegati: sono nel pacchetto consegnato e nel pacchetto di verifica. È il documento da conservare con la consegna. ## L'API locale La finestra e l'API condividono lo stesso codice. L'API ascolta solo sul PC (`http://127.0.0.1:47821/api/v1`, porta e token opzionale nelle impostazioni) ed è descritta da un documento **OpenAPI 3.0** servito dall'app su `/api/v1/openapi.json` e scaricabile qui: [dpac-t2-openapi.json](/downloads/dpac-t2-openapi.json). ![Impostazioni: accesso all'Hub, API locale con il contratto OpenAPI, validatore pubblico, valori predefiniti](/downloads/dpac-t2-impostazioni.png) ![Impostazioni: monitoraggio e assistenza, valori predefiniti e cartelle non zippate con il nome degli ZIP](/downloads/dpac-t2-artec.png) | Metodo | Rotta | Scopo | |---|---|---| | GET | `/health` | stato dell'app | | GET | `/openapi.json` | il contratto dell'API | | GET | `/disks` | volumi montati e spazio libero | | GET | `/artec/status` | la CLI `aec_artecViewer` è utilizzabile? (percorso, Node, versione) | | POST | `/artec/list` | elenca scansioni, frame e foto di un progetto Artec | | POST | `/build` | crea un pacchetto T2 (job) da una `BuildSpec` | | POST | `/check` | verifica una cartella o uno ZIP (job, oppure sincrona con `wait: true`) | | POST | `/zip` | verifica e zippa la cartella di un pacchetto (job) | | POST | `/acraw` | racchiude file grezzi in un contenitore `.acraw` (job) | | POST | `/pdf/setup`, `/pdf/elaborazione` | genera le due relazioni dei paradati | | GET | `/jobs`, `/jobs/{id}` | stato, risultato ed eventi di un job | | GET | `/jobs/{id}/events` | gli stessi eventi in Server-Sent Events | | GET, DELETE | `/packages`, `/packages/{id}` | il registro dei pacchetti generati e falliti | Autenticazione: nessuna per impostazione predefinita; quando nelle impostazioni è definito un token, va inviato come `X-Api-Token` oppure come bearer token. Ogni percorso nelle richieste è un percorso sul PC dove gira l'app. ### La richiesta di creazione ```json { "identity": { "codiceCantiere": "3D03CE05", "codiceLotto": "LDIG003", "pk": "PK0000002", "objid": "M489_XXXX", "dpacUuid": "6f1c2a3e-4b5d-4e6f-8a9b-0c1d2e3f4a5b", "title": "Titolo dell'opera", "inventory": "INV-1", "catalogId": "XXXX" }, "t1": { "source": "file", "path": "/dati/t1/M489_XXXX.xml" }, "paradata": { "setup": { "mode": "generate", "data": { "id_oggetto": "...", "setup_acquisizione": "SETUP_#1" } }, "elaborazione": { "mode": "generate", "data": { "operator": "...", "derivFile": "M489_XXXX_DRV.glb", "derivSoftware": "Blender" } } }, "raw": { "mode": "folder", "folder": "/dati/raw/M489_XXXX", "extensions": ["ply"], "acraw": { "enabled": false } }, "options": { "overwrite": true }, "output": { "dir": "/Volumes/DISCO/T2", "zip": true, "keepStaging": true } } ``` - `t1.source` vale `file` oppure `url` (con `headers`). - `paradata.*.mode` vale `generate` (dai dati), `file` (un PDF esistente, `path`) oppure `none`. - `raw.mode` vale `artec` (con `raw.artec`: `projectPath` o `projectS3Key`, `kind`, `scanGeometry`, `targetTotal`, `maxSize`, `onOversize`, `maxTotalSize`, `photos`), `files`, `folder`, `original` (con `originalPath` e `originalVendor`) oppure `none`; `raw.acraw.enabled` attiva il contenitore aperto. Il manifest della CLI Artec resta in `verifica/artec-manifest.json`. ### Il flusso di un job ``` POST /build -> 202 { "jobId": "..." } GET /jobs/{jobId} -> { "job": { "status": "running|done|failed", "result": ... }, "events": [...] } GET /jobs/{jobId}/events -> text/event-stream: progress, done, error ``` Gli eventi di avanzamento portano `step`, `percent` e `message`; il risultato di una creazione porta i percorsi della cartella, dello ZIP (con dimensione e MD5), del rapporto di verifica e del certificato. Una verifica sincrona: ``` POST /check { "target": "/Volumes/DISCO/T2/3D03CE05_LDIG003_PK0000002_T2.zip", "wait": true } -> 200 { "report": { "ok": true, "errors": 0, "warnings": 0, "items": [...], "certificatePath": "..." } } ``` Le stesse operazioni sono disponibili da riga di comando (`dpac-t2 build`, `check`, `zip`, `acraw`, `pdf-setup`, `pdf-elab`), con lo stesso codice. ## Guida e supporto AI Questa pagina è la guida dell'app: il menu **Guida** la apre nel browser. La stessa guida in Markdown, pensata come contesto per un assistente AI, si scarica da qui: [dpac-t2-guida.md](/downloads/dpac-t2-guida.md). Il menu **Collega ad AI** raccoglie tutto ciò che permette a un assistente (Claude Code, Claude Desktop, ChatGPT) o al team AerariumChain di aiutare quando qualcosa non va: - **Esporta diagnostica per l'AI**: un file Markdown (o la copia negli appunti) con ambiente, impostazioni senza segreti, pacchetti falliti con i problemi, il rapporto di verifica del pacchetto scelto, una nota dell'operatore, le ultime righe del log e la guida. Mai i file dei pacchetti. Lo stesso pulsante è su ogni pacchetto fallito. - **Connettore MCP**: l'app è un server MCP (Model Context Protocol) locale. Un clic la collega a Claude Code o Claude Desktop, che possono leggere stato, pacchetti, rapporti e log, lanciare una verifica o una build e risolvere il problema in diretta con l'operatore. ChatGPT richiede un server pubblico: si usa l'esportazione diagnostica. - **Guida** (link e download) e **Chiedi assistenza** (richiesta al team con il contesto dell'app). ![Collega ad AI: diagnostica, guida, connettore MCP, assistenza](/downloads/dpac-t2-ai.png) ## Aggiornamenti, monitoraggio e assistenza L'app dialoga con il manager AerariumChain (manager.aerariumchain.com) tramite l'Hub, con un identificativo di installazione e, se l'operatore è connesso, con la sua sessione: - **Aggiornamenti**: all'avvio e ogni sei ore controlla se è stata pubblicata una versione più recente; se c'è, la scarica in background e la barra laterale mostra "Aggiornamento X" con l'avanzamento e il pulsante Riavvia e aggiorna (l'installazione avviene anche alla chiusura). AerariumChain può segnare una versione come obbligatoria o forzare l'aggiornamento di una singola installazione dal manager: l'app lo installa da sola appena non ha lavorazioni in corso. - **Monitoraggio**: per ogni pacchetto creato invia un rapporto con identificativi (pacchetto, prefisso, UUID DPAC, opera, hive), esito della verifica con i problemi rilevati, hash e dimensione dello ZIP, conteggi (paradati, PLY, foto, immagini del T1), strumento di export e durate. Mai i file del pacchetto. Gli eventi si accodano offline e partono alla prima connessione; si disattiva in Impostazioni → Monitoraggio. - **Assistenza**: "Chiedi assistenza" nella barra laterale apre una richiesta al team AerariumChain con versione dell'app, sistema, stato della CLI e le ultime righe del log; la risposta arriva all'email indicata. ## Requisiti e distribuzione - macOS 11 o successivo (Apple Silicon o Intel) oppure Windows 10/11 a 64 bit; non serve altro software (i PDF dei paradati li genera lo strumento). - Spazio sul disco di destinazione per i dati grezzi e per lo ZIP. - Un account dell'Hub AerariumChain con una licenza attiva, e la connessione internet almeno una volta ogni 72 ore. - La CLI `aec_artecViewer` per l'export dai progetti Artec è integrata nell'app (presa dal suo repo in fase di compilazione) e gira sul runtime dell'app: non c'è nulla da installare. L'installer si scarica dall'Hub con un account che ha la licenza. Per una licenza o per assistenza [contattaci](https://aerariumchain.com/it/contact/).