imageio / imageio

Python library for reading and writing image data

IMAGEIO

Website: https://imageio.readthedocs.io/

Imageio is a Python library that provides an easy interface to read and write a wide range of image data, including animated images, video, volumetric data, and scientific formats. It is cross-platform, runs on Python 3.8+, and is easy to install.

Professional support is available via Tidelift.

Example

Here's a minimal example of how to use imageio. See the docs for more examples.

import imageio.v3 as iio
im = iio.imread('imageio:chelsea.png')  # read a standard image
im.shape  # im is a NumPy array of shape (300, 451, 3)
iio.imwrite('chelsea.jpg', im)  # convert to jpg

API in a nutshell

As a user, you just have to remember a handful of functions:

• imread() - for reading
• imwrite() - for writing
• imiter() - for iterating image series (animations/videos/OME-TIFF/...)
• improps() - for standardized metadata
• immeta() - for format-specific metadata
• imopen() - for advanced usage

See the API docs for more information.

Features

• Simple interface via a concise set of functions
• Easy to install using Conda or pip
• Few dependencies (only NumPy and Pillow)
• Pure Python, runs on Python 3.8+, and PyPy
• Cross platform, runs on Windows, Linux, macOS
• More than 295 supported formats
• Read/Write support for various resources (files, URLs, bytes, FileLike objects, ...)
• Code quality is maintained via continuous integration and continuous deployment

Dependencies

Minimal requirements:

• Python 3.8+
• NumPy
• Pillow >= 8.3.2

Optional Python packages:

• imageio-ffmpeg (for working with video files)
• pyav (for working with video files)
• tifffile (for working with TIFF files)
• itk or SimpleITK (for ITK plugin)
• astropy (for FITS plugin)
• imageio-flif (for working with FLIF image files)

Citing imageio

If you use imageio for scientific work, we would appreciate a citation. We have a DOI!

Security contact information

To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.

ImageIO for enterprise

Available as part of the Tidelift Subscription.

The maintainers of imageio and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.

Details

The core of ImageIO is a set of user-facing APIs combined with a plugin manager. API calls choose sensible defaults and then call the plugin manager, which deduces the correct plugin/backend to use for the given resource and file format. The plugin manager then adds sensible backend-specific defaults and then calls one of ImageIOs many backends to perform the actual loading. This allows ImageIO to take care of most of the gory details of loading images for you, while still allowing you to customize the behavior when and where you need to. You can find a more detailed explanation of this process in our documentation.

Contributing

We welcome contributions of any kind. Here are some suggestions on how you are able to contribute

• add missing formats to the format list
• suggest/implement support for new backends
• report/fix any bugs you encounter while using ImageIO

To assist you in getting started with contributing code, take a look at the development section of the docs. You will find instructions on setting up the dev environment as well as examples on how to contribute code.

imageio's Issues

relative imports

So that imageio can be used as a subpackage in a larger project (e.g. skimage)

Fix compression parameter for BMP

They do not work. Have looked into it and the right flag certainly seems to be passed to FreeImage. Tried setting the ctypes argtypes of FreeImage_Save, no luck. Tried casting flags to c_int c_uint etc., no luck.

Maybe it's a bug in FreeImage and we just need a new library.

imageio litters /usr/local in OS X

imageio was automatically installed on my Mac (OS X 10.10.2) as a dependency of moviepy via pip install moviepy.

Apparently, it wrote /usr/local/README.md and several other files, such as /usr/local/LICENSE, thereby overwriting Homebrew's README, causing it to fail when upgrading. It also created /usr/local/tests and other directories I now have to manually clean up.

Please do not litter into /usr/local, but choose a more sensible place. I don't know how Python packaging works exactly, but /usr/local does not seem to be the place where a package should reside.

If this is an issue with moviepy, please let me know so I can post it there instead. If this is caused by a configuration problem on my system, I wouldn't know which one, because I haven't done anything else other than installing latest Python via brew install python.

Allow ffmpeg to make use of system executable

Original discussion in #63. cc @ghisvail

A few suggestions concerning binary downloads

I installed imageio 3-4 times, and once "import imageio" produced a bug because it could not download a binary (temporary connection problem I guess). Just running the script a second time worked fine.

So maybe it would be worth combining the try/except statement with a "for" loop to retry binary downloads several times when it doesn't work. This way you're quasi-sure that it will always work, and when you get a bug report saying it couldn't download the binaries, you're sure it's something serious.

Also I think the binary downloads could use more text, like (maybe exagerated)

[imageio] X.exe wasn't found on your computer, downloading it now. This will only be done once.

And in case of bug: "Downlaod failed, please report the issue or try again in a moment".

Cheers !

Multiple icons in ICO file fails on win32

I get:

lib.FreeImage_AppendPage(self._bitmap, bitmap._bitmap)
 -> OSError: exception: priviledged instruction

Depending on the size of the images, I also get just segfaults.

How to make imageio work nice on systems with no internet connection?

Right now, imageio downloads external dependencies (the freeimage library, the avbin library, and the freeimage exe) at runtime, and caches them in the appdata directory. This keeps imageio lightweight and only fetches these rather large files when needed.

However, for people working in an environment with no internet connection, this makes makes imageio much less useful. We should aim to at least get the freeimage library available. And perhaps also some of our image suite.

ffmpeg leaves processes behind

Not sure if this is just me doping something stupid, but here goes:

for f in files:
         try:
             vol = imageio.mimread(f)
         except Exception as e:
             print f

This leaves me with this kind of process list:

As you can see, this is just a stupid loop to check I can actually load every file in my dataset, HMDB51 btw. Once this loop finishes (with the first error) the process list turns into this:

Now the error:

dataset/files/hmdb51_org/videos/scaled_256/stand/RETURN_OF_THE_KING_stand_u_cm_np1_fr_med_12.avi [Errno 24] Too many open files

looking at the ffmpeg plugin there is a _terminate function.
It sends a SIGTERM to the process and then waits for one second for it to terminate.
If I add a SIGKILL after the busy waiting the method looks like this:

def _terminate(self, timeout=1.0):
    """ Terminate the sub process.
    """
    # Check
    if self._proc is None:  # pragma: no cover
        return  # no process
    if self._proc.poll() is not None:
        return  # process already dead
    # Terminate process
    self._proc.terminate()
    # Wait for it to close (but do not get stuck)
    etime = time.time() + timeout
    while time.time() < etime:
        time.sleep(0.01)
        if self._proc.poll() is not None:
            break
    if self._proc.poll() is None:
        print('killing process')
        self._proc.kill()

And the kill seems to be called every time.
Any idea what's happening?
I am on Fedora 21 btw.

~/.imageio/ffmpeg/ffmpeg.linux64 -version
ffmpeg version 2.4.2-   http://johnvansickle.com/ffmpeg/    Copyright (c) 2000-2014 the FFmpeg developers
built on Oct  9 2014 07:24:56 with gcc 4.8 (Debian 4.8.3-11)
configuration: --enable-gpl --enable-version3 --disable-shared --disable-debug --enable-runtime-cpudetect --enable-libmp3lame --enable-libx264 --enable-libx265 --enable-libwebp --enable-libspeex --enable-libvorbis --enable-libvpx --enable-libfreetype --enable-fontconfig --enable-libxvid --enable-libopencore-amrnb --enable-libopencore-amrwb --enable-libtheora --enable-libvo-aacenc --enable-libvo-amrwbenc --enable-gray --enable-libopenjpeg --enable-libopus --disable-ffserver --enable-libass --enable-gnutls --cc=gcc-4.8
libavutil      54.  7.100 / 54.  7.100
libavcodec     56.  1.100 / 56.  1.100
libavformat    56.  4.101 / 56.  4.101
libavdevice    56.  0.100 / 56.  0.100
libavfilter     5.  1.100 /  5.  1.100
libswscale      3.  0.100 /  3.  0.100
libswresample   1.  1.100 /  1.  1.100
libpostproc    53.  0.100 / 53.  0.100

Allow testing without downloading resources - for Debian building

Test suite should be included in the source tarbal as well.

JPEG quality setting

I haven't tested it but this line confuses me and it would be good to have some confirmation that the code is correct:

https://github.com/imageio/imageio/blob/master/imageio/plugins/plugin_freeimage.py#L274

flags |= quality

The IO flags have quality flags for certain steps, like superb, average etc. but I can't find anything which says that any quality integer translates into a fitting flag that gets correctly interpreted by freeimage.

Imageio is handling numpy's array of float as a Negative image

I don't know if its intended, but here is some code proving. I'm using python 3.4.

from imageio import mimsave, imread

url = 'https://raw.githubusercontent.com/imageio/imageio-binaries/master/images/chelsea.png'
im = imread(url)
mimsave('result.gif', [1.0*im], 'GIF', duration=1.0)
imsave('result.jpg', 1.0*im, 'JPG')

And the result images:

Make avbin use system lib if possible

Original discussion in #63. cc @ghisvail

saving gif via libfreeimage dylib causes segfault on os x 10.10

When attempting to save a gif with the automatically downloaded libfreeimage I get a segfault on os x 10.10 with python 2.7.9.

import imageio
import numpy
im=numpy.zeros((400,400,3))
imageio.imsave('fail.gif',im)

lldb trace:

* thread #1: tid = 0xa6f3cd, 0x0000000105105eab libfreeimage-3.16.0-osx10.6.dylib`FreeImage_HasPixels + 11, queue = 'com.apple.main-thread', stop reason = EXC_BAD_ACCESS (code=1, address=0x2a4730)
    frame #0: 0x0000000105105eab libfreeimage-3.16.0-osx10.6.dylib`FreeImage_HasPixels + 11
libfreeimage-3.16.0-osx10.6.dylib`FreeImage_HasPixels + 11:

the internal FreeImage_HasPixels function is being passed an incorrect pointer (via first arg in %rdi) to the freeimage bitmap data, since it's often the first function called in freeimage routines, I suspect somehow the bitmap pointer is being mangled somewhere, perhaps by ctypes?

(the same segfault and stack trace occurs if I manually edit the library-searching code to use a locally compiled copy of libfreeimage 3.16.0 from homebrew.)

AVBIN plugin does not work on Snow Leopard (at least not on my VM)

output:

E           OSError: dlopen(/Users/almar/Library/Application Support/imageio/avbin/libavbin-11alpha4 osx.dylib, 6): Library not loaded:      
/System/Library/Frameworks/VideoDecodeAcceleration.framework/Versions/A/VideoDecodeAcceleration
E             Referenced from: /Users/almar/Library/Application Support/imageio/avbin/libavbin-11alpha4-osx.dylib
E             Reason: image not found

Format for 3D data (because npz is not so good)

NPZ is not supported on pypy and has issues with certain combinations of Python 2.x and numpy. We better had a good alternative ...

Support for playing sound during playing movie files

Title was: Perhaps the FFMPEG / AVBIN plugin can play sound while streaming?

But ffmpeg is an encoder/decoder, not a sound/video player. So perhaps using sdl2, or something else that can play audio. Synchronization may be an issue. Also, we could argue whether this is at all within the scope of imageio. Would be cool though.

Probably leave as-is until the a demand for this ...

Plugin: scientific TIFF files

In some fields a variant of the TIFF format is heavily used, e.g. for multiplanar microscopic images. Like OME-TIFF (https://www.openmicroscopy.org/site/support/ome-model/ome-tiff/).
The freeimage TIFF reader only deals with basic TIFF.

This is not really my field, so could use some input on what is needed.

One implementation that we could potentially use is: http://www.lfd.uci.edu/~gohlke/code/tifffile.py.html
I believe there was another, but I cannot remember.

imwrite("image.png") returns: IOError: The directory '' does not exist (Github version)

You need to amend the check for the case where the directory is the current directory. Do you want a PR on this ?

Possibility/plans to write GIFs with an alpha layer ?

I have seen in the docs that it is not possible right now, and I played a little bit with it but it is still unclear to me if it is a limitation of freeimage, or just not implemented yet.

Place doc sources in repo - for Debian building

Allow custom base url in get_remote_file function

This would allow 3d party modules to make use of this fetching functionality,

Python 2.7 Conda builds

At the moment, there only seems to be conda builds for Py34 and not for Py27.

One suggestion may be that since you are git tagging your releases, you could set up appveyor and travis to automatically upload builds on tagged releases?

Pure Python ico/png

I have code in zoof Flexx that can read/write ICO, BMP, PNG in pure Python. Limited to RGB(A) though. But might be interesting to not need freeimage for png. And also for #21

Protect user from using mimread on a large movies

doing imageio.mimread('lord of the rings - part1.avi') will quickly fill the working memory, go into swapping mode, and completely disable your machine. We probably want to protect the user for this ...

Keep imageio light while scaling the number of plugins

I think we should provide much of the IO implementation in one module (e.g. _swf.py), while the format itself is defined in another (e.g. swf.py). The former should not be imported by default, but only as the format is being used.

Images to video - Won't play back. Freezes after 725 images.

I've asked about the issue on stackoverflow, the link is here: http://stackoverflow.com/questions/30583873/ffmpeg-image-to-video-images-from-ram-python

INFO: Running Python 2.7.9/10 on Windows 7. Imageio downloaded from pip.
These are the two main problems

1. After creating an .mp4 file from several images(.png), it wont play back. The file does not have a thumbnail either. I've tried with both windows player, and vlc player.
2. My program looks for a path in a custom maze (explained in link), and makes an image for every step it makes. It creates 4840 images, and on the first prototype, I saved every image with PIL in a folder, and then ran FFMPEG commands from the command-line. This did the job, but when I try to add images on the go (from RAM) with "writer.append_data(image)", it just stops at 725 images. I confirmed this by adding "print loopCount" to my program. Nothing happens, no crash, just full stop.

Names of functions

Early on we decided on imread and imsave because these seemed to be the most used names in related software. However, we now have imageio.save returning Writer object, which seems inconsistent.

I propose to have imwrite mimwrite volwrite, and keep imsave as an alias. The mimsave and friends shall be deprecated and then removed in a later release.

Further, writer = imageio.write(...) feels a bit weird, because you might expect that someting is written at the moment that write is called. So mayber writer = imageio.Writer(...) makes more sense (even if its a factory function rather than a class).

Opinions?

cc @rossant

Debian packaging

This thread centralizes all queries and issues related with the Debian packaging effort I am currently undertaking on this library.

FFMPEG read camera stream on OSX

Reading from a camera stream is supported on Linux and Win, but mot yet on OSX. Mostly because I cannot test it (or at least I expect accessing my camera from a VM will be problematic).

The main changes requires are in _get_cam_inputname to specify how to read the camera, and in the beginning of the module to set CAM_FORMAT. Would be good if video4linux would just work on osx, but I doubt that it would.

cc @rreilink (if you have time, someday)

Implement video reading/saving via avbin

Rob has a proof of concept.

Is it possible to pass arbitrary arguments to ffmpeg with get_writer()

I would like to pass arguments like: bitrate, file for soundtrack, etc... and could not find an easy way, from the code I wonder if it's even possible. Thanks in advance !

"Subrectangles" optimization when writing GIFs

Hi there ! So apparently the subrectangles optimization to reduce the size of gifs is broken, but I'm not completely sure what is wrong. Is this something that we must wait for FreeImage to fix, or is there something that could be done at the level of ImageIO ?

Cheers !

Segmentation fault when writing a GIF in a non-existing folder

If I run imageio.get_writer("myfolder/test.gif") without creating myfolder first, I get a Segmentation fault. You should wrap this in a if os.path.exists, with a os.mkdir, or simply raise an error when the path doesn't exist (maybe the simplest solution).

The FFMPEG reader fetches frames with the wrong time

If I want the 300th frame and I call myreader.get_data(300) I will not get the 300th frame, but the frame from one second before. This is because this line in ffmpeg.py reads

iargs = ['-ss', "%.03f" % (starttime-offset)]

Where the offset is 1. Actually, after reaching starttime-offset, it should advance of 'offset' seconds to be exactly on 'starttime', like this:

i_arg = ['-ss', "%.06f" % (starttime - offset),
      '-i', self.filename,
      '-ss', "%.06f" % offset]

See here for details and explanations.

Images stored upside down

I find it extremely unintuitive that imageio (through freeimage) expects image arrays to be upside down to be saved correctly. Virtually every other library does it the other way. There should be a big fat warning in the imageio documentation that I have to flip my image. Ideally though, imageio would do the flipping for me (when reading or writing using freeimage). Or did I miss something fundamental? Btw, I'm writing 16bit tiff files.

Quoting freeimage docs:

In FreeImage, FIBITMAP are based on a coordinate system that is upside down
relative to usual graphics conventions. Thus, the scanlines are stored upside down,
with the first scan in memory being the bottommost scan in the image.

EDIT: Just noticed that I actually have to flip both axes, so img[::-1,::-1], really confusing.

EDIT2: Seems to be the same issue as in scikit-image/scikit-image#1101

avbin plugin yields black images the first 5 frames

On my machine its 5 frames. on Travis it seems more than that ...

Any idea @rreilink ?

Support for frozen apps

We would like imageio to work well in frozen apps.

For now, frozen apps with imageio should just work, but required binaries are still downloaded at runtime. This requires an internet connection, so it may be good to provide a way to ship the binary dependencies.

For this we need to provide a way for the developer to copy all required binaries to the app directory (so they can be shipped along) and we need to look in that directory too.

DICOM reading multi-frame files does not always work

The file dicom_file_2.dcm does not work. I am pretty sure that code has worked on some multi-frame data, but this one obviously does not, while it does work in PyDicom.

Support for FreeBSD OS ?

Hey ! I got this message on Reddit, do you think supporting FreeBSD would be possible ?

have a beefy FreeNAS server and have a ffmpeg jail setup to do some video editing and image processing.

Right now I'm using Make to edit movies (yes, GNU Make). I'd like to use moviepy however it doesn't look like it is supported:

FNAME_PER_PLATFORM = {
'osx32': 'libfreeimage-3.16.0-osx10.6.dylib',  # universal library
'osx64': 'libfreeimage-3.16.0-osx10.6.dylib',
'win32': 'FreeImage-3.15.4-win32.dll',
'win64': 'FreeImage-3.15.1-win64.dll',
'linux32': 'libfreeimage-3.16.0-linux32.so',
'linux64': 'libfreeimage-3.16.0-linux64.so',
}

distutils.util.get_platform() returns:

>>> get_platform()
'freebsd-9.3-RELEASE-p8-amd64'

Is there a way to switch off or prevent autodownload of binaries from imageio ?

Hi there !

I have had a complaint that imageio downloads binaries at first use, and it can be unwanted. Is there an easy way to prevent that from happening (apart from maybe installing the required binaries prior to importing imageio for the first time).

Thanks in advance !

DICOM allow specifying additional tags to read

Since pydicom is not py3k ready yet, it would be convenient if users could specify additional tags for meta information to read.

Plugin: MHD format for reading ITK image data

Used e.g. by the Elastix registration toolkiit.

http://www.itk.org/Wiki/ITK/MetaIO/Documentation

Make numpy an optional dependency

For some usages, you don't need performance, you need portability, ease of deployment, embedding, use with pypy... Making a pure Python lib but requiring a C extension as a dependancy defeats this purpose.

Would it be possible to optionally use Python byte arrays instead of numpy's ?

The lib could then try to load numpy, and then fallback on byte arrays if numpy is not avaible.

This would open the door to the dev of a pure Python PIL alternative and let projects built with Django, Pelican, etc. to add thumbnails generation/cropping/conversion without the need to install a compiled extension. Web hosting can still be hostile to newbies in Python and every time we have a pure Python option, it's a big win.

Use Wheels on PyPI

Right now, pip install imageio downloads the Linux tarball and associated freeimage library. Wheels are preferred downloads for pip.

Test (CI) for installing imageio

Currently all machines test from the repo.

We should also have a test for the correct working on setup.py. So a machine that first installs imageio and then runs the test suite from there ...

Deal with the fact that home dir may not be writable

See Zulko/moviepy#106

Get rid of add_potential_format?

Add Support for Mult-Page Images

Some image types (such as TIFF and GIF), and return multiple images.

conda recipe should include platform libs and example images

Currently it does not.

gif writer should have fps arg for consistency