External file format readers¶
File format readers recognized by Bio-Formats can be defined as either “core” or “external”. A core reader is maintained by the OME team, and included in either the formats-bsd or formats-gpl component in the ome/bioformats repository on GitHub. An external reader is not included in the ome/bioformats repository, and in most cases is not maintained by the OME team. [1]
Bio-Formats contains a file named readers.txt which records every recognized reader class name. This file is used by the main reader class (loci.formats.ImageReader) to find installed readers.
For readers that are included in core Bio-Formats (i.e. the ome/bioformats repository on GitHub), a line containing just the fully qualified class name is added, e.g.:
loci.formats.in.OMETiffReader # tif
An optional comment can be added after the class name using #.
Readers that are not in ome/bioformats and which are not included in Bio-Formats releases can be defined as “external” readers, e.g.:
loci.formats.in.ZarrReader[type=external] # .zarr
This allows Bio-Formats to attempt to load a reader that was installed separately, but quietly ignore if it is not found.
When to use an external reader¶
The OME team often encourages new readers to be proposed as “external” under any of the following conditions:
the newly introduced reader code is very large and/or complex
native libraries or closed-source dependencies are required
a public format specification document or reference implementation is not available
the reader covers an imaging domain which is unfamiliar to the OME team
test data cannot be provided to the OME team
the reader needs to be updated outside of the normal Bio-Formats release process
the reader code does not comply with OME code contribution policies
developers/maintainers of the reader are not able to address feedback provided by the OME team during code review and testing
When considering a new reader, we suggest discussing with the OME team first before making substantial development. The OME team is responsible for making the final determination of whether a new reader should be defined as external.
How to propose an external reader¶
As indicated above, we suggest discussing with the OME team before investing significant time in a new reader.
At minimum, open a new pull request or issue on ome/bioformats that proposes to update readers.txt as indicated above, including the following information:
where to find the reader source code
who is maintaining the external reader, and an acknowledgement that the OME team is not responsible for maintaining this reader
where/how the reader will be released
test data, if possible
supporting documentation (issues, forum threads, etc.) indicating why this reader is necessary
We strongly prefer to be able to test a proposed external reader before approving it, but recognize this may not always be possible. In these cases, we may ask for additional information in place of our own testing.
What external reader ownership involves¶
Developing an external reader means taking complete ownership and responsibility for the development, maintenance, testing, and distribution of the reader and its dependencies. The OME team will not review code, fix issues, or otherwise participate in the development or release process. As a result, it is very important to have a maintenance and testing plan that includes:
where issues should be reported
who is responsible for fixing issues and releasing new versions
where/how to find new versions of the reader, e.g. a Fiji update site
We strongly encourage reader maintainers to follow a support pattern similar to that used for core Bio-Formats, which includes:
publicly accessible issue tracking
participation in discussions on forum.image.sc
public roadmaps and release announcements
Recategorizing an existing reader¶
If the OME team determines that an existing core reader meets the external reader criteria in When to use an external reader, and a suitable maintainer can be identified, then we may propose to recategorize the reader as external. This is our preferred alternative to removing it from both core Bio-Formats and readers.txt.
In the event that recategorizing is necessary, we will make contact with the proposed maintainer to discuss next steps.