Bands RFC #1213

[m-mohr]

Related Issue(s): #1213

Proposed Changes:

• bands is a new field in common metadata to replace eo:bands and raster:bands (#1213)
• The fields data_type, nodata, statistics and unit have been added to common metadata (#1213)

This PR needs to wait for the EO and Raster Extension PRs.

ToDo:

• infinity, NaN in band statistics stac-extensions/raster#40
• Draft version 2.0 of eo:bands stac-extensions/eo#27
• Update to use STAC 1.1 bands stac-extensions/raster#45
• EO extension for STAC 1.1 stac-extensions/eo#29

PR Checklist:

• This PR is made against the dev branch (all proposed changes except releases should be against dev, not master).
• This PR has no breaking changes.
• I have added my changes to the CHANGELOG
  or a CHANGELOG entry is not required.
• This PR affects the STAC API spec,
  and I have opened issue/PR #XXX to track the change.

[emmanuelmathot]

Concerning the last commit, there is no way to make suggestions on unchanged file so I simply committed it. Let me know.

[m-mohr]

We should discuss whether we want to explicitly disallow to use of "bands" for single-band use-cases where instead people must provide the properties at the asset/item properties level directly.

[emmanuelmathot]

We should discuss whether we want to explicitly disallow to use of "bands" for single-band use-cases where instead people must provide the properties at the asset/item properties level directly.

I vote +1 for disallowing unique band

[emmanuelmathot]

@m-mohr Are we good for a merge in dev? At least to be able to release a beta version to validate extensions and pending PR that requires the band construct?

[m-mohr]

The extensions should validate without requiring 1.1.

I think we could do the following:

• Finish and merge extension PRs (potentially changing the base branch temporarily to the latest stable version to not confuse readers) - started this for eo
• Release rc.1 versions
• Update and merge this PR
• Release 1.1.0-rc.1 version of STAC
• Prepare everything for 1.1.0 (especially examples)
• Let users check everything for a month or two
• Release new stable versions for everything
• Change the base branch to main again

stac-extensions/raster#45 should finally be ready for review!

[m-mohr]

We should probably discuss in the PR when properties should be used on the asset level and when people should have a single-element bands array. I assume it's just if it's a named entity (i.e. name is required)?

[emmanuelmathot]

you mean allowing single band to be able to set properties only at band level?

[m-mohr]

I meant guiding users between the different options.

Single Band

For a single band asset, you could for example do one of the two options:

(1)

{
  "assets": {
    "example": {
      "href": "example.tif",
      "bands": [
        {
          "data_type": "uint16",
          "eo:common_name": "red",
          "raster:spatial_resoltion": 10
        }
      ]
    }
  }
}

or

(2)

{
  "assets": {
    "example": {
      "href": "example.tif",
      "data_type": "uint16",
      "eo:common_name": "red",
      "raster:spatial_resoltion": 10
    }
  }
}

If you add a name, it get's even more unclear:

(3)

{
  "assets": {
    "example": {
      "href": "example.tif",
      "bands": [
        {
          "name": "r",
          "data_type": "uint16",
          "eo:common_name": "red",
          "raster:spatial_resoltion": 10
        }
      ]
    }
  }
}

Would you then do the following?

(4)

{
  "assets": {
    "example": {
      "href": "example.tif",
      "data_type": "uint16",
      "eo:common_name": "red",
      "raster:spatial_resoltion": 10,
      "bands": [
        {
          "name": "r"
        }
      ]
    }
  }
}

Multi-band

And then for multi-band files, you can often also de-duplicate some properties.

Old example from 1.0:
(5)

{
  "assets": {
    "example": {
      "href": "example.tif",
      "eo:bands": [
        {
          "name": "r",
          "common_name": "red"
        },
        {
          "name": "g",
          "common_name": "green"
        },
        {
          "name": "b",
          "common_name": "blue"
        }
      ],
      "raster:bands": [
        {
          "data_type": "uint16",
          "spatial_resolution": 10
        },
        {
          "data_type": "uint16",
          "spatial_resolution": 10
        },
        {
          "data_type": "uint16",
          "spatial_resolution": 10
        }
      ]
    }
  }
}

If you would just merge them, you end up with:
(6)

{
  "assets": {
    "example": {
      "href": "example.tif",
      "bands": [
        {
          "name": "r",
          "eo:common_name": "red",
          "data_type": "uint16",
          "raster:spatial_resolution": 10
        },
        {
          "name": "g",
          "eo:common_name": "green",
          "data_type": "uint16",
          "raster:spatial_resolution": 10
        },
        {
          "name": "b",
          "eo:common_name": "blue",
          "data_type": "uint16",
          "raster:spatial_resolution": 10
        }
      ]
    }
  }
}

But ideally, I think, you could simplify to:
(7)

{
  "assets": {
    "example": {
      "href": "example.tif",
      "data_type": "uint16",
      "raster:spatial_resolution": 10,
      "bands": [
        {
          "name": "r",
          "eo:common_name": "red"
        },
        {
          "name": "g",
          "eo:common_name": "green"
        },
        {
          "name": "b",
          "eo:common_name": "blue"
        }
      ]
    }
  }
}

I think the difference between 5 and 7 shows the beauty of the new concept nicely ;-)

Edit: I tried to write something in best practices: 5b9af3b Please review.