Layer Blending

AerisWeather 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

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

Blending Two Layers

Blending occurs between a source layer and a destination layer. With 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

Last modified: August 02, 2021