The ImageIO Plugin API

Here you can find documentation on how to write your own plugin to allow ImageIO to access a new backend. Plugins are quite object oriented, and the relevant classes and their interaction are documented here:

imageio.core.Format(name, description[, ...])	Represents an implementation to read/write a particular file format
imageio.core.Request(uri, mode, *[, ...])	ImageResource handling utility.

Note

You can always check existing plugins if you want to see examples.

What methods to implement

To implement a new plugin, create a new class that inherits from imageio.core.Format. and implement the following functions:

imageio.core.Format.__init__(name, description)	Initialize the Plugin.
imageio.core.Format._can_read(request)	Check if Plugin can read from ImageResource.
imageio.core.Format._can_write(request)	Check if Plugin can write to ImageResource.

Further, each format contains up to two nested classes; one for reading and one for writing. To support reading and/or writing, the respective classes need to be defined.

For reading, create a nested class that inherits from imageio.core.Format.Reader and that implements the following functions:

• Implement _open(**kwargs) to initialize the reader. Deal with the

  user-provided keyword arguments here.

• Implement _close() to clean up.

• Implement _get_length() to provide a suitable length based on what

  the user expects. Can be inf for streaming data.

• Implement _get_data(index) to return an array and a meta-data dict.

• Implement _get_meta_data(index) to return a meta-data dict. If index

  is None, it should return the ‘global’ meta-data.

For writing, create a nested class that inherits from imageio.core.Format.Writer and implement the following functions:

• Implement _open(**kwargs) to initialize the writer. Deal with the

  user-provided keyword arguments here.

• Implement _close() to clean up.

• Implement _append_data(im, meta) to add data (and meta-data).

• Implement _set_meta_data(meta) to set the global meta-data.

Example / template plugin

# -*- coding: utf-8 -*-

# imageio is distributed under the terms of the (new) BSD License.



""" Example plugin. You can use this as a template for your own plugin.

"""



import numpy as np



from .. import formats

from ..core import Format





class DummyFormat(Format):

    """The dummy format is an example format that does nothing.

    It will never indicate that it can read or write a file. When

    explicitly asked to read, it will simply read the bytes. When

    explicitly asked to write, it will raise an error.



    This documentation is shown when the user does ``help('thisformat')``.



    Parameters for reading

    ----------------------

    Specify arguments in numpy doc style here.



    Parameters for saving

    ---------------------

    Specify arguments in numpy doc style here.



    """



    def _can_read(self, request):

        # This method is called when the format manager is searching

        # for a format to read a certain image. Return True if this format

        # can do it.

        #

        # The format manager is aware of the extensions and the modes

        # that each format can handle. It will first ask all formats

        # that *seem* to be able to read it whether they can. If none

        # can, it will ask the remaining formats if they can: the

        # extension might be missing, and this allows formats to provide

        # functionality for certain extensions, while giving preference

        # to other plugins.

        #

        # If a format says it can, it should live up to it. The format

        # would ideally check the request.firstbytes and look for a

        # header of some kind.

        #

        # The request object has:

        # request.filename: a representation of the source (only for reporting)

        # request.firstbytes: the first 256 bytes of the file.

        # request.mode[0]: read or write mode



        if request.extension in self.extensions:

            return True



    def _can_write(self, request):

        # This method is called when the format manager is searching

        # for a format to write a certain image. It will first ask all

        # formats that *seem* to be able to write it whether they can.

        # If none can, it will ask the remaining formats if they can.

        #

        # Return True if the format can do it.



        # In most cases, this code does suffice:

        if request.extension in self.extensions:

            return True



    # -- reader



    class Reader(Format.Reader):

        def _open(self, some_option=False, length=1):

            # Specify kwargs here. Optionally, the user-specified kwargs

            # can also be accessed via the request.kwargs object.

            #

            # The request object provides two ways to get access to the

            # data. Use just one:

            #  - Use request.get_file() for a file object (preferred)

            #  - Use request.get_local_filename() for a file on the system

            self._fp = self.request.get_file()

            self._length = length  # passed as an arg in this case for testing

            self._data = None



        def _close(self):

            # Close the reader.

            # Note that the request object will close self._fp

            pass



        def _get_length(self):

            # Return the number of images. Can be np.inf

            return self._length



        def _get_data(self, index):

            # Return the data and meta data for the given index

            if index >= self._length:

                raise IndexError("Image index %i > %i" % (index, self._length))

            # Read all bytes

            if self._data is None:

                self._data = self._fp.read()

            # Put in a numpy array

            im = np.frombuffer(self._data, "uint8")

            im.shape = len(im), 1

            # Return array and dummy meta data

            return im, {}



        def _get_meta_data(self, index):

            # Get the meta data for the given index. If index is None, it

            # should return the global meta data.

            return {}  # This format does not support meta data



    # -- writer



    class Writer(Format.Writer):

        def _open(self, flags=0):

            # Specify kwargs here. Optionally, the user-specified kwargs

            # can also be accessed via the request.kwargs object.

            #

            # The request object provides two ways to write the data.

            # Use just one:

            #  - Use request.get_file() for a file object (preferred)

            #  - Use request.get_local_filename() for a file on the system

            self._fp = self.request.get_file()



        def _close(self):

            # Close the reader.

            # Note that the request object will close self._fp

            pass



        def _append_data(self, im, meta):

            # Process the given data and meta data.

            raise RuntimeError("The dummy format cannot write image data.")



        def set_meta_data(self, meta):

            # Process the given meta data (global for all images)

            # It is not mandatory to support this.

            raise RuntimeError("The dummy format cannot write meta data.")





# Register. You register an *instance* of a Format class. Here specify:

format = DummyFormat(

    "dummy",  # short name

    "An example format that does nothing.",  # one line descr.

    ".foobar .nonexistentext",  # list of extensions

    "iI",  # modes, characters in iIvV

)

formats.add_format(format)