PortLab

1. Panoramica e navigazione della vista 3D

La pagina è divisa in due: a sinistra la vista 3D, a destra il pannello dei comandi, organizzato in sezioni a fisarmonica (Impostazioni generali, Serie dati, Assi e griglie, Importa/Esporta, Analisi dati, Animazione temporale, Sezione). Ogni modifica nel pannello si riflette in tempo reale nel grafico.

Nella vista 3D il mouse comanda la camera:

• trascinare col tasto sinistro ruota la scena;
• la rotella avvicina e allontana (zoom);
• trascinare col tasto destro sposta la scena (pan).

In basso a destra la bussola degli assi (triade X/Y/Z) ruota con la scena e dice da che parte si sta guardando; non compare nelle immagini esportate. La legenda (colorbar) è trascinabile: si prende con il mouse e si porta dove non disturba; la posizione viene ricordata. Rotazione, zoom, pan e bussola si possono abilitare o disabilitare singolarmente dalla Scena (capitolo 2).

2. Impostazioni generali: Scena, Legenda, Titolo

La sezione Impostazioni generali è divisa in tre schede. In fondo alla scheda Scena, Ripristina valori predefiniti riporta l'aspetto della scena ai default (chiede conferma; le serie non vengono toccate).

2.1 Scena

• Colore sfondo del grafico.
• Navigazione: interruttori e velocità per rotazione, zoom e pan; bussola degli assi; smorzamento = inerzia della rotazione (0 ferma la scena appena si lascia il mouse).
• Camera: campo visivo (stretto = prospettiva quasi ortografica, largo = esagerata), distanza, piani vicino/lontano (delimitano ciò che viene disegnato: alzare il vicino o abbassare il lontano fa sparire pezzi di superficie).
• Luci: colore e intensità della luce ambiente e di quella direzionale; azimut ed elevazione orientano la direzionale come un sole — è l'ombreggiatura che rivela il rilievo, con la sola luce ambiente la superficie resta piatta.

2.2 Legenda

• Visualizza: accende/spegne la legenda.
• Sfondo: colore e opacità del riquadro.
• Bordo: colore, spessore e opacità della cornice.
• Dimensioni colorbar: larghezza e altezza della barra; la larghezza massima (in % del grafico) decide quando più colorbar vanno a capo invece di allargarsi ancora.
• Intestazioni colorbar: colore, dimensione e carattere del titolo di ogni barra ("— come la legenda —" eredita il font generale); con Tag HTML attivo si possono usare <sup>, <sub> e simboli.
• Ticks: colore, dimensione e carattere delle etichette numeriche.
• Scala condivisa: stessa scala colore per tutte le serie a griglia — con scale diverse lo stesso colore significa valori diversi e due superfici non sono confrontabili a vista. Nubi di punti e campi vettoriali conservano la propria.

2.3 Titolo

Testo del titolo del grafico, con colore, dimensione e carattere propri. Come la legenda, anche il titolo si può trascinare nella posizione preferita.

3. Serie dati: accendere, selezionare, configurare

La sezione Serie dati elenca le serie del grafico. Nell'intestazione di ogni serie ci sono tre comandi:

• il radio a sinistra seleziona la serie su cui agiscono i bottoni "Duplica selezionata" e "Rimuovi selezionata" (spenti se nessuna è selezionata);
• l'occhio accende/spegne la serie nel grafico senza perderne la configurazione (👁 barrato = spenta); "Accendi/Spegni tutte" agisce su tutte insieme;
• accanto ad "Accendi/Spegni tutte" ci sono Annulla (↺) e Ripeti (↻): le operazioni distruttive — rimozione di una serie, import di un JSON, ripristino della scena — si possono annullare, fino a 20 passi indietro;
• il nome apre e chiude la card con i controlli della serie.

Dentro la card della serie, dall'alto in basso:

• Nome: l'etichetta che compare in intestazione e in legenda.
• Funzione: la sorgente della serie — una funzione analitica, un dataset, una funzione amministrata dal database o un dataset importato da CSV. La tendina ha la ricerca: basta digitare per filtrare le voci. Sotto compare il dominio applicato; l'icona ⓘ mostra la descrizione.
• Parametri: se la sorgente ne ha (es. ampiezza, frequenza, parametri del metodo di interpolazione), ciascuno ha il suo controllo; per i dataset c'è anche il metodo di interpolazione con i suoi parametri (vedi la pagina Interpolazione).
• Step: il passo di campionamento del dominio (più piccolo = più dettagli e più calcolo). Per le curve ci sono estremi di t e numero di campioni.
• zScale: esagerazione verticale.
• Modo: surface (superficie piena), wireframe (solo maglia), points (nuvola di punti).

4. Colore: colormap, tinta unita, classificazione

Colormap sceglie la scala colore: ogni voce della tendina mostra l'anteprima del gradiente. Modo colore decide come usarla:

• gradiente: colore continuo secondo la grandezza scelta in Colora per (di solito la quota z, ma un dataset può esporre altre grandezze — è la tematizzazione: stessa superficie, colore che racconta un'altra cosa);
• tinta unita: un colore solo, scelto dal selettore;
• categorie: classificazione a classi discrete (sotto).

Scala colore: lineare o logaritmica, con minimo/massimo (e centro, per le scale divergenti) impostabili a mano; vuoti = automatici dai dati.

4.1 Impostare una classificazione

Con Modo colore = categorie la grandezza viene divisa in classi, ognuna con un colore. Si sceglie il Metodo (quantili, intervalli uguali, passo fisso, Jenks…), il numero di classi (o il passo) e si preme Ricalcola. La tabella delle classi si modifica a mano:

• i confini sono accoppiati: cambiando il limite superiore di una classe si aggiorna il limite inferiore della successiva — niente buchi né sovrapposizioni;
• ogni classe ha il suo colore (cliccarlo per cambiarlo) e un'etichetta (vuota = generata dai confini);
• + aggiunge una classe (divide in due la più ampia, col colore preso dal gradiente), il cestino la elimina (la vicina assorbe l'intervallo).

5. Creare un gradiente (Gradient designer)

Il bottone Gradient designer apre l'editor dei gradienti personalizzati:

1. dare un nome (comparirà nella tendina delle colormap) o partire da un preset (viridis, magma, turbo…);
2. regolare gli stop: ognuno ha posizione (0–1), colore e opacità; "+ Aggiungi stop" inserisce un punto intermedio, il cestino lo toglie;
3. controllare l'anteprima e premere Salva gradiente: da quel momento il gradiente è selezionabile come qualunque colormap. "Reimposta" annulla le modifiche in corso.

6. Colorbar e formati numerici

Nel blocco Legenda della card si controlla la colorbar della serie:

• Numero ticks: quante etichette numeriche sulla barra;
• Tag HTML: consente markup nelle intestazioni;
• Modo del formato numerico:
  • fixed — decimali fissi (campo Decimali);
  • sprintf — pattern C nel campo apposito: %.2f, %+.3e, %d…;
  • locale/percent — formattazione secondo il Locale (es. it-IT, en-US);
• Prefisso/Suffisso: testo attaccato prima/dopo il numero (es. unità).

Le frecce ↑ ↓ in fondo alla card cambiano l'ordine delle serie (e delle colorbar).

6.1 Isolinee, opacità, wireframe

• Isolinee/contour: N linee di livello automatiche oppure livelli scritti a mano (separati da virgola); si possono disegnare sulla superficie, proiettare alla base, o riempire a bande;
• Opacità della serie (utile per vedere superfici sovrapposte);
• Wireframe: spessore in pixel e stile della maglia.

7. Assi e griglie

La sezione Assi e griglie ha una scheda per asse (X, Y, Z), ciascuna divisa in due gruppi come nella figura:

• Asse: minimo e massimo della finestra di vista (vuoti = automatici), scala lineare o logaritmica, etichetta dell'asse con colore/carattere/ dimensione/opacità, colore/spessore/opacità della linea;
• Ticks: numero o passo, formato (anche sprintf, come per la colorbar), colore, carattere, dimensione e opacità delle etichette.

Le schede Piano XY / XZ / YZ controllano le griglie di fondo: visibilità, colore e opacità di linee principali e secondarie.

8. Analisi dati

Con Modalità analisi attiva, cliccando sul grafico si interroga il punto: coordinate e valore compaiono con un marcatore (funziona anche sulle curve, agganciando il punto della polilinea più vicino al click). Gli altri strumenti:

• Serie attiva: su quale serie lavorare (o tutte);
• Snapping: aggancio del click (nessuno, al nodo della griglia, …);
• Evidenziazione intelligente: mette in risalto zone notevoli;
• Quota isocurva z₀: disegna l'isocurva alla quota scelta ("Usa z del click" la prende dall'ultimo punto interrogato);
• Statistiche serie: percentili a scelta (es. 25, 50, 75) con "Calcola";
• Differenza (A − B): confronta due serie e mostra la superficie differenza;
• Volume rispetto a z₀: integrale del solido tra la superficie e la quota;
• Evidenzia estremi locali: ▲ massimi / ▼ minimi con soglia di prominenza;
• Righello: due click sul grafico misurano la distanza.

9. Sezione (profilo 2D)

Attiva sezione taglia la scena con un piano e mostra sotto il grafico il profilo 2D delle superfici lungo il taglio (z in valori dati). Si sceglie il taglio (y = cost → profilo z(x), oppure x = cost → z(y)) e la posizione con il cursore. Il profilo si esporta in CSV o SVG.

10. Animazione temporale

Per i dataset con più frame nel tempo la sezione mostra il cursore del frame (con l'istante t), i comandi di riproduzione, la velocità in fps e le traiettorie: una coda di N frame che segue i punti in movimento. Durante l'animazione la superficie viene aggiornata in posto: la camera e la legenda non si muovono. L'animazione si può esportare in video (capitolo 11).

11. Importa / Esporta

• Esporta PNG / SVG: immagine del grafico, con o senza legenda e titolo, sfondo trasparente opzionale, risoluzione a multipli (×2, ×3…). Nell'SVG tutto quello che si legge è vettoriale: titolo, etichette degli assi, valori dei tick, riquadro della legenda e barre colore — queste ultime come gradienti veri — restano testo e forme, quindi si selezionano, si correggono in Inkscape o Illustrator e si stampano a qualunque dimensione senza sgranare. La superficie 3D invece resta un'immagine incorporata: sono decine di migliaia di triangoli ombreggiati, in vettoriale il file peserebbe megabyte e, senza il modello di illuminazione, verrebbe anche peggio. Il fattore di risoluzione agisce proprio su quell'immagine: ×3 la triplica in densità, senza toccare il testo, che è già nitido per definizione;
• Scena in vettoriale: se serve davvero anche la superficie in poligoni — per ritoccarla in un editor vettoriale o per una stampa molto grande — c'è la casella apposta. Ogni triangolo diventa un tracciato con il suo colore. Il prezzo è dichiarato: il file passa da qualche centinaio di kB a una decina di megabyte, l'ombreggiatura è piatta per faccia (la superficie appare sfaccettata) e quello che il motore 3D disegna con programmi propri — linee spesse, campi di frecce — resta fuori. Per l'uso normale, la casella spenta dà il file migliore;
• Esporta dati (CSV): i punti delle serie visibili;
• Esporta animazione (WebM): video dei frame temporali;
• Esporta / Importa JSON: l'intera configurazione del grafico (serie, colori, assi…) in un file, per riprenderla o passarla ad altri;
• Copia link condivisibile: URL che riproduce il grafico corrente;
• Importa dati (CSV/TSV): apre la finestra di importazione — si sceglie il file (o si incollano i dati), il separatore e la mappatura delle colonne (x, y, z, ed eventuali c, t, gruppo, u/v/w per i vettori); l'anteprima mostra le prime righe. I dataset importati sono di sessione: per renderli permanenti si usa l'export del payload e la console (capitolo 13);
• Le mie immagini (drappeggio): per i profili autorizzati, upload di ortofoto/carte da stendere su una superficie (nella card compare il selettore "Immagine drappeggiata": l'immagine sostituisce la colormap);
• Layer salvati (DB): per i profili autorizzati, salvataggio su database della serie selezionata o dello snapshot intero del grafico, con nome; si ricaricano dalla tendina, si condividono per profilo, si eliminano.

12. Consigli e casi particolari

• Molte serie pesanti? Riduci lo step solo dove serve: il costo cresce col quadrato della densità di campionamento.
• Assi logaritmici: con i tick personalizzati l'asse si estende di una decade oltre i dati; è un margine voluto (il tick in eccesso resta senza etichetta).
• Confrontare due superfici: attiva la scala condivisa (capitolo 2.2) oppure usa Differenza (A − B) (capitolo 8).
• Il grafico non si aggiorna? Quasi tutti i controlli agiscono in tempo reale; per i dataset con metodo di interpolazione, il ricalcolo parte quando si applica il metodo.
• Salvare il lavoro: "Esporta JSON" per un file, "Copia link condivisibile" per un URL, "Layer salvati" per il database (con condivisione per profilo). In più la configurazione viene salvata automaticamente nel browser e ripresa da sola al ritorno sulla pagina (un link condivisibile aperto esplicitamente ha comunque la precedenza).
• Calcoli lunghi: quando lo step è molto piccolo compare il velo "Calcolo in corso…" sopra la vista 3D — la pagina non è bloccata, sta campionando.
• Formati numerici: per notazioni tecniche il modo sprintf è il più flessibile (%.2e, %+.1f…); per i separatori delle migliaia usa il modo locale con it-IT.