Depth of field

The map effects plugin's depthOfField holds one distance sharp on a pitched map and defocuses the rest, the way a lens focused there would. It is the one effect that reads the map's camera. In the playground below, the band holds one run of the valley in focus and lets the ridges behind it soften:

Turning it on

effects.updateConfig({
    'depthOfField.intensity': 18, // the widest circle of confusion, in CSS pixels
    'depthOfField.focus': 0,      // 0 = the nearest ground, 1 = the farthest the frame shows
    'depthOfField.band': 0.3,     // how much of that depth stays sharp
    'depthOfField.bokeh': 0.5,    // whether a defocused highlight fades or returns as a disc
});

• focus: 0 needs nothing set: the nearest thing in a tilted shot is the bottom edge. Raise it and the middle distance is sharp, with the foreground and the horizon thrown off: the tilt-shift picture.
• The map needs preserveDrawingBuffer: true: the pass reads the rendered map back as a texture.

How it works

• It runs on the GPU, in the plugin's GPU chain: a full-screen pass gathering a disc of the map's pixels per fragment, at a radius that grows with distance from the plane of focus. A backdrop-filter, one radius for the whole layer, reads as haze rather than as a lens.
• Bokeh separates a defocus from a blur. Each sample is weighted by the fourth power of its brightness, so a lit road or a traffic tube keeps its brightness across the circle it is spread over; at 0 the light is averaged away, as a blur does.
• No depth buffer is needed: the map is a plane, so the reciprocal distance a lens defocuses by is affine in the screen row. The pitch and vertical field of view give the frame's whole depth as one ramp, span = 2·tan(fov/2)·tan(pitch) normalised to span/(1 + span/2): 0 from straight above, 0.5 at a 45° tilt, past 1 once the horizon is on screen.

Planning around it

• A flat map ends the effect, with no pitch check: every part of the ground is the same distance away, so the pass does not run. Tilt the map and it comes back.
• The same band covers more of the view at a gentle tilt, because it is a share of the frame's depth rather than of its height.
• Bloom glows over the defocus: it reads the chain's output, so a defocused highlight glows as a wide soft disc.
• Your own passes run before or after it, as you place them.

It pairs with 3D terrain, which gives the view relief to defocus — the 3D terrain playground above — and with the fly-over plugin, as in the route fly-over playground, where it holds the road ahead in focus through the whole flight.

Related guides and examples

Related guides

• Map effects plugin - Setup, how the effects render, and every knob
• Terrain - The relief a depth of field defocuses
• Globe and sky - The sky above a tilted view
• Fly-over plugin - A camera flying a route, with the road ahead in focus

Related examples

• 3D terrain playground - A depth of field over a valley
• Route fly-over playground - A depth of field holding the road ahead in focus