Pubblicazione Separate e Combined, calibrazioni multiple e nomi dei Dataset
Il Curve Digitalizer di GX-TXT consente di raccogliere più realizzazioni di calibrazione dello stesso grafico. L’operatore può pubblicarle in due modi: Separate, che genera un Dataset numerico per ogni calibrazione selezionata, oppure Combined, che raccoglie più realizzazioni nello stesso Dataset aggiungendo l’identità della calibrazione a ogni riga.
Questa guida illustra le differenze nella GUI, i controlli sui nomi, la verifica delle coordinate nel CORE Scientific Dataset Viewer e l’impiego delle API pubbliche. Sono particolarmente importanti due distinzioni: calibrazione attiva non equivale a calibrazione selezionata per Publish; inoltre venti righe provenienti da dieci punti e due calibrazioni non rappresentano venti osservazioni indipendenti.
La sorgente utilizzata è una figura sintetica didattica. Gli angoli delle due calibrazioni sono stati scelti intenzionalmente in posizioni leggermente diverse: le differenze numeriche fra i risultati servono a mostrare la propagazione geometrica della trasformazione, non a stimare l’incertezza di uno strumento.
1. La figura di riferimento
Il raster originale contiene una traccia scura e una traccia rosa secondaria. La prima è l’oggetto della digitalizzazione.

Le dimensioni della sorgente sono 1280 × 900 pixel. Il nome del Dataset sorgente, la sua identità e la geometria dei pixel rimarranno invariati durante tutte le pubblicazioni descritte.
2. Una prima calibrazione a quattro angoli
Nella scheda Calibration definiamo X da 0 a 10 s e Y da −20 a 80 mV, entrambi lineari. Selezioniamo i quattro angoli del rettangolo del grafico e confermiamo la calibrazione.


I quattro punti definiscono una trasformazione dai pixel originali alle coordinate scientifiche. La prima realizzazione verrà chiamata Trial A.
3. Acquisire dieci punti manuali
Nella scheda Curves creiamo una curva scientifica, quindi utilizziamo Add per acquisire dieci punti della linea scura.

I punti possiedono un identificativo interno, una posizione originale sul raster e una coordinata X/Y calcolata. Il loro point_id non viene ricreato quando si seleziona una differente calibrazione.
4. Il gestore Calibration measurements
La sezione Calibration measurements distingue le realizzazioni che sono draft, accepted, rejected e active.
Accepted significa che la realizzazione può essere usata per la pubblicazione. Active indica invece la trasformazione mostrata e utilizzata nel documento corrente. La scheda Publish può selezionare una calibrazione accettata anche quando non è quella attiva.
5. Creare una seconda realizzazione
Premiamo New nel gestore delle misure di calibrazione.

Si crea un secondo elemento inizialmente draft. Il programma non lo tratta come già accettato: occorre fornire una nuova geometria completa e confermarla.
6. Selezionare gli angoli per Trial B
Per la seconda realizzazione selezioniamo angoli leggermente diversi dagli originali, pur mantenendo la stessa immagine e gli stessi limiti fisici degli assi.


Questa differenza è volutamente didattica. Non è una replica sperimentale e non permette, da sola, di stimare incertezze standard o accuratezza.
7. Accettare entrambe le calibrazioni
Dopo aver completato i quattro angoli, premiamo Accept.


Sono ora presenti due realizzazioni accettate, con identificativi differenti. Entrambe possono essere scelte nella scheda Publish.
8. Attiva e selezionata: che cosa cambia?
Attivando la prima realizzazione, le coordinate X/Y del documento vengono ricalcolate sulla sua trasformazione; quando è attiva la seconda, vengono ricalcolate sulla trasformazione di quest’ultima.

Le coordinate pixel e gli identificativi dei dieci punti restano invariati. La scelta Active non decide automaticamente quali calibrazioni saranno incluse in un’operazione Publish.
9. Perché il nome visibile non è un identificativo
Per mostrare un errore comune, assegniamo temporaneamente lo stesso nome visibile alle due calibrazioni, pur mantenendo distinti i loro identificativi interni.


Un nome come Measurement 1 è una descrizione modificabile. L’identità scientifica stabile della realizzazione è il suo measurement_id.
10. La collisione nel piano di pubblicazione
Con il layout Separate e il template predefinito, due calibrazioni dallo stesso nome generano lo stesso ID previsto.


La scheda Publish segnala che i nomi collidono. Questo avviene prima di creare i Dataset canonici.
11. Il blocco della pubblicazione con nomi duplicati
Tentando di proseguire compare il messaggio nativo relativo alla collisione.

La protezione impedisce di produrre due Dataset con lo stesso identificativo. Si può risolvere il problema cambiando i nomi delle calibrazioni oppure introducendo nel template [calibration_id] o [index].
12. Assegnare nomi distinti alle realizzazioni
Rinominiamo le due misure Trial A e Trial B tramite il gestore Calibration measurements.


Non sono state modificate né le posizioni degli angoli né le coordinate originali dei punti: è cambiata soltanto la descrizione visibile.
13. Trial B attiva e Trial A disponibile
Attiviamo Trial B, mantenendo Trial A nello stato Accepted.

Nella scheda Publish possiamo selezionare entrambe le realizzazioni: la pubblicazione non è limitata a quella attiva.
14. Separate: un output per calibrazione
Apriamo la scheda Publish, scegliamo Separate, selezioniamo entrambe le calibrazioni e impostiamo un ID base per gli output.


Il template predefinito [name].[calibration].curves genera in questo esempio due nomi distinti: uno termina in trial_a.curves, l’altro in trial_b.curves.
15. Pubblicare i due Dataset Separate
Premiamo Publish selected calibrations.


La GUI conferma due Dataset pubblicati, ognuno con dieci righe. Entrambi sono tabelle numeriche canoniche di GX-TXT, separate dal raster originale e dal documento interattivo.
16. Una sola origine, due trasformazioni
Nei due output Separate i dieci point_id e le coordinate pixel sono uguali. Le coordinate scientifiche X/Y sono invece leggermente differenti, perché sono state calcolate usando due omografie accettate differenti.
Questo significa che sono state pubblicate due interpretazioni della stessa acquisizione di punti. Non sono state acquisite altre dieci posizioni sul raster.
17. Combined: un solo Dataset
Torniamo a Publish, selezioniamo Combined e manteniamo le due calibrazioni accettate.


L’anteprima mostra un solo ID, il cui nome predefinito contiene combined. Questo layout non crea un Dataset Group: crea una sola tabella con più realizzazioni.
18. La conferma avverte del rischio di mescolare dati
Premendo Publish, GX-TXT presenta una conferma specifica per Combined.

L’avviso è importante: un programma che unisse tutte le righe ignorando calibration_key potrebbe mescolare coordinate ottenute con trasformazioni differenti.
19. Rispondere No: non viene creato nulla
Scegliendo No, il Viewer abbandona la pubblicazione Combined.
I due Dataset Separate precedenti restano disponibili e non nasce alcun terzo risultato. L’anteprima può continuare a mostrare l’ID Combined progettato: l’anteprima non dimostra che il Dataset sia stato registrato.
20. Rispondere Yes: il risultato Combined
Ripetiamo l’azione e scegliamo Yes nella conferma.
Il programma registra un solo Dataset Combined, costituito da venti righe.


Le venti righe rappresentano i dieci punti originali, ciascuno espresso una volta con Trial A e una volta con Trial B.
21. Due chiavi per un raggruppamento sicuro
Nel Dataset Combined, il raggruppamento non deve avvenire soltanto per curva. La API pubblica dichiara grouping_roles = curve_key + calibration_key.
La prima chiave indica la serie, la seconda la realizzazione della calibrazione. I campi descrittivi curve_name e calibration_name non devono essere utilizzati come identificativi stabili.
Selezionare correttamente le due chiavi impedisce di collegare punti fisicamente non omogenei tra le due trasformazioni.
22. Il template predefinito dei nomi
In Configuration → Viewer settings… → Axes & output compare la casella Dataset naming template.


Il valore predefinito è:
[name].[calibration].curves
Il template è distinto dall’ID base inserito in Publish. Il primo decide come comporre il nome completo; il secondo fornisce il valore del token [name].
23. I sei token riconosciuti
Il template supporta questi elementi di sostituzione:
| Token | Significato |
|---|---|
| [name] | ID base dell’output |
| [calibration] | Etichetta della calibrazione normalizzata |
| [calibration_id] | Identificativo stabile della realizzazione |
| [configuration] | Nome della configurazione normalizzato |
| [index] | Indice dell’output nel piano corrente, a partire da 1 |
| [mode] | Modalità Separate o Combined |
Il modello deve contenere [name]. Le parti letterali ammesse usano caratteri ASCII e separatori consentiti; il risultato finale deve essere un ID Dataset valido.
24. Token sconosciuti: operazione rifiutata
Inseriamo volutamente il token inesistente [unknown].
L’editor rifiuta il template e indica i token riconosciuti.

La configurazione CORE non viene aggiornata da un tentativo di Apply non valido.
25. Il token [name] è obbligatorio
Proviamo un secondo template che contiene il nome della calibrazione ma non l’ID base.
La GUI richiede esplicitamente [name].

Questo controllo impedisce di generare identificativi completamente scollegati dalla scelta effettuata in Publish.
26. Un template personalizzato non ambiguo
Scegliamo:
[name].[index].[calibration_id].[mode].curves


Questo template contiene sia un indice progressivo di output sia l’ID stabile della calibrazione. Può evitare collisioni anche quando due calibrazioni condividono la stessa etichetta.
27. Apply salva le preferenze della Session
Premendo Apply, la GUI registra il nuovo template.

Il CORE conferma che il template personalizzato è un Session override. Il template User predefinito rimane invariato. Nell’esempio è stato salvato Combined come layout predefinito della Session.
Ciò non impedisce di scegliere Separate nella singola scheda Publish, dove la scelta locale può essere differente.
28. Calibrazione attiva contro selezione Publish
Per distinguere i due concetti, manteniamo Trial A attiva nel documento.

Nella scheda Publish è possibile scegliere soltanto Trial B. Il risultato numerico deve corrispondere alla calibrazione selezionata, non a quella attiva.
29. Anteprima con due calibrazioni selezionate
Con il template personalizzato, selezioniamo entrambe le realizzazioni in modalità Separate.


L’anteprima produce due nomi: il primo usa index = 1, il secondo index = 2. Entrambi includono il rispettivo calibration_id.
30. Selezionare soltanto la Trial B
Ora scegliamo soltanto Trial B, lasciando Trial A attiva.


Poiché il piano contiene un solo output, l’indice riparte da 1. Non è l’indice immutabile della calibrazione nel gestore delle misure, ma la posizione dell’output nel piano di pubblicazione corrente.
31. Pubblicare realmente il nome personalizzato
Confermiamo Publish.


Il Dataset risultante contiene dieci righe di Trial B, con la stessa trasformazione della pubblicazione Separate precedente di Trial B. L’ID personalizzato è più lungo, ma non cambia le coordinate.
32. Il template in modalità Combined
Se scegliamo nuovamente Combined con entrambe le calibrazioni, l’anteprima del template diventa un unico ID contenente i valori index = 1, calibration_id = combined e mode = combined.

È una nuova anteprima, non un’ulteriore pubblicazione. La scelta dei token dipende dal layout effettivo selezionato, non soltanto dal default della Session.
33. Consultare la Trial A nel CORE
Apriamo il risultato Separate di Trial A dal browser Dataset di GX-TXT.

Il CORE Scientific Dataset Viewer visualizza la curva nella vista Plot. La tabella canonica è il riferimento per controllare esattamente le coordinate pubblicate.
34. Le dieci righe di Trial A
Nella scheda Canonical table troviamo dieci righe.


Il Variable Schema v3 descrive le otto variabili del Dataset Separate: coordinate scientifiche, identificativi della curva e del punto, ordine e posizioni raster.

Per un Dataset Separate l’ID della calibrazione è conservato nei metadati del Dataset, non ripetuto come campo di ogni singola riga.
35. Aprire la Trial B come Dataset autonomo
Apriamo il secondo Dataset Separate nel Viewer CORE.

Anche in questo caso il risultato è un oggetto canonico autonomo, con dieci righe e un riferimento alla propria realizzazione di calibrazione.
36. Le coordinate di Trial B sono diverse
La tabella canonica di Trial B contiene gli stessi dieci identificativi e pixel della Trial A.


I valori X/Y differiscono: nell’esempio lo scarto massimo osservato per gli stessi dieci punti è circa 0,0475 s su X e 0,3272 mV su Y. È un effetto delle due calibrazioni sintetiche, non una stima di accuratezza strumentale.

37. Selezionare il risultato Combined nel browser
Nel catalogo GX-TXT possiamo scegliere il Dataset Combined, distinto da Trial A e Trial B.

Il suo identificativo e il suo payload canonico sono diversi dalle due pubblicazioni Separate.
38. La vista Plot non risolve da sola la semantica
Il CORE Scientific Dataset Viewer apre anche il Combined.

Una rappresentazione grafica che ignori le due realizzazioni può risultare fuorviante. La chiave di calibrazione è parte integrante del significato dei record.
39. La tabella Combined ha venti righe
La sezione Canonical table mostra venti record, con i campi aggiuntivi calibration_id e calibration_label.


Le prime dieci righe sono associate a Trial A e le successive dieci a Trial B. Gli stessi point_id possono quindi comparire due volte, ma ciascuna riga è distinta anche dalla sua calibration_key.
40. Dieci variabili nel Variable Schema v3
Il Combined dichiara dieci variabili, contro le otto del Separate.


I ruoli semantici aggiuntivi sono calibration_key e calibration_name. Il secondo è una descrizione, il primo è l’identificativo stabile. Il CORE dichiara che il raggruppamento completo utilizza curve_key e calibration_key.
41. Provenienza e trasformazioni
I metadati del Combined conservano l’origine e le realizzazioni di calibrazione pubblicate.

La sezione Source ancestry mostra il legame con l’immagine originale.


Questo legame permette di ricondurre le coordinate al raster e alla trasformazione appropriata, evitando di confondere due interpretazioni della stessa posizione pixel.
42. Verificare il Dataset con nome personalizzato
Nel browser Dataset è disponibile anche la pubblicazione personalizzata della sola Trial B.

Il CORE Scientific Dataset Viewer ne mostra Plot e Canonical table.

I metadati confermano che è stata pubblicata la realizzazione Trial B, benché durante la procedura fosse attiva Trial A.

43. Salvare il lavoro e verificare la riapertura
Prima di chiudere il Viewer, il gestore Calibration mostra entrambe le realizzazioni accettate.

La scheda Publish contiene ancora la scelta locale Separate, anche se il layout predefinito della Session è Combined.

Dopo Configuration → Save configuration, Close e Reopen, sono ancora disponibili i dieci punti e le due calibrazioni.

La scheda Publish continua a permettere la scelta degli output e il template personalizzato.

44. Preferenze della Session e sorgente dopo Reopen
Aprendo Viewer settings si ritrovano il template personalizzato e il layout predefinito Combined.


La sorgente originale e i quattro Dataset numerici già pubblicati sono ancora disponibili.

L’identità degli output canonici è indipendente dal fatto che il Viewer sia aperto; le tabelle già pubblicate non vengono riscritte dalla riapertura.
45. Controllare la selezione dopo Reopen: una precauzione importante
Dopo la riapertura del Viewer è possibile che Publish ripristini una selezione diversa da quella salvata. Nell’esempio era stata selezionata soltanto Trial B, mentre Trial A era attiva.


Dopo la riapertura, la GUI ha mostrato Trial A selezionata al posto della Trial B precedentemente scelta.

Dopo ogni riapertura, controllare e, se necessario, riselezionare le calibrazioni in Publish prima di pubblicare. Gli output canonici precedenti non vengono modificati: il problema riguarda soltanto la selezione ripristinata nell’Interactive Document, non le trasformazioni già pubblicate.
46. API pubbliche: riconoscere il layout
Un programma che lavora sui Dataset dovrebbe risolvere le colonne e i loro ruoli tramite le API pubbliche, senza affidarsi alla posizione delle colonne CSV.
Nel framework con la Session pertinente attiva, utilizzare gli identificativi effettivi del Dataset e della realizzazione di calibrazione al posto dei valori esemplificativi nel codice:
# Activate versioned, public Curve Digitalizer Dataset Schema API.
::GX::modulePublicApiActivate viewer.curve_digitizer CURVE_DIGITIZER_DATASET_SCHEMA_API_v1
set dataset_id "example.combined.curves"
set manifest [::GX::CurveDigitizerDataset::read $dataset_id]
# The full set of grouping roles may contain more than one key.
set roles [dict get $manifest grouping_roles]
set curve_column [dict get $manifest columns curve_key]
if {[dict exists $manifest columns calibration_key]} {
set calibration_column [dict get $manifest columns calibration_key]
}
# Read a bounded canonical subset for one calibration realization.
set measurement_id "example_measurement_id"
set rows [::GX::CurveDigitizerDataset::rasterPoints \
$dataset_id "" 0 100 $measurement_id]
La firma di rasterPoints ammette un filtro sul parametro calibrationKey, oltre all’eventuale filtro curveKey. Il numero di righe restituite va verificato; non bisogna presumere che corrisponda all’intero Dataset Combined.
47. API di calibrazione: leggere ogni realizzazione
La API CURVE_DIGITIZER_CALIBRATION_API_v1 permette di consultare le realizzazioni pubblicate e applicare la trasformazione adeguata ai pixel originali. Nel blocco Tcl successivo, dataset_id è lo stesso identificativo impostato nell’esempio precedente.
# Activate the public calibration manifest API.
::GX::modulePublicApiActivate viewer.curve_digitizer CURVE_DIGITIZER_CALIBRATION_API_v1
set calibrations [::GX::CurveDigitizerCalibration::replicates $dataset_id]
foreach cal $calibrations {
if {![dict get $cal valid]} {
continue
}
set mid [dict get $cal measurement_id]
set original_pixels {{235.74 441.71}}
set xy [::GX::CurveDigitizerCalibration::transformPoints \
$dataset_id $original_pixels pixel_to_scientific $mid]
}
La realizzazione deve essere indicata tramite measurement_id, non dedotta dalla sua etichetta. La stessa API consente la trasformazione inversa scientific_to_pixel con la calibrazione specificata.
48. Regole per scegliere Separate o Combined
Utilizzare Separate quando è utile trattare ciascuna calibrazione come un Dataset distinto, con la sua identità e la sua tabella. La gestione è più semplice per i consumatori che non sono predisposti a distinguere più realizzazioni nello stesso output.
Utilizzare Combined quando serve un’unica tabella con più realizzazioni, ma soltanto se gli strumenti a valle rispettano calibration_key e il CORE conferma che le unità fisiche degli assi sono compatibili.
La pubblicazione Combined richiede infatti le stesse unità fisiche X per tutte le calibrazioni selezionate e le stesse unità Y. Non è un modo per unire direttamente grandezze incompatibili.
49. Limiti della procedura
Questa guida ha esaminato una curva, due calibrazioni accettate e quattro pubblicazioni di prova, tutte provenienti dallo stesso raster sintetico.
Non abbiamo creato nuove misure indipendenti, calcolato intervalli di confidenza o dichiarato incertezze metrologiche. Un modello d’incertezza revisionato per una calibrazione non deve essere trasferito automaticamente a un’altra. La pubblicazione Combined di più calibrazioni con incertezza numerica revisionata non è supportata scientificamente da questa versione: utilizzare Separate o disabilitare la dichiarazione, quando appropriato.
I Dataset Group, i due assi Y e gli schemi multi-Y sono trattati in una guida successiva, non sono impliciti nel semplice layout Combined.
50. Procedura operativa consigliata
- Conservare il raster originale e acquisire i punti scientifici da una sorgente identificata.
- Creare e accettare le realizzazioni di calibrazione, mantenendo distinti i loro measurement_id.
- Assegnare nomi descrittivi, ma non usare l’etichetta come identità scientifica stabile.
- Controllare la differenza fra misura attiva nel Viewer e misure selezionate in Publish.
- Scegliere Separate per Dataset distinti oppure Combined per una tabella unica con calibration_key.
- Verificare l’anteprima degli ID prima della pubblicazione. Usare [calibration_id] o [index] quando le etichette possono collidere.
- Per un template personalizzato, includere [name] e soltanto token autorizzati.
- In Combined, leggere l’avviso e proseguire soltanto se gli strumenti a valle comprendono le chiavi di calibrazione.
- Controllare i Dataset nel CORE, confrontando i record con le realizzazioni attraverso le API pubbliche.
- Dopo Save/Close/Reopen, verificare nuovamente le calibrazioni selezionate in Publish prima di confermare un’ulteriore uscita.
Conclusione: Separate e Combined consentono due organizzazioni differenti di dati ottenuti dagli stessi punti pixel. La correttezza scientifica dipende dal mantenimento delle identità di calibrazione, dalla denominazione non ambigua e dalla lettura dei ruoli semantici, non soltanto dal numero di righe della tabella.