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 <versione>.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:

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:

<destinazione>/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)
    <prefisso>.xml                       METS T2 (UPDATE_3D, UUID DPAC, SIZE e MD5 reali)
    <prefisso>_PARADATA_3D/              relazione di setup / scheda di rilievo e relazione di elaborazione (PDF)
    <prefisso>_RAW_3D/                   dati grezzi: export Artec (PLY + foto), file, contenitore .acraw o progetto originale
    <prefisso>_Thumbnail_3D/             thumbnail già nel T1, rimesso nel T2
    <prefisso>_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 <prefisso>_PARADATA_HQ e <prefisso>_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.

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, <prefisso>_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;
   • 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.

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ì.

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:

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.

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

{
  "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.

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).

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.