Data Fusion

Data fusion lets you combine more than one data source in a single request. Each source is requested with its own filters (for example, its own time range) and is made available to the evalscript under its own identifier. This is useful to:

• Combine different collections — for example, fill cloudy Sentinel-2 pixels with Sentinel-1 radar, or pan-sharpen one collection with another.
• Compare the same collection at two dates — for example, before/after change detection, where the two acquisition dates come from the request rather than being hardcoded in the evalscript.

Data fusion is available across the data-processing APIs (Processing, Statistical, Batch, and others).

note

Combining collections hosted in different regions is only supported by the Processing API. Other APIs require all sources to be in the same region.

note

A data fusion request processes more than one input, so it can consume more processing units than a single-source request. See processing units for how the cost is calculated.

Request Body

In the input.data array, add one object per source. Give each one an id — a string of your choosing — so it can be referenced from the evalscript. All collection-specific filters and processing options remain available per source.

{
  "input": {
    "data": [
      {
        "type": "byoc-<your-collection-id>",
        "id": "before",
        "dataFilter": {
          "timeRange": {
            "from": "2022-04-26T00:00:00Z",
            "to": "2022-04-26T23:59:59Z"
          }
        }
      },
      {
        "type": "byoc-<your-collection-id>",
        "id": "after",
        "dataFilter": {
          "timeRange": {
            "from": "2022-08-05T00:00:00Z",
            "to": "2022-08-05T23:59:59Z"
          }
        }
      }
    ]
  }
}

tip

The id is technically optional, but specifying it is recommended. The collection type alone is not enough to tell two inputs apart when both come from the same collection (as in the before/after example above).

Evalscript Setup

In the setup function, declare one input object per source and set its datasource to match the id from the request body. This binds each input's bands to the correct source.

//VERSION=3
function setup() {
  return {
    input: [
      { datasource: 'before', bands: ['red', 'nir', 'dataMask'] },
      { datasource: 'after', bands: ['red', 'nir', 'dataMask'] },
    ],
    output: { bands: 1, sampleType: 'FLOAT32' },
    mosaicking: 'SIMPLE',
  };
}

If you omit datasource, the order of the input objects must match the order of the data array in the request body.

Per-input Mosaicking

You can set a mosaicking value on each input object, which overrides the global mosaicking. The default is SIMPLE.

input: [
  { datasource: 'before', bands: ['red', 'nir'], mosaicking: 'ORBIT' },
  { datasource: 'after', bands: ['red', 'nir'], mosaicking: 'ORBIT' },
],

Accessing Data

In evaluatePixel, the samples parameter is an object keyed by datasource. Each key holds an array of mosaics — even with SIMPLE mosaicking, where the array contains a single mosaic (or is empty if there is no data). This differs from a single-source request, where samples is not keyed by datasource.

function evaluatePixel(samples) {
  var before = samples.before[0]; // first mosaic of the "before" source
  var after = samples.after[0]; // first mosaic of the "after" source
  // access bands per source, e.g. before.nir, after.red
}

If datasource was not specified in setup, access the inputs by their ordinal position as a string key instead (samples['0'], samples['1'], …), in the order they appear in the request body.

note

With ORBIT or TILE mosaicking each datasource array can hold more than one mosaic. With SIMPLE mosaicking — the most common case for data fusion — each array holds at most one.

Example

For a complete, runnable example, see Comparing two dates to perform change detection, which fuses two dates of the same collection to compute an NDVI difference.