imread Documentation Release 0.6

Luis Pedro Coelho

Sep 30, 2018

Contents

1 Citation 3 1.1 INSTALL...... 3 1.2 Bug Reports...... 9

2 Indices and tables 11

i ii imread Documentation, Release 0.6

Imread is a very simple libray. It has three functions imread Reads an image from disk imread_multi Reads multiple images from disk (only for file formats that support multiple images) imwrite Save an image to disk That’s it. This needs to be used with a a computer vision & image processing packages: • mahotas • scikit-image • OpenCV This grew out of frustration at current image loading solutions in Python, in either my packages [mahotas] or packages from others [scikit-image, for example]. The relationship with numpy is very contained and this could be easily repurposed to load images in other frameworks, even other programming languages.

Contents 1 imread Documentation, Release 0.6

2 Contents CHAPTER 1

Citation

This package is an off-shoot of mahotas. As it, currently, does not have its own publication, so you are asked to cite the mother package: If you use imread-mahotas on a scientific publication, please cite: Luis Pedro Coelho Mahotas: Open source software for scriptable computer vision in Journal of Open Research Software, vol 1, 2013. [DOI] In Bibtex format:

@article{mahotas, author= {Luis Pedro Coelho}, title= {Mahotas: Open source software for scriptable computer vision}, journal= {Journal of Open Research Software}, year={2013}, doi= {http://dx.doi.org/10.5334/jors.ac}, month= {July}, volume={1} }

1.1 INSTALL

On Windows, you can also just download a pre-built package from C. Gohlke’s repository To compile on debian/ubuntu:

sudo apt-get install libpng12-dev libtiff4-dev libwebp-dev sudo apt-get install xcftools

To compile on Mac:

sudo port install libpng

Either way, you can then install:

3 imread Documentation, Release 0.6

pip install imread

Contents:

1.1.1 IMREAD

This is library to read & write image files.

1.1.2 How To Install Mahotas-imread

From source

You can get the released version using our favorite Python package manager: pip install imread

If you prefer, you can download the source from PyPI and run: python setup.py install

You will need to have numpy and a C++ compiler.

Bleeding Edge (Development)

Development happens on github. You can get the development source there. Watch out that these versions are more likely to have problems.

On Windows

On Windows, Christoph Gohlke does an excelent job maintaining binary packages of imread (and several other pack- ages). conda

Imread is not a part of standard conda packages, but on 64 bit Linux, you can get it ‘from this repository

4 Chapter 1. Citation imread Documentation, Release 0.6

1.1.3 Formats Supported

Format Read Write Since version Notes PNG Y Y 0.1 PNG (16 bits) Y Y 0.4 TIFF Y Y 0.1 JPEG Y Y 0.1 WEBP Y N 0.2 BMP Y N 0.2.5 Only uncompressed are supported. STK Y N 0.2 LSM Y N 0.2.2 XCF Y N 0.2.2 Only if xcf2png utility is found in the path.

Options

Some of the formats allow you to specify options when saving. These are inevitably format specific.

PNG

png:compression_level Compression level to use, from 0 (no compression) to 9. Setting it to 0 is discouraged.

JPEG

:quality An integer 1-100 determining the quality used by JPEG backend (default is libjpeg default: 75).

TIFF tiff:compress Whether to use compression when saving TIFF (default: True) tiff:horizontal-predictor Whether to use horizontal prediction in TIFF. This defaults to True for 16 bit images, and to False for 8 bit images. This is because compressing 16 bit images without horizontal prediction is often counter-productive (see http://www.asmail.be/msg0055176395.html)

1.1.4 Using imread outside of Python

Actually, imread is not a Python library. It’s really a C++ library with very good Python/numpy bindings. But you can easily use it from other languages (including C++, of course) by adapting your image representation to the imread interface.

The Image and the ImageFactory interfaces

You need to support the Image interface:

class Image { public: // number of dimensions virtual int ndims() const = 0;

(continues on next page)

1.1. INSTALL 5 imread Documentation, Release 0.6

(continued from previous page) // size of dimension d virtual int dim(int d) const = 0;

// get a pointer to row `r` virtual void* rowp(int r) = 0; };

It is assumed that an RGB image is represented as H x W x 3 and RGBA as H x W x 4. You also need to support the ImageFactory interface: class ImageFactory { public: Image* create(int nbits, int w, int h, int d); };

The create methods create 2 or 3-dimensional images with nbits per . See the numpy interface in the source code for inspiration.

1.1.5 History

Version 0.7.0 (2018-09-30)

• Add support for reading ImageJ ROIs

Version 0.6.1 (2018-02-15)

• Support pathlib paths as function arguments • Fix 16 bit PNG write support (patch by Tomi Aarnio)

Version 0.6 (2016-09-21)

• Add supports_format function • Make png compression level tunable when calling imsave • Add imsave_multi • Add partial support for reading PNG files in Gray+alpha format

Version 0.5.1 (2014-11-06)

• Improve tests to work after installation • Fix compilation in MSVC (patch by Christoph Gohlke)

Version 0.5 (2014-10-16)

• Add magic-number based format auto-detection • Auto detect whether webp is installed • Fix WebP reading (update to newer API)

6 Chapter 1. Citation imread Documentation, Release 0.6

Version 0.4 (2014-07-21)

• Add configuration for TIFF saving • Correctly save 16 bit PNG images • Better error messages for JPEG

Version 0.3.2 (2013-10-06)

• Added imload*/imwrite synonyms as suggested by Thouis (Ray) Jones • Options framework • Allow user to specify JPEG quality when saving • Fix loading of 16 bit PNG images

Version 0.3.1 (2013-06-20)

• Fix possible crash on error with TIFF • Fix compilation on Windows (reported by Volker Hilsenstein) • Make it easy to compile without WebP

Version 0.3.0 (2013-07-29)

• Support for reading from in-memory blobs • Support for reading & writing TIFF • Add PHOTOMETRIC tag to TIFF (reported by Volker Hilsenstein) • Support writing RGB

Version 0.2.6 (2013-06-19)

• Fix hard crash when saving with non-existing file type • Fix compilation on MacOS (patch by Alexander Bohn) • Add verbose argument to tests.run() • Better error when attempting to save floating point images

Version 0.2.5 (2012-10-29)

• Correctly accept uppercase extensions • Python 3 support (patch by Christoph Gohlke [pull request 8 on github]) • Read 1-Bit PNGs • Read simple BMPs (compression and many bit types not supported) • More complete debug mode (export DEBUG=2 when building), more checks

1.1. INSTALL 7 imread Documentation, Release 0.6

Version 0.2.4 (2012-06-26)

• Add lzw.cpp to source distribution • Support saving 16-bit TIFF • Better Mac OS support (patch from Alexander Bohn)

Version 0.2.3 (2012-06-8)

• Fix imread_multi

Version 0.2.2 (2012-06-5)

• Add formatstr argument to imread • Open files in binary mode on Windows (patch by Christoph Gohlke) • Read-only support for LSM files • Read-only support for XCF files (through xcf2png) • Fix writing of non-contiguous images (at least PNG was affected)

Version 0.2.1 (2012-02-11)

• Add missing files to distribution

Version 0.2 (2012-03-19)

• Compile on MSVC++ (Patches by Christoph Gohlke) • Support for WebP • Support for 1-bit TIFFs • Better error message • Support for multi-page TIFF reading • Experimental read-only support for STK files

Version 0.1 (2012-02-28)

• Support for PNG • Support for TIFF • Support for JPEG

8 Chapter 1. Citation imread Documentation, Release 0.6

1.2 Bug Reports

Please report any bugs either on github or by email to [email protected] If you have a test case where are not sure of whether imread is behaving correctly, you can discuss this on the python- vision mailing list If at all possible, include a small image as a test case.

1.2. Bug Reports 9 imread Documentation, Release 0.6

10 Chapter 1. Citation CHAPTER 2

Indices and tables

• genindex • modindex • search

11