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

Fri Nov 18 12:15:56 GMT 2016

Dear Roger,

Many thanks for your help on this. I *think* I am slowly getting my head around some of the concepts.

A small matter I am confused over the parameters to many of the calls. for example, the javaDoc for setChannelID states arg1 is an imageIndex whereas the example at https://github.com/openmicroscopy/bioformats/blob/v5.2.4/components/formats-api/src/loci/formats/MetadataTools.java
seems to suggest it is the image series index. The images series index seems more logical as I  cannot see why or what an image index might be.

public void setChannelID(String arg0, int arg1, int arg2)
// Set the ID property of Channel.
// Parameters:
// id - ID to set.
// imageIndex - the Image index.
// channelIndex - the Channel index.

— Michael Ellis

> On 16 Nov 2016, at 15:48, Roger Leigh <rleigh at dundee.ac.uk> wrote:
> 
> 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 <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#ImageID>
> 
> 
> http://www.openmicroscopy.org/Schemas/Documentation/Generated/OME-2016-06/ome_xsd.html#PixelsID <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 <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 <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 <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#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-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 <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
> _______________________________________________
> ome-devel mailing list
> ome-devel at lists.openmicroscopy.org.uk <mailto:ome-devel at lists.openmicroscopy.org.uk>
> http://lists.openmicroscopy.org.uk/mailman/listinfo/ome-devel <http://lists.openmicroscopy.org.uk/mailman/listinfo/ome-devel>
Michael Ellis (Managing Director)
Digital Scientific UK Ltd.
http://www.dsuk.biz <http://www.dsuk.biz/>
michael.ellis at dsuk.biz
tel: +44(0)1223 911215

The Commercial Centre
6 Green End
Cambridge
CB23 7DY

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openmicroscopy.org.uk/pipermail/ome-devel/attachments/20161118/a2066e00/attachment.html>