# 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.

See also

OME’s Third Party Contribution and Interaction Policy

## 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.

[1]

A notable exception is ZarrReader, which is an external reader maintained by the OME team. This reader is externalized primarily to allow for updates outside of the normal Bio-Formats release process. See further discussion in this issue.