Scale HSLA

Xweather Raster Maps provides the ability to tint and modify the color of an individual layer by scaling the HSLA (hue, saturation, lightness, and alpha transparency). This feature allows you to tweak the layer's existing colors slightly or tint a layer to a specific color completely. The scale-hsla modifier is available to all Maps subscribers.

When used in combination with other modifiers, such as blend and invert, the scale-hsla modifier can assist with creating unique effects, such as drop shadows and pseudo-heatmaps.

Usage

The scale-hsla modifier is one of the more complex modifiers and takes eight (8) parameters, each parameter being a floating-point number between 0 and 1. The modifier usage is similar to:

scale-hsla(h0,h1,s0,s1,l0,l1,a0,a1), where:

• h0: the primary hue to scale to
• h1: the secondary hue used when scaling
• s0: the primary saturation to scale to
• s1: the secondary saturation used when scaling
• l0: the primary lightness to scale to
• l1: the secondary lightness used when scaling
• a0: the primary alpha to scale to
• a1: the secondary alpha used when scaling

In general usage, the a0 and a1 values will be 0 and 1 respectively.

Scaling Method

The scale-hsla modifier uses the following method when scaling the hue, saturation, and lightness. We are using hue in the following example formula, but it's the same for saturation and lightness when referencing their respective values.

h = h0 + ( hp * (h1 - h0)), where

• h0 the primary hue to scale to
• h1 the secondary hue used when scaling
• hp the hue of the pixel being adjusted
• h the new hue value

Based on the above formula, if you want to tint an image with a specific HSL color, set the h0, s0, and l0 value to the corresponding HSL color, and h1, s1, and l1 to a value of zero (0).

Likewise, if both values for hue, saturation, and lightning are equal to the corresponding HSL color, then the layer will be converted to the new color.

Converting an RGB color to HSL

When using the scale-hsla modifier, you will need to use colors based on HSL instead of RGB. Many online tools (opens in a new tab) can convert RGB to HSLA or provide both values, such as this color picker (opens in a new tab).

Once you have a color in HSL, it then needs to be converted to values between 0 and 1 for use by the scale-hsla modifier. Use the following rules to convert the HSL color to usable values:

Hue: Normally given as a value from 0 to 360. Divide the hue by 360 to convert to a value from 0 to 1.
Saturation: Normally given as a percentage between 0 and 100. Divide by 100 to convert to a value from 0 to 1.
Lightness: Normally given as a percentage between 0 and 100. Divide by 100 to convert to a value from 0 to 1.

For example, using a color picker (opens in a new tab), the color red has an RGB hex value of FF0000 and an HSL of (0, 100%, 50%). The corresponding values for use with the scale-hsla modifier would be:

hue = 0 / 360 = 0 saturation = 100 / 100 = 1 lightness = 50/100 = 0.5

As another example, the color blue has an RGB hex value of 0000FF and an HSL of (250, 100, 50). The corresponding values for use by with the scale-hsla modifier are:

hue = 250 / 360 = 0.69 saturation = 100 / 100 = 1 lightness = 50.100 = 0.5

Tinting a Layer

One usage of the scale-hsla modifier is to tint a layer with another color. For example, the lightning-strikes layer displays the last 5 minutes of lightning strikes in shades of gray based on the age of the lightning strike.

https://maps.api.xweather.com/{client_id}_{client_secret}/flat,lightning-strikes,cities-dk/700x300/dallas,tx,6/current.png

However, you may prefer a different color in some cases. If you wanted to tint the layer with red, we would use the HSL values for red (0, 1, 0.5). Oftentimes when tinting, the h0,s0, and l0 values will be set to the color to tint with, and the h1, s1, and l1 values will be zero (0). In this example, to tint the layer red we would use lightning-strikes:scale-hsla(0,0,1,0,0.5,0,0,1).
Note that is most cases, the last two values for the alpha channel will be set to 0 and 1 respectively.

https://maps.api.xweather.com/{client_id}_{client_secret}/flat,lightning-strikes:scale-hsla(0,0,1,0,0.5,0,0,1),cities-dk/700x300/dallas,tx,6/current.png

Likewise, to tint the lightning strikes blue, use the HSL values for blue (0.69, 1, 0), giving lightning-strikes:scale-hsla(0.69,0,1,0,0.5,0,0,1):

https://maps.api.xweather.com/{client_id}_{client_secret}/flat,lightning-strikes:scale-hsla(0.69,0,1,0,0.5,0,0,1),cities-dk/700x300/dallas,tx,6/current.png

In the examples above, the original lightning strikes had a darker center after tinting since they were initially shades of gray. We can then use the invert modifier before the scale-hsla. The final result will have the strike centers being closer to the desired tint color. For example, lightning-strikes:invert():scale-hsla(0.69,0,1,0,0.5,0,0,1):

https://maps.api.xweather.com/{client_id}_{client_secret}/flat,lightning-strikes:invert():scale-hsla(0.69,0,1,0,0.5,0,0,1),cities-dk/700x300/dallas,tx,6/current.png

Changing a Layer to a New Color

The scale-hsla modifier can be used to change all the colors in a layer to a new single color. To accomplish this, set the hue's h0 and h1 values the same, the saturation's s0 and s1 value the same, and finally the lightness l0 and l1 values the same when implementing the scale-hsla modifier.

For example, our default lightning-strikes layer looks like the following:

https://maps.api.xweather.com/{client_id}_{client_secret}/flat,lightning-strikes,cities-dk/700x300/dallas,tx,6/current.png

To make the lightning strikes a solid red, use the HSL color for red (0, 1, 0.5). Using lightning-strikes:scale-hsla(0,0,1,1,0.5,0.5,0,1) would result in the following:

https://maps.api.xweather.com/{client_id}_{client_secret}/flat,lightning-strikes:scale-hsla(0,0,1,1,0.5,0.5,0,1),cities-dk/700x300/dallas,tx,6/current.png

Creating a Psuedo-Heatmap

With some point data layers such as lightning-strikes, you can create a pseudo-heatmap by using a combination of the scale-hsla, invert, and blur modifiers.

For example, to create an orange pseudo-heatmap of lightning strikes, use the HSL color for orange (0.1, 1, 0.5) and then invert and blur the layer:

https://maps.api.xweather.com/{client_id}_{client_secret}/flat,lightning-strikes:invert():scale-hsla(0.1,0.1,1,1,0.5,0.5,0,1):blur(5),cities-dk/700x300/dallas,tx,6/current.png

Increasing the blur amount can improve the effect:

https://maps.api.xweather.com/{client_id}_{client_secret}/flat,lightning-strikes:invert():scale-hsla(0.1,0.1,1,1,0.5,0.5,0.1):blur(10),cities-dk/700x300/dallas,tx,6/current.png

You can also adjust the opacity for the layer:

https://maps.api.xweather.com/{client_id}_{client_secret}/flat,lightning-strikes:invert():scale-hsla(0.1,0.1,1,1,0.5,0.5,0.1):blur(5):70,cities-dk/700x300/dallas,tx,6/current.png

Creating Shadow / Glow Effects

Another common use of the scale-hsla is to combine it with the blur modifier to create a shadow or glow effect. An example use case could be to add a dark shadow/glow behind the surface analysis layer. The following is the default surface-analysis layer:

https://maps.api.xweather.com/{client_id}_{client_secret}/flat,cities-dk,surface-analysis/700x400/39,-96,4/current.png

To add a shadow behind the fronts, we would use the scale-hsla to turn fronts black and then blur the layer. Using the HSL color for black (0,0,0) would result in surface-analysis-fronts:scale-hsla(0,0,0,0,0,0,0,1):blur(10):

https://maps.api.xweather.com/{client_id}_{client_secret}/flat,cities-dk,surface-analysis-fronts:scale-hsla(0,0,0,0,0,0,0,1):blur(10)/700x400/39,-96,4/current.png

Next, we replot the surface-analysis layer on top of the shadow layer, resulting in surface-analysis-fronts:scale-hsla(0,0,0,0,0,0,0,1):blur(10),surface-analysis:

https://maps.api.xweather.com/{client_id}_{client_secret}/flat,cities-dk,surface-analysis-fronts:scale-hsla(0,0,0,0,0,0,0,1):blur(10),surface-analysis/700x400/39,-96,4/current.png

Note that since we are plotting the surface-analysis layer twice, this would double the number of map units utilized.