ZDefocus

Function
This is identical to the Defocus blurring filter, except you can do a realistic depth-of-field by using the image's Z channel. The Z channel is usually coming from a Z-depth 3D render, but of course can also be placed with Shake channel swapping tools (Reorder and Copy).

Like ZBlur, this function works best when there is no abrupt overlapping of foreground objects over background. The foreground elements will work fine, but the background will have ringing. If you are developing a shot of this nature, try to split your foreground into a separate element.

Parameters
Type
Defaults
Function
x,yPixels
float
11,11 Kernal size for the defocus in pixels. Anything less than 3 does nothing. This is the general size of the flare.
channels
string
"rgba"

Which channels are calculated for the blur.

percent
float
100 The mix between the blurred and non-blurred image.
shape
string
"gaussian" Either "fast gaussian", "fast box", "circle", "square", "hexagon", or "octagon". This describes the shape of the flaring. The fast modes give you low quality but fast results.
boostPoint
float
.95 The image value where the superwhite boosting starts. If boostPoint is .75, rgb values above .75 will be boosted to increase flaring effects. A high value generally decreases flare areas, since fewer candidate pixels are flared out.
superWhite
float
1 Max value to boost image to. A value of 1 in the original will be boosted to this value. By boosting this, you increase the brightness of the flare area. Values around 50 give you a very strong boost.
near
float
0

The value of distance towards the camera at which maximum blur occurs

far
float
1 The value of distance away from the camera at which maximum blur occurs
focusCenter
float
(far-near)/2+near The distance from the camera at which there is no blur.
focusRange
float
0 The distance away from the focusCenter, both towards and away from the camera, that remains in un-blurred.
steps
int
5 The amount of steps that the total range is divided between.
stepBlend
float
1 The mixing of the different steps. 0 means no mixing, and it good for getting a feel for your step ranges. 1 means complete, linear blending.


Synopsis

image ZDefocus( image, 
  float xPixels,
  float yPixels,
  const char * channels, 
  float percent, 
  const char * shape,
  float boostPoint, 
  float superWhite
  float near,
  float far,
  float focusCenter,
  float focusRange,
  int steps,
  float stepBlend
);


Script

image = ZDefocus( image, 
  xPixels,
  yPixels,
  "channels",
  percent,
  "shape",
  boostPoint,
  superWhite        
  near,
  far,
  focusCenter,
  focusRange,
  steps,
  stepBlend
);


Command Line

shake -zdefocus xPixels yPixels channels etc...

See Also
PercentBlur, Blur, Defocus, ZBlur, IDefocus