Короткий довідник з SeExpr

На цій сторінці наведено подробиці щодо усіх доступних змінних, функцій та операторів у SeExpr. Це значно перероблена версія офіційної документації для користувачів, яку адаптовано до використання у Krita.

Дивись також

• Із початковим кодом можна ознайомитися на KDE Invent

• Документація з програмного інтерфейсу SeExpr від Disney

Дивись також

• Вступ до SeExpr

• SeExpr

• Скрипти SeExpr

• «Процедурний генератор текстур (приклад і побажання)» на Krita Artists

• Статті Іньїго Куїлеса

• Книга шейдерів

Змінні

Зовнішні змінні

Ці змінні надаються основними програмами, у нашому випадку — Krita. Їх пов’язано із можливістю автоматичного доповнення коду SeExpr, доступ до якої можна отримати за допомогою комбінації клавіш Ctrl+Пробіл.

$u, $v

Позиція пікселя у нормалізованих координатах.

$w, $h

Ширина і висота зображення у пікселях.

Локальні змінні

Локальні змінні можна визначити на початку виразу:

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

Зовнішні змінні можна також перевизначати локальними інструкціями. Це може бути корисним, наприклад, для масштабування частоти шуму.

$P = $P * 10; # збільшити частоту шуму
fbm(vnoise($P) + $P/4)

Ви також можете визначати змінні із прив’язкою до простору назв. Приклад:

$A::a = $u * 10;

Структури керування

У SeExpr передбачено добре відому конструкції умови if:

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

$color

І тернарний оператор:

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

Передбачено можливість довільного вкладання тернарних операторів. Приклад:

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

Того самого результату можна досягти за допомогою конструкцій if:

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

$color

Оператори (список упорядковано за зменшенням пріоритетності)

[a,b,c]

конструктор вектора

$P[ n ]

доступ до компонента вектора

Підказка

n має бути 0, 1 або 2, приклад:

$P[0]

^

піднесення до степеня

Примітка

Те саме, що і функція pow.

!

логічне «НІ»

~

інверсія

Підказка

~$A

дає той самий результат, що і таке:

1 - $A

*/ %

множення, ділення, ділення за модулем

Примітка

% є тим самим, що і функція fmod.

+-

додавання, віднімання

<> <= >=

порівняння: менше, більше, менше або дорівнює, більше або дорівнює

Примітка

Використовує лише перший компонент вектора.

== !=

рівність, нерівність

&&

логічне «І»

||

логічне «АБО»

?:

тернарний оператор if

Підказка

Приклад:

$u < .5 ? 0 : 1

->

застосувати — функцію праворуч від стрілки буде застосовано до виразу ліворуч від неї.

Підказка

Приклади:

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

Оператори надання значення

Окрім базової інструкції надання значення:

$foo = $bar

ви також можете виконувати операторні надання значення ось так:

$foo += $bar;

що еквівалентне до такого:

$foo = $foo + $bar;

Додатково передбачено:

• +=

• -=

• /=

• %=

• *=

• ^=

Коментарі

Ви можете додавати коментарі до ваших скриптів за допомогою символу #. SeExpr просто пропустить решту рядка після цього символу для обробки. Втім, цю решту рядка не буде проігноровано — коментарями все одно можна скористатися для оголошення чинного діапазону значень цілочисельних змінних, змінних із рухомою крапкою та векторних змінних. Це надає вам змогу керувати змінними за допомогою віджетів, які показуватимуть відповідний діапазон.

Підказка

$var0 є цілочисельною змінною у діапазоні від 0 до 10 включно:

$var0 = 0; # 0, 10

$var1 є змінною із рухомою крапкою і тим сами діапазоном:

$var1 = 0; # 0.000, 10.000

$var2 є векторною змінною:

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

Останній приклад є дуже корисним; у SeExpr вектори із діапазоном [0, 1] вважаються кольорами:

# це темний червоний
$color = [0.5, 0, 0] # 0.000, 1.000

В усіх випадках, якщо не вказано, діапазон у пов’язаному віджеті вважатиметься таким, що починається з 0 і завершується 1.

У багаторядковому виразі кожен рядок може мати власний коментар.

Функції журналювання

float printf ( string формат, [параметр0, параметр1, …] )

Виводить рядок до стандартного виведення у вказаному форматуванні. Можливими параметрами форматування є %f для чисел з рухомою крапкою (приймає перший компонент векторного аргументу) або %v для векторів.

Підказка

Наприклад, якщо ви напишете таке:

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

ви отримаєте таке у вашій консолі:

test 1 [4,5,6]

string sprintf ( string формат, [double|string, double|string, …] )

Повертає рядок, форматований з вказаних значень. Див. man sprintf, щоб дізнатися більше про форматування.

Функції, пов’язані із кольорами, маскуванням та перетвореннями

float bias ( float x, float b)

Варіація гамми, де параметр керування має значення від 0 до 1 зі значеннями > 0.5, які піднімають криву, і значеннями < 0.5, які опускають криву. Визначається як 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 )

Сходинкові функції дорівнюють нулеві для x < a і одиниці для x > b (або x > a у випадку миттєвого переходу). Між a і b значення функції змінюється неперервно між нулем і одиницею. У функції gausstep використано стандартну гаусову дзвоноподібну криву, яку засновано на експоненті. У функції smoothstep використано кубічну криву. Інтуїтивно зрозуміло, що gausstep має різкіший перехід в околі одиничного значення функції і плавніший перехід поряд із нульовим значенням, а smoothstep має посередню плавність в околі як одиничного, так і нульового значень.

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

Обмежити x до діапазону [lo, hi].

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

Стиснути динамічний діапазон з [0, 1] до [lo, hi].

float contrast ( float x, float c )

Скоригувати контрастність. Для c у діапазоні від 0 до 0.5 контрастність зменшуватиметься. Для c > 0.5 контрастність збільшуватиметься.

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

Розширити динамічний діапазон з [lo, hi] до [0, 1].

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

Лінійне відображення [a1..x..b1] на [a2..x..b2]

float gamma ( float x, float g)

pow(x, 1/g)

float invert ( float x )

Інвертувати значення. Інверсія визначається як 1 - x.

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

Функція hsi зсуває відтінок на h (у градусах) і масштабує насиченість та інтенсивність на s і i, відповідно. Функції може бути передано значення map, яке контролюватиме зсув — повний зсув відбуватиметься, якщо map дорівнює одиниці. Якщо ж значенням map буде нуль, зсув не відбуватиметься. Зсув буде масштабовано до значень між нулем та одиницею.

color hsltorgb ( color hsl )

color rgbtohsl ( color rgb )

Перетворення з простору кольорів RGB до простору кольорів HSL. Колір у HSL визначається значеннями відтінку (Hue), насиченості (Saturation), освітленості (Lightness) (усі в діапазоні [0, 1]). Ці функції також розширено для підтримки значень RGB і HSL поза діапазоном [0, 1] у природний спосіб. Для будь-якого значення RGB або HSL (окрім від’ємних значень) перетворення є коректним і оборотним.

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

Функція midhsi є подібною до функції hsi, але керівне відображення (map) центровано за середньою точкою (значенням 0.5) і може масштабувати зсув у обох напрямках. У середній точці зсув не відбувається. У 1.0 відбувається повний зсув, а у 0.0 відбувається повний обернений зсув. Передбачено додаткові параметри керування falloff і interp для коригування відображення за допомогою функції remap. За типових значень falloff і interp повторне відображення не відбувається.

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

Злити a і b відповідно до вказаного значення прозорості, alpha. Перетворення визначається як a*(1-alpha) +b*alpha.

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

Загальна функція повторного відображення. Якщо x перебуває у діапазоні джерела ± range, результатом буде одиниця. Результат спадає до нуля за межами діапазону на відстані falloff. Форма спадання контролюється параметром interp.

Примітка

Можна використовувати числові значення або іменовані сталі:

• int linear = 0

• int smooth = 1

• int gaussian = 2

Функції, які пов’язано із шумом

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 створює поле кубів розфарбованих сталим кольором на основі цілочисельного розташування вершин. Ця функція збігається із функцією cellnoise PRMan.

Примітка

ccellnoise виводить шумність у комірці кольору.

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 (Fractal Brownian Motion або фрактальний броунівський рух) є багаточастотною функцію шуму. Базова частота збігається із частотою функції noise. Загальна кількість частот керується значенням octaves. Значення lacunarity є інтервалом між частотами — значення 2 означає, що у кожній наступній октаві частота подвоюється. Значення gain керує тим, наскільки буде масштабовано кожну частоту відносно попередньої частоти.

Примітка

cfbm і cfbm4 виводять шумність кольору.

vfbm і vfbm4 виводять шумність вектора

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

Подібна до rand, але без внутрішніх базових значень псевдовипадковості. Можна надавати довільну кількість базових значень (seed). Результатом буде випадкова функція на основі усіх базових значень.

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 є функцією, яка повертає псевдовипадкові значення, які плавно переходять між значеннями вибірки у цілих точках. Це реалізація оригінальної функції шуму Кена Перліна.

Примітка

cnoise і cnoise4 виводять шумність кольору.

noise4 виводить шумність вектора зі знаком.

pnoise виводить періодичний шум.

snoise і snoise4 виводять шумність зі знаком у діапазоні [-1, 1].

vnoise виводить шумність вектора зі знаком.

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

Випадкове число у проміжку [min, max] (або [0, 1], якщо проміжок не вказано). Якщо вказано базове значення (seed), його буде використано на додачу до вбудованих базових значень. Цим значенням можна скористатися для створення декількох різних генераторів.

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 є варіантом fbm, де кожен компонент шуму береться за модулем. У такий спосіб можна отримати хвилястіший вигляд.

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 є комірковим шумовим візерунком. Це варіант cellnoise із тремтінням. Параметр type описує різні варіанти функції шумності. Параметр jitter керує тим, наскільки нерегулярним є візерунок (0 — звичайний cellnoise). Параметрами fbm... можна скористатися для викривлення поля шуму. Якщо fbmScale дорівнює нулю (типове значення), викривлення не відбувається. Решта параметрів збігається із параметрами функції fbm.

Підказка

Типи Вороного від 1 до 5:

Примітка

cvoronoi повертає випадковий колір для кожної з комірок, а pvoronoi повертає розташування центральної точки комірки.

Функції вибору

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

Вибирає один із наданих варіантів на основі індексу (припускається значення у діапазоні [0, 1]).

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

Циклічно переходить значеннями між loRange і hiRange на основі наданого індексу (index). Це зсунута версія функції mod. Результат обчислюється за формулою loRange + value % (hiRange-loRange+1).

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

Випадково вибирає значення між loRange і hiRange на основі наданого індексу (index, який автоматично хешується). Значення буде розподілено за вказаними значеннями ваги (weight). Усі ваги, значення яких не вказано, вважатимуться рівними 1.0.

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

Вибирає один із наданих варіантів на основі індексу (припускається значення у діапазоні [0, 1]). Значення буде розподілено відповідно до наданих значень ваги (weight).

Підказка

У цьому прикладі буде повернуто цілі значення від 1 до 10:

pick(value, 1, 10)

У цьому прикладі буде повернуто значення 1 і 2 двічі і значення 2.5 кількість разів, яка є відносною щодо інших значень (3-10):

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

У цьому прикладі буде повернуто 10, 11 і числа від 13 до 20 (12 буде пропущено через нульову вагу):

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

Загальні математичні сталі та функції

float PI

float PI = 3.14159...

float E

float E = 2.71828...

float abs ( float x)

Значення x за модулем.

float cbrt ( float x )

Кубічний корінь.

float ceil ( float x )

Найближче більше ціле.

float exp ( float x )

Основа натурального логарифма, яку піднесено до степеня x.

float floor ( float x )

Найближче менше ціле.

float fmod ( float x, float y )

Лишок від ділення x / y.

Примітка

Також можна скористатися у форматі оператора %.

float log ( float x )

Натуральний логарифм.

float log10 ( float x )

Десятковий логарифм.

float max ( float a, float b )

Більше зі значень a або b.

float min ( float a, float b )

Менше зі значень a або b.

float pow ( float x, float y )

x у степені y.

Примітка

Також можна скористатися у форматі оператора ^.

float round ( float x )

Найближче ціле.

float sqrt ( float x )

Квадратний корінь.

float trunc ( float x )

Найближче ціле у напрямку нуля.

Тригонометричні функції

float acos ( float x )

Арккосинус.

float acosd ( float x )

Арккосинус у градусах.

float acosh ( float x )

Гіперболічний арккосинус.

float asin ( float x )

Арксинус.

float asind ( float x )

Арксинус у градусах.

float asinh ( float x )

Гіперболічний арксинус.

float atan ( float x )

Арктангенс.

float atand ( float x )

Арктангенс у градусах.

float atan2 ( float y, float x)

Арктангенс значення y/x у межах від -PI до PI.

float atan2d ( float y, float x )

Арктангенс у градусах значення y/x у межах від -180º до 180º.

float atanh ( float x )

Гіперболічний арктангенс.

float cos ( float x )

Косинус.

float cosd ( float x )

Косинус для градусів.

float cosh ( float x )

Гіперболічний косинус.

float deg ( float x )

Переведення радіан у градуси.

float hypot ( float x, float y )

Довжина двовимірного вектора [x, y].

float rad ( float x )

Переведення градусів у радіани.

float sin ( float x )

Синус.

float sind ( float x )

Синус для градусів.

float sinh ( float x )

Гіперболічний синус.

float tan ( float x )

Тангенс.

float tand ( float x )

Тангенс для градусів.

float tanh ( float x )

Гіперболічний тангенс.

Функції, які пов’язано із векторами

float angle ( vector a, vector b )

Кут між двома векторами (у радіанах).

vector cross ( vector a, vector b )

Векторний добуток векторів.

float dist ( vector a, vector b )

Відстань між двома точками.

float dot ( vector a, vector b)

Скалярний добуток векторів.

float length ( vector v )

Довжина вектора.

vector norm ( vector v )

Вектор, який масштабовано до одиничної довжини (орт).

vector ortho ( vector a, vector b )

Перпендикулярний до двох векторів вектор.

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

Обертає вектор v навколо вісі axis на заданий кут angle (у радіанах).

vector up ( vector v, vector up )

Обертає v так, щоб вісь Y вказувала у заданому напрямку up.

Підтримка векторів

Вектори (точки, кольори або просторові вектори) можна використовувати у операціях із скалярами (простими значеннями із рухомою крапкою). Якщо скаляр використовується у контексті вектора, його буде розгорнуто до трьох компонентів, наприклад, 0.5 буде перетворено на [0.5, 0.5, 0.5].

Якщо вектор використано у контексті скаляра, буде використано лише перший компонент. Однією із переваг подібного підходу є те, що усі функції, які визначено для скалярів, автоматично працюють для векторів. Наприклад, pick, choose, cycle, spline тощо працюватимуть і для векторних аргументів.

Арифметичні дії, зокрема +, *, та скалярні функції застосовуються до векторів за компонентами. Наприклад, застосування функції gamma до кольору скоригує гамму для усіх трьох каналів кольорів.

Функції, які пов’язано із кривими

Інтерполяцією значення параметра до набору контрольних точок керують вказані нижче функції.

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

Інтерполює набір кольорів, які задано контрольними точками для значення param. Контрольні точки задаються трійками параметрів pos_i, val_i і interp_i.

Підказка

Коди інтерполяції:

• 0 — немає

• 1 — лінійна

• 2 — згладжування

• 3 — сплайн

• 4 — монотонний сплайн (без осциляції)

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

Інтерполює одновимірний набір, які задано контрольними точками для значення param. Контрольні точки задаються трійками параметрів pos_i, val_i і interp_i.

Підказка

Коди інтерполяції:

• 0 — немає

• 1 — лінійна

• 2 — згладжування

• 3 — сплайн

• 4 — монотонний сплайн (без осциляції)

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

Інтерполює набір значень до вказаного параметра, де y1, …, yn розподілено рівномірно у проміжку [0, 1].

Нетипові додатки

Нетипові функції може бути реалізовано мовою C++ і завантажено як один або декілька динамічних додатків. Див. Написання нетипових додатків виразів, щоб дізнатися більше.

Попередження

Підтримки цієї функціональної можливості у Krita не передбачено.