Announcement : All noncommercial projects registered to use Earth Engine before April 15, 2025 must verify noncommercial eligibility to maintain access. If you have not verified by September 26, 2025, your access may be on hold.

ee.Image.mask

AI-generated Key Takeaways

The Image.mask() method is used to get or set an image's mask.
When setting a mask, pixels where the mask value changes to zero will be filled with zeros or the closest values to zero.
The functionality to set a mask using Image.mask() will be deprecated and replaced by Image.updateMask and Image.unmask .
Calling Image.mask() without an argument returns an image representing the input image's mask, scaled to a 0-1 range.
The mask can be applied to all image bands or a single band.

Gets or sets an image's mask. The output image retains the metadata and footprint of the input image. Pixels where the mask changes from zero to another value will be filled with zeros, or the values closest to zero within the range of the pixel type.

Usage	Returns
`Image. mask ( mask )`	Image

Argument	Type	Details
this: `image`	Image	The input image.
`mask`	Image, default: null	The mask image. If specified, the input image is copied to the output but given the mask by the values of this image. If this is a single band, it is used for all bands in the input image. If not specified, returns an image created from the mask of the input image, scaled to the range [0:1] (invalid = 0, valid = 1.0).

Examples

Code Editor (JavaScript)

 // A Sentinel-2 surface reflectance image. 
 var 
  
 img 
  
 = 
  
 ee 
 . 
 Image 
 ( 
 'COPERNICUS/S2_SR/20210109T185751_20210109T185931_T10SEG' 
 ); 
 var 
  
 trueColorViz 
  
 = 
  
 { 
  
 bands 
 : 
  
 [ 
 'B4' 
 , 
  
 'B3' 
 , 
  
 'B2' 
 ], 
  
 min 
 : 
  
 0 
 , 
  
 max 
 : 
  
 2700 
 , 
  
 gamma 
 : 
  
 1.3 
 }; 
 print 
 ( 
 'Sentinel-2 image' 
 , 
  
 img 
 ); 
 Map 
 . 
 setCenter 
 ( 
 - 
 122.36 
 , 
  
 37.47 
 , 
  
 10 
 ); 
 Map 
 . 
 addLayer 
 ( 
 img 
 , 
  
 trueColorViz 
 , 
  
 'Sentinel-2 image' 
 ); 
 // Get masks for all image bands; each band has an independent mask. 
 // Valid pixels are value 1, invalid are 0. 
 var 
  
 multiBandMaskImg 
  
 = 
  
 img 
 . 
 mask 
 (); 
 print 
 ( 
 'Multi-band mask image' 
 , 
  
 multiBandMaskImg 
 ); 
 Map 
 . 
 addLayer 
 ( 
 multiBandMaskImg 
 , 
  
 null 
 , 
  
 'Multi-band mask image' 
 ); 
 // Get the mask for a single image band. 
 var 
  
 singleBandMaskImg 
  
 = 
  
 img 
 . 
 select 
 ( 
 'B1' 
 ). 
 mask 
 (); 
 print 
 ( 
 'Single-band mask image' 
 , 
  
 singleBandMaskImg 
 ); 
 Map 
 . 
 addLayer 
 ( 
 singleBandMaskImg 
 , 
  
 null 
 , 
  
 'Single-band mask image' 
 );

Python setup

See the Python Environment page for information on the Python API and using geemap for interactive development.

 import 
  
 ee 
 import 
  
 geemap.core 
  
 as 
  
 geemap

Colab (Python)

 # A Sentinel-2 surface reflectance image. 
 img 
 = 
 ee 
 . 
 Image 
 ( 
 'COPERNICUS/S2_SR/20210109T185751_20210109T185931_T10SEG' 
 ) 
 true_color_viz 
 = 
 { 
 'bands' 
 : 
 [ 
 'B4' 
 , 
 'B3' 
 , 
 'B2' 
 ], 
 'min' 
 : 
 0 
 , 
 'max' 
 : 
 2700 
 , 
 'gamma' 
 : 
 1.3 
 , 
 } 
 display 
 ( 
 'Sentinel-2 image' 
 , 
 img 
 ) 
 m 
 = 
 geemap 
 . 
 Map 
 () 
 m 
 . 
 set_center 
 ( 
 - 
 122.36 
 , 
 37.47 
 , 
 10 
 ) 
 m 
 . 
 add_layer 
 ( 
 img 
 , 
 true_color_viz 
 , 
 'Sentinel-2 image' 
 ) 
 # Get masks for all image bands each band has an independent mask. 
 # Valid pixels are value 1, invalid are 0. 
 multi_band_mask_img 
 = 
 img 
 . 
 mask 
 () 
 display 
 ( 
 'Multi-band mask image' 
 , 
 multi_band_mask_img 
 ) 
 m 
 . 
 add_layer 
 ( 
 multi_band_mask_img 
 , 
 None 
 , 
 'Multi-band mask image' 
 ) 
 # Get the mask for a single image band. 
 single_band_mask_img 
 = 
 img 
 . 
 select 
 ( 
 'B1' 
 ) 
 . 
 mask 
 () 
 display 
 ( 
 'Single-band mask image' 
 , 
 single_band_mask_img 
 ) 
 m 
 . 
 add_layer 
 ( 
 single_band_mask_img 
 , 
 None 
 , 
 'Single-band mask image' 
 ) 
 m