Masks

Masks are used to exclude certain pixels from image processing or when computing image statistics. Masked pixels appear as transparent when displayed in a view. This topic describes different methods for creating a mask using ENVI tools and the application programming interface (API). See the following sections:

Background

Before doing any spectral analysis or image processing, you can choose to exclude certain pixels from consideration so that they do not influence the analysis results. Here are some examples:

Masked pixels will be excluded from any processing and will be displayed as transparent in the resulting image (called a masked raster). When you save a masked raster to a file on disk, you must specify a data ignore value.

Data Ignore Value

A data ignore value is a designated pixel value that ENVI should ignore when processing an image or computing statistics.

The Data Ignore Value field is available in the Save File As Parameters dialog when you save an image to disk. For example, if you set the Data Ignore Value to 100, ENVI assigns a value of 100 to the masked pixels and displays them as NoData when the image is displayed in a view.

If you create a masked image and you do not set the Data Ignore Value, ENVI sets those pixel values to 0 and they will be visible (not transparent) when the image is displayed.

If you specify a Data Ignore Value, the pixels with that value will have a pixel state of 1 (NoData) and will be transparent in the view when the image is displayed. See Raster Pixel State in the ENVI API Programming Guide for more information on pixel state.

Here are some frequently asked questions about specifying a data ignore value:

Why does it matter what value I choose? All masked pixels will be ignored and be displayed as transparent, regardless of what value I choose.

The point of a data ignore value is to have a specific value set aside to mark masked pixels, one that is not used elsewhere in your image. If you choose a value that is already used, you risk masking out good pixels.

How do I select a proper data ignore value for my image?

Choose a value that you are certain is not used in any of the valid pixels in the image. In the Save File As Parameters dialog, click the Find Suitable Data Ignore Value button to automatically find a suitable value to use, based on the image statistics and data type.

If you are writing an ENVI+IDL script, see How do I set a data value to ignore? in the ENVI API Programming Guide.

Does the data ignore value have to be of the specified data type?

Yes. If your image consists of byte data whose pixel values range from 0 to 255, you cannot select a data ignore value outside of that range. The same concept applies to other data types. For example, you risk mathematical overflow errors if you choose a negative value when your data is unsigned integer.

Why do my masked pixels not appear when I processed a masked raster and display the result?

Certain ENVI processes do not fully support pixel state, and you might not get a fully masked raster with transparent masked pixels as a result. In these cases, all output masked pixels will have a pixel value of 0 (normally shown as black). We recommend that you reapply masking by saving the result to a new file on disk. Select File > Save As > Save As (ENVI, NITF, TIFF, DTED) from the menu bar, select the masked raster as input, provide a valid data ignore value, then select an output filename and location.

The next section describes different options for creating masks in ENVI.

Options for Creating a Mask

You can create a mask from a region of interest (ROI), from a shapefile, by creating binary rasters, or by using options available in the Build Raster Mask tool. This section describes each option.

Regions of Interest (ROIs)

A common scenario is to create ROIs to define pixels that you want to include or exclude from image processing. Follow these steps to create a mask from ROIs. You will not see the binary mask; ENVI creates it internally and applies it to the input image.

  1. Display the input image, then select File > New > Region of Interest from the menu bar.
  2. Choose whether to create ROIs from band thresholds or from geographic features of interest:
    • To create an ROI from specific data values (for example, all pixels with a value of 0), follow the steps in Create ROIs from Band Thresholds. This is the preferred method when defining background pixels or invalid image data.
    • To create an ROI from geographic features, follow the steps in Create ROIs from Geometry. Use the Polygon option to draw polygon ROIs around the features.
  3. From the Region of Interest Tool, select File > Save As and save the ROI to .xml format.
  4. From the menu bar, select File > Save As > Save As (ENVI, NITF, TIFF, DTED).
  5. In the Data Selection dialog, select the input image and click the Mask button.
  6. Select the ROI that you created.
  7. Enable the Inverse mask option if you want to create an inverse mask.
  8. Click OK.
  9. Enter a Data Ignore Value.
  10. Click OK.
  11. Select an output format and filename, then click OK.
  12. When processing is complete and the image is displayed, open the Cursor Value tool to verify that the masked pixels have values of NoData. The image is now ready for further processing.

Programming API

You can also write an ENVI+IDL script to create and apply a mask from ROIs. Use the ENVIROIMaskRaster routine as the following code example shows. Or, use the ROIMaskRaster task when writing a script that uses ENVITasks. To specify a single ROI in a multi-part ROI file, use the bracket notation (for example, rois[2]).

; Start the application

e = envi()

 

; Open an input raster

file = FILEPATH('qb_boulder_msi', ROOT_DIR=e.root_dir, $

  SUBDIRECTORY=['data'])

raster = e.OpenRaster(file)

 

; Open ROIs

ROIFile = FILEPATH('qb_boulder_roi.xml', $

  ROOT_DIR=e.root_dir, SUBDIRECTORY=['data'])

rois = e.OpenROI(ROIFile)

 

; Create a masked raster

maskedRaster = ENVIROIMaskRaster(raster, rois)

 

; Display the masked raster

view = e.GetView()

layer = view.CreateLayer(maskedRaster)

Vectors

You can create a mask from a vector (for example, a shapefile). An example is masking pixels outside of a watershed boundary as the following image shows:

Tip: You can draw vectors in ENVI to define areas of interest, then export them to shapefiles. See the Vectors topic for details.

If you have a shapefile that contains multiple records and you only want to create a mask from one record, follow these steps to isolate the individual record:

  1. Display the shapefile.
  2. Right-click on the shapefile in the Layer Manager and select View/Edit Attributes.
  3. Click on a specific record in the display or in the Attribute Viewer.
  4. From the Attribute Viewer menu, select File > Save Selected Records to a New Shapefile.
  5. In the Select Output Shapefile Name dialog, select Shapefile for the Output Format.
  6. Select an output filename, then click OK.

Follow these steps to create and apply a mask from a shapefile.

  1. Open the input image and shapefile.
  2. From the menu bar, select File > Save As > Save As (ENVI, NITF, TIFF, DTED).
  3. In the Data Selection dialog, select the input image and click the Mask button.
  4. Select the shapefile.
  5. Enable the Inverse mask option if you want to create an inverse mask.
  6. Click OK.
  7. Enter a Data Ignore Value.
  8. Click OK.
  9. Select an output format and filename, then click OK.

Programming API

You can also write an ENVI+IDL script to create and apply a mask from a shapefile. Use the ENVIVectorMaskRaster routine as the following code example shows. Or, use the VectorMaskRaster task when writing a script that uses ENVITasks.

; Start the application

e = envi()

 

; Open an input raster

file = FILEPATH('qb_boulder_msi', ROOT_DIR=e.root_dir, $

  SUBDIRECTORY=['data'])

raster = e.OpenRaster(file)

 

; Create a mask from a shapefile

vectorFile = FILEPATH('qb_boulder_msi_vectors.shp', $

  ROOT_DIR=e.root_dir, SUBDIRECTORY=['data'])

vector = e.OpenVector(vectorFile)

 

; Create a masked raster

maskedRaster = ENVIVectorMaskRaster(raster, vector)

 

; Display the masked raster

view = e.GetView()

layer = view.CreateLayer(maskedRaster)

The above example creates and applies a mask to a raster. Another task called GenerateMaskFromVector creates a binary raster only without applying it to another raster.

Binary Rasters

A binary raster contains pixel values of 0 and 1, for example:

When applied to a source image, it indicates which pixels should be processed and which pixels should be ignored.

You can use the Binary Raster by Automatic Threshold tool to create a binary raster from threshold values that are automatically determined from an image. This can be useful for binary classification of an image.

You can also use the following steps for the Build Raster Mask tool to create a binary raster from specific pixel values or ranges of pixel values:

  1. Display an image that you want to mask.
  2. From the Toolbox, select Raster Management > Build Raster Mask. The Build Mask Input File dialog appears.
  3. Select the input file and click OK. The Mask Definition dialog appears.
  4. From the Mask Definition dialog menu bar, select Options > Import Data Range. The Select Input for Mask Data Range dialog appears.
  5. Enter a minimum and/or maximum value in the Data Min Value and Data Max Value fields. If you enter only a minimum or maximum value, the data’s actual maximum or minimum, respectively, will be used as the other end value. If the input file has a data ignore value, then the dialog opens with the values automatically entered in these fields.
  6. Select either Mask pixel if ALL bands match range or Mask pixel if ANY bands match range. The ALL option includes all pixels that are in the data range for all bands (a logical AND operation). The ANY option includes all pixels that are in the data range for any band (a logical OR operation).
  7. Click OK to enter the range into the mask definition list.
  8. Choose to output the result to file or memory.
  9. Click OK.

Tip: The Build Raster Mask functionality is also available in select tools when you select an input file. When you select an input file, click the Mask Options drop-down button to create a binary mask using the methods described here.

Programming API

You can use the ENVI API to create and apply a mask based on pixel values above or below a given threshold.

Use the BinaryAutomaticThresholdRaster task to create a binary mask using automatically determined threshold values. Or, created a masked image using custom threshold values, as the following example shows.

This example creates a mask where pixels greater than 220 are set to 1 all others are set to 0. The original image is multispectral, so the code example uses ENVISubsetRaster to create a spectral subset consisting of only one band. Use ENVIBinaryGTThresholdRaster to create the binary mask, as this example shows. (Or, use the BinaryGTThresholdRaster task when writing a script that uses ENVITasks.) Finally, use ENVIMaskRaster to apply the mask to the single-band image.

; Start the application

e = ENVI()

 

; Open an input file

file = FILEPATH('qb_boulder_msi', ROOT_DIR=e.ROOT_DIR, $

SUBDIRECTORY=['data'])

raster = e.OpenRaster(file)

 

; Create a binary mask by thresholding the first band

subset = ENVISubsetRaster(raster, BAND=[0])

threshold = [220.]

binaryMask = ENVIBinaryGTThresholdRaster(subset, threshold)

 

; Optionally export the binary mask to disk

outFile = e.GetTemporaryFilename()

binaryMask.Export, outFile, 'ENVI'

 

; Apply the mask to the single-band raster

maskedRaster = ENVIMaskRaster(subset, binaryMask)

 

; Display the masked raster

view = e.GetView()

layer = view.CreateLayer(maskedRaster)

You can similarly use the ENVIBinaryLTThresholdRaster routine to create a mask where pixels less than a given threshold are masked.

You can also use the ENVI API to create and apply a mask based on ranges of pixel values. The following example masks out pixels that range from 0 to 220 and 700 to 10,000.

Use ENVIDataValuesMaskRaster to create the binary mask, as this example shows. (Or, use the DataValuesMaskRaster task when writing a script that uses ENVITasks). Finally, use ENVIMaskRaster to apply the mask to the image.

; Start the application

e = ENVI()

 

; Open an input file

file = FILEPATH('qb_boulder_msi', ROOT_DIR=e.ROOT_DIR, $

  SUBDIRECTORY=['data'])

raster = e.OpenRaster(file)

 

; Define the data ranges

ranges = [[0,220], [700, 10000]]

 

; Create a masked raster

maskedRaster = ENVIDataValuesMaskRaster(raster, ranges)

 

; Display the masked raster

view = e.GetView()

layer = view.CreateLayer(maskedRaster)

Build Raster Mask Options

The Build Raster Mask tool has other options to help you build masks, including from finite values, from NaN values, from ROI files, and from ENVI vector files (EVFs).

To mask finite values, select Options > Mask Finite Values from the Mask Definition dialog menu bar. Select an input file and click OK. In the FINITE Option dialog, select an option and click OK:

To mask NaN (Not a Number) data values, select Options > Mask NaN Values from the Mask Definition dialog menu bar. Select an input file and click OK. In the NaN Option dialog, select an option and click OK:

To use a region of interest (ROI) as the basis for a mask, select Options > Import ROIs from the Mask Definition menu bar. Select an .roi or .xml file, select the ROIs, and click OK. All imported ROIs are treated as a single mask layer.

To use an ENVI Vector File (EVF) as the basis for a mask, select Options > Import EVFs from the Mask Definition dialog menu bar. Select the vector file to input, then click OK.

To set the defined areas in the mask to 1 (On) or to 0 (Off), select Options > Selected Areas On/Off from the Mask Definition dialog menu bar. By choosing Selected Areas Off, the masked pixels will have a value of 0, meaning that those areas of the source image will be ignored during image processing after applying the mask.

The mask is built using a Logical OR or Logical AND operation between all of the items in the list. The default, Logical OR, uses all the defined areas to make the mask. Using the Logical AND masks only the areas where all of the defined areas overlap. Selected areas are those pixels that satisfy the masking criteria.

To define the mask using only those areas where the listed data ranges, annotation shapes, and/or ROIs overlap, select Options > Selected Attributes [Logical AND] from the Mask Definition dialog menu bar.

To use all the defined areas to make the mask, select Options > Selected Attributes [Logical OR] from the Mask Definition dialog menu bar.

To delete an item from the Selected Attributes list in the Mask Definition dialog, highlight the item and click Delete Item.

To remove all items from the Selected Attributes list in the Mask Definition dialog, click Delete All Items.

The next section describes different ways that you can select masked rasters in ENVI once you have created them.

Options for Selecting Masked Rasters

Here are some different ways to select a masked raster in ENVI.

ENVI User Interface

Click the Mask button in the Data Selection dialog. This option accepts ROIs, vectors, and binary mask rasters. The Regions of Interest (ROIs) and Shapefile instructions (earlier in this topic) used this option.

Click the Select Mask Band button to select a raster mask:

Specify an Input Mask in workflows. This option accepts vectors and binary mask rasters.

ENVI API

If you are writing a programming script using the ENVI API, several routines are available to help you create and define masked rasters. These are described in the Options for Creating a Mask section in this help topic.

You can also use masks with most ENVITasks. See Masking Support in ENVITasks for a complete list. You create a mask first, then set the task INPUT_RASTER property to the mask. The following code example creates and applies a mask using a shapefile, then it uses the masked raster as input to ISODATA classification.

; Start the application

e = envi()

 

; Open an input raster

file = FILEPATH('qb_boulder_msi', ROOT_DIR=e.root_dir, $

  SUBDIRECTORY=['data'])

raster = e.OpenRaster(file)

 

; Open an input shapefile vector

vectorFile = FILEPATH('qb_boulder_msi_vectors.shp', $   

  ROOT_DIR=e.root_dir, SUBDIRECTORY=['data'])

vector = e.OpenVector(vectorFile)

 

; Create a masked raster

maskedRaster = ENVIVectorMaskRaster(raster, vector)

 

; Get the classification task

task = ENVITask('ISODATAClassification')

 

; Define task inputs

task.INPUT_RASTER = maskedRaster

task.NUMBER_OF_CLASSES = 3

 

; Run the task

task.Execute

 

; Display the classification image

view = e.GetView()

layer = view.CreateLayer(task.OUTPUT_RASTER)

view.zoom, /FULL_EXTENT

See Also

Calculate Cloud Mask Using Fmask, Raster Pixel State