======================================================
Tiff Tools |build-status| |codecov-io| |license-badge|
======================================================
Pure Python tools for reading and writing all TIFF IFDs, sub-IFDs, and tags.
Developed by Kitware, Inc. with funding from The National Cancer Institute.
Example
=======
.. code-block:: python
import tifftools
info = tifftools.read_tiff('photograph.tif')
info['ifds'][0]['tags'][tifftools.Tag.ImageDescription.value] = {
'data': 'A dog digging.',
'datatype': tifftools.Datatype.ASCII
}
exififd = info['ifds'][0]['tags'][tifftools.Tag.EXIFIFD.value]['ifds'][0][0]
exififd['tags'][tifftools.constants.EXIFTag.FNumber.value] = {
'data': [54, 10],
'datatype': tifftools.Datatype.RATIONAL
}
tifftools.write_tiff(info, 'photograph_tagged.tif')
Commands
========
``tifftools --help`` and ``tifftools <command> --help`` provide usage details.
- ``tifftools split [--subifds] [--overwrite] source [prefix]``: split a tiff file into separate files. This is also available as the library function ``tifftools.tiff_split``.
- ``tifftools concat [--overwrite] source [source ...] output``: merge multiple tiff files together. Alias: ``tifftools merge``. This is also available as the library function ``tifftools.tiff_concat``.
- ``tifftools dump [--max MAX] [--json] source [source ...]``: print information about a tiff file, including all tags, IFDs, and subIFDs. Alias: ``tifftool info``. This is also available as the library function ``tifftools.tiff_dump``.
- ``tifftools set source [--overwrite] [output] [--set TAG[:DATATYPE][,<IFD-#>] VALUE] [--unset TAG:[,<IFD-#>]] [--setfrom TAG[,<IFD-#>] TIFFPATH]``: modify, add, or remove tags. This is also available as the library function ``tifftools.tiff_set``.
Library Functions
=================
- read_tiff
- write_tiff
- Constants
- Tag
- Datatype
- get_or_create_tag
- EXIFTag, GPSTag, etc.
Installation
============
``tifftools`` is available on PyPI and conda-forge.
To install with pip from PyPI::
pip install tifftools
To install with conda::
conda install -c conda-forge tifftools
Purpose
=======
tifftools provides a library and a command line program for maniplulating TIFF
files. It can split multiple images apart, merge images together, set any tag
in any IFD, and dump all IFDs and tags in a single command. It only uses
python standard library modules, and is therefore widely compatible.
Rationale
---------
There was a need to combine images from multiple TIFF files without altering
the image data or losing any tag information. Further, when changing tag
values, it was essential that the old values were fully removed from the
output.
The command line tools associated with libtiff are commonly used for similar
purposes. The libtiff command tools have significant limitations: ``tiffdump``
and ``tiffinfo`` require multiple commands to see information from all IFDs.
``tiffset`` does not remove data from a file; rather it appends to the file to
only reference new data, leaving the old values inside the file. ``tiffsplit``
doesn't keep tags it doesn't recognize, losing data. ``tiffcp`` always
reencodes images and will fail for compression types it does not know.
Likewise, there is a wide variety of EXIF tools. For the most part, these only
alter tags, usually by appending to the existing file. ImageMagick's
``convert`` command also recompresses images as it combines them.
Many programs deal with both classic and BigTIFF. Some will start writing a
classic TIFF, but leave a small amount of unused space just after the file
header. If the file exceeds 4Gb, parts of the file are rewritten to convert it
to a BigTIFF file, leaving small amounts of abandoned data within the file.
``tifftools`` fills this need. All tags are copied, even if unknown. Files
are always rewritten so that there is never abandoned data inside the file.
``tifftools dump`` shows information on all IFDs and tags. Many of the command
line options are directly inspired from libtiff.
``tifftools`` does NOT compress or decompress any image data. This is not an
image viewer. If you need to recompress an image or otherwise manipulate pixel
data, use libtiff or another library.
As an explicit example, with libtiff's ``tiffset``, tag data just gets
dereferenced and is still in the file:
.. code-block:: bash
$ grep 'secret' photograph.tif || echo 'not present'
not present
$ tiffset -s ImageDescription "secret phrase" photograph.tif
$ tiffinfo photograph.tif | grep ImageDescription
ImageDescription: secret phrase
$ grep 'secret' photograph.tif || echo 'not present'
Binary file photograph.tif matches
$ tiffset photograph.tif -s ImageDescription "public phrase"
$ tiffinfo photograph.tif | grep ImageDescription
ImageDescription: public phrase
$ grep 'secret' photograph.tif || echo 'not present'
Binary file photograph.tif matches
Whereas, with ``tifftools``:
.. code-block:: bash
$ grep 'secret' photograph.tif || echo 'not present'
not present
$ tifftools set -y -s ImageDescription "secret phrase" photograph.tif
$ tiffinfo photograph.tif | grep ImageDescription
ImageDescription: secret phrase
$ grep 'secret' photograph.tif || echo 'not present'
Binary file photograph.tif matches
$ tifftools set -y photograph.tif -s ImageDescription "public phrase"
$ tiffinfo photograph.tif | grep ImageDescription
ImageDescription: public phrase $ grep 'secret' photograph.tif || echo
'not present' not present
TIFF File Structure
===================
TIFF Files consist of one or more IFDs (Image File Directories). These can be
located anywhere within the file, and are referenced by their absolute position
within the file. IFDs can refer to image data; they can also contain a
collection of metadata (for instance, EXIF or GPS data). Small data values are
stored directly in the IFD. Bigger data values (such as image data, longer
strings, or lists of numbers) are referenced by the IFD and are stored
elsewhere in the file.
In the simple case, a TIFF file may have a list of IFDs, each one referencing
the next. However, a complex TIFF file, such as those used by some Whole-Slide
Image (WSI) microscopy systems, can have IFDs organized in a branching
structure, where some IFDs are in a list and some reference SubIFDs with
additional images.
TIFF files can have their primary data stored in either little-endian or
big-endian format. Offsets to data are stored as absolute numbers inside a
TIFF file. There are two variations: "classic" and "BigTIFF" which use 32-bits
and 64-bits for these offsets, respectively. If the file size exceeds 4 Gb or
uses 64-bit integer datatypes, it must be written as a BigTIFF.
Limitations
===========
Unknown tags that are offsets and have a datatype other than IFD or IFD8 won't
be copied properly, as it is impossible to distinguish integer data from
offsets given LONG or LONG8 datatypes. This can be remedied by defining a new
``TiffConstant`` record which contains a ``bytecounts`` entry to instruct
whether the offsets refer to fixed length data or should get the length of data
from another tag.
Because files are ALWAYS rewritten, ``tifftools`` is slower than libtiff's
``tiffset`` and most EXIF tools.
.. |build-status| image:: https://circleci.com/gh/DigitalSlideArchive/tifftools.png?style=shield
:target: https://circleci.com/gh/DigitalSlideArchive/tifftools
:alt: Build Status
.. |codecov-io| image:: https://img.shields.io/codecov/c/github/DigitalSlideArchive/tifftools.svg
:target: https://codecov.io/gh/DigitalSlideArchive/tifftools
:alt: codecov.io
.. |license-badge| image:: https://img.shields.io/badge/license-Apache%202-blue.svg
:target: https://raw.githubusercontent.com/DigitalSlideArchive/tifftools/master/LICENSE
:alt: License
Raw data
{
"_id": null,
"home_page": "https://github.com/DigitalSlideArchive/tifftools",
"name": "tifftools",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "tiff",
"author": "Kitware, Inc.",
"author_email": "kitware@kitware.com",
"download_url": "https://files.pythonhosted.org/packages/cc/15/e902583d3353a3a316ede3e831fc4383b39f97d99a000c7d5d0f2da112dc/tifftools-1.5.2.tar.gz",
"platform": null,
"description": "======================================================\nTiff Tools |build-status| |codecov-io| |license-badge|\n======================================================\n\nPure Python tools for reading and writing all TIFF IFDs, sub-IFDs, and tags.\n\nDeveloped by Kitware, Inc. with funding from The National Cancer Institute.\n\nExample\n=======\n\n.. code-block:: python\n\n import tifftools\n info = tifftools.read_tiff('photograph.tif')\n info['ifds'][0]['tags'][tifftools.Tag.ImageDescription.value] = {\n 'data': 'A dog digging.',\n 'datatype': tifftools.Datatype.ASCII\n }\n exififd = info['ifds'][0]['tags'][tifftools.Tag.EXIFIFD.value]['ifds'][0][0]\n exififd['tags'][tifftools.constants.EXIFTag.FNumber.value] = {\n 'data': [54, 10],\n 'datatype': tifftools.Datatype.RATIONAL\n }\n tifftools.write_tiff(info, 'photograph_tagged.tif')\n\nCommands\n========\n\n``tifftools --help`` and ``tifftools <command> --help`` provide usage details.\n\n- ``tifftools split [--subifds] [--overwrite] source [prefix]``: split a tiff file into separate files. This is also available as the library function ``tifftools.tiff_split``.\n\n- ``tifftools concat [--overwrite] source [source ...] output``: merge multiple tiff files together. Alias: ``tifftools merge``. This is also available as the library function ``tifftools.tiff_concat``.\n\n- ``tifftools dump [--max MAX] [--json] source [source ...]``: print information about a tiff file, including all tags, IFDs, and subIFDs. Alias: ``tifftool info``. This is also available as the library function ``tifftools.tiff_dump``.\n\n- ``tifftools set source [--overwrite] [output] [--set TAG[:DATATYPE][,<IFD-#>] VALUE] [--unset TAG:[,<IFD-#>]] [--setfrom TAG[,<IFD-#>] TIFFPATH]``: modify, add, or remove tags. This is also available as the library function ``tifftools.tiff_set``.\n\nLibrary Functions\n=================\n\n- read_tiff\n\n- write_tiff\n\n- Constants\n\n- Tag\n\n- Datatype\n\n- get_or_create_tag\n\n- EXIFTag, GPSTag, etc.\n\nInstallation\n============\n\n``tifftools`` is available on PyPI and conda-forge.\n\nTo install with pip from PyPI::\n\n pip install tifftools\n\nTo install with conda::\n\n conda install -c conda-forge tifftools\n\nPurpose\n=======\n\ntifftools provides a library and a command line program for maniplulating TIFF\nfiles. It can split multiple images apart, merge images together, set any tag\nin any IFD, and dump all IFDs and tags in a single command. It only uses\npython standard library modules, and is therefore widely compatible.\n\nRationale\n---------\n\nThere was a need to combine images from multiple TIFF files without altering\nthe image data or losing any tag information. Further, when changing tag\nvalues, it was essential that the old values were fully removed from the\noutput.\n\nThe command line tools associated with libtiff are commonly used for similar\npurposes. The libtiff command tools have significant limitations: ``tiffdump``\nand ``tiffinfo`` require multiple commands to see information from all IFDs.\n``tiffset`` does not remove data from a file; rather it appends to the file to\nonly reference new data, leaving the old values inside the file. ``tiffsplit``\ndoesn't keep tags it doesn't recognize, losing data. ``tiffcp`` always\nreencodes images and will fail for compression types it does not know.\n\nLikewise, there is a wide variety of EXIF tools. For the most part, these only\nalter tags, usually by appending to the existing file. ImageMagick's\n``convert`` command also recompresses images as it combines them.\n\nMany programs deal with both classic and BigTIFF. Some will start writing a\nclassic TIFF, but leave a small amount of unused space just after the file\nheader. If the file exceeds 4Gb, parts of the file are rewritten to convert it\nto a BigTIFF file, leaving small amounts of abandoned data within the file.\n\n``tifftools`` fills this need. All tags are copied, even if unknown. Files\nare always rewritten so that there is never abandoned data inside the file.\n``tifftools dump`` shows information on all IFDs and tags. Many of the command\nline options are directly inspired from libtiff.\n\n``tifftools`` does NOT compress or decompress any image data. This is not an\nimage viewer. If you need to recompress an image or otherwise manipulate pixel\ndata, use libtiff or another library.\n\nAs an explicit example, with libtiff's ``tiffset``, tag data just gets\ndereferenced and is still in the file:\n\n.. code-block:: bash\n\n $ grep 'secret' photograph.tif || echo 'not present'\n not present\n $ tiffset -s ImageDescription \"secret phrase\" photograph.tif\n $ tiffinfo photograph.tif | grep ImageDescription\n ImageDescription: secret phrase\n $ grep 'secret' photograph.tif || echo 'not present'\n Binary file photograph.tif matches\n $ tiffset photograph.tif -s ImageDescription \"public phrase\"\n $ tiffinfo photograph.tif | grep ImageDescription\n ImageDescription: public phrase\n $ grep 'secret' photograph.tif || echo 'not present'\n Binary file photograph.tif matches\n\nWhereas, with ``tifftools``:\n\n.. code-block:: bash\n\n $ grep 'secret' photograph.tif || echo 'not present'\n not present\n $ tifftools set -y -s ImageDescription \"secret phrase\" photograph.tif\n $ tiffinfo photograph.tif | grep ImageDescription\n ImageDescription: secret phrase\n $ grep 'secret' photograph.tif || echo 'not present'\n Binary file photograph.tif matches\n $ tifftools set -y photograph.tif -s ImageDescription \"public phrase\"\n $ tiffinfo photograph.tif | grep ImageDescription\n ImageDescription: public phrase $ grep 'secret' photograph.tif || echo\n 'not present' not present\n\nTIFF File Structure\n===================\n\nTIFF Files consist of one or more IFDs (Image File Directories). These can be\nlocated anywhere within the file, and are referenced by their absolute position\nwithin the file. IFDs can refer to image data; they can also contain a\ncollection of metadata (for instance, EXIF or GPS data). Small data values are\nstored directly in the IFD. Bigger data values (such as image data, longer\nstrings, or lists of numbers) are referenced by the IFD and are stored\nelsewhere in the file.\n\nIn the simple case, a TIFF file may have a list of IFDs, each one referencing\nthe next. However, a complex TIFF file, such as those used by some Whole-Slide\nImage (WSI) microscopy systems, can have IFDs organized in a branching\nstructure, where some IFDs are in a list and some reference SubIFDs with\nadditional images.\n\nTIFF files can have their primary data stored in either little-endian or\nbig-endian format. Offsets to data are stored as absolute numbers inside a\nTIFF file. There are two variations: \"classic\" and \"BigTIFF\" which use 32-bits\nand 64-bits for these offsets, respectively. If the file size exceeds 4 Gb or\nuses 64-bit integer datatypes, it must be written as a BigTIFF.\n\nLimitations\n===========\n\nUnknown tags that are offsets and have a datatype other than IFD or IFD8 won't\nbe copied properly, as it is impossible to distinguish integer data from\noffsets given LONG or LONG8 datatypes. This can be remedied by defining a new\n``TiffConstant`` record which contains a ``bytecounts`` entry to instruct\nwhether the offsets refer to fixed length data or should get the length of data\nfrom another tag.\n\nBecause files are ALWAYS rewritten, ``tifftools`` is slower than libtiff's\n``tiffset`` and most EXIF tools.\n\n\n.. |build-status| image:: https://circleci.com/gh/DigitalSlideArchive/tifftools.png?style=shield\n :target: https://circleci.com/gh/DigitalSlideArchive/tifftools\n :alt: Build Status\n\n.. |codecov-io| image:: https://img.shields.io/codecov/c/github/DigitalSlideArchive/tifftools.svg\n :target: https://codecov.io/gh/DigitalSlideArchive/tifftools\n :alt: codecov.io\n\n\n.. |license-badge| image:: https://img.shields.io/badge/license-Apache%202-blue.svg\n :target: https://raw.githubusercontent.com/DigitalSlideArchive/tifftools/master/LICENSE\n :alt: License\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "Pure python tiff tools to handle all tags and IFDs.",
"version": "1.5.2",
"project_urls": {
"Homepage": "https://github.com/DigitalSlideArchive/tifftools"
},
"split_keywords": [
"tiff"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "23d3266e38f9b4e55e5a8d79d2f2e77544eebeed55a2a1dea053f13e17be0231",
"md5": "b40495c8a39565b03b2068d750a13a30",
"sha256": "fcfef4a032459c702b0ef628c1e56b03a3fe9ca953caab48bc54958bc0ac4361"
},
"downloads": -1,
"filename": "tifftools-1.5.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b40495c8a39565b03b2068d750a13a30",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 40148,
"upload_time": "2024-04-25T17:45:34",
"upload_time_iso_8601": "2024-04-25T17:45:34.193406Z",
"url": "https://files.pythonhosted.org/packages/23/d3/266e38f9b4e55e5a8d79d2f2e77544eebeed55a2a1dea053f13e17be0231/tifftools-1.5.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cc15e902583d3353a3a316ede3e831fc4383b39f97d99a000c7d5d0f2da112dc",
"md5": "3032fd2df5ec5d22ea3b42bc0f44fee7",
"sha256": "a7d7e001191d6813c1ae05f4b58485e646d4de36b5e16575b1c869a7c3a21bbb"
},
"downloads": -1,
"filename": "tifftools-1.5.2.tar.gz",
"has_sig": false,
"md5_digest": "3032fd2df5ec5d22ea3b42bc0f44fee7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 56325,
"upload_time": "2024-04-25T17:45:37",
"upload_time_iso_8601": "2024-04-25T17:45:37.018104Z",
"url": "https://files.pythonhosted.org/packages/cc/15/e902583d3353a3a316ede3e831fc4383b39f97d99a000c7d5d0f2da112dc/tifftools-1.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-25 17:45:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DigitalSlideArchive",
"github_project": "tifftools",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"tox": true,
"lcname": "tifftools"
}
JSON
