Welcome to Pytiff¶

Pytiff is a Python library for reading and writing large Tiff files. It supports tiled Tiffs and is able to read only a part of the image.

While this is pytiffs main advantage, it also supports reading of many other image formats and writing of greyscale images in tile or scanline mode.

Quick start guide¶

This document talks you through everything you need to get started with pytiff.

Installing¶

Clone the github repository and install pytiff using setup.py or pip. Requirements are listed in the requirements.tx:

numpy
cython
libtiff C library > 4.0

Using pip:

pip install pytiff

Install from sources:

git clone https://github.com/FZJ-INM1-BDA/pytiff.git
cd pytiff
pip install .

You can also use the -e option with pip for development purposes. Be aware that you have to rebuild the cython parts if they are changed.

python setup.py build_ext --inplace

Reading a tiff file¶

Pytiff can read greyscale as well as RGB(A) images. For a greyscale image it assumes a tiled image in order to be able to load parts of it. If this is not the case the whole image is loaded and cropped afterwards. The following code returns a numpy array with the shape (100, 200).

import pytiff

with pytiff.Tiff("test_data/small_example_tiled.tif") as handle:
  part = handle[100:200, 200:400]

Reading a multipage tiff file¶

A multipage tiff file can be read by iterating over the pages. The pages attribute returns a list of pages:

import pytiff

with pytiff.Tiff("test_data/multi_page.tif") as handle:
  for page in handle.pages:
    print("Current shape: {}".format(handle.shape))
    current_page = handle[:]

or manually:

import pytiff

with pytiff.Tiff("test_data/multi_page.tif") as handle:
  for p in range(handle.number_of_pages):
    handle.set_page(p)
    print("Current shape: {}".format(handle.shape))
    current_page = handle[:]

Writing a tiff file¶

Pytiff is able to save two dimensional numpy arrays as images.

import numpy as np
import pytiff
with pytiff.Tiff("test_data/tmp.tif", "w") as handle:
  data = np.random.randint(low=0, high=255, size=(500, 300), dtype=np.uint8)
  handle.write(data, method="scanline")

Writing a multipage tiff file¶

A multipage tiff file can be created by calling the write method multiple times. The following code creates a tiff file with 5 pages.

import numpy as np
import pytiff
with pytiff.Tiff("test_data/tmp.tif", "w") as handle:
  for i in range(5):
    data = np.random.randint(low=0, high=255, size=(100, 100), dtype=np.uint8)
    handle.write(data, method="tile")

Writing a bigtiff file¶

A bigtiff file can be created by telling pytiff to use the bigtiff mode.

import numpy as np
import pytiff
with pytiff.Tiff("test_data/tmp.tif", "w", bigtiff=True) as handle:
  data = np.random.randint(high=255, size=(80000, 80000), dtype=np.uint8)
  handle.write(data, method="tile")

Reading and Writing Standard Tags¶

A tiff file can contain many tags. Pytiff supports reading and writing baseline tags and some more.

import pytiff
with pytiff.Tiff("test_data/small_example.tif") as handle:
  for k in handle.tags:
    print("{key}: {value}".format(key=k, value=tags[k]))

Writing tags has to be done before image data is written to the current page.

import pytiff
with pytiff.Tiff("test_data/tmp.tif", "w") as handle:
  handle.set_tags(image_description="Image description")
  handle.write(data)

All available tags can be found at pytiff.tags.

More information¶

More information on the available methods and attributes can be found in the api documentation.

Pickle a Tiff object¶

While it is not recommended, a Tiff object can be pickled using the pickle or cPickle modules. It only saves the filename, filemode, bigtiff and the current page_number.

When loading a Tiff object the saved information is used to create a new object. Be aware that the same filemode is used. If you open a file in writing mode and pickle it, it will be opened in writing mode again. Thus overriding all written data.

Pickling is supported, so that a Tiff object can be used as a input source in a multiprocessing environment. Frameworks for multiprocessing often share data between different processes by sending pickled objects.

pytiff package¶

Module contents¶

pytiff.byteorder(filename)¶

Check the byteorder of a given file.

Parameters:	filename (str) – Filename of a tiff image.
Returns:	‘<’ for little endian, ‘>’ for big endian.
Return type:	str

pytiff.is_bigtiff(filename)¶

Check if a tiff image is bigtiff or not.

Parameters:	filename (str) – Filename of a tiff image.
Returns:	True if the file is a bigtiff, False otherwise.
Return type:	bool