3.5. The 'pprocess.inc' include file

Włodzimierz ABX Skiba

3.5.1. Macros with effects

Because using functions is not equally easy to every user, some predefined post processing effects can be used in the form of macros with user-friendly syntax (like every other functionality of the POV-Ray™).

To use these macros with post process effects, the include file pprocess.inc must be included. Several of these macros have a syntax similar to the old MegaPOV post process, so they may be familiar to you.

Following macros are available to the user:

3.5.1.1. Clipping colors

post_process { PP_Clip_Colors(color_min,color_max) }

Clips all colors in the image to the range color_min and color_max

3.5.1.2. Color matrix

post_process { PP_Color_Matrix(Array) }
      
// Runs the color through a 3*3 matrix expressed in Array.
// The equation is:
// R = r*AA + g*AB + b*AC
// G = r*BA + g*BB + b*BC
// B = r*CA + g*CB + b*CC
// and Array means
// array[9]{AA, AB, AC, BA, BB, BC, CA, CB, CC}

Combination of colors.

3.5.1.3. Convolution matrix

post_process { PP_Convolution_Matrix(XDim,YDim,Divisor,Leveling,Matrix) }

Multiplies the pixel and the adjacent pixels (in the area defined by the matrix size) by the respective values in the matrix, adds the results together and divides by Divisor to get an average color. A leveling value can be added in before the final division.

3.5.1.4. Depth

post_process { PP_Depth(Field_Start,Field_Depth) }

The image is converted to a gray-scale image with the gray-value of the pixel depending of the depth location in the scene.

Field_Start specifies the beginning of the focal range in units from the camera.

Field_Depth specifies the length of the focal range.

3.5.1.5. Finding edges

post_process {
  PP_Find_Edges(Depth_Thresh,Normal_Thresh,Color_Thresh,Line_Radius,Sharpness,Pigment)
}

This post process effect finds the edges in an image using depth, normal, and color information. Separate thresholds are specified for each of the three methods of edge detection.

  • Depth_Thresh: range: 0 to infinity. An edge is detected if the difference of depth (of the first intersection) in two consecutive pixels exceeds this value.
  • Normal_Thresh: range: 0 to 1. Zero represents normal vectors pointing in the same direction, 0.5 means a 90 degree difference, and 1.0 means the normal vectors point in opposite directions.
  • Color_Thresh: range: 0 to 1. Zero means no color difference, 1 means the opposite color. The color channels (red, green, and blue) are differenced separately and the results are averaged to produce the final difference.

The width of the lines is controlled by the "Line_Radius" parameter.

The sharpness of the lines is controlled by the "Sharpness" parameter. A sharpness of 1.0 yields nicely anti-aliased lines. A sharpness value of 0.0 leads to blurry lines when larger radii are used, and a sharpness value of greater than 1.0 begins to remove anti-aliasing from the lines.

The color of the line is controlled by the pigment specified. This pigment is evaluated over the range of <x,y> = <0,0> ... <1,1> (with z=0) over the full size of the image. Using solid colors is usually a good idea, unless special effects are desired.

Example 3.15. Find edge macro

PP_Find_Edges( 1.0, 0.3, 0.15, 2, 1.0, rgb 0 )

Finds edges wherever there is a depth difference greater than 1.0, a normal difference greater than 0.3 (about 60 degrees), or a color difference of 0.15. It uses a line radius of 2.0, with black (rgb 0) antialiased (sharpness 1.0) lines.

The PP_Find_Edges macro is a straight implementation of the functionality of the effect available in previous versions of MegaPOV. In fact this macro is a wrapper to the more functional macro PP_Find_Edges_Back():

post_process {
  PP_Find_Edges_Back(
    Depth_Thresh,Normal_Thresh,Color_Thresh,Line_Radius,Sharpness,Pigment,
    Background,Background_Filter,Width,Height
  )
}

This macro adds four more parameters:

Background: a pigment as replacement to be placed between edges instead of the original rendering.

Background_Filter: pigment with a filter value for weighting between the "Background" parameter and the "Pigment" parameter.

Width,Height: the image sizes to make the parameter "Line_Radius" relative to the image area. It is usually image_width and image_height but can be something different in case somebody wants a special effect like larger rectangles instead of lines.

3.5.2. Shared predefined effects

Macros mentioned in earlier sections are prefixed with 'PP_' on purpose. Include file pprocess.inc for those macros with respective equivalents for camera_view and referenced post processing. For example:

// create clipping effect of the rendering output
post_process { PP_Clip_Colors(COLOR_MIN,COLOR_MAX) }

// create clipping effect of another post processing stage
post_process { PP_Clip_Colors_Ref(Nth,COLOR_MIN,COLOR_MAX) }

// create clipping effect of another camera output
post_process { PP_Clip_Colors_Cam(CAMERA,COLOR_MIN,COLOR_MAX) }

// create a pigment with clipping of the other camera output
#declare Pigment = Pig_Clip_Colors_Cam(CAMERA,COLOR_MIN,COLOR_MAX) }