Prev Up Home Next

3.6. Functions

PDF supports several types of functions. A function is a numerical transformation which can take any number of input numerical values and produce any number of output numerical values.

Each function defines its domain which is a set of allowed input values. Some functions also define its range which is a set of allowed output values. If a value is outside the specified domain (input) or the range (output) then it is clipped accordingly.

JagPDF supports the following function types

  • Type 2 - exponential interpolation functions
  • Type 3 - stitching functions
  • Type 4 - PostScript calculator functions

In the following sections we will show examples of individual function types. The detailed description can be found in the PDF Reference, chapter Syntax | Functions.

Type 2

Type 2 functions are 1-in, n-out functions that perform exponential interpolation. The following example shows how to load a Type 2 function:

red_to_green = doc.function_2_load("domain=0, 1; c0=1, 0, 0; c1=0, 1, 0")
green_to_blue = doc.function_2_load("domain=0, 1; c0=0, 1, 0; c1=0, 0, 1")

These are examples of 1-in, 3-out functions which interpolate linearly between c0 and c1 defined over (0, 1) domain. For instance, if we interpret c0 and c1 as RGB color values then the functions above represent linear interpolation between red and green (red_to_green) and green and blue (green_to_blue).

Type 3

Type 3 functions combine several 1-input functions into a single new 1-input function. Let's show how to combine red_to_green and green_to_blue functions from the previous example:

fn3 = doc.function_3_load("domain=0, 1; bounds=0.5; encode=0, 1, 0, 1",
                          [red_to_green, green_to_blue])

The red_to_green function applies to input values in <domain[0], bounds), the green_to_blue function applies to input values in <bounds, domain[1]). The pairs in the encode array map <domain[0], bounds) and <bounds, domain[1]) to domains of the corresponding functions.

Type 4

Type 4 functions are defined by a subset of the PostScript language. The input values are pushed to the initial operand stack. After the execution of the function the operand stack contains the output values. The number of operands left on the operand stack must be in concert with the range option. To illustrate, let's load a 2-in, 1-out function:

rhomboid = doc.function_4_load("domain=-1, 1, -1, 1; range=-1, 1;"
                               "func={abs exch abs 0.9 mul add 2 div}")

The stack will initially contain two input variables and after executing the function there will be a single output variable.

For allowed PostScript operators refer to the PDF Reference, chapter Syntax | Functions | Type 4 (PostScript Calculator) Functions, table Operators in type 4 functions.


JagPDF does not verify correctness of the PostScript code. The user is responsible for specifying valid PostScript code and also for ensuring that the operand stack will contain the correct number of output variables after executing the function.

Functions Summary

Functions Reference

function_2_load(), function_3_load(), function_4_load()

PDF Reference

the PDF Reference, chapter Syntax | Functions

Prev Up Home Next