APL Filters

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

Use the APL filters to apply different effects to images defined with the Image component. Some filters work on a single image. Other filters combine two images and produce a new image you can display on the screen.

Important: All filters except Blur and Noise require APL 1.5 or later. Provide an alternate experience for devices running older versions of APL.

About filters

To use filters, you provide an array of filters and an initial array of images. You add both of these arrays to the properties on the Image component:

Provide the array of filters in the filters property. Each filter has a type property and then a set of filter-specific properties that determine the result of the filter.
Provide the URL for a single image or an array of URLs for multiple images in the source / sources property. As of APL 1.5, the Image component sources property can take an array of image URLs instead of a single URL. Earlier versions of APL take a single URL in the source property.

The following example shows an Image component with two filters to apply to single image.

Copied to clipboard.

{
  "type": "Image",
  "height": "200dp",
  "width": "300dp",
  "filters": [
    {
      "type": "Blur",
      "radius": "10dp"
    },
    {
      "type": "Noise",
      "sigma": 10
    }
  ],
  "source": "https://example.com/images/duck.jpg"
}

The Image component sources property takes either a single image URL or multiple image URLs in an array. The filter loads the values provided in sources into an image array to provide the source images for the filter.

When the filters property contains multiple filters, Alexa applies the filters in array order. Each filter applies its effect, and then adds the resulting image to the end of the images array. After all filters finish processing, Alexa displays the final image. Because each filter adds its resulting image to the end of the array, the images array changes during filter processing.

In the example shown earlier, the Blur filter loads the original "duck.png" image into the images array, applies the blur effect and saves the resulting image to the array. The Noise filter then uses the last image in the array, the modified duck image, as its source and saves the resulting image to the end of the array. Finally, the Image component displays the final modified image that reflects the result of "blur" followed by "noise" effects.

A filter that acts on a single image chooses the last image in the array as the image source by default. You can control this by setting the source on the filter to the index of the image you want to modfiy in the images array. The images array is zero-based, so setting source to 0 applies the filter to the first image in the array. Remember that the images array for the filters might not match the original Image component sources array since each filter adds its result. Use -1 to target the last image in the array.

If the filter encounters an error when loading the images from the Image component sources array, it replaces the image with a virtual image that has zero size and a transparent black color.

The Color and Gradient filters each add a new item to the images array with the specified coloration or gradient. You would typically combine this filter with Blend to merge the color or gradient into the image.

Available filters

The following table summarizes the available filters.

Filter	Description	Version Added
`Blend`	Merges two images together with a defined operation mode.	APL 1.5
`Blur`	Applies a Gaussian blur to the image.	APL 1.0
`Color`	Creates a solid color image and appends it to the array of images. Combine this filter with `Blend` to apply the color to your image.	APL 1.5
`Gradient`	Creates a gradient image and appends it to the array of images. Combine this filter with `Blend` to apply the gradient to your image.	APL 1.5
`Grayscale`	Converts the image to grayscale.	APL 1.5
`Noise`	Adds generated noise to the image.	APL 1.2
`Saturate`	Changes the color saturation of the image.	APL 1.5

Blend

Merges two images from the image array, and then appends the new image to the end of the array.

Property	Type	Default	Description
`type`	Blend	REQUIRED	Set to `Blend`.
`destination`	Integer	-2	Index of the destination image in the image array. Defaults to the second-to-last image in the array.
`mode`	Blend Mode	`normal`	Blend mode to apply
`source`	Integer	-1	Index of the source image in the image array. Defaults to the last image in the array.

Set the mode property to one of the following modes:

normal
multiply
screen
overlay
darken
lighten
color-dodge
color-burn
hard-light
soft-light
difference
exclusion
hue
saturation
color
luminosity

The Blend filter also supports the following Porter-Duff operations:

source-atop
source-in
source-out

The Blend filter combines two images. The filter can also combine an image with a solid color or a gradient produced with the Color and Gradient filters. These filters each add a color or gradient to the images array.

At least one of the source or destination images must be a bitmap image and not a color, gradient, or missing image:

When both the source and destination are bitmap images, the resulting image has the same size as the destination image. The source image aligns with the top-left corner of the destination image.
When either the source or destination images is a bitmap and the other is a color, gradient, or missing image, the resulting image has the same size as the bitmap.
When both the source and destination images are colors, gradients, or missing, the filter doesn't do any blending and returns the destination image.

The following example shows a Blend filter that combines two images using the default source and destination values. The source is the last image in the array (the duck) and the destination is the second-to-last image (the lake). Note that the duck image in this example has a transparent background. If it had a white background, you would not be able to see the lake photo behind it in the blended version.

Copied to clipboard.

{
  "type": "Image",
  "height": "200dp",
  "width": "300dp",
  "sources": [
    "https://example.com/images/lake.jpg",
    "https://example.com/images/duck.jpg"
  ],
  "filters": [
    {
      "type": "Blend",
      "mode": "normal"
    }
  ]
}

Combining two images with the normal blend mode

The following example shows how you can specify the source and destination images directly. The example swaps the order sources array on the Image component, then uses the source and destination properties to override the defaults, so the duck image is still the source. This version uses the multiply mode to combine the images.

Copied to clipboard.

{
  "type": "Image",
  "sources": [
    "https://example.com/images/duck.jpg",
    "https://example.com/images/lake.jpg"
  ],
  "filters": {
    "type": "Blend",
    "mode": "multiply",
    "source": 0,
    "destination": 1
  }
}

Combining two images with the multiply blend mode. — Combining two images with the multiply blend mode

For examples of using Blend with a solid color or gradient, see the Color and Gradient filters.

Blur

Applies a Gaussian blur with a specified radius to the image, and then adds the new image to the end of the images array.

Property	Type	Default	Description
`type`	Blur	REQUIRED	Set to `Blur`
`radius`	Absolute Dimension	REQUIRED	Radius of the blur effect.
`source`	Integer	-1	Index of the source image in the image array. Defaults to the last image in the array.

The following example shows the Blur filter.

Copied to clipboard.

{
  "type": "Image",
  "height": "200dp",
  "width": "300dp",
  "source": "https://example.com/images/duck.jpg",
  "filters": {
    "type": "Blur",
    "radius": "5dp"
  }
}

Color

Appends a new zero-size solid color to the image array.

Property	Type	Default	Description
`type`	Color	REQUIRED	Set to `Color`
`color`	Color	transparent	Solid color to add to the images array.

When color doesn't contain a value, the filter uses a transparent black color.

On its own, the Color filter doesn't create a modified version of any of the images in the image array. To combine the color with an image, use the Color filter first to add the color to the array, then use the Blend filter.

The following example shows the results of combining the Color and Blend filters. The Blend filter uses the luminosity mode. The source for the Blend filter is the duck image and the destination is the solid color.

Copied to clipboard.

{
  "type": "Image",
  "height": "200dp",
  "width": "300dp",
  "source": "https://example.com/images/duck.jpg",
  "filters": [
    {
      "type": "Color",
      "color": "#B620E0"
    },
    {
      "type": "Blend",
      "mode": "luminosity",
      "source": -2,
      "destination": -1
    }
  ]
}

Combine an image with a solid color using the luminosity blend mode

The overlayColor property of the Image component is equivalent to combining the Color and Blend filters.

Copied to clipboard.

{
  "type": "Image",
  "height": "200dp",
  "width": "300dp",
  "description": "Example of using overlayColor to apply a scrim over the image.  Be sure to specify a color with transparency or it will cover the image.",
  "source": "https://example.com/images/duck.jpg",
  "overlayColor": "rgb(red,20%)"
}

Copied to clipboard.

{
  "type": "Image",
  "height": "200dp",
  "width": "300dp",
  "description": "Example of using the Color and Blend filters apply a scrim over the image. Be sure to specify a color with transparency or it will cover the image.",
  "source": "https://example.com/images/duck.jpg",
  "filters": [
    {
      "type": "Color",
      "color": "rgb(red,20%)"
    },
    {
      "type": "Blend",
      "mode": "normal"
    }
  ]
}

Gradient

Appends a new zero-size gradient to the image array.

Property	Type	Default	Description
`type`	Gradient	REQUIRED	Set to `Gradient`
`gradient`	Gradient	transparent	Gradient

When gradient doesn't contain a value, the filter uses a transparent black color.

On its own, the Gradient filter doesn't create a modified version of any of the images in the image array. To combine the gradient with an image, use the Gradient filter first to add the gradient to the array, then use the Blend filter.

The following example shows the results of combining the Gradient and Blend filters. The Blend filter uses the color-burn mode. The source for the Blend filter is the duck image and the destination is the gradient.

Copied to clipboard.

{
  "type": "Image",
  "height": "200dp",
  "width": "300dp",
  "source": "https://example.com/images/duck.png",
  "filters": [
    {
      "type": "Gradient",
      "gradient": {
        "type": "linear",
        "colorRange": ["#FF000066","#F7C10066","#6DD40066","#0091FF66","#6236FF66"],
        "inputRange": [0,0.25,0.55,0.8,1],
        "angle": 270
      }
    },
    {
      "type": "Blend",
      "mode": "color-burn",
      "source": -2,
      "destination": -1
    }
  ]
}

Combine an image with a gradient using the color-burn blend mode

The overlayGradient property of the Image component is equivalent to combining the Gradient and Blend filters.

Copied to clipboard.

{
  "type": "Image",
  "height": "200dp",
  "width": "300dp",
  "description": "Example of using overlayGradient on the image.",
  "source": "https://example.com/images/duck.png",
  "overlayGradient": "@myGradient"
}

Copied to clipboard.

{
  "type": "Image",
  "height": "200dp",
  "width": "300dp",
  "description": "Example of using the Gradient and Blend filters to apply a gradient overlay.",
  "source": "https://example.com/images/duck.png",
  "filters": [
    {
      "type": "Gradient",
      "gradient": "@myGradient"
    },
    {
      "type": "Blend",
      "mode": "normal"
    }
  ]
}

Both of the previous examples use a gradient defined in resources called myGradient. This creates a radial, rainbow gradient.

Copied to clipboard.

{
  "resources": [
    {
      "gradients": {
        "myGradient": {
          "type": "radial",
          "colorRange": ["#FF000066","#F7C10066","#6DD40066","#0091FF66","#6236FF66"],
          "inputRange": [0,0.25,0.55,0.8,1],
          "angle": 270
        }
      }
    }
  ]
}

Grayscale

Converts the input image to grayscale, and then appends it to the end of the image array.

Property	Type	Default	Description
`type`	Grayscale	REQUIRED	Set to `Grayscale`.
`amount`	Non-negative number	0.0	Proportion of the conversion
`source`	Integer	-1	Index of the source image in the image array. Defaults to the last image in the array.

An amount of 0 leaves the input unchanged. An amount of 1 (100%) results in a completely grayscale image. Amounts greater than 100% are equivalent to 100%. The source image must be a bitmap.

The following example shows a Grayscale filter that makes the image completely grayscale.

Copied to clipboard.

{
  "type": "Image",
  "height": "200dp",
  "width": "300dp",
  "sources": [
    "https://example.com/images/duck.png"
  ],
  "filters": [
    {
      "type": "Grayscale",
      "amount": 1
    }
  ]
}

Noise

Adds generated noise to the image, and then adds the new image to the end of the images array.

Property	Type	Default	Description
`type`	Noise	REQUIRED	Set to `Noise`.
`kind`	uniform, gaussian	gaussian	The probability distribution used to generate the noise.
`useColor`	Boolean	false	When true, use colored noise. When false, generate monochromatic noise.
`sigma`	Number	10	Standard deviation of the noise
`source`	Integer	-1	Index of the source image in the image array. Defaults to the last image in the array.

The Noise filter adds the generated noise to each pixels in the image. The kind property sets the probability distribution to use. When useColor is true, the filter treats the red, green, and blue channels of the image separately.

The sigma property sets the standard deviation of the noise on the color pixels. Each color pixel falls in the range [0,255], so a sigma of 10 means that, on average, a pixel varies from its original value by 10. In practice, the sigma property is commonly set between 5 and 50.

The source image must be a bitmap.

The following example shows the Noise filter.

Copied to clipboard.

{
  "type": "Image",
  "height": "200dp",
  "width": "300dp",
  "source": "https://example.com/images/duck.png",
  "filters": [
    {
      "type": "Noise",
      "useColor": true
    }
  ]
}

Saturate

Changes the color saturation of the image, and then appends the new image to the end of the array.

Property	Type	Default	Description
`type`	Saturate	REQUIRED	Set to `Saturate`.
`amount`	Non-negative number	1.0	Amount of saturation to apply
`source`	Integer	-1	Index of the source image in the image array. Defaults to the last image in the array.

An amount of 0 completed unsaturates the image. An amount of 1 (100%) leaves the image the same. Values greater than 1 produce super-saturation.

The following example shows the Saturate filter.

Copied to clipboard.

{
  "type": "Image",
  "height": "200dp",
  "width": "300dp",
  "sources": [
    "https://example.com/images/duck.png"
  ],
  "filters": [
    {
      "type": "Saturate",
      "amount": 2.0
    }
  ]
}