SeExpr 表达式参考

本页面列出了所有在 Krita 中可用的 SeExpr 变量、函数和运算符，并介绍它们的功能和用法。所有内容均基于 SeExpr 官方用户文档 修改而来，为了方便 Krita 用户的使用进行了一些语句上的调整。(译者注：为了照顾脚本编程的实际需要，本页的某些部分采用中英对照翻译。)

参见

参见

Variables (变量)

External variables (外部变量)

这些变量由宿主程序 (Krita) 提供。它们被注册到 SeExpr 模块的自动完成提示信息中，可以通过 Ctrl+Space 快捷键访问。

$u, $v

图像位置的归一化坐标信息。

$w, $h

图像的像素宽度和高度信息。

Local Variables (局部变量)

局部变量可以在表达式的开头处定义:

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

外部变量也可以被局部赋值所改写。例如对噪声频率进行缩放:

$P = $P * 10; # 提高噪声频率
fbm(vnoise($P) + $P/4)

你也可以定义命名空间变量，例如:

$A::a = $u * 10;

Control Structures (控制结构)

SeExpr 提供了常见的 if 条件结构:

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

$color

它也提供了 ternary operator (三元运算符):

$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

Operators (运算符/按递减顺序排列)

[a,b,c]

vector constructor (矢量构造函数)

$P[ n ]

vector component access (矢量分量访问)

提示

n 必须是 0、1 或者 2，例如:

$P[0]
^

exponentiation (取幂、乘方)

备注

与 pow 函数相同。

!

logical NOT (逻辑非)

~

inversion (求逆/反相)

提示

~$A

上面的表达式将给出与下面的表达式相同的结果:

1 - $A
*/ %

分别是：multiply (乘)、divide (除)、modulus(模)。

备注

% 与 fmod 函数相同。

+-

分别是：add (加)、subtract (减)

<> <= >=

比较，分别是：less than (小于)、greater than (大于)、less or equal than (小于等于)、greater or equal than (大于等于)。

备注

它们只使用矢量的第一分量进行对比。

== !=

分别是：equality (等于)、inequality (不等于)

&&

logical AND (逻辑与)

||

logical OR (逻辑或)

?:

ternary if operator (三元 if 运算符)

提示

示例:

$u < .5 ? 0 : 1
->

apply (应用)：将箭头右边的函数应用到箭头左边的表达式。

提示

示例:

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

Assignment Operators (赋值运算符)

你可以使用基本赋值语句，例如:

$foo = $bar

你也可以在赋值语句中使用运算符:

$foo += $bar;

上面的语句相当于:

$foo = $foo + $bar;

可以使用的赋值运算符如下：

  • +=

  • -=

  • /=

  • %=

  • *=

  • ^=

Comments (代码注释)

你可以用 # 字符给对脚本进行代码注释。SeExpr 不会对一行代码里位于 # 号后面的内容进行渲染，但这不意味着它们被完全忽略——代码注释可以用来声明整数、浮点和矢量变量的有效范围，你可以使用 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

不管是哪种数值类型，如果没有指定范围，那么 SeExpr 对话框控件将默认范围为 0 - 1 (含)。

多行表达式的每一行都可以有自己的代码注释。

Logging Functions (日志函数)

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

将字符串按照给定格式输出到 stdout 标准输出。可用的格式参数有： %f 浮点 (取矢量参数的第一分量) 和 %v 矢量。

提示

输入以下代码:

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

命令行控制台将返回:

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

返回一组按照给定值进行格式化的字符串。请在命令行控制台输入 man sprintf 查看格式的相关细节。

Color, Masking, and Remapping Functions (颜色、遮蔽、重映射函数)

float bias ( float x, float b)

这是一个 gamma 变量，它的控制参数范围为 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 )

step (梯度) 函数在 x < a 时为 0，在 x > b (boxstep 正方插值的场合则是 x > a ) 时为 1。在 a 和 b 之间，数值从 0 到 1 连续过渡。 gaussstep (高斯梯度) 函数使用基于指数曲线的标准高斯钟形曲线。 smoothstep 函数则使用三次曲线 (立方曲线)。从直觉感受来说， gaussstep 在接近 1 时过渡陡峭，而在接近 0 时过渡平缓。 smoothstep 在 1 和 0 附近的过渡具有中等的柔和度。

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 (单位为度) 对色相进行 shift (偏移)，按 s 对饱和度进行 scale (按比例缩放)，按 i 对亮度进行缩放。可以提供 map (映射值) 来控制偏移量。map 为 1 时色相旋转一周；map 为 0 时色相不旋转；对于 0 到 1 之间的数值，偏移量将等比例缩放。

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

RGB 到 HSL 色彩空间转换。HSL 代表 Hue (色相)、Saturation (饱和度)、Lightness (亮度) (这些数值的范围全部为 [0, 1] )。可扩展至支持在合理范围内超出 [0, 1] 的 RGB 和 HSL 数值。对于任意 RGB 或者 HSL 数值 (负值除外)，此转换操作是定义明确且可逆的。

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

midhsi 函数和 hsi 函数类似，但它的控制映射按中间点对齐 (数值为 0.5)，且可以向两个方向按比例缩放色相偏移量。数值在中间点时色相不发生偏移。数值为 1.0 时色相顺时针旋转一周，数值为 0.0 时色相逆时针旋转一周。另外还可以使用 falloff 和 interp 来控制 remap 函数对映射进行调整。 falloff 和 interp 为默认值时不发生重映射。

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

根据 alpha (透明度通道) 混合 a 和 b 。按照 a*(1-alpha) +b*alpha 进行定义。

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

常规重映射函数。当 x 在源数据的 ± range 范围内时，结果为 1。当超出 falloff 距离时数值降为 0。falloff shape (滚降形状) 由 interp 进行控制。

备注

滚降形状可以用数字或者具名常量控制：

  • int linear = 0 (线性)

  • int smooth = 1 (平滑)

  • int gaussian = 2 (高斯)

Noise Functions (噪声函数)

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 会在一片区域中依据整数位置生成一片带有恒定颜色的方块。它和 PRMan cellnoise function 功能一致 。

备注

ccellnoise 输出 color cellnoise (色块噪声)。

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 时代表每一 octave (八度) 的频率是前一八度的 2 倍。 gain 控制每个频率相对前一频率如何按比例缩放。

备注

cfbm 和 cfbm4 输出颜色噪声。

vfbm 和 vfbm4 输出矢量噪声。

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

和 rand 类似，但不带有内部种子。可以指定任意数量的种子，结果为基于所有种子的随机函数。

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 是一个随机函数，它会在整数位置平滑地混合样本。这也是 Ken Perlin 发明的原始噪声函数 (柏林噪声)。

备注

cnoise 和 cnoise4 输出颜色噪声。

noise4 输出有正负之分的矢量噪声。

pnoise 输出周期噪声。

snoise 和 snoise4 输出有正负之分的噪声，范围为 [-1, 1] 。

vnoise 输出有正负之分的矢量噪声。

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

在 [min, max] 范围内的随机数字 (如果不指定范围则是 [0, 1] )。如果提供了外部种子，内部种子将和外部种子一同被使用，可以用于编写各种效果独特的生成器。

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 的抖动变体。它的类型参数描述了不同的噪声函数变体。 jitter 参数控制蜂窝形状的不规则程度 (0 与一般 cellnoise 图案相同)。 fbm... 参数可被用于扭曲噪声场。当 fbmScale 为 0 (默认值) 时不发生扭曲。其余参数和 fbm 函数中的相同。

提示

Voronoi 的类型，从 1 到 5：

image0 image1 image2 image3 image4

备注

cvoronoi 给蜂窝图案的每一格返回一种随机颜色， pvoronoi 返回蜂窝图案格子中心点位置。

Selection Functions (选择函数)

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

在提供的选项中基于 index (索引) 选取其中之一 (假设范围为 [0, 1])。

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

按照提供的 index (索引) 在 loRange 和 hiRange 之间 cycle (循环) 输出数值。这是一个 offset (偏移)的 mod 函数。其结果按照 loRange + value % (hiRange-loRange+1) 进行计算。

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

按照提供的 index (索引值，通过自动散列得到 / automatically hashed) 在 loRange 和 hiRange 之间随机选取数值。数值将按照提供的 weight (权重) 进行分布。未提供权重的假设其权重为 1.0。

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

按照索引 (假设范围为 [0, 1]) 从提供的选项中选择其一。数值将按照提供的权重进行分布。

提示

此例子返回整数数值，范围为 1 - 10:

pick(value, 1, 10)

此例子返回数值为 1 的频率为 3 - 10 的 2 倍，2 的频率为 3 - 10 的 2.5 倍:

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

此例子返回 10、11 和 13 - 20 (12 的权重为 0，它被跳过):

This example returns 10, 11, and 13 through 20 (12 is skipped due to zero weight)::

   dummy literal

一般数学常量和函数

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

求 x 的绝对值。

float cbrt ( float x )

求 x 的立方根。

float ceil ( float x )

取下一更大整数。

float exp ( float x )

求 E 的 x 次方。

float floor ( float x )

取下一更小整数。

float fmod ( float x, float y )

求 x / y 的余数。

备注

也可以通过 % 运算符调用。

float log ( float x )

求自然对数。

float log10 ( float x )

求以 10 为底的对数。

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 )

取 x 的最近似整数。

float sqrt ( float x )

求 x 的平方根。

float trunc ( float x )

趋零截尾，求 x 在趋近零方向上的最近似整数。

Trigonometry Functions (三角函数)

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)

在 -PI 和 PI 之间求 y/x 的反正切弧度。

float atan2d ( float y, float x )

在 -180º 和 180º 之间求 y/x 的反正切角度。

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 )

求双曲正切弧度。

Vector Functions (矢量函数)

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 )

按照给定的角度 angle (弧度数值)，绕轴旋转矢量 v 。

vector up ( vector v, vector up )

旋转矢量 v ，使其 Y 轴指向给定的 up 方向。

Vector Support (矢量功能支持)

** Vectors (矢量)** 包括矢量点、颜色矢量和三维矢量，有时也和 scalars (标量) (simple floating point values / 简单浮点数值) 混用。如果在矢量语境里面使用标量，它将会被复制到矢量的三个分量上，例如 0.5 将被转换为 [0.5, 0.5, 0.5] 。

矢量在标量语境中使用时，只有它的第一分量才会被使用。这种做法的好处是所有给标量准备的函数也可以自动支持矢量。例如 pick 、 choose 、 cycle 、 spline 等均可使用矢量。

算数运算符，如 + 、 * 等，还有标量函数会按照分量应用到矢量。例如将 gamma 函数应用到一个 mao (映射) 时将调整全部三个颜色通道的 gamma 值。

Curve Functions (曲线函数)

将参数数值按照下列函数指定的控制点进行插值。

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

用 param 处给定的控制点对颜色梯度进行插值。控制点由三元参数 pos_i 、 val_i 、 interp_i 进行指定。

提示

插值方式代码如下：

  • 0 - none (无)

  • 1 - linear (线性)

  • 2 - smooth (平滑)

  • 3 - spline (样条曲线)

  • 4 - monotone (non-oscillating) spline (单调/非振动样条曲线)

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

用 param 处给定的控制点对一维梯度进行插值。控制点由三元参数 pos_i 、 val_i 、 interp_i 进行指定。

提示

插值方式代码如下：

  • 0 - none (无)

  • 1 - linear (线性)

  • 2 - smooth (平滑)

  • 3 - spline (样条曲线)

  • 4 - monotone (non-oscillating) spline (单调/非振动样条曲线)

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

将一组数值按照指定参数进行插值， y1 至 yn 的数值在 [0, 1] 范围内等距分布。

自定义插件

自定义函数可用 C++ 编写后作为动态插件加载。详情请参照 SeExpr 的 Writing Custom Expression Plugins / 编写自定义表达式插件 文章。

警告

Krita 不支持此功能。