Awesome

Classification Extension Specification

• Title: Classification
• Identifier: https://stac-extensions.github.io/classification/v2.0.0/schema.json
• Field Name Prefix: classification
• Scope: Item, Collection
• Extension Maturity Classification: Pilot
• Owner: @drwelby @m-mohr @pjhartzell

This document explains the Classification Extension to the SpatioTemporal Asset Catalog (STAC) specification.

• Examples:
  • Asset level:
    • Raster Classes example: STAC Item with classified raster bands in asset (Maxar)
    • Bitfields example: STAC Item with bit fields in asset (Landsat)
  • Item level:
    • Model Classes example: STAC Item with classes of a Machine Learning Model output
  • Collection level:
    • Item Assets example: STAC Collection using Item Assets for classed child Items
• JSON Schema
• Changelog

Note that Classification in this context is about providing semantic information on the pixel content. It does not relate in any way to security classification or other confidentiality labeling.

Classification Types

classification:classes is for when one or more unique coded integer values are present within a raster asset or band therein. These coded values translate to classes of data with verbose descriptions.

An example would be a cloud mask raster that stores values that represent image conditions in each pixel.

classification:bitfields is for classes that are stored in fields of continuous bits within the pixel's value. Files using this strategy are commonly given the name 'bit mask' or 'bit index'. The values stored are the integer representation of the bits in the field when summed as an isolated string. Bits are always read right to left. The position of the first bit in a field is given by its offset. Therefore the first (rightmost) bit is at offset zero.

These classification objects can be used in the following places:

• In a raster Asset object if single band.
• For multiband rasters, use raster:bands and store the classes in each Band Object.
• In a Machine Learning Model output object to define the classes represented within that output.
• As an item-assets field in a Collection object, to indicate that the classification is used across child Items.

Bit Field Object

Describes multiple classes stored in a field of a continuous range of bits

A Bit Field stores classes within a range of bits in a data value. The range is described by the offset of the first bit from the rightmost position, and the length of bits used to store the class values.

Since bit fields are often used to store data masks, they can also use optional STAC roles to identify their purpose to clients.

Following is a simplified example a bit field scheme for cloud data using 4 bits. The bits are broken into 3 bit fields.

3210
||||
...X   - 1 here means "no data", 0 means "valid data"
..X.   - 1 here means "cloud pixel", 0 means "clear pixel"
XX..   - these two bits are "cloud confidence" and give 4 classes (binary 00, 01, 10, and 11)

Working right to left, these four bits represent 3 bit fields:

• ...X is offset:0, length:1
• ..X. is offset:1, length:1
• XX.. is offset:2, length:2

To extract the values in a bit field from a value called data, you typically would use the expression:

data >> offset & (1<<length) - 1

This does:

• data >> offset right-shifts the bits in the data value offset number of times
• (1 << length) - 1 gives us length number of 1 bits going right to left, which gives us a bit mask
• ANDing (&) the values together gives the binary representation of the class value

An example of finding the cloud confidence class value from the 4 bit example above for the data value of integer 6:

• Integer 6 is 0110 in binary
• We want to extract the field at offset:2, length:2
• First, right-shift twice (0110 >> 2), which results in 1001
• Next, make the bit mask, which is 2 left shifts of 0001 to get 0100 (integer 4), then subtract 1 to get 0011 (integer 3)
• AND these two values together 1001 & 0011 and you get 0001, or integer 1
• Therefore at this pixel the cloud confidence field is storing class 1

The key distinction with bit fields from other types of bit masks is that the bits in the field are summed as standalone bits. Therefore 01.. cloud confidence class uses the value of 1, not 4 (binary 0100)

For a real world example, see Landsat 8's Quality raster.

Class Object

Describes a data class

Class objects enumerate data values and their corresponding classes. A cloud mask raster could contain the following four classes:

• 0: "No data"
• 1: "Clear"
• 2: "Cloud"
• 3: "Cloud shadow"

color_hint only is intended to hint a reasonable color for clients to use and is not intended to define styling. For example, the ESA landcover datasets use "color_hint":"006400" to suggest using a green color for a class of "Tree cover".

For conveying styling see the Raster Extension and cpt2json for discussion on passing styling as an item asset instead.

Contributing

All contributions are subject to the STAC Specification Code of Conduct. For contributions, please follow the STAC specification contributing guide Instructions for running tests are copied here for convenience.

Running tests

The same checks that run as checks on PRs are part of the repository and can be run locally to verify that changes are valid. To run tests locally, you'll need npm, which is a standard part of any node.js installation.

First you'll need to install everything with npm once. Just navigate to the root of this repository and on your command line run:

npm install

Then to check markdown formatting and test the examples against the JSON schema, you can run:

npm test

This will spit out the same texts that you see online, and you can then go and fix your markdown or examples.

If the tests reveal formatting problems with the examples, you can fix them with:

npm run format-examples