Masking images

Image masking is a method for making areas of an image transparent. Images are defined as rectangular, but their contents can have irregular shapes. For example, an image that contains the land mass for a country has areas that are outside the country's borders. These areas are called fill, or no-data regions, and they are usually black or white. When the image is overlaid on a base map, these areas should be transparent, to allow the base map to show through.

A mask is a set of pixels that specifies where to make an image transparent. By default, Maps Engine automatically applies a mask when it processes an image but you can also provide custom mask data or prevent masking altogether.

This article describes the masking mode options and how to change modes.

Masking mode options

The masking options are auto mask, alpha channel mask, associated file, and no mask. The associated file option appears only if you upload a mask file with the source image.

Auto mask

Maps Engine uses auto masking by default. Auto masking applies if a contiguous region is either all black or all white and touches a corner of the image rectangle.

Auto masking is not recommended for an image whose no-data regions do not touch a corner. Those regions are considered "holes" in the image and are supported only by alpha channel masks and masking files.

Alpha channel mask

If an image file contains an alpha channel, Maps Engine uses it to mask the no-data regions. The alpha channel mask can cover arbitrary regions that do not touch a corner of the image, called "holes." In an alpha channel, values should be 0 for transparent pixels and 255 for non-transparent pixels. Transparent pixels in the mask make the underlying imagery visible, whereas non-transparent pixels in the mask occlude the underlying imagery. Maps Engine does not currently support partial transparency.

Maps Engine determines which channel contains the mask as follows:

  • You can order the channels in any order. The alpha channel does not necessarily need to be the fourth channel.
  • If there are two channels or four channels and Maps Engine cannot determine the type of the last channel, it treats the channel as an alpha channel.

Auto masking can work on four-channel images only if the fourth channel has a color interpretation of alpha or if it is unknown. If the fourth channel is used for something other than a mask, such as near infrared, use the auto mask mode or associated file mode.

Associated file

If you upload a separate mask file with the image file, Maps Engine uses the Associated file masking mode, even if the image file also has an alpha channel mask. A mask file is an extra gray-scale file that's useful if the source image does not contain an alpha channel, or if it uses an alpha channel for something other than masking.

Like an alpha channel mask, a masking file can cover holes. Values should be 0 for transparent pixels and 255 for non-transparent pixels.

You can provide a mask file for any of the supported imagery types. The mask must have the same resolution as the image.

The mask file name must have the following format:


The name must be exactly the same as the source file name, but with -mask appended. Here's an example:

  • Source file: NewYork.tif
  • Mask file: NewYork-mask.tif

No mask

This option specifies that you want fill areas to occlude the underlying image.

Changing the imagery masking mode

Masking is specified on a per-image basis. To apply masking to a mosaic, you must mask each image in the mosaic.

When you change the masking mode for an image, you'll need to reprocess the image. Furthermore, the status of all layers and mosaics that contain the image change to ...not ready to reprocess until Maps Engine finishes reprocessing the image. At that point, the layer or mosaic status changes to ready to process. If the image is part of a mosaic, first reprocess the mosaic and then reprocess the layer that contains the mosaic.

Was this article helpful?