ee.Image.sample

Stay organized with collections Save and categorize content based on your preferences.
Samples the pixels of an image, returning them as a FeatureCollection. Each feature will have 1 property per band in the input image. Note that the default behavior is to drop features that intersect masked pixels, which result in null-valued properties (see dropNulls argument).

UsageReturns
Image.sample(region, scale, projection, factor, numPixels, seed, dropNulls, tileScale, geometries)FeatureCollection
ArgumentTypeDetails
this: imageImageThe image to sample.
regionGeometry, default: nullThe region to sample from. If unspecified, uses the image's whole footprint.
scaleFloat, default: nullA nominal scale in meters of the projection to sample in.
projectionProjection, default: nullThe projection in which to sample. If unspecified, the projection of the image's first band is used. If specified in addition to scale, rescaled to the specified scale.
factorFloat, default: nullA subsampling factor, within (0, 1]. If specified, 'numPixels' must not be specified. Defaults to no subsampling.
numPixelsLong, default: nullThe approximate number of pixels to sample. If specified, 'factor' must not be specified.
seedInteger, default: 0A randomization seed to use for subsampling.
dropNullsBoolean, default: truePost filter the result to drop features that have null-valued properties.
tileScaleFloat, default: 1A scaling factor used to reduce aggregation tile size; using a larger tileScale (e.g. 2 or 4) may enable computations that run out of memory with the default.
geometriesBoolean, default: falseIf true, adds the center of the sampled pixel as the geometry property of the output feature. Otherwise, geometries will be omitted (saving memory).

Examples

Code Editor (JavaScript)

// Demonstrate extracting pixels from an image as features with
// ee.Image.sample(), and show how the features are aligned with the pixels.

// An image with one band of elevation data.
var image = ee.Image('CGIAR/SRTM90_V4');
var VIS_MIN = 1620;
var VIS_MAX = 1650;
Map.addLayer(image, {min: VIS_MIN, max: VIS_MAX}, 'SRTM');

// Region to sample.
var region = ee.Geometry.Polygon(
  [[[-110.006, 40.002],
    [-110.006, 39.999],
    [-109.995, 39.999],
    [-109.995, 40.002]]], null, false);
// Show region on the map.
Map.setCenter(-110, 40, 16);
Map.addLayer(ee.FeatureCollection([region]).style({"color": "00FF0022"}));

// Perform sampling; convert image pixels to features.
var samples = image.sample({
  region: region,

  // Default (false) is no geometries in the output.
  // When set to true, each feature has a Point geometry at the center of the
  // image pixel.
  geometries: true,

  // The scale is not specified, so the resolution of the image will be used,
  // and there is a feature for every pixel. If we give a scale parameter, the
  // image will be resampled and there will be more or fewer features.
  //
  // scale: 200,
});

// Visualize sample data using ee.FeatureCollection.style().
var styled = samples
  .map(function (feature) {
    return feature.set('style', {
      pointSize: feature.getNumber('elevation').unitScale(VIS_MIN, VIS_MAX)
          .multiply(15),
    });
  })
  .style({
    color: '000000FF',
    fillColor: '00000000',
    styleProperty: 'style',
    neighborhood: 6,  // increase to correctly draw large points
  });
Map.addLayer(styled);

// Each sample feature has a point geometry and a property named 'elevation'
// corresponding to the band named 'elevation' of the image. If there are
// multiple bands they will become multiple properties. This will print:
//
// geometry: Point (-110.01, 40.00)
// properties:
//   elevation: 1639
print(samples.first());