# mahotas-imread: Read Image Files

[![License](https://anaconda.org/conda-forge/imread/badges/license.svg)](https://opensource.org/licenses/MIT)
[![Install with conda](https://img.shields.io/badge/install%20with-conda-brightgreen.svg?style=flat)](https://anaconda.org/conda-forge/imread)
[![image](https://anaconda.org/conda-forge/imread/badges/downloads.svg)](https://anaconda.org/conda-forge/imread)
[![Test mahotas-imread](https://github.com/luispedro/imread/actions/workflows/test-python-package-with-conda.yml/badge.svg)](https://github.com/luispedro/imread/actions/workflows/test-python-package-with-conda.yml)
[![Documentation Status](https://readthedocs.org/projects/imread/badge/?version=latest)](https://imread.readthedocs.io/en/latest/?badge=latest)

IO with images and NumPy arrays.

Mahotas-imread is a simple module with a small number of functions:

- `imread`: Reads an image file
- `imread_multi`: Reads all the images in a multi-image file (TIFF and STK)
- `imread_from_blob`: Reads an image from a `bytes` object in memory
- `imsave`: Writes an image file
- `imsave_multi`: Writes several images into a single file (TIFF only)
- `detect_format`: Detects the format of a file or blob from its magic number (PNG and JPEG only)
- `supports_format`: Checks whether a format is supported
- `imread.ijrois.read_roi` and `imread.ijrois.read_roi_zip`: Read [ImageJ](https://imagej.net/) regions of interest

`imload`, `imload_multi`, `imload_from_blob`, `imwrite` and `imwrite_multi`
are aliases.

PNG, JPEG and TIFF can be read and written. WebP, BMP, LSM, STK and XCF can
be read. XCF needs the `xcf2png` utility (from xcftools).

Example (which uses [mahotas](https://luispedro.org/software/mahotas)
for Gaussian filtering):

```python
import numpy as np
from imread import imread, imsave
from mahotas import gaussian_filter

image = imread('photo.jpeg', as_grey=True)
blurred = gaussian_filter(image, 4.)
imsave('photo-blurred.png', blurred.astype(np.uint8))
```

`imsave` only accepts integer arrays, so floating point results must be
converted (here, to `uint8`) before saving.

This grew out of frustration at current image loading solutions in
Python, in either my packages \[[mahotas](https://mahotas.rtfd.io)\] or
packages from others \[[scikit-image](https://scikit-image.org/), for
example\].

The relationship with NumPy is very contained, so this could easily be
repurposed to load images in other frameworks, or even in other programming
languages.

[Online documentation](https://imread.rtfd.io/)

## Citation

If you use imread in a publication, please cite the main
[mahotas](https://mahotas.rtfd.io) paper (imread is a spin-off of
mahotas):

> **Luis Pedro Coelho** Mahotas: Open source software for scriptable
> computer vision in Journal of Open Research Software, vol 1, 2013.
> \[[DOI](https://doi.org/10.5334/jors.ac)\]

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 = {10.5334/jors.ac},
    month = {July},
    volume = {1}
}
```

## Installation

imread requires Python 3.11 or later and NumPy 2.0 or later.

### With pixi (recommended)

[pixi](https://pixi.sh) installs imread, together with the C libraries it
needs, from [conda-forge](https://conda-forge.org):

```bash
pixi init my-project
cd my-project
pixi add imread
pixi run python -c "import imread; print(imread.__version__)"
```

In an existing pixi project, `pixi add imread` is all you need.

### With pip

```bash
pip install imread
```

Binary wheels are provided for Linux (x86_64 and aarch64), macOS (Intel and
Apple Silicon, macOS 15 or later) and Windows (AMD64 and ARM64). On other
platforms, pip builds imread from source (see below).

### From source

Building imread needs a C++ compiler, `pkg-config` and the development files
for libpng, libjpeg and libtiff. libwebp is optional: WebP support is built
only if it is found. pixi can provide all of these:

```bash
git clone https://github.com/luispedro/imread
cd imread
pixi init --format pixi
pixi add python numpy pip meson-python meson ninja pkg-config cxx-compiler \
    zlib libpng libjpeg-turbo libtiff libwebp
pixi run pip install --no-build-isolation .
```

To build without WebP support, pass
`--config-settings=setup-args=-Dwebp=disabled` to `pip install`.

### With nix

```
nix-env -iA nixpkgs.python3Packages.imread
```

or use the `pkgs.python3Packages.imread` object in your `*.nix` files.

## Links & Contacts

- *Documentation*: https://imread.readthedocs.io/
- *Issue Tracker*: [GitHub imread issues](https://github.com/luispedro/imread/issues)
- *Mailing List*: Use the [pythonvision mailing list](https://groups.google.com/group/pythonvision?pli=1) for questions, bug submissions, etc.
- *Main Author & Maintainer*: [Luis Pedro Coelho](https://luispedro.org) (follow on [Twitter](https://twitter.com/luispedrocoelho) or [GitHub](https://github.com/luispedro)).

## History

### Version 0.7.7+

-   Require Python 3.11 or later and NumPy 2.0 or later
-   Switch build system to meson-python
-   Build wheels for Linux (x86_64, aarch64), macOS and Windows
-   Fix the `tiff:YResolution` option, which was ignored (`tiff:XResolution` was used for both)
-   Fix hang and buffer over-read on truncated JPEG files
-   Raise `TypeError` on invalid options instead of aborting the interpreter
-   Fix out-of-bounds reads in `imread_from_blob` on malformed or truncated input
-   Fix crash when reading an empty WebP blob
-   Fix BMP reading: top-down bitmaps, BITMAPV4/V5 headers, and swapped red and blue channels in paletted images
-   Support 1-, 4- and 32-bit BMPs; 16-bit BMPs are now returned as RGB
-   Fix saving of big-endian (non-native byte order) arrays, which were written byte-swapped
-   Raise an error when saving TIFF metadata containing NUL bytes, instead of silently truncating it

### Version 0.7.6 (2024-08-02)

-   Fix loading paletted PNGs with transparency

### Version 0.7.5 (2023-11-22)

-   Fix build issue (#43, patch by @carlosal1015)

### Version 0.7.4 (2020-04-14)

-   Add missing header files to distribution

### Version 0.7.3 (2020-04-09)

-   Add missing test data to distribution

### Version 0.7.2 (2020-03-24)

-   Fix several memory access bugs in parsers (reported by Robert Scott)

### Version 0.7.1 (2019-05-09)

-   Fix 16-bit RGB/RGBA TIFF write (patch by Tomi Aarnio)

### 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 with 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)

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

-   Add 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-08-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 metadata
-   Add PHOTOMETRIC tag to TIFF (reported by Volker Hilsenstein)
-   Support writing RGB TIFFs

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

### Version 0.2.4 (2012-06-26)

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

### Version 0.2.3 (2012-06-08)

-   Fix imread_multi

### Version 0.2.2 (2012-06-05)

-   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-04-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