diff --git a/latest/examples/label_strict/colors_properties.json b/latest/examples/label_strict/colors_properties.json
index 7f1d6f20..c96820e1 100644
--- a/latest/examples/label_strict/colors_properties.json
+++ b/latest/examples/label_strict/colors_properties.json
@@ -3,23 +3,25 @@
"version": "0.5-dev",
"colors": [
{
- "label-value": 1,
- "rgba": [255, 255, 255, 255]
+ "label-value": 0,
+ "rgba": [0, 0, 128, 128]
},
{
- "label-value": 4,
- "rgba": [0, 255, 255, 128]
+ "label-value": 1,
+ "rgba": [0, 128, 0, 128]
}
],
"properties": [
{
- "label-value": 1,
+ "label-value": 0,
"area (pixels)": 1200,
- "class": "foo"
+ "class": "intercellular space"
},
{
- "label-value": 4,
- "area (pixels)": 1650
+ "label-value": 1,
+ "area (pixels)": 1650,
+ "class": "cell",
+ "cell type": "neuron"
}
],
"source": {
diff --git a/latest/index.bs b/latest/index.bs
index bb935c48..aa5feb95 100644
--- a/latest/index.bs
+++ b/latest/index.bs
@@ -444,59 +444,65 @@ for more information.
"labels" metadata {#labels-md}
------------------------------
-The special group "labels" found under an image Zarr contains the key `labels` containing
-the paths to label objects which can be found underneath the group:
+In OME-Zarr, Zarr arrays representing pixel-annotation data are stored in a group called "labels". Some applications--notably image segmentation--produce
+a new image that is in the same coordinate system as a corresponding multiscale image (usually having the same dimensions and coordinate transformations).
+This new image is composed of integer values corresponding to certain labels with custom meanings. For example, pixels take the value 1 or 0
+if the corresponding pixel in the original image represents cellular space or intercellular space, respectively.
+Such an image is referred to in this specification as a 'label image'.
+
+The "labels" group is nested within an image group, at the same level of the Zarr hierarchy as the resolution levels for the original image.
+The "labels" group is not itself an image; it contains images. The pixels of the label images MUST be integer data types, i.e. one of
+[`uint8`, `int8`, `uint16`, `int16`, `uint32`, `int32`, `uint64`, `int64`]. Intermediate groups between "labels" and the images within it are allowed,
+but these MUST NOT contain metadata. Names of the images in the "labels" group are arbitrary.
+
+The `.zattrs` file associated with the "labels" group MUST contain a JSON object with the key `labels`, whose value is a JSON array of paths to the
+labeled multiscale image(s). All label images SHOULD be listed within this metadata file. For example:
```json
{
"labels": [
- "orphaned/0"
+ "cell_space_segmentation"
]
}
```
-Unlisted groups MAY be labels.
+The `.zattrs` file for the label image MUST implement the multiscales specification. Within the `multiscales` object, the JSON array
+associated with the `datasets` key MUST have the same number of entries (scale levels) as the original unlabeled image.
-"image-label" metadata {#label-md}
-----------------------------------
+In addition to the `multiscales` key, the JSON object in this image-level `.zattrs` file SHOULD contain another key, `image-label`,
+whose value is also a JSON object. The `image-label` object stores information about the display colors, source image, and optionally,
+further arbitrary properties of the label image. That `image-label` object SHOULD contain the following keys: first, a `colors` key,
+whose value MUST be a JSON array describing color information for the unique label values. Second, a `version` key, whose value MUST be a
+string specifying the version of the OME-NGFF `image-label` schema.
-Groups containing the `image-label` dictionary represent an image segmentation
-in which each unique pixel value represents a separate segmented object.
-`image-label` groups MUST also contain `multiscales` metadata and the two
-"datasets" series MUST have the same number of entries.
+Conforming readers SHOULD display labels using the colors specified by the `colors` JSON array, as follows. This array contains one
+JSON object for each unique custom label. Each of these objects MUST contain the `label-value` key, whose value MUST be the integer
+corresponding to a particular label. In addition to the `label-value` key, the objects in this array MAY contain an `rgba` key whose
+value MUST be an array of four integers between 0 and 255, inclusive. These integers represent the `uint8` values of red, green, and
+blue that comprise the final color to be displayed at the pixels with this label. The fourth integer in the `rgba` array represents alpha,
+or the opacity of the color. Additional keys under `colors` are allowed.
-The `image-label` dictionary SHOULD contain a `colors` key whose value MUST be a
-list of JSON objects describing the unique label values. Each color object MUST
-contain the `label-value` key whose value MUST be an integer specifying the
-pixel value for that label. It MAY contain an `rgba` key whose value MUST be an array
-of four integers between 0 and 255 `[uint8, uint8, uint8, uint8]` specifying the label
-color as RGBA. All the values under the `label-value` key MUST be unique. Clients
-who choose to not throw an error SHOULD ignore all except the _last_ entry.
+Next, the `image-label` object MAY contain the following keys: a `properties` key, and a `source` key.
-Some implementations MAY represent overlapping labels by using a specially assigned
-value, for example the highest integer available in the pixel range.
+Like the `colors` key, the value of the `properties` key MUST be an array of JSON objects describing the set of unique possible pixel values.
+Each object in the `properties` array MUST contain the `label-value` key, whose value again MUST be an integer specifying the pixel value for that label.
+Additionally, an arbitrary number of key-value pairs MAY be present for each label value, denoting arbitrary metadata associated with that label.
+Label-value objects within the `properties` array do not need to have the same keys.
-The `image-label` dictionary MAY contain a `properties` key whose value MUST be a
-list of JSON objects which also describes the unique label values. Each property object
-MUST contain the `label-value` key whose value MUST be an integer specifying the pixel
-value for that label. Additionally, an arbitrary number of key-value pairs
-MAY be present for each label value denoting associated metadata. Not all label
-values must share the same key-value pairs within the properties list.
+The value of the `source` key MUST be a JSON object containing information about the original image from which the label image derives.
+This object MAY include a key `image`, whose value MUST be a string specifying the relative path to a Zarr image group.
+The default value is `../../` since most labeled images are stored in a "labels" group that is nested within the original image group.
-The `image-label` dictionary MAY contain a `source` key whose value MUST be a JSON
-object containing information on the image the label is associated with. If included,
-it MAY include a key `image` whose value MUST be a string specifying the relative
-path to a Zarr image group. The default value is "../../" since most labels are stored
-under a subgroup named "labels/" (see above).
-
-The `image-label` dictionary SHOULD contain a `version` key whose value MUST be a string
-specifying the version of the image-label specification.
+Here is an example of a simple `image-label` object for a label image in which 0s and 1s represent intercellular and cellular space, respectively:
path: examples/label_strict/colors_properties.json
highlight: json
+In this case, the pixels consisting of a 0 in the Zarr array will be displayed as 50% blue and 50% opacity. Pixels with a 1 in the Zarr array,
+which correspond to cellular space, will be displayed as 50% green and 50% opacity.
+
"plate" metadata {#plate-md}
----------------------------
@@ -671,6 +677,11 @@ Version History {#history}
Description |
+
+ | 0.4.1 |
+ 2023-02-09 |
+ expand on "labels" description |
+
| 0.4.1 |
2022-09-26 |