Guida rapida a SeExpr

Questa pagina descrive in dettaglio tutte le variabili, le funzioni e gli operatori disponibili in SeExpr. È una versione pesantemente modificata della documentazione ufficiale dell’utente, adattata per l’utilizzo con Krita.

Vedi anche

• Codice sorgente su KDE Invent

• Documentazione API <http://wdas.github.io/SeExpr/doxygen/> di SeExpr di Disney

Vedi anche

• Introduzione a SeExpr

• SeExpr

• Script SeExpr

• «Procedural texture generator (example and wishes)» su Krita Artists

• Articoli di Inigo Quilez

• The Book of Shaders

Variabili

Variabili esterne

Queste variabili sono fornite dalle applicazioni host, in questo caso Krita. Esse sono registrate con la guida di completamento automatico di SeExpr, a cui è possibile accedere da: kbd: Ctrl + Spazio.

$u, $v

Posizione dei pixel in coordinate normalizzate.

$w, $h

Larghezza e altezza dell’immagine in pixel.

Variabili locali

Le variabili locali possono essere definite all’inizio dell’espressione:

$a = noise($P);
$b = noise($a * 1);
pow($a, 0.5) + $b

Le variabili esterne possono anche essere sovrascritte dall’assegnazione locale. Questo può essere utile per scalare la frequenza del rumore, ad esempio:

$P = $P * 10; # aumenta la frequenza del rumore
fbm(vnoise($P) + $P/4)

Puoi anche definire variabili con spazio dei nomi, ad es.:

$A::a = $u * 10;

Strutture di controllo

SeExpr fornisce la ben nota struttura condizionale if:

if ($ u > 0.5) {
    $color = [0, 0, 1];
}
else {
    $color = [1, 0, 0];
}

$color

E l”operatore ternario:

$u = $i < .5 ? 0.0 : 10.0

Puoi nidificare liberamente operatori ternari, ad es.:

$color = $u < .5 ? ($v < 0.5 ? [0, 0, 1] : [1, 0, 0]) : [0, 1, 0];
$color

Puoi ottenere lo stesso risultato anche con le strutture if:

if ($ u > 0.5) {
    if ($v < 0.5) {
        $color = [0, 0, 1];
    }
    else {
        $color = [1, 0, 0];
    }
}
else {
    $color = [1, 0, 0];
}

$color

Operatori (elencati con precedenza decrescente)

[a,b,c]

costruttore di vettori

$P[ n ]

accesso ai componenti vettoriali

Suggerimento

n deve essere 0, 1, o 2, ad es.:

$P[0]

^

esponenziazione

Nota

Uguale alla funzione pow.

!

NOT logico

~

inversione

Suggerimento

~$A

restituisce lo stesso risultato di:

1 - $A

*/ %

moltiplica, dividi, modulo

Nota

%” è uguale alla funzione fmod.

+-

aggiungi, sottrai

<> <= >=

confronto: minore di; maggiore di, minore o uguale a, maggiore o uguale a

Nota

Utilizza solo il primo componente di un vettore.

== !=

uguaglianza, disuguaglianza

&&

AND logico

||

OR logico

?:

operatore if ternario

Suggerimento

Esempio:

$u < .5 ? 0 : 1

->

applica - la funzione a destra della freccia viene applicata all’espressione a sinistra.

Suggerimento

Esempi:

$Cs->contrast(.7) -> clamp(0.2,0.8)
$u->hsi(20,1.2,1,$Cs->gamma(1.2))

Operatori di assegnazione

Oltre alla dichiarazione di assegnazione di base:

$foo = $bar

puoi anche eseguire assegnazioni di operatore come:

$foo += $bar;

che è equivalente a:

$foo = $foo + $bar;

In aggiunta, ci sono:

• +=

• -=

• /=

• %=

• *=

• ^=

Commenti

Puoi aggiungere commenti al tuo script usando il carattere #. SeExpr salterà quindi il resto della riga per scopi di rendering. Tuttavia, non vengono ignorati; i commenti possono ancora essere utilizzati per dichiarare l’intervallo di valori valido delle variabili intere, float e vector. Ciò consente di gestirli utilizzando oggetti che accetteranno l’intervallo specificato.

Suggerimento

$var0 è una variabile intera che va da 0 a 10 inclusi:

$var0 = 0; # 0, 10

$var1 è una variabile in virgola mobile con lo stesso intervallo:

$var1 = 0; # 0.000, 10.000

$var2 è una variabile vettoriale:

$var2 = [0, 0, 0] # 0.000, 10.000

Quest’ultimo è molto utile; SeExpr considera i vettori con intervallo ``[0, 1]` come colori:

# questo è un rosso scuro
$color = [0.5, 0, 0] # 0.000, 1.000

In tutti i casi, se non specificato, l’intervallo degli oggetti associati andrà da 0 a 1.

Per un’espressione su più righe, ogni riga può avere il proprio commento.

Funzioni di registrazione

float printf ( formato stringa, [param0, param1, …] )

Stampa una stringa su stdout formattata come indicato. Parametri di formattazione possibili sono %f per float (accetta il primo componente dell’argomento del vettore) o %v per il vettore.

Suggerimento

Ad esempio, se hai scritto:

$u = printf("test %f %v",[1,2,3],[4,5,6]);

dovresti ottenere nella tua console:

test 1 [4,5,6]

string sprintf ( formato stringa, [double|string, double|string, …] )

Restituisce una stringa formattata dai valori forniti. Vedi man sprintf per i dettagli del formato.

Funzioni di colore, mascheramento e rimappatura

float bias ( float x, float b)

Variazione della gamma dove il parametro di controllo va da 0 a 1 con valori >0,5 che sollevano la curva e valori < 0,5 che abbassano la curva. Definita come pow (x, log(b)/log(0.5)).

float boxstep ( float x, float a )

float gaussstep ( float x, float a, float b )

float linearstep ( float x, float a, float b )

float smoothstep ( float x, float a, float b )

Le funzioni a gradino sono zero per x < a` e uno per x > b (o x > a nel caso di boxstep). Tra a e b, il valore cambia continuamente tra zero e uno. La funzione gausstep utilizza l’estensione curva a «campana» gaussiana standard basata su una curva esponenziale. La funzione smoothstep utilizza una curva cubica. Intuitivamente, gausstep ha una transizione più netta vicino a uno e una transizione più morbida vicino a zero, mentre``smoothstep`` ha una morbidezza media vicina sia all’uno che allo zero.

float clamp ( float x, float lo, float hi )

Vincola x all’intervallo [lo, hi].

float compress ( float x, float lo, float hi )

Comprimi la gamma dinamica da [0, 1] a [lo, hi].

float contrast ( float x, float c )

Regola il contrasto. Per c da 0 a 0,5, il contrasto viene diminuito. Per c > 0,5, il contrasto viene aumentato.

float expand ( float x, float lo, float hi )

Espandi l’intervallo dinamico da [lo, hi] a [0, 1].

float fit ( float x, float a1, float b1, float a2, float b2 )

Rimappatura lineare di [a1..x..b1] a [a2..x..b2]

float gamma ( float x, float g)

pow(x, 1/g)

float invert ( float x )

Inverti il valore. Definito come 1 - x.

color hsi ( color x, float h, float s, float i, float map=1 )

La funzione hsi sposta la tonalità di h (in gradi) e scala la saturazione e l’intensità rispettivamente di s e i. Può essere fornita una mappa che controllerà lo spostamento - lo spostamento completo si verificherà quando la mappa è una e nessuno spostamento avverrà quando la mappa è zero. Lo spostamento sarà ridimensionato per valori compresi tra zero e uno.

color hsltorgb ( color hsl )

color rgbtohsl ( color rgb )

Conversione dello spazio colore da RGB a HSL. HSL è Tonalità, Saturazione, Luminosità (tutto nell’intervallo [0, 1]). Queste funzioni sono state estese anche per supportare valori RGB e HSL al di fuori dell’intervallo [0, 1] in modo ragionevole. Per qualsiasi valore RGB o HSL (ad eccezione dei valori negativi), la conversione è ben definita e reversibile.

color midhsi ( color x, float h, float s, float i, float map, float falloff=1, int interp=0 )

La funzione midhsi è proprio come la funzione hsi tranne per il fatto che la mappa di controllo è centrata attorno al punto medio (valore di 0,5) e può scalare lo spostamento in entrambe le direzioni. A metà, non avviene alcun cambiamento. A 1,0, si verifica lo spostamento completo e con 0,0 si verifica lo spostamento inverso completo. Vengono forniti ulteriori controlli falloff e interp per regolare la mappa utilizzando la funzione remap. I valori predefiniti di falloff e interp non producono la rimappatura.

float mix ( float a, float b, float alpha )

Miscela di a e b secondo alfa. Definito come a*(1-alfa)+b*alfa.

float remap ( float x, float source, float range, float falloff, int interp )

Funzione generale di rimappatura. Quando x si trova all’interno di ±intervallo della sorgente, il risultato è uno. Il risultato scende a zero oltre tale intervallo sulla distanza di decadimento. La forma del decadimento è controllata da interp.

Nota

È possibile utilizzare valori numerici o costanti con nome:

• int linear = 0

• int smooth = 1

• int gaussian = 2

Funzioni di rumore

float cellnoise ( vector v )

float cellnoise1 ( float x )

float cellnoise2 ( float x, float y )

float cellnoise3 ( float x, float y, float z )

color ccellnoise ( vettore v )

cellnoise genera un campo di cubi colorati costanti in base alla posizione intera. È lo stesso della funzione PRMan cellnoise.

Nota

ccellnoise restituisce cellnoise a colori.

float fbm ( vector v, int octaves=6, float lacunarity=2, float gain=0.5 )

color cfbm ( vector v, int octaves=6, float lacunarity=2, float gain=0.5 )

vector vfbm ( vector v, int octaves=6, float lacunarity=2, float gain=0.5 )

float fbm4 ( vector v, float time, int octaves=6, float lacunarity=2, float gain=0.5 )

color cfbm4 ( vector v, float time, int octaves=6, float lacunarity=2, float gain=0.5 )

vector vfbm4 ( vector v, float time, int octaves=6, float lacunarity=2, float gain=0.5 )

fbm (moto browniano frazionario) è una funzione di rumore multi-frequenza. La frequenza di base è la stessa della funzione «noise». Il numero totale di frequenze è controllato da ottave. La lacunarità è la spaziatura tra le frequenze - un valore di 2 significa che ogni ottava è due volte la frequenza precedente. Il guadagno controlla quanto ciascuna frequenza viene scalata rispetto alla frequenza precedente.

Nota

cfbm e cfbm4 restituiscono rumore di colore.

vfbm e vfbm4 restituiscono rumore vettoriale.

float hash ( float seed1, [float seed2, …] )

Come rand, ma senza semi interni. Può essere fornito un numero qualsiasi di semi e il risultato sarà una funzione casuale basata su tutti i semi.

float noise ( vettore v )

float noise ( float x, float y )

float noise ( float x, float y, float z )

float noise ( float x, float y, float z, float w )

color cnoise ( vettore v)

color cnoise4 ( vettore v, float t)

float pnoise ( vettore v, periodo vettore )

float snoise ( vettore v)

float snoise4 ( vettore v, float t)

vector vnoise (vector v )

vector vnoise4 (vector v, float t )

noise è una funzione casuale che miscela uniformemente campioni a posizioni intera. Questa è la funzione di rumore originale di Ken Perlin.

Nota

cnoise e cnoise4 restituiscono rumore di colore.

noise4 restituisce rumore vettoriale con segno.

pnoise restituisce rumore periodico.

snoise e snoise4 restituiscono rumore con segno con intervallo [-1, 1].

vnoise restituisce rumore vettoriale con segno.

float rand ( [float min, float max], [float seed] )

Numero casuale compreso tra [min, max] (o [0, 1] se non specificato). Se un seme è fornito, sarà utilizzato in aggiunta ai semi interni e può essere utilizzato per creare più generatori distinti.

float turbulence ( vector v, int octaves=6, float lacunarity=2, float gain=0.5 )

color cturbulence ( vector v, int octaves=6, float lacunarity=2, float gain=0.5 )

vector vturbulence ( vector v, int octaves=6, float lacunarity=2, float gain=0.5 )

turbulence è una variante di fbm dove viene preso il valore assoluto di ogni termine di rumore. Questo conferisce un aspetto più ondoso.

float voronoi ( vector v, int type=1, float jitter=0.5, float fbmScale=0, int fbmOctaves=4, float fbmLacunarity=2, float fbmGain=0.5)

color cvoronoi ( vector v, int type=1, float jitter=0.5, float fbmScale=0, int fbmOctaves=4, float fbmLacunarity=2, float fbmGain=0.5)

vector pvoronoi ( vector v, float jitter=0.5, float fbmScale=0, int fbmOctaves=4, float fbmLacunarity=2, float fbmGain=0.5)

voronoi è un modello di rumore cellulare. È una variante con jitter di cellnoise. Il parametro tipo descrive diverse varianti della funzione di rumore. Il parametro jitter controlla quanto sia irregolare il pattern (0 è come cellnoise ordinaria). I parametri fbm... possono essere usati per distorcere il campo di rumore. Quando fbmScale è zero (impostazione predefinita), non è presente alcuna distorsione. I restanti parametri sono gli stessi della funzione fbm.

Suggerimento

Tipi di Voronoi da 1 a 5:

Nota

cvoronoi” restituisce un colore casuale per ogni cella e pvoronoi restituisce la posizione del punto del centro della cella.

Funzioni di selezione

float choose ( float index, float choice1, float choice2, […] )

Seleziona una delle scelte fornite in base all’indice (che si presume sia nel file intervallo [0, 1]).

int cycle ( int index, int loRange, int hiRange )

Passa attraverso i valori tra loRange e hiRange in base all’indice fornito. Questa è una funzione mod di scostamento. Il risultato viene calcolato come loRange + valore % (hiRange-loRange+1).

int pick ( float index, int loRange, int hiRange, [ float weights, … ] )

Seleziona i valori in modo casuale tra loRange e hiRange in base all’indice fornito (per cui viene generato automaticamente un hash). I valori saranno distribuiti in base ai pesi forniti. Si assume che i pesi non forniti siano 1.0.

float wchoose ( float index, float choice1, float weight1, float choice2, float weight2, […] )

Seleziona una delle scelte fornite in base all’indice (che si presume sia nell’intervallo [0, 1]). I valori saranno distribuiti in base ai pesi forniti.

Suggerimento

Questo esempio restituisce valori interi compresi tra 1 e 10:

pick(valore, 1, 10)

Questo esempio restituisce i valori 1 e 2 due volte e 2,5 volte più spesso rispetto agli altri valori (3-10):

pick(valore, 1, 10, 2, 2.5)

Questo esempio restituisce 10, 11 e da 13 a 20 (12 viene ignorato a causa del peso zero):

pick(valore, 10, 20, 1, 1, 0)

Costanti matematiche generali e funzioni

float PI

float PI = 3.14159...

float E

float E = 2.71828...

float abs ( float x)

Valore assoluto di x.

float cbrt ( float x )

Radice cubica.

float ceil ( float x )

Intero successivo più alto.

float exp ( float x )

E elevato alla potenza di x.

float floor ( float x )

Intero successivo inferiore.

float fmod ( float x, float y )

Resto di x / y.

Nota

Disponibile anche come operatore %.

float log ( float x )

Logaritmo naturale.

float log10 ( float x )

Logaritmo in base 10.

float max ( float a, float b )

Maggiore di a e b.

float min ( float a, float b )

Minore di a e b.

float pow ( float x, float y )

x alla potenza di y.

Nota

Disponibile anche come operatore ^.

float round ( float x )

Intero più vicino.

float sqrt ( float x )

Radice quadrata.

float trunc ( float x )

Numero intero più vicino verso zero.

Funzioni trigonometriche

float acos ( float x )

Arcocoseno.

float acosd ( float x )

Arcocoseno in gradi.

float acosh ( float x )

Arcocoseno iperbolico.

float asin ( float x )

Arcoseno.

float asind ( float x )

Arcoseno in gradi.

float asinh ( float x )

Arcoseno iperbolico.

float atan ( float x )

Arcotangente.

float atand ( float x )

Arcotangente in gradi.

float atan2 ( float y, float x)

Arcotangente di y/x tra -PI e PI.

float atan2d ( float y, float x )

Arcotangente in gradi di y/x tra -180º e 180º.

float atanh ( float x )

Arcotangente iperbolica.

float cos ( float x )

Coseno.

float cosd ( float x )

Coseno in gradi.

float cosh ( float x )

Coseno iperbolico.

float deg ( float x )

Radianti in gradi.

float hypot ( float x, float y )

Lunghezza del vettore 2D [x, y].

float rad ( float x )

Gradi a radianti.

float sin ( float x )

Seno.

float sind ( float x )

Seno in gradi.

float sinh ( float x )

Seno iperbolico.

float tan ( float x )

Tangente.

float tand ( float x )

Tangente in gradi.

float tanh ( float x )

Tangente iperbolica.

Funzioni vettoriali

float angle ( vector a, vector b )

Angolo tra due vettori (in radianti).

vector cross ( vector a, vector b )

Prodotto vettoriale.

float dist ( vector a, vector b )

Distanza tra due punti.

float dot ( vector a, vector b)

Prodotto scalare.

float length ( vector v )

Lunghezza del vettore.

vector norm ( vector v )

Vettore scalato alla lunghezza unitaria.

vector ortho ( vector a, vector b )

Vettore ortografico a due vettori.

vector rotate ( vector v, vector axis, float angle )

Ruota v attorno all’asse dell”angolo specificato (in radianti).

vector up ( vector v, vector up )

Ruota v in modo tale che l’asse Y punti nella direzione su specificata.

Supporto vettoriale

I vettori (punti, colori o vettori 3D) possono essere mescolati con scalari (valori in virgola mobile semplici). Se uno scalare viene utilizzato in un contesto vettoriale, esso viene replicato nei tre componenti, ad es. 0,5 diventa [0,5, 0,5, 0,5].

Se un vettore viene utilizzato in un contesto scalare, viene utilizzato solo il primo componente. Uno dei vantaggi di questo è che tutte le funzioni a cui sono definite per lavorare con gli scalari si estendono automaticamente ai vettori. Ad esempio, pick, choose, cycle, spline, ecc. funzioneranno perfettamente con i vettori.

Gli operatori aritmetici come + ``, ``*, ecc., e le funzioni scalari vengono applicati per componenti ai vettori. Ad esempio, l’applicazione della funzione gamma a una mappa regola la gamma di tutti e tre i canali di colore.

Funzioni curve

L’interpolazione dei valori dei parametri in un insieme di punti di controllo è regolata dalle seguenti funzioni.

color ccurve ( float param, float pos0, color val0, int interp0, float pos1, color val1, int interp1, […] )

Interpola la scala di colori data dai punti di controllo in param. I punti di controllo sono specificati da triple di parametri pos_i, val_i e interp_i.

Suggerimento

I codici di interpolazione sono:

• 0 - nessuno

• 1 - lineare

• 2 - smussatura

• 3 - spline

• 4 - spline monotona (non oscillante)

float curve ( float param, float pos0, float val0, int interp0, float pos1, float val1, int interp1, […] )

Interpola una rampa 1D definita dai punti di controllo in param. I punti di controllo sono specificati da triple di parametri pos_i, val_i e interp_i.

Suggerimento

I codici di interpolazione sono:

• 0 - nessuno

• 1 - lineare

• 2 - smussatura

• 3 - spline

• 4 - spline monotona (non oscillante)

float spline ( float param, float y1, float y2, float y3, float y4, […] )

Interpola un insieme di valori nel parametro specificato dove y1'', ..., ``yn sono distribuiti uniformemente da [0, 1].

Estensioni personalizzate

Le funzioni personalizzate possono essere scritte in C ++ e caricate come una o più estensioni dinamiche. Vedere Writing Custom Expression Plugins per maggiori dettagli.

Avvertimento

Questa funzionalità non è supportata in Krita.