Layer Blending

Xweather Raster 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:

https://maps.api.xweather.com/{client_id}_{client_secret}/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:

https://maps.api.xweather.com/{client_id}_{client_secret}/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 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:

https://maps.api.xweather.com/{client_id}_{client_secret}/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)

https://maps.api.xweather.com/{client_id}_{client_secret}/terrain,cities/700x300/salt+lake+city,ut,5/current.png

Base Terrain Image (Destination)

Temperature Image (Source) with no Blend

https://maps.api.xweather.com/{client_id}_{client_secret}/terrain,temperatures,cities/700x300/salt+lake+city,ut,5/current.png

Example Temperature Image (Source) with no blend

Overlay

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/terrain,temperatures:blend(contrast),cities/700x300/salt+lake+city,ut,5/current.png

contrast example

Screen

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/terrain,temperatures:blend(invert),cities/700x300/salt+lake+city,ut,5/current.png

invert example

Grain Extract

https://maps.api.xweather.com/{client_id}_{client_secret}/terrain,temperatures:blend(grain-extract),cities/700x300/salt+lake+city,ut,5/current.png

Grain Extract example

Darken

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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 Blending

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

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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

https://maps.api.xweather.com/{client_id}_{client_secret}/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) :

https://maps.api.xweather.com/{client_id}_{client_secret}/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.

Blur Gray