[ome-devel] Help with setPixelsID() and setImageID()

[Roger Leigh]

On 15/11/16 18:30, Michael Ellis wrote:
> I am still trying to make headway with BioFormats
>
> There are the following lines from the worked example at http://www.openmicroscopy.org/site/support/bio-formats5.2/developers/export2.html
>
> omexml.setImageID("Image:0", 0);
> omexml.setPixelsID(“Pixels:0", 0);
>
> The documentation for setPixelsID() and setImageID() is not enlightening!
>
> //Set the ID property of Pixels.
> //Set the ID property of Image.
>
> In both case parameters are documented as:
>       id - ID to set.
>       imageIndex - the Image index.
>
> Omitting either of these calls from my program results in a loci.formats.FormatException: Image ID #0 is null (or Pixels ID #0 is null). But I seem to be able to specify any String names and then it works.
>
> Can someone explain these calls, or better still update the Javadoc for these routines?

Dear Michael,

I'm afraid this is one of the hairier corners of the Bio-Formats API,
and the documentation here is not ideal.  I'll try to provide some
references and explanation of how it all fits together.

Firstly, the metadata API is entirely generated from the OME-XML schema
definition.  You can find the documentation for that here:


http://www.openmicroscopy.org/Schemas/Documentation/Generated/OME-2016-06/ome.html

with Image and Pixels here:


http://www.openmicroscopy.org/Schemas/Documentation/Generated/OME-2016-06/ome_xsd.html#ImageID


http://www.openmicroscopy.org/Schemas/Documentation/Generated/OME-2016-06/ome_xsd.html#PixelsID

This schema definition is used to generate two separate sets of classes.

1. OME Model objects
2. Metadata store and retrieve interfaces (which you are using here)

The model objects map 1:1 (as a rule) with the schema elements.  So
you'll find Image and Pixels classes here, along with others, for example:


http://downloads.openmicroscopy.org/bio-formats/5.2.4/api/ome/xml/model/Image.html

The OME-XML xml document is serialised to and from a tree of OME model
objects.  These are the in-memory representation of the metadata model.

The metadata store and retrieve interfaces wrap the tree of OME model
objects.  These are intended to be a higher-level interface to
manipulating and introspecting the model, as well as permitting
implementations which are not based upon the model objects (such as
databases, OMERO, other file formats).  Because the interfaces delegate
all operations as changes to the underlying model objects, it is
stateful and the call order must be correct in order for the calls to
have the intended effect.  The order is unfortunately not in the API
reference, but it is fully described in the implementation here:


https://github.com/openmicroscopy/bioformats/blob/v5.2.4/components/formats-api/src/loci/formats/meta/MetadataConverter.java#L810

or in C++ (more concisely):


https://github.com/openmicroscopy/bioformats/blob/v5.2.4/cpp/lib/ome/xml/meta/Convert.cpp#L592

But the reason for the ordering is simply that an object needs to exist
before you can use it, and so you must create an object (and all its
parents) before doing that.

While the model objects all have unique IDs, the metadata API references
all object by index.  And when an object contains another object, it's
referred to using the index of the parent object, and its own index.  A
special case (e.g. for Pixels) is that since there's only a single
Pixels element within Image, it doesn't require a unique index, so only
the image index is required.  The API has the index names as the method
parameters, to tell you which indexes are required.

The sequence for using the metadata store essentially boils down to:

- calling setXXXId to create an object, where XXX is the object type,
plus any additional indexes needed to reference it.  An object is
created if the index doesn't yet exist
- setting any required properties on that object using the other setXXX
methods
- recursively repeating this for child objects
- setting any links (cross-references); both objects must exist

Some examples:

https://github.com/openmicroscopy/bioformats/blob/v5.2.4/components/formats-api/src/loci/formats/MetadataTools.java#L252
https://github.com/openmicroscopy/bioformats/blob/v5.2.4/components/formats-api/src/loci/formats/MetadataTools.java#L277

https://github.com/openmicroscopy/bioformats/blob/v5.2.4/components/formats-gpl/src/loci/formats/in/FlexReader.java#L562


I hope that's helpful.  Please do let me know if there's anything I can
explain in more detail.


Kind regards,
Roger

--
Dr Roger Leigh -- Open Microscopy Environment
Wellcome Trust Centre for Gene Regulation and Expression,
College of Life Sciences, University of Dundee, Dow Street,
Dundee DD1 5EH Scotland UK   Tel: (01382) 386364

The University of Dundee is a registered Scottish Charity, No: SC015096