Referència ràpida de SeExpr

Aquesta pàgina detalla totes les variables, funcions i operadors disponibles al SeExpr. És una versió molt editada de la documentació oficial per a l'usuari, adaptada per al seu ús amb el Krita.

Vegeu també

Vegeu també

Variables

Variables externes

Aquestes variables són proporcionades per les aplicacions amfitrió, en aquest cas el Krita. Estan registrades amb l'ajuda de la compleció automàtica de SeExpr, a la qual es pot accedir mitjançant la drecera Ctrl + Espai.

$u, $v

Posició dels píxels en coordenades normalitzades.

$w, $h

Amplada i alçada de la imatge en píxels.

Variables locals

Les variables locals es poden definir al començament de l'expressió:

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

Les variables externes també es poden sobreescriure mitjançant una assignació local. Això podria ser útil per a escalar la freqüència del soroll, per exemple:

$P = $P * 10; # augmenta la freqüència del soroll
fbm(vnoise($P) + $P/4)

També podeu definir variables d'espai de noms, p. ex.:

$A::a = $u * 10;

Estructures de control

El SeExpr proporciona la coneguda estructura condicional if:

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

$color

I l'operador ternari:

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

Podeu niuar lliurement els operadors ternaris, p. ex:

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

També podeu aconseguir el mateix amb les estructures if:

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

$color

Operadors (llistats en precedència decreixent)

[a,b,c]

Constructor de vectors.

$P[ n ]

Accés a components vectorials.

Suggeriment

n haurà de ser 0, 1 o 2, p. ex.:

$P[0]
^

Potenciació.

Nota

Igual que la funció pow.

!

«NOT» lògic.

~

Inversió.

Suggeriment

~$A

dona el mateix resultat que:

1 - $A
*/ %

Multiplica, divideix, mòdul.

Nota

% és el mateix que la funció fmod.

+-

Afegeix, sostreu.

<> <= >=

Comparació: menor que, major que, menor o igual que, major o igual que.

Nota

Només utilitza el primer component d'un vector.

== !=

Igualtat, desigualtat.

&&

«AND» lògic.

||

«OR» lògic.

?:

Operador if ternari.

Suggeriment

Exemple:

$u < .5 ? 0 : 1
->

Aplica: la funció que hi ha a la dreta de la fletxa s'aplica a l'expressió de l'esquerra.

Suggeriment

Exemples:

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

Assignació d'operadors

A més de l'assignació bàsica d'un operador:

$foo = $bar

També podeu realitzar assignacions d'operador com:

$foo += $bar;

El qual és equivalent a:

$foo = $foo + $bar;

A més, hi ha:

  • +=

  • -=

  • /=

  • %=

  • *=

  • ^=

Comentaris

Podeu afegir comentaris a l'script utilitzant el caràcter #. El SeExpr després saltarà la resta de la línia per a fins de renderitzat. No obstant això, no s'ignoraran. Els comentaris encara es poden utilitzar per a declarar l'interval vàlid de valors per a variables amb enters, coma flotant i vectors. Això permet la gestió utilitzant ginys que acceptaran l'interval especificat.

Suggeriment

$var0 és una variable d'enter que oscil·la entre el 0 i el 10 inclusivament:

$var0 = 0; # 0, 10

$var1 és una variable de coma flotant amb el mateix interval:

$var1 = 0; # 0.000, 10.000

$var2 és una variable vectorial:

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

Aquesta última és molt útil. El SeExpr considera els vectors amb un interval de [0, 1] com a colors:

# aquest és un vermell fosc
$color = [0.5, 0, 0] # 0.000, 1.000

En tots els casos, si no s'especifica, l'interval en els ginys associats anirà del 0 fins a l'1.

Per a una expressió de múltiples línies, cada línia pot tenir el seu propi comentari.

Funcions de registre

float printf ( string format, [param0, param1, ...] )

Imprimeix una cadena a la sortida estàndard (stdout) amb el format indicat. El format possible dels paràmetres és %f per a «float» (pren el primer component de l'argument de vector) o %v per a «vector».

Suggeriment

Per exemple, si escriviu:

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

a la consola obtindreu:

test 1 [4,5,6]
string sprintf ( string format, [double|string, double|string, ...] )

Retorna una cadena amb format a partir dels valors indicats. Per a obtenir detalls sobre el format, vegeu man sprintf.

Funcions de Color, Emmascarament i Remapatge

float bias ( float x, float b)

Variació de gamma on el paràmetre de control va des del 0 fins a l'1, amb els valors > 0.5 estirant la corba cap amunt i els valors < 0.5 estirant la corba cap avall. Definit com a 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 )

Les funcions de pas són zero per a x < a i u per a x > b (o x > a en el cas de «boxstep»). Entre a i b, el valor canvia contínuament entre zero i u. La funció gausstep utilitza la corba estàndard de «campana» gaussiana, la qual es basa en una corba exponencial. La funció smoothstep utilitza una corba cúbica. De manera intuïtiva, gausstep té una transició definida quan es troba més a prop d'u i una transició més suau quan es troba a prop de zero, mentre que smoothstep té una suavitat mitjana quan es troba a prop d'u i zero.

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

Restringeix x a l'interval [lo,hi].

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

Comprimeix l'interval dinàmic des de [0, 1] fins a [lo, hi].

float contrast ( float x, float c )

Ajusta el contrast. Per a c des de 0 fins a 0.5, es redueix el contrast. Per a c > 0.5, el contrast augmenta.

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

Expandeix l'interval dinàmic des de [lo, hi] fins a [0, 1].

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

Reassignació lineal de [a1..x..b1] a [a2..x..b2].

float gamma ( float x, float g)

pow(x, 1/g)

float invert ( float x )

Inverteix el valor. Definit com a 1 - x.

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

La funció hsi desplaça el to per h (en graus) i escala la saturació i la intensitat per s i i respectivament. Es pot proporcionar un mapa que controlarà el desplaçament: tot el desplaçament succeirà quan el mapa sigui u, i no succeirà cap canvi quan el mapa sigui zero. El desplaçament s'escalarà a menys per als valors entre zero i u.

color hsltorgb ( color hsl )
color rgbtohsl ( color rgb )

Conversió des de l'espai de color RGB a HSL. El HSL és To, Saturació i Claredat (tots en l'interval [0, 1]). Aquestes funcions també s'han ampliat per a admetre valors RGB i HSL fora de l'interval [0, 1] de manera raonable. Per a qualsevol valor RGB o HSL (excepte per als valors negatius), la conversió estarà ben definida i serà reversible.

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

La funció midhsi és com la funció hsi, excepte que el mapa de control està centrat al voltant del punt mitjà (valor de 0.5) i pot escalar el desplaçament en ambdues direccions. En el punt mitjà, no succeeix cap canvi. A l'1.0, succeeix tot el canvi, i al 0.0, succeeix tot el desplaçament invers. Es proporcionen controls addicionals falloff i interp per a ajustar el mapa utilitzant la funció remap. Els valors predeterminats de falloff i interp no provoquen cap reassignació.

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

Barreja d'«a» i «b» segons alfa. Definit com a a*(1-alpha) +b*alpha.

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

Funció de reassignació general. Quan x es troba a dins de ± range de la font, el resultat és u. El resultat caurà a zero més enllà d'aquest interval sobre la distància de falloff. La forma «fallof» està controlada per interp.

Nota

Es poden utilitzar valors numèrics o constants amb nom:

  • int linear = 0

  • int smooth = 1

  • int gaussian = 2

Funcions del soroll

float cellnoise ( vector v )
float cellnoise1 ( float x )
float cellnoise2 ( float x, float y )
float cellnoise3 ( float x, float y, float z )
color ccellnoise ( vector v )

cellnoise genera un camp de cubs amb colors constants en funció de la ubicació del nombre enter. És el mateix que la funció «cellnoise» de PRMan.

Nota

ccellnoise emet el soroll de la cel·la.

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 (moviment brownià fraccional) és una funció de soroll amb múltiples freqüències. La freqüència base és la mateixa que la funció noise (soroll). El nombre total de freqüències està controlat per octaves (octaves). La lacunarity (lacunaritat) és l'espai entre les freqüències: un valor de 2 vol dir que cada vuitena és el doble de la freqüència anterior. El gain (guany) controla quant s'escalarà cada freqüència en relació amb la freqüència anterior.

Nota

cfbm i cfbm4 emeten el soroll del color.

vfbm i vfbm4 emeten el soroll del vector.

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

Com rand, però sense llavors internes. Es pot indicar qualsevol nombre de llavors i el resultat serà una funció aleatòria basada en totes les llavors.

float noise ( vector 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 ( vector v)
color cnoise4 ( vector v, float t)
float pnoise ( vector v, vector period )
float snoise ( vector v)
float snoise4 ( vector v, float t)
vector vnoise (vector v )
vector vnoise4 (vector v, float t )

noise (soroll) és una funció aleatòria que barreja suaument entre les mostres en ubicacions d'enters. Aquesta és la funció de soroll original d'en Ken Perlin.

Nota

cnoise i cnoise4 emeten el soroll del color.

noise4 emet el soroll vectorial signat.

pnoise emet el soroll periòdic.

snoise i snoise4 emeten soroll signat amb l'interval [-1, 1].

vnoise emet el soroll vectorial signat.

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

Nombre aleatori entre [min, max] (o [0, 1] si no s'especifica). Si se subministra una llavor, s'utilitzarà a més de les llavors internes i es podrà utilitzar per a crear múltiples generadors diferents.

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 és una variant de fbm on es pren el valor absolut de cada terme de soroll. Això li dona una aparença més ondulada.

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 és un patró de soroll cel·lular. És una variant nerviosa de cellnoise. El paràmetre de tipus descriu diferents variants de la funció de soroll. El paràmetre jitter controla com és d'irregular el patró (0 és com un soroll de cel·la ordinari). Els paràmetres de fbm... es poden utilitzar per a distorsionar el camp de soroll. Quan fbmScale és zero (el valor predeterminat), no hi haurà distorsió. Els paràmetres restants són els mateixos que per a la funció fbm.

Suggeriment

Tipus de Voronoi, des de l'1 fins al 5:

image0 image1 image2 image3 image4

Nota

cvoronoi retorna un color aleatori per a cada cel·la i pvoronoi retorna la ubicació del punt al centre de la cel·la.

Funcions de selecció

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

Tria una de les opcions proporcionades segons l'índex (se suposa que està en l'interval [0, 1]).

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

Recorre els valors entre «loRange» i «hiRange» segons l'índex proporcionat. Aquesta és una funció mod de compensació. El resultat es calcula com a loRange + value % (hiRange-loRange+1).

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

Tria aleatòriament els valors entre «loRange» i «hiRange» segons l'índex proporcionat (el qual automàticament té una suma). Els valors es distribuiran segons els pesos subministrats. S'assumirà que qualsevol pes no subministrat serà 1.0.

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

Tria una de les opcions proporcionades segons l'índex (se suposa que està en l'interval [0, 1]). Els valors es distribuiran segons els pesos subministrats.

Suggeriment

Aquest exemple retorna valors enters entre l'1 i el 10:

pick(value, 1, 10)

Aquest exemple retorna els valors 1 i 2, dues vegades i 2,5 vegades més sovint, respectivament, en comparació amb els altres valors (3-10):

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

Aquest exemple retorna 10, 11 i 13 a través de 20 (s'omet el 12 a causa del pes zero):

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

Constants i funcions matemàtiques generals

float PI
float PI = 3.14159...
float E
float E = 2.71828...
float abs ( float x)

Valor absolut de x.

float cbrt ( float x )

Arrel cúbica.

float ceil ( float x )

Següent enter més gran.

float exp ( float x )

E elevat a la potència de x.

float floor ( float x )

Següent enter més petit.

float fmod ( float x, float y )

La resta de x / y.

Nota

També disponible com a l'operador %.

float log ( float x )

Logaritme natural.

float log10 ( float x )

Logaritme en base 10.

float max ( float a, float b )

Major que a i b.

float min ( float a, float b )

Menor que a i b.

float pow ( float x, float y )

x a la potència de y.

Nota

També disponible com a l'operador ^.

float round ( float x )

Enter més proper.

float sqrt ( float x )

Arrel quadrada.

float trunc ( float x )

Enter més proper a zero.

Funcions trigonomètriques

float acos ( float x )

Arccosinus.

float acosd ( float x )

Arccosinus en graus.

float acosh ( float x )

Arccosinus hiperbòlic.

float asin ( float x )

Arcsinus.

float asind ( float x )

Arcsinus en graus.

float asinh ( float x )

Arcsinus hiperbòlic.

float atan ( float x )

Arctangent.

float atand ( float x )

Arctangent en graus.

float atan2 ( float y, float x)

Arctangent de y/x entre -PI i PI.

float atan2d ( float y, float x )

Arctangent en graus de y/x entre -180º i 180º.

float atanh ( float x )

Arctangent hiperbòlic.

float cos ( float x )

Cosinus.

float cosd ( float x )

Cosinus en graus.

float cosh ( float x )

Cosinus hiperbòlic.

float deg ( float x )

Radians a graus.

float hypot ( float x, float y )

Longitud del vector en 2D [x, y].

float rad ( float x )

Graus a radians.

float sin ( float x )

Sinus.

float sind ( float x )

Sinus en graus.

float sinh ( float x )

Sinus hiperbòlic.

float tan ( float x )

Tangent.

float tand ( float x )

Tangent en graus.

float tanh ( float x )

Tangent hiperbòlica.

Funcions vectorials

float angle ( vector a, vector b )

Angle entre dos vectors (en radians).

vector cross ( vector a, vector b )

Producte vectorial.

float dist ( vector a, vector b )

Distància entre dos punts.

float dot ( vector a, vector b)

Producte d'un punt vectorial.

float length ( vector v )

Longitud del vector.

vector norm ( vector v )

Vector escalat a una unitat de longitud.

vector ortho ( vector a, vector b )

Vector ortogràfic a dos vectors.

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

Gira v al voltant de l'eix en un angle indicat (en radians).

vector up ( vector v, vector up )

Gira v de manera que l'eix Y apunti en la direcció amunt indicada.

Implementació dels vectors

Els vectors (punts, colors o vectors en 3D) poden entremesclar amb escalars (valors senzills de coma flotant). Si s'utilitza un escalar en un context vectorial, es replicarà en els tres components, p. ex., 0.5 esdevindrà [0.5, 0.5, 0.5].

Si s'utilitza un vector en un context escalar, només s'utilitzarà el primer component. Un dels beneficis d'això és que totes les funcions que estan definides per a treballar amb escalars, s'estendran automàticament als vectors. Per exemple, pick, choose, cycle, spline, etc., funcionaran bé amb els vectors.

Els operadors aritmètics com +, *, etc., i les funcions escalars s'apliquen als vectors per component. Per exemple, aplicar la funció gamma a un mapa, ajustarà la gamma de tots tres canals de color.

Funcions de corba

La interpolació dels valors de paràmetre a un conjunt de punts de control es regeix per les funcions següents.

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

Interpola la rampa de color indicada pels punts de control en el param. Els punts de control s'especifiquen mitjançant triples dels paràmetres pos_i, val_i i interp_i.

Suggeriment

Els codis de la interpolació són:

  • 0 - cap

  • 1 - lineal

  • 2 - suavitzat

  • 3 - spline

  • 4 - spline monòton (no oscil·lant)

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

Interpola la rampa en 1D definida pels punts de control en el param. Els punts de control s'especifiquen mitjançant triples dels paràmetres pos_i, val_i i interp_i.

Suggeriment

Els codis de la interpolació són:

  • 0 - cap

  • 1 - lineal

  • 2 - suavitzat

  • 3 - spline

  • 4 - spline monòton (no oscil·lant)

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

Interpola un conjunt de valors al paràmetre especificat on y1, «...», yn són distribuïts homogèniament des de [0, 1].

Connectors personalitzats

Les funcions personalitzades es poden escriure en C++ i carregar-se com a un o més connectors dinàmics. Per a més detalls, vegeu Writing Custom Expression Plugins.

Avís

Aquesta funcionalitat no està admesa en el Krita.