A lightwight wrapper around the LibTIFF library (http://www.libtiff.org/). LibTIFF is a widely used C library for reading and writing Tagged Image File Format (TIFF) files.
The current implementation supports:
- Version: 42 (TIFF), 43 (BigTIFF)
- Storage organization: strip-based or tile-based
- Color depth: 8bit and 16bit
- Sub-File type: reduced image, page, mask
The library was tested on Windows and Linux - not (yet) on MacOS!
To avoid conflicts with other packages, it is recommended to install PyLibTIFF within a virtual environment. Please refer to "The Python Tutorial" for further information (https://docs.python.org/3/tutorial/venv.html).
PyLibTIFF can be installed using a pre-compiled Wheel package available at https://github.com/fmi-basel/pylibtiff/releases. After downloading a wheel matching your operating system, your CPU architecture and Python version you can install the package via pip. E.g., the following command installs PyLibTIFF v1.0.7 on a 64bit Windows with Python 3.6:
pip install pylibtiff-1.0.7-cp36-cp36m-win_amd64.whl
To install PyLibTIFF from the source code you need a C/C++ compiler (e.g. GCC) and the following C libraries (as devel package or source code):
- zlib (https://zlib.net/) [tested: v1.2.11]
- libjpeg (https://www.ijg.org/) [tested: v9.4.0]
- libtiff (http://www.libtiff.org/) [tested: v4.0.7]
Moreover, the following Python packages are required:
- pybind11 [tested: v2.2.4]
- wheel (optional, required for compiling Wheel packages) [tested: v0.34.2]
PyLibTIFF can be installed via pip...
pip install .
...or, compiled as a Wheel package.
python setup.py bdist_wheel
Under Linux, PyLibTIFF is linked agains dynamic libraries as recommended by Red Hat while on Windows it is linked agains static libraries. This reflects the expectation of the two user groups. While it is common to install devel packages and to compile binaries on Linux a Windows user expects a pre-build binary.
Depending on your development environment you many need to specify additional include or library paths for the compiler or linker. This can be specified by the "build_ext" option:
pip install . --global-option=build_ext --global-option="-I/path/to/include-dir" --global-option="-L/path/to/library-dir"
The following code snippet shows how to use the Python package within another project:
import numpy as np
from pylibtiff import TiffFile
# initialize a TIFF file (only reads meta information)
file_path = 'path_to_tiff_file'
tiff = TiffFile(file_path)
# read first subfile as Numpy array
np_array = tiff.read_subfile(0)
# modify subfile
np_array *= 0
# write modified subfile (as 16bit image, in tiles) at the end of the TIFF file
tiff.write_subfile(np_array.astype(np.uint16), tile_size=1024)
# read TIFF tags from last subfile
tiff_tags = tiff.subfile_tags[-1]
print(tiff_tags.tile_width) # output: 1024This repository comes with a set of automated tests that can be run by the following command:
python setup.py test
PyLibTIFF comes with two documentations for Python (using Sphinx) and C++ (using Doxygen).
Generating the main documentation is a two-step process. Firstly, you have to generate the source files for the API documentation:
sphinx-apidoc --module-first -o ./sphinx_docs/pylibtiff/api_reference ./src/pylibtiff ./src/pylibtiff/ext
In a second step, you can generate the full documentation e.g. as a series of HTML files:
sphinx-build -b html ./sphinx_docs ./_sbuild
A secondary documentation can be generated for the C++ code:
doxygen ./doxygen_docs/doxyfile.cfg
This will generate HTML and LaTeX files within the directory "./_dbuild".
Note: The C++ documentation only covers the API reference and does not include the user guide.
This project is licensed under the MIT License - see the LICENSE file for details.