PortLab

Funzioni e serie dati

Le serie di func3d nascono da due registri JavaScript: SERIES_FUNCS (funzioni analitiche, file js/local/func3d/series-funcs.js) e SERIES_DATA (dataset numerici, file js/local/func3d/series-data.js). Un modulo ponte (series-bridge.js) registra ogni dataset come "funzione" campionabile tramite un metodo di interpolazione, così superfici analitiche e superfici da dati condividono la stessa pipeline di disegno.

Funzioni analitiche implementate

Le superfici chiuse (z a due valori: la pagina disegna automaticamente i rami superiore e inferiore):

Ellissoide e toroide stavano in questo elenco e adesso sono parametrici (qui sotto). Cucire due rami z(x,y) lungo l'equatore lascia una fessura dove la derivata diverge: alla giunzione i triangoli dei due rami non combaciano e la superficie appare lacerata. In forma parametrica il problema non esiste, perché la maglia è una sola.

Le superfici parametriche (u,v) → (x,y,z): oggetti non esprimibili come z(x,y), disegnati in proporzioni reali con scala uniforme; il colore si può basare sulla quota z oppure sui parametri u/v (select Base colore nella card):

Una voce parametrica dichiara parametric: true, i range dei parametri nei defaults (xMin/xMax = u, yMin/yMax = v), il numero di campioni nU/nV e una build(params) che restituisce (u, v) => [x, y, z]. Per questi oggetti non esistono isolinee, sezione 2D e zScale (non c'è una z(x,y)); l'export CSV fornisce i punti 3D della griglia.

Le curve parametriche t → (x,y,z): una curva non è una superficie sottile, può passare più volte sopra lo stesso punto del piano, e questo un campo di quota non lo sa fare. Il colore segue il parametro t, quindi si legge anche il verso di percorrenza; lo spessore è in pixel reali (fat lines) e i punti non finiti spezzano la linea invece di chiuderla con un segmento inventato:

Nella card della serie i campi diventano t iniziale, t finale, Campioni e Spessore linea: modo superficie/wireframe, zScale, isolinee, sezione e classi non compaiono, perché su una curva non vogliono dire nulla. Se in scena non c'è nessuna superficie, i tick degli assi seguono gli estremi della curva.

Questi comandi agiscono in posto: muovere un parametro (il raggio dell'elica, il ρ di Lorenz) ricampiona la curva dentro il gruppo esistente, con la stessa normalizzazione — durante il gesto la scala non balla, e trascinare lo slider diventa un'animazione fluida. Un ricostruire completo (qualsiasi altro comando) rinormalizza sui dati nuovi.

Il piano immagine non è una funzione: è un rettangolo texturizzato su uno dei tre piani coordinati (xy, xz, yz), spostabile lungo la propria normale e ridimensionabile. Serve a mettere una foto, una mappa, una scansione o un fotogramma accanto ai dati — non sopra, come fa il drappeggio. La posizione è espressa, a scelta, in frazioni del riquadro degli assi (−1…1, utile per uno sfondo) oppure in coordinate dati: un rettangolo x0…x1, y0…y1 alla quota z, nelle unità della prima superficie a griglia in scena — il caso dell'ortofoto sul DEM, dove l'immagine deve stare dove stanno i metri. In coordinate dati il rettangolo può non essere quadrato e viene piazzato a fine costruzione, quando la mappatura della superficie di riferimento esiste; senza superficie di riferimento le coordinate si leggono come unità del riquadro. Le immagini disponibili sono quelle del registro (le stesse del drappeggio, vedi sotto).

Dataset di esempio

Aggiungere una funzione analitica (su file)

Una voce di SERIES_FUNCS dichiara etichetta, parametri (con default e limiti per la UI) e la fabbrica build(params) che restituisce la funzione campionabile:

nome_funzione: {
  label: 'La mia funzione',
  params: [
    { name: 'k', label: 'k', type: 'number', step: 0.1, min: 0, max: 10, default: 1.0 }
  ],
  defaults: { xMin: -8, xMax: 8, yMin: -8, yMax: 8, step: 0.3, zScale: 1.0 },
  build: (p) => (x, y) => Math.sin(p.k * x) * Math.cos(p.k * y)
}

Per una superficie chiusa si aggiunge closed: true e la build riceve in params._branch il ramo (+1 superiore, −1 inferiore).

Aggiungere un dataset (su file)

Una voce di SERIES_DATA porta i dati e il metodo con cui campionarli. Punti sparsi in data (righe [x, y, z]) oppure griglie/frame in values:

mio_dataset: {
  label: 'Il mio dataset',
  defaults: {
    xMin: -3, xMax: 3, yMin: -3, yMax: 3, step: 0.15, zScale: 1.0,
    mode: 'surface', colormap: { mode: 'preset', name: 'viridis' }
  },
  method: { name: 'idw', params: { power: 2 } },   // nearest | idw | bilinear | bicubic | lanczos | natural | rbf | rst | bspline | krige | points
  data: [
    [-2, -2, 1.0], [-2, 0, 0.3], [0, 0, 1.0], [2, 2, 0.1]
  ],
  enabled: false,   // true = compare tra le serie all'apertura
  onLoad: false     // true = viene anche plottato subito
}

Varianti:

• griglia regolare: values = matrice di z + estremi del dominio (metodo bilinear);
• serie temporale: values = array di frame (matrici per le griglie, liste di punti per le nubi) con passo temporale nei defaults;
• nube di punti: kind: 'cloud', righe [x, y, z, c] o [x, y, z, c1, c2] (c = colore, c2 = dimensione), con bounds e range c fissi dichiarati nel dataset;
• campo vettoriale: kind: 'vector', righe [x, y, z, u, v, w].

Aggiungere una curva parametrica o un piano immagine (su file)

Una curva dichiara isCurve: true, l'intervallo del parametro nei defaults (xMin/xMax = t), il numero di campioni nU e una build(params) che restituisce (t) => [x, y, z]:

elica: {
  label: 'Elica cilindrica',
  isCurve: true,
  nU: 800,
  params: [
    { name: 'R', label: 'R (raggio)', type: 'number', step: 0.1, min: 0.1, max: 20, default: 1.0 },
    { name: 'c', label: 'c (passo/2π)', type: 'number', step: 0.05, min: -5, max: 5, default: 0.25 }
  ],
  defaults: { xMin: 0, xMax: 8 * Math.PI, wireWidth: 3, colormap: { mode: 'preset', name: 'turbo' } },
  build: (p) => (t) => [p.R * Math.cos(t), p.R * Math.sin(t), p.c * t]
}

Se la curva non ha forma chiusa (una traiettoria integrata, per esempio) si integra una volta sola dentro build e la funzione restituita legge il risultato per interpolazione: rifare l'integrazione a ogni campione costerebbe O(n²) e darebbe la stessa curva. La traiettoria di Lorenz è scritta così.

Un piano immagine dichiara isImagePlane: true e i tre parametri piano (xy|xz|yz), posizione e copertura; l'immagine si scegle nella card fra quelle del registro. La build non viene usata (resta un segnaposto).

Le colonne in più (dimensioni extra)

Un dato di ricerca ha di solito più di tre colonne: x, y, quota, e poi la concentrazione, la data del rilievo, l'errore di misura, il numero di campione. Le colonne non assegnate a un ruolo nell'import non vengono più buttate: restano accanto ai dati, allineate riga per riga, e compaiono nella select Colora per della card.

// come si presentano nel dataset (import CSV o payload sul database)
{
  id: 'imp_1', label: 'campagna 2026',
  data: [ [x, y, z], ... ],                       // geometria: la quota
  extra: {
    names:  ['concentrazione', 'errore'],
    values: [ [12.4, 0.3], ... ]                  // una riga per punto, nello stesso ordine
  }
}

Scegliendo una di queste grandezze la superficie resta quella della quota e il colore racconta l'altra cosa. Il campo viene interpolato sulla stessa griglia e con lo stesso metodo (vedi Interpolazione): se colore e forma venissero da griglie diverse non parlerebbero degli stessi punti. Dove il campo non è definito il vertice resta grigio, che è diverso dal prendere un colore della scala — quello direbbe un valore che non c'è.

Immagini utente e layer salvati (profilo graph_editor)

Gli utenti col profilo graph_editor (o admin) trovano nel pannello Importa/Esporta due blocchi in più: Le mie immagini — upload personale di immagini da drappeggio (ridimensionate lato client, salvate fuori dal docroot in upload/graph/<utente>/ con quota per utente; nel select delle card compaiono accanto a quelle di sistema) — e Layer salvati — salvataggio su DB della serie selezionata (ricombinabile in altri grafici) o dello snapshot intero del grafico, con nome.

Immagini e layer nascono privati. Accanto a ogni elemento proprio c'è il controllo di condivisione, con la stessa semantica del resto della piattaforma: interruttore spento = privato; acceso senza profili = pubblico; acceso con profili scelti = visibile solo a quelli. Gli elementi condivisi da altri compaiono negli elenchi con l'etichetta condiviso e sono in sola lettura. Le tabelle di gestione dei grafici vivono nello schema graph del DB boot.

L'amministratore fa eccezione: vede tutti i contenuti di tutti gli utenti, compresi quelli privati (identificati dal nome del proprietario), e li può rinominare, ricondividere, sovrascrivere ed eliminare — dalla pagina stessa oppure, con la vista d'insieme di tutti gli utenti, dalla console gest → database → Dati func3d.

Importare da CSV (runtime)

Il pannello Importa/Esporta di func3d costruisce dataset temporanei a partire da CSV/TSV o dagli appunti, con mappatura guidata delle colonne (x, y, z, c, c2, t, gruppo, u, v, w). Sono dataset di sessione: per renderli permanenti si esporta il payload e lo si salva come dataset amministrato dalla console.

Keywords: funzioni, serie dati, dataset, registro, payload, grafici 3D