From b24c65baa18805b3c16729e47d1ab19b191d5808 Mon Sep 17 00:00:00 2001 From: jmoore Date: Tue, 7 Jul 2020 13:56:34 +0200 Subject: [PATCH 1/8] Initial draft of mask metadata --- spec.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 82 insertions(+), 16 deletions(-) diff --git a/spec.md b/spec.md index adfef52..274d9fb 100644 --- a/spec.md +++ b/spec.md @@ -5,22 +5,55 @@ scripts provided by this repository will support one or more versions of this file, but they should all be considered internal investigations, not intended for public re-use. -## Basic layout +## On-disk (or in-cloud) layout ``` + . # Root folder, potentially in S3, -├── 123.zarr # with a flat list of images by image ID. -└── 456.zarr # - ├── .zattrs # Group level metadata. - ├── .zgroup # Each image is a Zarr group with multscale metadata. - └── 0 # Each multiscale level is stored as a separate Zarr array. - ├── .zarray # - ├── 0.0.0.0.0 # Chunks are stored with the flat directory layout. - └── t.c.z.y.x # All image arrays are 5-dimensional - # with dimension order (t, c, z, y, x). +│ # with a flat list of images by image ID. +│ +├── 123.zarr # One image (id=123) converted to Zarr. +│ +└── 456.zarr # Another image (id=456) converted to Zarr. + │ + ├── .zgroup # Each image is a Zarr group, or a folder, of other groups and arrays. + ├── .zattrs # Group level attributes are stored in the .zattrs file and include + │ # "multiscales" and "omero" below) + │ + ├── 0 # Each multiscale level is stored as a separate Zarr array, + │ │ # which is a folder containing chunk files which compose the array. + │ │ + │ ├── .zarray # All image arrays are 5-dimensional + │ │ # with dimension order (t, c, z, y, x). + │ │ + │ ├── 0.0.0.0.0 # Chunks are stored with the flat directory layout. + │ │ ... # Each dotted component of the chunk file represents + │ └── t.c.z.y.x # a "chunk coordinate", where the maximum coordinate + │ # will be `dimension_size / chunk_size`. + │ + └── masks + │ + ├── .zgroup # The masks group is a container which holds a list + ├── .zattrs # of masks to make the objects easily discoverable, + │ # e.g. `{ "masks": [ "original/0" ] }` + │ + └── original # Intermediate folders are permitted but not necessary + │ # and currently contain no extra metadata. + └── 0 + ├── .zgroup # Each mask itself is also a multiscale image with the extra key + ├── .zattrs # "color". + │ + └── t.c.z.y.x # Chunks as above. + + ``` -## "multiscales" metadata +## Metadata + +The various `.zattrs` files throughout the above array hierarchy may contain metadata +keys as specified below for discovering certain types of data, especially images. + +### "multiscales" metadata Metadata about the multiple resolution representations of the image can be found under the "multiscales" key in the group-level metadata. @@ -43,7 +76,7 @@ if not datasets: The subresolutions in each multiscale are ordered from highest-resolution to lowest. -## "omero" metadata +### "omero" metadata Information specific to the channels of an image and how to render it can be found under the "omero" key in the group-level metadata: @@ -74,13 +107,46 @@ can be found under the "omero" key in the group-level metadata: } ``` - See https://docs.openmicroscopy.org/omero/5.6.1/developers/Web/WebGateway.html#imgdata for more information. +### "masks" + +The special group "masks" found under an image Zarr contains the key `masks` containing +the paths to mask objects which can be found underneath the group: + +``` +{ + "masks": [ + "orphaned/0" + ] +} +``` + +Unlisted groups MAY be masks. + +### "color" + +The `color` key defines an image that is "labeled", i.e. every unique value in the image +represents a unique, non-overlapping object within the image. The value associated with +the `color` key is another JSON object in which the key is the pixel value of the image and +the value is an RGBA color for representing the object: + +``` +{ + "color": { + "1": 8388736, + ... +``` + + + | Revision | Date | Description | | ---------- | ------------ | ------------------------------------------ | -| - | 2020-05-07 | Add description of "omero" metadata | -| - | 2020-05-06 | Add info on the ordering of resolutions | -| 0.1 | 2020-04-20 | First version for internal demo | +| 0.1.3 | 2020-07-07 | Add mask metadata | +| 0.1.2 | 2020-05-07 | Add description of "omero" metadata | +| 0.1.1 | 2020-05-06 | Add info on the ordering of resolutions | +| 0.1.0 | 2020-04-20 | First version for internal demo | + +SubMISSION PROCESS From bc54cce571a32622712bbb2cf84c7fc41ad091ec Mon Sep 17 00:00:00 2001 From: Josh Moore Date: Tue, 7 Jul 2020 16:51:46 +0200 Subject: [PATCH 2/8] Clarify RGBA color Co-authored-by: Simon Li --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 274d9fb..af33d60 100644 --- a/spec.md +++ b/spec.md @@ -130,7 +130,7 @@ Unlisted groups MAY be masks. The `color` key defines an image that is "labeled", i.e. every unique value in the image represents a unique, non-overlapping object within the image. The value associated with the `color` key is another JSON object in which the key is the pixel value of the image and -the value is an RGBA color for representing the object: +the value is an RGBA color (4 byte, `0-255` per channel) for representing the object: ``` { From cad78f667ab5143cdee8aa2af453887caa38eb5e Mon Sep 17 00:00:00 2001 From: Josh Moore Date: Tue, 7 Jul 2020 16:52:14 +0200 Subject: [PATCH 3/8] Clarify "masks" metadata Co-authored-by: Simon Li --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index af33d60..479b3f3 100644 --- a/spec.md +++ b/spec.md @@ -35,7 +35,7 @@ for public re-use. │ ├── .zgroup # The masks group is a container which holds a list ├── .zattrs # of masks to make the objects easily discoverable, - │ # e.g. `{ "masks": [ "original/0" ] }` + │ # All masks will be listed in `.zattrs` e.g. `{ "masks": [ "original/0" ] }` │ └── original # Intermediate folders are permitted but not necessary │ # and currently contain no extra metadata. From a4f61cd353aa52c50537891d8c8412e5740f24ef Mon Sep 17 00:00:00 2001 From: jmoore Date: Tue, 7 Jul 2020 16:52:44 +0200 Subject: [PATCH 4/8] Clarify array names --- spec.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 479b3f3..7e26dcd 100644 --- a/spec.md +++ b/spec.md @@ -21,7 +21,9 @@ for public re-use. │ # "multiscales" and "omero" below) │ ├── 0 # Each multiscale level is stored as a separate Zarr array, - │ │ # which is a folder containing chunk files which compose the array. + │ ... # which is a folder containing chunk files which compose the array. + ├── n # The name of the array is arbitrary with the ordering defined by + │ │ # by the "multiscales" metadata, but is often a sequence starting at 0. │ │ │ ├── .zarray # All image arrays are 5-dimensional │ │ # with dimension order (t, c, z, y, x). From 60ee51a90bac6c96233f2bf6904f68d992376896 Mon Sep 17 00:00:00 2001 From: jmoore Date: Tue, 7 Jul 2020 16:52:53 +0200 Subject: [PATCH 5/8] Remove extraneous text --- spec.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/spec.md b/spec.md index 7e26dcd..ee3fa1f 100644 --- a/spec.md +++ b/spec.md @@ -150,5 +150,3 @@ the value is an RGBA color (4 byte, `0-255` per channel) for representing the ob | 0.1.2 | 2020-05-07 | Add description of "omero" metadata | | 0.1.1 | 2020-05-06 | Add info on the ordering of resolutions | | 0.1.0 | 2020-04-20 | First version for internal demo | - -SubMISSION PROCESS From c15b68b9e8e61e7fd7c547af11f90c91509a5aab Mon Sep 17 00:00:00 2001 From: jmoore Date: Fri, 10 Jul 2020 09:37:02 +0200 Subject: [PATCH 6/8] Drop groups and specify highest-resolution --- spec.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/spec.md b/spec.md index ee3fa1f..3b1cccc 100644 --- a/spec.md +++ b/spec.md @@ -42,10 +42,8 @@ for public re-use. └── original # Intermediate folders are permitted but not necessary │ # and currently contain no extra metadata. └── 0 - ├── .zgroup # Each mask itself is also a multiscale image with the extra key - ├── .zattrs # "color". - │ - └── t.c.z.y.x # Chunks as above. + ├── .zarray # Each mask itself is a 5D array matching the highest resolution + └── .zattrs # of the related image and has an extra key, "color", with display information. ``` From 228fbff1ced1f8bfb9973631b9727a0977db9b20 Mon Sep 17 00:00:00 2001 From: Josh Moore Date: Fri, 10 Jul 2020 09:40:02 +0200 Subject: [PATCH 7/8] Clarify mask dimensions Co-authored-by: Simon Li --- spec.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/spec.md b/spec.md index 3b1cccc..0fc703d 100644 --- a/spec.md +++ b/spec.md @@ -38,6 +38,9 @@ for public re-use. ├── .zgroup # The masks group is a container which holds a list ├── .zattrs # of masks to make the objects easily discoverable, │ # All masks will be listed in `.zattrs` e.g. `{ "masks": [ "original/0" ] }` + │ # Each dimension of the mask `(t, c, z, y, x)` should be either the same as the + │ # corresponding dimension of the image, or `1` if that dimension of the mask + │ # is irrelevant. │ └── original # Intermediate folders are permitted but not necessary │ # and currently contain no extra metadata. From 6add68047269f0d85e7dc94251445da57d43c27f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Besson?= Date: Fri, 17 Jul 2020 14:08:44 +0200 Subject: [PATCH 8/8] Add optional image key Co-authored-by: Simon Li --- spec.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/spec.md b/spec.md index 0fc703d..ff9dfd9 100644 --- a/spec.md +++ b/spec.md @@ -141,7 +141,26 @@ the value is an RGBA color (4 byte, `0-255` per channel) for representing the ob "1": 8388736, ... ``` +### "image" +The `image` key is an optional dictionary which contains information on the image the mask is associated with. +If included it must include a key `array` whose value that is either: +- A relative path to a Zarr image array, for example: + ``` + { + "image": { + "array": "../../0" + } + } + ``` +- A URL to a Zarr image array (use this if the mask is stored seperately from the image Zarr), for example: + ``` + { + "image": { + "array": "https://s3.embassy.ebi.ac.uk/idr/zarr/v0.1/6001240.zarr/0" + } + } + ```