APL Filters

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.

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 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
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"
  }
}
Blur filter
Blur filter

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
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
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
    }
  ]
}
Grayscale filter
Grayscale filter

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
    }
  ]
}
Noise filter
Noise filter

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
    }
  ]
}
Saturate filter
Saturate filter

Images used in examples: