Determining "primary" asset

[mojodna]

When consuming a STAC Item without detailed knowledge of vendor-specific properties or filename conventions, I'd like to know which asset should be treated as the "primary" one.

Specifically, when pointing STAC Browser at a catalog, I'd like to make an informed choice about which asset to provide an interactive preview for. Since assets is an object, there's no "first" item to use as a default.

We have the thumbnail key (which should also be rel=thumbnail?). Should we also introduce a primary key (and rel) for this purpose?

(Additional keys / rels are already relegated to extension / vendor-specific use, which should handle use-cases like "analytic")

[mojodna]

In the case of datasets with bands split into individual files (Landsat 8), multiple assets may be "primary".

[m-mohr]

What I don't really get: Is primary just a special thumbnail or could it also be used for other purposes? I'm wondering whether we could come up with a more intelligent way of determining the "primary" asset. We would need it anyway for cases without a primary in the assets - or should primary be required? Not sure whether there is always a primary asset though. I am also wondering how we would name the keys for multiple thumbnails. thumbnail, thumbnail2, etc? I agree that asset rel seems very useful (#309) as the asset keys are somewhat restricted. I think we should wait for the asset discussions in 0.7.0 (dict vs. list, asset schemas, etc). We may find solutions there (e.g. using arrays).

[mojodna]

"primary" would be the primary dataset(s) (not thumbnail) associated with an Item--all other items would be derivatives / sidecars, e.g. QA band, etc. Maybe "visual" is actually what I'm looking for here.

"analytic" would be another rel, at least from the Planet perspective.

[cholmes]

I definitely see a need for this. I see it as a 'hint' that a data provider gives to help clients determine what to 'display'. It is more than just a thumbnail, ideally it's the full Cloud Optimized GeoTIFF that can be fully browsed. Indeed having STAC refer to COG's to me is one of the most compelling features, as data can be used right there. But you may have an Unusable Data Mask and a 4-band analytic product both as COG's, and you need a way to hint which should be used in a COG slippy map. So I wouldn't see primary as being required, indeed Items with just one asset wouldn't really need it.

I've also wondered about making the dictionary names useful - like defining some common ones.

But I agree we need to have a fuller discussion for 0.7.0 on asset definitions in general, and keep this bit in mind as something we need to do.

@mojodna - I do think we can experiment with this with STAC browser and a couple of the repositories to show how it would work.

[matthewhanson]

It's certainly a valid use case, but I think you're on the right track that 'primary' isn't the right term here. A 'primary' asset completely depends on the use case, and it's really a vague term.

'visual', 'true-color', 'rgb' are all terms that I think more accurately describes this. You are looking for which asset or assets are needed to display as a byte-scaled 3 color image.

This very much fits in with the asset definition talk. Perhaps part of the asset definition is specifying certain combinations of assets that give a desired set of data:

'usecase': {
    'visual': [ 'B4', 'B3', 'B2'],
    'ard': [ 'B1', 'B2', 'B3', 'B4', 'B5', 'B6', 'B7', 'B8'],
    'qa': ['BQA']
}

In the first use case it tells me that assets with those keys form a 3 band color image, in that order.

In the second use case it tells me that assets with those keys are part of a 3d raster set of data, and it excludes asset keys that represent non-raster sources of data, or QA bands.

In the third use case it tells me which assets are used for quality information.

In reality, the situation is even more complicated than this. In fact, I could have the same assets be used for a visual usecase, as for an ARD use case, but supplying different scales and offsets to the data.

Which is why...we need to discuss this with asset definitions.

[mojodna]

See #316 for proposed changes.

(Agreed that "primary" isn't the right term.)

I also want to reiterate that I anticipate multiple asset types serving a single role being a relatively common occurrence. DG scenes are another example of this where multiple images are "visual" and need to be combined / displayed together to show the full extent of the item.

[matthewhanson]

Since multiple assets serve a single role, the order of those need to be captured somewhere. It is not good enough to just state that 3 bands are used to make a visual image.

[mojodna]

They don't necessarily need to be ordered; the DG images don't overlap (and are each 3 band), so they can be rendered in any order.

Moving assets back to a list would provide a preliminary ordering to draw from.

[simonff]

In Earth Engine, we sort of denote the primary "assets" when we specify the preferred visualization for rasters. In most cases this is just the list of bands, plus maybe gain/bias or min/max, plus maybe a palette. Also a lat/lon/zoom with an interesting viewport. This is done at the collection level - we don't have cases where different items in a collection need different primary assets.

[m-mohr]

I also wondered this morning where/how we could place a collection level thumbnail.

[philvarner]

Rebooting this conversation in light of the new asset-level "role" attribute.

Here's an example of how I'd see this working, with roles "overview", "thumbnail", "analytic", and "visual". (open question - should roles be an array rather than a string?)

I feel a key part here is that I should be able to find assets by their description, without needing to know the implementation-specific, arbitrary object keys that have been assigned to them. I think of it it like a decision tree, that I might first look for all the assets with "eo:common_name == green", then select by "role == analysis" (not visual), then select by "gsd == 10" (not 60), then by media type "type == image/jp2" (not cog).

      "assets": {
        "TCI_60m": {
          "eo:gsd": 60.0,
          "href": "s3://sentinel-s2-l2a/tiles/46/V/CQ/2019/5/27/0/R60m/TCI.jp2",
          "size": 616584,
          "title": "True Color Composite",
          "type": "image/jp2",
          "role": "overview"
        },
        "TCI_60m_jpg": {
          "eo:gsd": 60.0,
          "href": "s3://sentinel-s2-l2a/tiles/46/V/CQ/2019/5/27/0/R60m/TCI.jpg",
          "size": 616584,
          "title": "True Color Composite",
          "type": "image/jpg",
          "role": "overview"
        },
        "TCI_thumb": {
          "eo:gsd": 60.0,
          "href": "s3://sentinel-s2-l2a/tiles/46/V/CQ/2019/5/27/0/preview.jpg",
          "size": 10584,
          "title": "True Color Composite",
          "type": "image/jpg",
          "role": "thumbnail"
        },
        "B03_60m": {
          "eo:common_name": "green",
          "eo:gsd": 60.0,
          "href": "s3://sentinel-s2-l2a/tiles/46/V/CQ/2019/5/27/0/R60m/B03.jp2",
          "size": 616584,
          "title": "Band 3 - Green 0.560μm (60m)",
          "type": "image/jp2",
          "role": "analytic"
        },
      "B03_10m": {
          "eo:common_name": "green",
          "eo:gsd": 10.0,
          "href": "s3://sentinel-s2-l2a/tiles/46/V/CQ/2019/5/27/0/R10m/B03.jp2",
          "size": 8016584,
          "title": "Band 3 - Green 0.560μm (60m)",
          "type": "image/jp2",
          "role": "analytic"
        },
      "B03_10m_cog": {
          "eo:common_name": "green",
          "eo:gsd": 10.0,
          "href": "s3://sentinel-s2-l2a/tiles/46/V/CQ/2019/5/27/0/R10m/B03.TIF",
          "size": 8016584,
          "title": "Band 3 - Green 0.560μm (60m)",
          "type": "image/tiff; application=geotiff",
          "role": "analytic"
        },
        "B03_preview": {
          "eo:common_name": "green",
          "eo:gsd": 60.0,
          "href": "s3://sentinel-s2-l2a/tiles/46/V/CQ/2019/5/27/0/preview/B03.jpg",
          "size": 6584,
          "title": "Band 3 - Green 0.560μm (60m)",
          "type": "image/jpeg",
          "role": "visual"
        },
}

[m-mohr]

open question - should roles be an array rather than a string?

Yes, maybe it should. Similarly to the roles for the providers.

[m-mohr]

Should be solved with #651