stac-spec

stac-spec copied to clipboard

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:

• https://github.com/stac-extensions/raster/issues/40
• https://github.com/stac-extensions/eo/issues/27

PR Checklist:

• [x] This PR is made against the dev branch (all proposed changes except releases should be against dev, not master).
• [x] This PR has no breaking changes.
• [x] 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.

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

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.

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

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

https://github.com/stac-extensions/raster/pull/45 should finally be ready for review!

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)?

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

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: https://github.com/radiantearth/stac-spec/pull/1254/commits/5b9af3b240848cb2828206485354dfe449a77bfe Please review.