bioformats2raw.layout

latest/examples/bf2raw/bioformats2raw_layout.json

@@ -0,0 +1,3 @@
+{
+  "bioformats2raw.layout" : 3
+}

latest/index.bs

@@ -101,6 +101,14 @@ The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL
 “RECOMMENDED”, “MAY”, and “OPTIONAL” are to be interpreted as described in
 [RFC 2119](https://tools.ietf.org/html/rfc2119).
 
+<p>
+<dfn>Transitional</dfn> metadata is added to the specification with the
+intention of removing it in the future. Implementations may be expected (MUST) or
+encouraged (SHOULD) support the reading of the data, but writing will usually
+be optional (MAY). Examples of transitional metadata include custom additions by
+implementations that are later submitted as a formal specification. (See [[#bf2raw]])
+</p>
+
 Some of the JSON examples in this document include commments. However, these are only for
 clarity purposes and comments MUST NOT be included in JSON objects.
 
@@ -242,9 +250,35 @@ keys as specified below for discovering certain types of data, especially images
 
 If part of [[#multiscale-md]], the length of "axes" MUST be equal to the number of dimensions of the arrays that contain the image data.
 
+"bioformats2raw.layout" (transitional) {#bf2raw}
+------------------------------------------------
+
+[=Transitional=] "bioformats2raw.layout" metadata identifies a group which implicitly describes a series of images.
+The need for the collection stems from the common "multi-image file" scenario in microscopy. Parsers like Bio-Formats
+define a strict, stable ordering of the images in a single container that can be used to refer to them by other tools.
+In order to capture that information within an OME-NGFF dataset, `bioformats2raw` internally introduced a wrapping
+layer. An upcoming NGFF specification will replace this layout with explicit metadata.
+
+Conforming groups MUST have the value "3" for the "bioformats2raw.layout" key in their `.zattrs` metadata at the top of the hierarchy:
+
+<pre class=include-code>
+path: examples/bf2raw/bioformats2raw_layout.json
+highlight: json
+</pre>
+
+Additionally:
+- MUST store separate "multiscales" images in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...);
+- MAY have OME metadata representing the entire collection of images in a file named "OME/METADATA.ome.xml";
+- if so, MUST represent every "multiscales" group as exactly one OME-XML "Image" in the same order as the group numbers.
+
+Conforming readers:
+- SHOULD detect the presence of more than one image and make users aware of the fact;
+- MAY choose to show all images within the collection or offer the user a choice of images, as with <dfn export="true"><abbr title="High-content screening">HCS</abbr></dfn> plates;
+- MAY ignore other groups or arrays under the root of the hierarchy.
+
 
 "coordinateTransformations" metadata {#trafo-md}
--------------------------------------
+------------------------------------------------
 
 "coordinateTransformations" describe a series of transformations that map between two coordinate spaces (defined by "axes").
 For example, to map a discrete data space of an array to the corresponding physical space.

latest/schemas/bf2raw.schema

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ngff.openmicroscopy.org/latest/schemas/bf2raw.schema",
+  "title": "NGFF container produced by bioformats2raw",
+  "description": "JSON from OME-NGFF .zattrs",
+  "type": "object",
+  "properties": {
+    "bioformats2raw.layout": {
+      "description": "The top-level identifier metadata added by bioformats2raw",
+      "type": "number",
+      "enum": [3]
+    }
+  }
+}

latest/tests/test_validation.py

@@ -7,19 +7,25 @@
 from jsonschema.exceptions import ValidationError
 
 
+with open('schemas/bf2raw.schema') as f:
+    bf2raw_schema = json.load(f)
 with open('schemas/image.schema') as f:
     image_schema = json.load(f)
 with open('schemas/strict_image.schema') as f:
     strict_image_schema = json.load(f)
+
 schema_store = {
+    bf2raw_schema['$id']: bf2raw_schema,
     image_schema['$id']: image_schema,
     strict_image_schema['$id']: strict_image_schema,
 }
 
 resolver = RefResolver.from_schema(image_schema, store=schema_store)
 validator = Draft202012Validator(image_schema, resolver=resolver)
 strict_validator = Draft202012Validator(strict_image_schema, resolver=resolver)
+bf2raw_validator = Draft202012Validator(bf2raw_schema, resolver=resolver)
 
+bf2raw_files = list(glob.glob("examples/bf2raw/*.json"))
 valid_strict_files = list(glob.glob("examples/valid_strict/*.json"))
 valid_files = list(glob.glob("examples/valid/*.json"))
 invalid_files = list(glob.glob("examples/invalid/*.json"))
@@ -31,6 +37,15 @@ def ids(files):
     return [str(x).split("/")[-1][0:-5] for x in files]
 
 
+@pytest.mark.parametrize(
+    "testfile", bf2raw_files, ids=ids(bf2raw_files))
+def test_bf2raw(testfile):
+    with open(testfile) as f:
+        data = ''.join(line for line in f if not line.lstrip().startswith('//'))
+        jsondata = json.loads(data)
+        bf2raw_validator.validate(jsondata)
+
+
 @pytest.mark.parametrize(
     "testfile", valid_strict_files, ids=ids(valid_strict_files))
 def test_valid_strict(testfile):