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

Roger Leigh rleigh at dundee.ac.uk
Sun Nov 20 19:30:09 GMT 2016 

Dear Michael,

This is unfortunately another point where the terminology is confusing.
The Bio-Formats FormatReader and FormatWriter classes (and helper
classes such as FormatTools and MetadataTools) use a slightly different
terminology than that used by the OME-XML schema and the model and
metadata classes described in my previous mail.

   Model  Bio-Formats  Description
   -----  -----------  ----------------------------
   Image  Series       Image series number
   Plane  Image        Plane number within an image

So when using the reader and writer APIs, methods such as
"getSeriesCount", "setSeries", "getSeries" are all working with Image
elements from the model.

The most egregious discrepancy is the "getImageCount" method.  For the
metadata API, this gets you the total number of Image elements.  For the
Bio-Formats APIs, this gets you the total number of *Plane* elements.

The reason for the discrepancy is that the Bio-Formats reader and writer
APIs predate the OME-XML schema and model APIs, and the OME-XML support
was integrated at a later date (and, even today, is theoretically optional).


Kind regards,
Roger


On 18/11/16 12:15, Michael Ellis wrote:
> 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
>> <mailto: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
>>
>> 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
>> _______________________________________________
>> 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
>
> Michael Ellis (Managing Director)
> Digital Scientific UK Ltd.
> http://www.dsuk.biz
> michael.ellis at dsuk.biz <mailto:michael.ellis at dsuk.biz>
> tel: +44(0)1223 911215
>
> The Commercial Centre
> 6 Green End
> Cambridge
> CB23 7DY
>
>
>
> _______________________________________________
> ome-devel mailing list
> ome-devel at lists.openmicroscopy.org.uk
> http://lists.openmicroscopy.org.uk/mailman/listinfo/ome-devel
>

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

More information about the ome-devel mailing list