doc/functions/expr.rst

   1 Expr
   2 ====
   3
   4 .. function:: Expr(clip[] clips, data[] expr[, int format])
   5    :module: std
   6
   7    Expr evaluates an expression per pixel for up to 3 input *clips*.
   8    The expression, *expr*, is written using reverse polish notation and can be specified for each plane individually.
   9    The expression given for the previous plane is used if the *expr* array contains fewer expressions than the input clip has planes.
  10    In practice this means that a single expression will be applied to all planes by default.
  11
  12    Specifying an empty string as the expression enables a fast plane copy from the first specified clip, when possible. If it is not possible due to the output *format* being incompatible the plane contents will be undefined.
  13
  14    Since the expression is evaluated at runtime there are a few pitfalls. In order to keep speed up the input ranges are not normalized to the usual floating point ranges. Instead they are left as is,
  15    meaning that an 8 bit clip will have values in the 0-255 range and a 10 bit clip will have values in the 0-1023 range.
  16    Note that floating point clips are even more difficult, as most channels are stored in the 0-1 range with the exception of U, V, Co and Cg planes, which are in the -0.5-0.5 range.
  17    If you mix clips with different input formats this must be taken into consideration.
  18
  19    By default the output *format* is the same as the first input clip's format.
  20    You can override it by setting *format*. The only restriction is that the output *format* must have the same subsampling as the input *clips* and be 8 or 16 bit integer or 32 bit float.
  21
  22    Logical operators are also a bit special, since everything is done in floating point arithmetic.
  23    All values greater than 0 are considered true for the purpose of comparisons. Logical operators return 0.0 for false and 1.0 for true in their operations.
  24    Since the expression is being evaluated at runtime, there are also the stack manipulation operators, *swap* and *dup*. The former swaps the topmost and second topmost values, and the latter duplicates the topmost stack value.
  25
  26    Load operators::
  27
  28       x y z
  29
  30    The operators taking one argument are::
  31
  32       exp log sqrt abs not dup
  33
  34    The operators taking two arguments are::
  35
  36       + - * / max min > < = >= <= and or xor swap
  37
  38    The operators taking three arguments are::
  39
  40       ? (ternary operator, equivalent to a ? b : c in C)
  41
  42    How to average the Y planes of 3 YUV clips and pass through the UV planes unchanged (assuming same format)::
  43
  44       std.Expr(clips=[clipa, clipb, clipc], expr=["x y + z + 3 /", "", ""])
  45
  46    How to average the Y planes of 3 YUV clips and pass through the UV planes unchanged (different formats)::
  47
  48       std.Expr(clips=[clipa16bit, clipb10bit, clipa8bit],
  49          expr=["x y 64 * + z 256 * + 3 /", ""])
  50
  51    Setting the output format because the input format isn't allowed as output (note that the U and V planes will contain junk since direct copy isn't possible)::
  52
  53       std.Expr(clips=[clipa10bit, clipb16bit, clipa8bit],
  54          expr=["x 64 * y + z 256 * + 3 /", ""], format=vs.YUV420P16)