4

In many Earth Engine functions such as Image.reduceRegions or Image.sample, there is an argument called tileScale. The API documentation generally interprets it as:

A 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.

While this seems to be well documented, I still do not understand the effect of tileScale on the final result of the computation.

  • What does tileScale do?
  • Does tileScale chunks the image before performing the computation?
  • Does it have an effect on the scale?

Below is a code sample to work with (code link).

// Getting the image of the region of interest
var roi = ee.Geometry.Point([1.864578244475683, 14.492292970253338]);
var image = ee.ImageCollection('LANDSAT/LC08/C01/T1_TOA')
                .filterDate('2019-01-01', '2019-01-31')
                .filterBounds(roi)
                .select(['B5', 'B4', 'B3'])
                .toBands()
                .rename(['B5', 'B4', 'B3']);
                
// Checking it out
print(image);

// Define the visualization parameters.
var vizParams = {
  bands: ['B5', 'B4', 'B3'],
  min: 0,
  max: 0.5,
  gamma: [0.95, 1.1, 1]
};

// Center the map and display the image.
Map.centerObject(image, 9);
Map.addLayer(image, vizParams, 'false color composite');

// Computing the band means at 30 meters and tileScale of 1: (Computation succeeded)
var control = image.reduceRegion({
  reducer:ee.Reducer.mean(),
  scale    :  30,
  tileScale:   1, 
  maxPixels:1e13
});

print(control, 'first scenario');

// Computing the band means at 5 meters and tileScale of 1: (Computation succeeded)
var scenario2 = image.reduceRegion({
  reducer:ee.Reducer.mean(),
  scale:        5,
  tileScale:    1, 
  maxPixels: 1e13
});

print(scenario2, 'second scenario');

// Computing the band means at 5 meters and tileScale of 16: (Computation Error: Computation timed out.)
var scenario3 = image.reduceRegion({
  reducer:ee.Reducer.mean(),
  scale:        5,
  tileScale:   16, 
  maxPixels: 1e13
});

print(scenario3, 'third scenario');
4

What does tileScale do? Does tileScale chunks the image before performing the computation?

Yes.

Whenever you perform an operation like reduceRegion, where you're computing one or more reduced values out of an image, the image pixels that go into the reducer are computed in tiles (just like the tiles used for viewing on a map), the reducer is applied to those tiles of pixels to produce intermediate results, and then those intermediate results are combined together.

Setting a higher tileScale reduces the size of those tiles. This means that:

  • Less memory is used by each tile (so the computation is less likely to run out of memory).
  • There are more tiles, which take more time to set up (so the computation will take longer).

Does it have an effect on the scale?

If you mean the resolution / pixel size of the image: no. If the computation succeeds, the result should always be the same regardless of tileScale (except for small differences due to order of floating-point operations).

2
  • Thanks for your time and details @Kevin Reid. Following up on your 2 bullets above, I read somewhere in the documentation that the image is aggregated such that it fits into 256x256 pixel tile and the tileScale argument is treated as tileScale^2. Does is means if I set tileScale: 16, the image will be chunked into 16^2 = 256 tiles? Does that mean the tileScale has to be less or equal than 16? – Liman Sep 4 '20 at 18:28
  • 1
    @Liman The details are subject to change — you should think of it as a tuning parameter, that you adjust based on observed performance, but I believe that's how it works at the moment. However, that doesn't mean the maximum is 16: a tileScale of 256 would mean working in 256^2 = 65536 tiles each 1×1, and 16 would create 256 tiles each 16×16. Of course, 1×1 tiles will be quite slow. – Kevin Reid Sep 4 '20 at 19:26

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.