Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Resolving misc issues and ambiguities in labels section #170

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Resolving misc issues and ambiguities in labels section #170

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
16f2e41
Clarify labels section as discussed in PR 165
virginiascarlett Mar 7, 2023
4bacf52
label image .zattrs SHOULD contain image-label key
virginiascarlett Mar 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions latest/index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -450,6 +450,7 @@ This new image is composed of integer values corresponding to certain labels wit
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'.

Each label image MUST be stored within a "labels" group.
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,
Expand All @@ -467,15 +468,16 @@ labeled multiscale image(s). All label images SHOULD be listed within this metad
```

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.
associated with the `datasets` key MAY have the same number of elements (scale levels) as the original unlabeled image.
Therefore it is acceptable for a label image to have fewer scale levels than the original image.

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,
The label image .zattrs file SHOULD also contain the `image-label` key, whose value is a JSON object.
The `image-label` object stores information about the display colors, source image, and optionally,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since there are no mandatory contents of the image-label dictionary, it would be valid to have image-label: {}.
It seems that making the spec more strict (a breaking change) to require the image-label dict is probably not worth it in that case?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that that 'MUST' was in response to @sbesson's comment on my previous PR:
"For the image-label specification, my personal opinion would be to enforce it at a MUST level. Doing so would have the advantage of making it unambiguous and potentially reducing the number of graph operations."

Maybe @sbesson can comment here?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the ping @virginiascarlett. Trying to justify, the rationale behind my original statement, I see a label image as a specialized type of multiscales image. At the moment, the specification enforces that such data must be stored within a well-defined labels hierarchy but moving forward, I could certainly imagine a relaxation of this constraint.

A typical use case that comes immediately to mind is the one where segmentation / classification is performed against a read-only Zarr dataset e.g. public data and the output of this process needs to be stored as a new dataset. At the moment, the structure which is the most compliant with the spirit of the specification is create an artificial labels/<label_name>/ hierarchy under the root even if there is no multiscales image. Assuming we relaxed this constraint to allow label images to be stored at the root of the Zarr dataset, I would argue the image-label metadata would become a critical element to identify what we are dealing with.

That being said, Will's point makes sense and if this specification change simply leads to most implementations adding image-label: {} in the metadata, I don't find this is particularly helpful.
Happy to separate this discussion from your proposal, revert the requirement level back to the SHOULD level and come back to this discussion if we decide to specify standalone label images.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would be happy with keeping image-label at the SHOULD level if we agree.

Good points raised by @sbesson on having standalone label images. I agree those would be a nice addition, and worth discussing in its own issue. I may start one now, but will likely neglect it until the next release is pushed through.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!

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.

Conforming readers SHOULD display labels using the colors specified by the `colors` JSON array, as follows. This array contains one
Conforming readers SHOULD display labels using the colors specified by the `colors` JSON array, as follows. This array SHOULD contain 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
Expand Down