Clarify difference between image-label properties and colors

[lassoan]

We are planning to replace our previous text-based image label description format with a new json-based format for better interoperability. NGFF's image-label is simple and flexible enough, so we could use it.

However, there is an odd separation of colors from all other properties.

Some grouping of properties could make sense, for example separating display properties (color, opacity, fill opacity, border width, border opacity, etc.), content (name, standard terminology, etc.), and derived data (measurements, classification results, etc.). However, it is hard to find justification for just singling out color.

Would you consider the following options to improve this data structure?

Option A. Move all properties under a single properties object

"image-label":
  {
    "properties": [
      { "label-value": 1, "name": "liver", "color": "0000FF", "opacity": 0.5, "area (pixels)": 1200, "class": "foo" },
      { "label-value": 4, "name": "tumor", "color": "00FF00", "opacity": 1.0, "area (pixels)": 1650 },
      ...
      ]
  },
  "source": {
    "image": "../../"
  }

Option B. Move properties under a few objects, such as properties and display; or properties, display, and measurements.

"image-label":
  {
    "version": "0.4",
    "properties": [
      { "label-value": 1, "name": "liver", "area (pixels)": 1200, "class": "foo" },
      { "label-value": 4, "name": "tumor", "area (pixels)": 1650 },
      ...
      ],
    "display": [
      { "label-value": 1, "color": "0000FF", "opacity": 0.5 },
      { "label-value": 4, "color": "00FF00", "opacity": 1.0 },
      ...
      ]
  },
  "source": {
    "image": "../../"
  }

or

"image-label":
  {
    "version": "0.4",
    "properties": [
      { "label-value": 1, "name": "liver" },
      { "label-value": 4, "name": "tumor" },
      ...
      ],
    "display": [
      { "label-value": 1, "color": "0000FF", "opacity": 0.5 },
      { "label-value": 4, "color": "00FF00", "opacity": 1.0 },
      ...
      ],
    "measurements": [
      { "label-value": 1, "area (pixels)": 1200, "class": "foo" },
      { "label-value": 4, "area (pixels)": 1650 },
      ...
      ]
  },
  "source": {
    "image": "../../"
  }

Note that I've changed the color definition from "rgba"=[255,255,255,255] to "color": "0000FF"match how it is defined elsewhere in NGFF.

[will-moore]

Thanks for the suggestions. I think the current state was influenced by napari labels.

The distinction is really between key words defined by the spec, and user-defined (custom) "properties". All the user-defined custom attributes are grouped under properties but all the values defined by the spec go at the top-level. So far the only key-word defined by the spec is colors, but we'd expect others to be added in the same place. This concept is most similar to your first B suggestion, except the spec-defined properties in future may not necessarily be "display" properties.