Layer Blending

Aeris Maps includes the ability to blend layers together as they are added to generate your map.  Blends can be thought of as compositing operations, which can be used to affect the color and texture of the layers being combined.  The blend option takes a string value, where the string is the type of blend to apply to the layer.

One common use of the blend functionality is to pull the textures from a terrain map into weather layers.

Temperatures Without Blending:
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures,cities/700x300/salt+lake+city,ut,6/current.png
Blur at 0 example

Blending Temperatures onto a Terrain Base Map using an Overlay Blend:
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures:blend(overlay),cities/700x300/salt+lake+city,ut,6/current.png
Blur at 0 example

Blending Two Layers

Blending occurs between a source layer and a destination layer. With Aeris Maps, the layers are adding left to right with the combined layers being the destination and the new layer the source. For example, when using “terrain,alerts,radar”:

Layer 1: Adding the terrain layer: destination is the blank image, source is the terrain layer
Layer 2: Adding the alerts layer: destination is the terrain layer, source is the alerts layer
Layer 3: Adding the radar layer: destination is the combined terrain,alerts layer, source is the radar layer

To blend a source layer to a destination add :blend([blendmode]) immediately after the source layer name, where [blendmode] is the blend type to apply.

Blending Alerts onto a Terrain Base Map:
http://maps.aerisapi.com/[client_id]_[client_key]/terrain-dk,alerts:blend(grain-merge),cities/700x300/salt+lake+city,ut,6/current.png
Grain merge blend of alerts on terrain map

Only one blend type may be applied to a single source layer, meaning terrain-dk,alerts:blend(grain-merge):blend(overlay) is an invalid request and may return an error or unexpected result.

Blend Types

Blend modes can be broken down into two groups: composite blends, which affect color blending between layers, and alpha blends, which are useful for creating masks between layers.

Composite Blends

plus minus difference exclusion
multiply contrast screen invert
overlay grain-merge grain-extract darken
lighten hue color-dodge color-burn
saturation hard-light soft-light  

Alpha Blends

src dst src-over dst-over
src-in dst-in src-out dst-out
src-atop dst-atop    

Composite Examples

The following examples illustrate the various composite blending options using the terrain map as the destination and the temperature layer as the source. Some composite blend options may return alternative results by reversing the destination and source layers, such as using the temperatures as the destination and the terrain as the source.
 

Base Terrain Image (Destination)
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,cities/700x300/salt+lake+city,ut,5/current.png
Base Terrain Image (Destination)

Temperature Image (Source) with no Blend
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures,cities/700x300/salt+lake+city,ut,5/current.png
Example Temperature Image (Source) with no blend

Overlay
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures:blend(overlay),cities/700x300/salt+lake+city,ut,5/current.png
Overlay example
The overlay blend combines colors form the source image with the brightness and darkness of the destination. The overlay blend is useful for showing terrain texture within the source image and works best with lighter destination layers.

Multiply
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures:blend(multiply),cities/700x300/salt+lake+city,ut,5/current.png
Multiply example
The multiply blend multiplies colors form the source image with the colors of the destination. The result tends to be a darker image that highlights the source. The multiply blend is useful with showing terrain texture within the source image and works best with lighter destination layers.

Grain-Merge
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures:blend(grain-merge),cities/700x300/salt+lake+city,ut,5/current.png
Grain-Merge example
The grain-merge blend is useful with showing terrain texture within the source image and works well with both light and dark destination layers. This blend type is also useful when using the base terrain map as the source, example: temperatures,terrain:blend(grain-merge).

Plus
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures:blend(plus),cities/700x300/salt+lake+city,ut,5/current.png
Plus example
The plus blend adds the source color to the destination, tinting the destination towards the source. The lighter the source, the lighter the result. This blend type works best with darker source images.

Minus
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures:blend(minus),cities/700x300/salt+lake+city,ut,5/current.png
Minus example
The minus blend subtracts the source color to the destination, tinting the destination opposite of the source. The lighter the source, the lighter the result.

Difference
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures:blend(difference),cities/700x300/salt+lake+city,ut,5/current.png
difference example
The difference blend looks at the color information in each channel and subtracts either the source from the destination or the destination from the source, depending on which has the greater brightness value. Blending with white inverts the base color values, whereas blending with black produces no change.

Exclusion
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures:blend(exclusion),cities/700x300/salt+lake+city,ut,5/current.png
exclusion example
An exclusion blend creates an effect similar to but lower in contrast than the difference blend mode. Blending with white inverts the base color values, whereas blending with black produces no change.

Contrast
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures:blend(contrast),cities/700x300/salt+lake+city,ut,5/current.png
contrast example

Screen
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures:blend(screen),cities/700x300/salt+lake+city,ut,5/current.png
screen example
A screen blend multiplies the inverse of the source and destination colors, resulting in a lighter color. Screening with black produces no change, whereas screening with white produces white.

Invert
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures:blend(invert),cities/700x300/salt+lake+city,ut,5/current.png
invert example

Grain Extract
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures:blend(grain-extract),cities/700x300/salt+lake+city,ut,5/current.png
Grain Extract example

Darken
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures:blend(darken),cities/700x300/salt+lake+city,ut,5/current.png
darken example
The darken blend looks at the color information in each channel and selects the destination or source color, whichever is darker, as the result.

Lighten
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures:blend(lighten),cities/700x300/salt+lake+city,ut,5/current.png
lighten example
The lighten blend looks at the color information in each channel and selects the destination or source color, whichever is lighter, as the result.

Hue
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures:blend(hue),cities/700x300/salt+lake+city,ut,5/current.png
hue example
The hue blend creates a result with the luminance and saturation of the destination and the hue of the source.

Saturation
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures:blend(saturation),cities/700x300/salt+lake+city,ut,5/current.png
saturation example
The saturation blend creates a result with the luminance and hue of the destination and the saturation of the source. This preserves the grey levels in the image and is useful for coloring monochrome images or tinting color images.

Color Dodge
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures:blend(color-dodge),cities/700x300/salt+lake+city,ut,5/current.png
Color Dodge example
The color-dodge blend looks at the color information in each channel and brightens the destination to reflect the source by decreasing the contrast between the two. Blending with black produces no change.

Color Burn
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures:blend(color-burn),cities/700x300/salt+lake+city,ut,5/current.png
Color Burn example
The color-burn blend looks at the color information in each channel and darkens the destination to reflect the source by increasing the contrast between the two. Blending with white produces no change.

Hard Light
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures:blend(hard-light),cities/700x300/salt+lake+city,ut,5/current.png
Hard Light example
The hard-light blend multiplies or screens the colors depending on the source. The effect is similar to shining a harsh spotlight on the image. If the source is lighter than 50% gray, the result is lightened, otherwise the result is darkened.

Soft Light
http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures:blend(soft-light),cities/700x300/salt+lake+city,ut,5/current.png
Soft Light example
The soft-light blend darkens or lightens the colors depending on the source. The effect is similar to shining a diffused spotlight on the image. If the source is lighter than 50% gray, the result is lightened, otherwise the result is darkened.

Alpha Examples

The following examples illustrate the various alpha blending options, using the terrain map as the destination and the temperature overlay as the source. Some alpha blend options may return alternative results by reversing the destination and source layers, such as using the temperatures as the destination and the terrain as the source.
 

Src
http://maps.aerisapi.com/[client_id]_[client_key]/alerts,radar:blend(src),cities/700x300/salt+lake+city,ut,5/current.png
Src alpha blend example
The src alpha blend will simply return the source image, ignoring the destination image.

Dst
http://maps.aerisapi.com/[client_id]_[client_key]/alerts,radar:blend(dst),cities/700x300/salt+lake+city,ut,5/current.png
dst alpha blend example
The dst alpha blend will simply return the destination image, ignoring the source image.

Src Over
http://maps.aerisapi.com/[client_id]_[client_key]/alerts,radar:blend(src-over),cities/700x300/salt+lake+city,ut,5/current.png
src-over alpha blend example
The src-over alpha blend will layer the source image on top of the destination image. This is the same as using no blend. i.e. alerts,radar:blend(src-over) is the same as alerts,radar

Dst Over
http://maps.aerisapi.com/[client_id]_[client_key]/alerts,radar:blend(dst-over),cities/700x300/salt+lake+city,ut,5/current.png
dst-over alpha blend example
The dst-over alpha blend will layer the destination image on top of the source image.

Src In
http://maps.aerisapi.com/[client_id]_[client_key]/alerts,radar:blend(src-in),cities/700x300/salt+lake+city,ut,5/current.png
src-in alpha blend example
The src-in alpha blend will only include portions of the source if they intersect with parts of the destination. The colors of the destination will not be drawn.

Dst In
http://maps.aerisapi.com/[client_id]_[client_key]/alerts,radar:blend(dst-in),cities/700x300/salt+lake+city,ut,5/current.png
dst-in alpha blend example
The dst-in alpha blend will only include portions of the destination if they intersect with parts of the source. The colors of the source will not be drawn.

Src Out
http://maps.aerisapi.com/[client_id]_[client_key]/alerts,radar:blend(src-out),cities/700x300/salt+lake+city,ut,5/current.png
src-out alpha blend example
The src-out alpha blend will only include portions of the source that do not intersect with parts of the destination. The colors of the destination will not be drawn.

Dst Out
http://maps.aerisapi.com/[client_id]_[client_key]/alerts,radar:blend(dst-out),cities/700x300/salt+lake+city,ut,5/current.png
dst-out alpha blend example
The dst-out alpha blend will only include portions of the destination if they do not intersect with parts of the source. The colors of the source will not be drawn.

Src Atop
http://maps.aerisapi.com/[client_id]_[client_key]/alerts,radar:blend(src-atop),cities/700x300/salt+lake+city,ut,5/current.png
src-atop alpha blend example
The src-atop alpha blend will only include portions of the source that intersect the destination. These portions will be layered on top of the destination image.

Dst Atop
http://maps.aerisapi.com/[client_id]_[client_key]/alerts,radar:blend(dst-atop),cities/700x300/salt+lake+city,ut,5/current.png
dst-atop alpha blend example
The dst-atop alpha blend will only include portions of the destination if that intersect with parts of the source. These destination parts will be layered on top of the source layer.

Blend With Other Modifiers

Blend and other layer modifiers, such as opacity, may be used together by chaining them in the url. For example, to render temperatures at 70% opacity, a blur level of 2 and blending using the grain-merge blend type would use temperatures:70:blur(2):blend(grain-merge) :

http://maps.aerisapi.com/[client_id]_[client_key]/terrain,temperatures:70:blur(2):blend(grain-merge),cities-dk/700x300/salt+lake+city,ut,6/current.png
Multiple Modifiers example

When using multiple layer modifiers, their order in the URL is arbitrary. For example temperatures:70:blend(overlay) is the same as temperatures:blend(overlay):70.