| Name | tiffdata JSON |
| Version |
0.5.1
JSON |
| download |
| home_page | None |
| Summary | Streamlined TIFF image metadata parsing and updating. |
| upload_time | 2025-08-07 06:51:13 |
| maintainer | None |
| docs_url | None |
| author | Daniel Sissman |
| requires_python | >=3.10 |
| license | None |
| keywords |
image
metadata
tiff
data
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# TIFFData
The TIFFData library for Python provides a streamlined way to work with TIFF image files
offering the ability to extract and modify metadata and tags without modifying any the
of image data held within the file itself.
The library can be used to support a range of use cases, including situations where it
is important to be able to read, modify and write TIFF image metadata without affecting
the visual quality and fidelity of any image canvases held within the file. This is
especially important in cases where a TIFF file holds one or more image canvases encoded
using a lossy compression algorithm such as JPEG encoding. Loading, modifying and
resaving such files using libraries which also load and decompress image canvas data
before recompressing and resaving the file will result in a reduction in image quality
and fidelity during each load-and-save cycle.
The TIFFData library does not provide any image canvas transformation capabilities, such
as resizing or rotation. For cases where one needs to perform such image transformation
operations, other libraries such as PyVIPS and Pillow are recommended. However, for use
cases related specifically to TIFF metadata and TIFF tag manipulation, the TIFFData
library offers many unique features. One can also develop workflows which leverage
functionality from libraries such as PyVIPS and Pillow, in combination with the metadata
inspection and modification capabilities offered by the TIFFData library.
### Requirements
The TIFFData library has been tested to work with Python 3.10, 3.11, 3.12 and 3.13, but
has not been tested, nor is its use supported with earlier versions of Python.
### Installation
The library is available from the PyPI repository, so may be added easily to a project's
dependencies via its `requirements.txt` file or similar by referencing the library's
name, `tiffdata`, or the library may be installed directly onto your local development
system using `pip install` by entering the following command:
$ pip install tiffdata
### Introduction
The TIFFData library provides access to the embedded metadata within TIFF files as well
as the ability to modify certain metadata values within the file. The library does not
provide support for modifying image canvas data held within the file, and some metadata
fields are considered read-only as they are essential to describing the content of the
image data held in the file, and any modifications to those fields could affect the
ability of software, including the TIFFData library, to successfully load the image.
The TIFFData library supports Standard/Classic TIFF files, as well as Big TIFF files,
encoded using both big and little endian byte orders.
### TIFF File Format
The TIFF (Tagged Image File Format) is a flexible, adaptable image file format that is
widely used for storing high-quality raster (bitmapped) graphics. The file format was
originally developed by Aldus Corporation in the mid-1980s for desktop publishing and
scanning applications. Aldus was acquired by Adobe in 1994, and Adobe has continued to
lead development of the TIFF file format in the years since. The current version of the
TIFF specification, version 6.0, was released in 1992, and was supplemented in 2002, so
the format is considered stable and offers many features that help support long term use
and flexibility for a range of use cases, such as support for custom metadata tags and
the ability to add support for additional image compression algorithms as needs arise.
#### Key Features:
* Lossless Compression: The TIFF format supports lossless compression options, including
the LZW, ZIP, Deflate, and PackBits algorithms, as well as raw uncompressed data, which
preserves full image quality without any loss, as well as several lossy compression options
including JPEG compression.
* Multiple Images: The TIFF format can be used to store multiple images within a single
file, which is useful for multiple-page documents, such as scanned documents, as well as
cases where storing multiple resolutions of the same image in a pyramidal arrangement is
used to support dynamic image derivative generation and viewing.
* Metadata: Uses a system of tags (hence the format name) to describe image attributes,
such as width, height, resolution, color depth, and many properties besides, as well as
providing support for embedding metadata payloads of other formats such as IPTC and XMP
into the file, which are also recorded using tags.
* Color Support: The TIFF format can handle various color spaces, including:
* Black & White (1-bit)
* Grayscale
* Indexed color (palette-based)
* RGB
* CMYK
* YCbCr (used in video and photography)
* Bit Depths: Supports a range of bit depths – 1, 4, 8, 16, 24 or 32 bits per channel.
* Extensibility: Allows for custom tags and metadata, making it a highly extensible file
format for specialized applications, such as medical imaging and geospatial data.
#### Common Use Cases:
* Scanning and archiving (due to high image fidelity and lossless storage options).
* Publishing and printing.
* Medical imaging, for example, the DICOM image file format uses the TIFF format internally.
* Geographic Information Systems (GIS), often in the form of GeoTIFF, which is based on the TIFF file format.
#### File Extensions:
* The most common file extensions for TIFF files are `.tif` and `.tiff` – however, to
identify TIFF files with certainty it is best to parse the contents of the files to
ensure the expected TIFF magic number and other required file contents are present.
#### Format Variants:
* Baseline TIFF: A minimal standard that all TIFF readers must support.
* TIFF/EP: Enhanced version used in digital photography as the basis for most camera RAW
image file formats.
* BigTIFF: Supports files larger than 4 GB by using 64-bit offsets.
TIFF is favored where image quality and flexibility are paramount. However, due to often
large file sizes and limited browser support, TIFFs are not ideal for everyday web use.
#### TIFF File Structure
TIFF files can contain one or more images, and are typically structured as illustrated
below, beginning with the TIFF file header which details the byte order used to encode
data structures within the file, followed by the file format specifier and the offset to
the first (known as the _zeroth_ or 0th) Image File Directory (IFD). Each IFD contains a
number of Tags and each tag contains data about or relating to the image within the IFD.
The Tags contain a tag ID, which identifies the type of tag, a data type specifier that
specifies the way that the data held within the tag is encoded, as well as a data count
which notes how many values the tag holds, followed by the data itself. As a Tag holds a
limited amount of data, four bytes for Standard/Classic TIFF files, and eight bytes for
Big TIFF files, the data field of a Tag may hold the actual data (if it will fit) or the
offset to the Tag's data that has been stored elsewhere in the file.
Some of the tags are essential to the IFD, and include information such as the offset of
the image data within the IFD, the compression format used, the pixel dimensions and the
resolution of the image, and much more besides. The values of these tags are considered
read-only as if changes were made to the data values of these tags without corresponding
changes to the associated image canvas data could affect the ability of software to read
the TIFF file after it was resaved.
Most IFDs carry metadata and image data, while others carry only metadata. Within a TIFF
file, at least one of the IFDs should carry image data, while there may be other IFDs
such as an EXIF IFD or GPS IFD that contain additional image related metadata. While the
"Next IFD Offset" field within an IFD is the main way that subsequent IFDs are specified,
certain tags are also used to specify the offsets of other IFDs, effectively supporting
a hierarchical structure of IFDs and tags. The offsets to any EXIF and GPS IFDs within
the file are specified in this way.
```
┌──────────────────────────────────────────────────────────────────────────────────┐
│ TIFF File Header (contains byte order, file format, and first IFD offset) |
└──┬───────────────────────────────────────────────────────────────────────────────┘
┌──▼───────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐
│ Image File Directory │ ┌──▶│ Image File Directory │ ┌──▶│ Image File Directory │
└──┬───────────────────┘ │ └──┬───────────────────┘ │ └──┬───────────────────┘
┌─────┤ ┌────────────────┐ │ │ ┌────────────────┐ │ │ ┌────────────────┐
│ ├──▶ Tag │ │ ├──▶ Tag │ │ ├──▶ Tag │
│ │ └────────────────┘ │ │ └────────────────┘ │┌─────┤ └────────────────┘
│ │ ┌────────────────┐ │ │ ┌────────────────┐ ││ │ ┌────────────────┐
│ ├──▶ Tag │ │ ├──▶ Tag │ ││ ├──▶ Tag │
│ │ └────────────────┘ │┌─────┤ └────────────────┘ ││ │ └────────────────┘
│ │ ┌────────────────┐ ││ │ ┌────────────────┐ ││ │ ┌────────────────┐
│ ├──▶ Tag │ ││ ├──▶ Tag │ ││ ├──▶ Tag │
│ │ └────────────────┘ ││ │ └────────────────┘ ││ │ └────────────────┘
│ ┌──▼───────────────────┐ ││ ┌──▼───────────────────┐ ││ ┌──▼───────────────────┐
│ │ Next IFD Offset │──┘│ │ Next IFD Offset │──┘│ │ Zero Next IFD Offset │
│ └──────────────────────┘ │ └──────────────────────┘ │ └──────────────────────┘
│ ┌──────────────────────┐ │ ┌──────────────────────┐ │ ┌──────────────────────┐
└─▶│ Image Data │ └─▶│ Image Data* │ └─▶│ Image Data* │
└──────────────────────┘ └──────────────────────┘ └──────────────────────┘
```
* As noted, some IFDs within a TIFF file only contain metadata tags, so image data may
not be present for every IFD.
#### Header Structure
The header for a valid Classic TIFF file will consist of the following elements:
| Element | Description |
|:-----------------|:-----------------------------------------------------------------|
| Byte Order Mark | The byte order mark notes the byte order that the TIFF file uses |
| Format Marker | The format marker notes the file format used by the TIFF file |
| First IFD Offset | The first IFD offset contains the offset to the first IFD |
* The byte order mark always occupies the first two bytes of a valid TIFF file and will
contain either `MM` to denote the file is encoded using big-endian (Motorola) encoding
or `II` to denote the file is encoded using little-endian (Intel) encoding. The byte
order mark is always encoded within two single byte ASCII characters.
* The format marker always occupies the next two bytes of a valid TIFF file and will
contain either the value `42` for Classic TIFF files or `43` for Big TIFF files. The
format marker value is encoded using an unsigned 16-bit integer, following the byte
order established by the byte order marker field.
* The first IFD offset notes the absolute offset from the start of the file that the
first IFD may be found. In a Classic TIFF file, the offset is encoded in an unsigned
32-bit integer, following the byte order established by the byte order marker field.
The header for a valid Big TIFF file will consist of the following elements:
| Element | Description |
|:-----------------|:-----------------------------------------------------------------|
| Byte Order Mark | The byte order mark notes the byte order that the TIFF file uses |
| Format Marker | The format marker notes the file format used by the TIFF file |
| Offset Size | The offset size notes how many bytes the offset field uses |
| Reserved | The reserved field is reserved for future use |
| First IFD Offset | The first IFD offset contains the offset to the first IFD |
* The byte order mark always occupies the first two bytes of a valid TIFF file and will
contain either `MM` to denote the file is encoded using big-endian (Motorola) encoding
or `II` to denote the file is encoded using little-endian (Intel) encoding. The byte
order mark is always encoded within two single byte ASCII characters.
* The format marker always occupies the next two bytes of a valid TIFF file and will
contain either the value `42` for Classic TIFF files or `43` for Big TIFF files. The
format marker value is encoded using an unsigned 16-bit integer, following the byte
order established by the byte order marker field.
* The offset size notes how many bytes the first IFD offset field occupies; its value
is encoded in an unsigned 16-bit integer, and for Big TIFF files, the value is always
`8`, following the byte order established by the byte order marker field, while
offering a path to support even larger TIFF files in the future such as files that
could encode their offsets using 16 bytes (128-bits).
* The reserved field occupies an unsigned 16-bit integer, and for Big TIFF files, the
value is always `0`, following the byte order established by the byte order marker
field, but may be used for other purposes for future variants of TIFF.
* The first IFD offset notes the absolute offset from the start of the file that the
first IFD may be found. In a Big TIFF file, the offset is encoded in an unsigned
64-bit integer, following the byte order established by the byte order marker field.
#### IFD Structure
IFD0 is always the first IFD in a TIFF file and contains the main image data, including
resolution, color space, and other essential image attributes. It can also store EXIF
metadata like camera settings, date, and time, via its associated EXIF IFD.
IFD1 is often used to store information about a thumbnail image, which is a smaller
version of the main image, and is included to support faster previews. All tags from
IFD0 may also be present in IFD1.
IFD2 and onwards, while less common, may exist to store additional image data or
information about related images, such as linked images or other image formats. Within
multi-page TIFFs the additional IFDs will store the additional page images, and within
pyramidal TIFFs the additional IFDs will store additional resolutions of the main image.
All IFDs comprise the following components:
| Element | Description |
|:-----------------|:----------------------------------------------------------------|
| Tag Count | Two bytes holding the count of tags that follow. |
| Tags | One or more byte-encoded IFD Tag values, the length of which can be determined by multiplying the tag count by 12 for Standard/Classic TIFF files, and by 20 for Big TIFF files. |
| Next Offset | Four or eight bytes holding the pointer to the next IFD or zero if no further IFD follows, depending on the file format; four bytes for Standard/Classic TIFFs and eight bytes for Big TIFF files. |
* The tag count is always stored as a short integer (`UInt16`) comprised of 2 bytes or 16 bits.
* The tags are encoded according to the format specified for an IFD Tag as noted below.
* The next IFD offset is stored as a long integer (`UInt32`) comprised of 4 bytes or 32 bits
in Standard/Classic TIFF files, or as a long long integer (`UInt64`) comprised of 8 bytes for Big TIFF files.
#### Tag Structure
An IFD Tag comprises of the following elements, consisting of 12 bytes within Standard/Classic TIFF files and 20 bytes in Big TIFF files:
| Element | Description |
|:-----------------|:-----------------------------------------------------------------|
| Tag ID | Two bytes holding the tag ID |
| Data Type | Two bytes holding the data type indicator (listed below) |
| Data Count | Four or eight bytes holding the count of values that follow |
| Data / Offset | Four or eight bytes holding the data or an offset to the data |
* The tag ID is used to identify the purpose of the tag, and its value is always
encoded as an unsigned 16-bit integer (`UInt16`) regardless of the TIFF file format.
* The data type field of each tag will have one of the following values, encoded using
an unsigned 16-bit integer (`UInt16`), regardless of the TIFF file format.
* The data count field of each tag is used to note how many values of the given type are
held by the tag, and its value is encoded using an unsigned 32-bit integer (`UInt32`)
for Classic TIFF files and an unsigned 64-bit integer (`UInt64`) for Big TIFF files.
* The data / offset field of each tag is used to hold the data of the tag, if the data
can fit within the available number of bytes (four bytes for Classic TIFF and eight for
Big TIFF files) or if the data exceeds this length, then the offset to the data will be
held in the tag instead, and the data will be stored outside of an IFD or Tag elsewhere
in the file.
#### Tag Data Types
The data type field of each tag will have one of the following values, encoded using an
unsigned 16-bit integer, regardless of the TIFF file format:
| Data Type ID | Type | Description |
|:-------------|:-----------|:--------------------------------------------------------|
| 0 | Empty | An empty padded tag data value |
| 1 | Byte | A 8-bit unsigned byte integer |
| 2 | ASCII | A 8-bit holding 7-bit ASCII code, nul-terminated |
| 3 | Short | A 16-bit unsigned short integer |
| 4 | Long | A 32-bit unsigned long integer |
| 5 | Rational | Two unsigned longs; holding numerator and denominator |
| 6 | SByte | An 8-bit signed byte integer |
| 7 | Undefined | A 8-bit byte holding any value per field specs |
| 8 | SShort | A 16-bit signed short integer |
| 9 | SLong | A 32-bit signed integer (2's compliment) |
| 10 | SRational | A signed rational of two signed-longs |
| 11 | Float | A signed 32-bit float (IEEE-754 single-precision) |
| 12 | Double | A signed 64-bit float (IEEE-754 double-precision) |
| 13 | ClassicIFD | A 32-bit unsigned integer for sub IFD offset |
| 16 | LongLong | A 64-bit unsigned long long integer |
| 17 | SLongLong | A 64-bit signed long long integer |
| 18 | BigIFD | A 64-bit unsigned integer for sub IFD offset |
| 129 | UTF-8 | An 8-bit byte UTF-8 string, nul-terminated |
### Classes, Methods & Properties
The TIFFData library's main class is the `TIFF` class through which TIFF image files can
be loaded, modified via the supported actions, and saved. The library supports reading
both Classic TIFF and Big TIFF formatted files, in both big and little endianness.
The `TIFF` class offers the following methods:
* `TIFF(filepath: str)` - The `TIFF()` class constructor expects an absolute filepath at
a minimum for the TIFF file you wish to open. Upon initializing the class with the file,
the library will then attempt to load and parse the file. Assuming that the file is a
valid TIFF file, the library will parse the file, identify any IFDs contained within the
file, and any tags associated with each of the IFDs, including any embedded metadata and
any image data, stored either as image strips or image tiles.
* `get(key: int | str, default: object = None)` (`object`) – The `get()` method can be
used to obtain the TIFF tag identified by the provided `key`, which can be provided as a
tag ID, tag name or `TIFFTag` enumeration option. A `default` value can also be provided
to use as a fallback. If the TIFF does not contain the specified tag, the default will
be returned instead. If tag does not exist and no `default` has been set, `None` will be
returned.
* `set(key: int | str, value: object)` – The `set()` method can be used to set the value
of supported and writable TIFF tags. The tag is identified by the provided `key`, which
can be provided as a tag ID, tag name or `TIFFTag` enumeration option, and the provided
value must use a data type supported by the tag being set. The `set()` method returns a
reference to the `TIFF` class instance's `self` property, so that calls to `set()` can
be chained with calls to other `TIFF` class methods.
* `remove(key: int | str)` (`bool`) – The `remove()` method can be used to remove certain tags
from the TIFF that support removal; certain tags are intrinsic to the TIFF, so cannot be
removed, as if they were absent, many applications would be unable to read the TIFF file.
The tag is identified by the provided `key` argument, which can be provided as a tag ID,
tag name or tag enumeration option. The `remove()` method returns `True` if the tag was
removed, and returns `False` if the tag does not exist or could not be removed.
* `save(filepath: str = None, order: ByteOrder = None, format: Format = None)` – the
`save()` method supports saving the TIFF file back to storage after making any desired
changes to the TIFF. The `filepath` argument can be used to specify a destination path
to save the file to; if no `filepath` has been specified and if the optional `overwrite`
boolean argument has been set to `True`, the library will attempt to save the TIFF file
at the file path that it was loaded from, overwriting the original file.
The `save()` method also accepts an optional `order` argument that can be used to change
the byte order of the saved file. Note that this option should be used with caution if
the TIFF file contains embedded data stored in unrecognised tags or custom data payloads
which the library may not be able to understand, as changing the byte order may affect
the ability to read data from those tags from the saved file for software that supports
parsing the custom data from such tags.
The `save()` method also accepts an optional `format` argument that can be used to change
the file format of the saved file, for example through loading a Classic TIFF formatted
file and saving it to a Big TIFF formatted file.
The `save()` method also accepts an optional `status` argument that can be used to enable
save status progress reporting while the save is being performed. The status will be
printed to the command line while the save is running, allowing progress to be monitored
and for the save duration to be captured. The length of time needed to save a TIFF file
depends on the complexity of the source TIFF file and its size, as well as what changes
if any were made to the TIFF via the library after it was loaded.
Save status progress reporting, if enabled, will look similar to the following:
```
> Saving TIFF file to /path/to/file.tiff
> Saving element 1515/1515 • 100.00% • 352100585/352100585 bytes • 5.880 seconds
> Saving complete • 5.881 seconds
```
The `TIFF` class offers the following properties:
* `info` (`Information`) – The `info` property can be used to access the `Information`
class instance that is created when the `TIFF` class instance is created and the file is
parsed. The `Information` class instance contains core information about the parsed file
including the `filepath`, `filesize`, (byte) `order`, `format`, and first IFD offset.
This property is used internally by the class to populate the corresponding top level
properties of the same names noted below.
* `filepath` (`str`) – The `filepath` property can be used to get the original file path
that was specified at the time the class was initialised.
* `filesize` (`int`) – The `filesize` property can be used to get the original file size
of the file that was specified at the time the class was initialised.
* `order` (`ByteOrder`) – The `order` property can be used to determine the byte order
of the TIFF file. The property will report either `ByteOrder.MSB` for big endian files
or `ByteOrder.LSB` for little endian files.
* `format` (`Format`) – The `format` property can be used to determine the file format
of the TIFF file. The property will report either `Format.ClassicTIFF` for Classic TIFF
formatted files, or `Format.BigTIFF` for Big TIFF formatted files.
### Example of Use
To create an instance of the `TIFF` class, import the `TIFF` class from the library and
specify the absolute file path to the TIFF file you wish to open as the first argument.
If the specified file can be opened successfully, the library will return an instance of
either the `ClassicTIFF` or the `BigTIFF` subclass, depending on the file format of the
specified TIFF file; these classes are subclasses of the library's `TIFF` base class.
<!--pytest.mark.skip-->
```python
from tiffdata import TIFF
filepath = "/path/to/file.tiff"
# Initialize the library with the absolute file path of the TIFF file to load
tiff = TIFF(filepath=filepath)
# If desired, iterate through the IFDs held within the file, accessing the tags of each
for ifd in tiff:
print(ifd)
for tag in ifd:
print(tag.id, tag.name, tag.values)
# Get the value of a specified TIFF tag
value = tiff.get(key=...)
# Set the value of a specified TIFF tag
tiff.set(key=..., value=...)
# Save the modified TIFF file back to the original file path, overwriting the original;
# alternatively provide a different file path for saving via the the `filepath` argument
tiff.save(overwrite=True)
```
In addition to the `get()` and `set()` methods, the `TIFF` class also provides access to
tag values on the first matching IFD via the attribute access pattern:
<!--pytest.mark.skip-->
```python
from tiffdata import TIFF
filepath = "/path/to/file.tiff"
# Initialize the library with the absolute file path of the TIFF file to load
tiff = TIFF(filepath=filepath)
print(tiff.imageWidth)
print(tiff.imageLength)
```
### Disclaimer
While every effort has been made to ensure that the library works reliably with TIFF
files and embedded metadata, you must ensure that all files are backed up before using
the TIFFData library with any files, especially as the library is in early development.
Furthermore, the library may not be able to read nor preserve all metadata or other data
within a TIFF file, especially if manufacturer specific, custom tags, or other "private"
data are present. As such, it is possible that loss of data could occur if an image is
loaded and is then overwritten by saving the file back to the same file path.
Use of the library is entirely at your own risk and the authors bear no responsibility
for losses of any kind. By using the software you assume all such risk and liability.
THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
OR OTHER DEALINGS IN THE SOFTWARE.
### Credits & References
The TIFF file format, and the related EXIF, IPTC and XMP metadata model specifications
were researched across various sources. Please visit these valuable online resources to
learn more about the TIFF file format and related metadata model specifications and to
support these world class organisations and their products:
* TIFF File Format
* https://www.loc.gov/preservation/digital/formats/fdd/fdd000022.shtml (TIFF)
* https://www.loc.gov/preservation/digital/formats/fdd/fdd000328.shtml (Big TIFF)
* https://libtiff.gitlab.io/libtiff/specification/bigtiff.html (Big TIFF)
* https://en.wikipedia.org/wiki/TIFF (TIFF)
* https://www.fileformat.info/format/tiff/egff.htm (TIFF and Big TIFF)
* https://www.itu.int/itudoc/itu-t/com16/tiff-fx/docs/tiff6.pdf (TIFF Specification)
* https://github.com/DigitalSlideArchive/tifftools (TIFF Tags)
* EXIF Metadata Model & Fields
* https://www.cipa.jp/e/index.html
* https://www.loc.gov/preservation/digital/formats/fdd/fdd000146.shtml
* https://exiftool.org/TagNames/EXIF.html
* https://www.media.mit.edu/pia/Research/deepview/exif.html
* https://exiv2.org/tags.html
* IPTC Metadata Model & Fields
* https://www.iptc.org/std/photometadata/specification/IPTC-PhotoMetadata
* https://exiftool.org/TagNames/IPTC.html
* XMP Metadata Model & Fields
* https://www.adobe.com/products/xmp.html
* https://exiftool.org/TagNames/XMP.html
### Copyright & License Information
Copyright © 2025 Daniel Sissman; licensed under the MIT License.
Raw data
{
"_id": null,
"home_page": null,
"name": "tiffdata",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "image, metadata, tiff, data",
"author": "Daniel Sissman",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ae/4d/a5e2c93c2b8bbeeadc02a72d4f6281683f94c81ea2961c0ac157fad1acfb/tiffdata-0.5.1.tar.gz",
"platform": "any",
"description": "# TIFFData\n\nThe TIFFData library for Python provides a streamlined way to work with TIFF image files\noffering the ability to extract and modify metadata and tags without modifying any the\nof image data held within the file itself.\n\nThe library can be used to support a range of use cases, including situations where it\nis important to be able to read, modify and write TIFF image metadata without affecting\nthe visual quality and fidelity of any image canvases held within the file. This is\nespecially important in cases where a TIFF file holds one or more image canvases encoded\nusing a lossy compression algorithm such as JPEG encoding. Loading, modifying and\nresaving such files using libraries which also load and decompress image canvas data\nbefore recompressing and resaving the file will result in a reduction in image quality\nand fidelity during each load-and-save cycle.\n\nThe TIFFData library does not provide any image canvas transformation capabilities, such\nas resizing or rotation. For cases where one needs to perform such image transformation\noperations, other libraries such as PyVIPS and Pillow are recommended. However, for use\ncases related specifically to TIFF metadata and TIFF tag manipulation, the TIFFData\nlibrary offers many unique features. One can also develop workflows which leverage\nfunctionality from libraries such as PyVIPS and Pillow, in combination with the metadata\ninspection and modification capabilities offered by the TIFFData library.\n\n### Requirements\n\nThe TIFFData library has been tested to work with Python 3.10, 3.11, 3.12 and 3.13, but\nhas not been tested, nor is its use supported with earlier versions of Python.\n\n### Installation\n\nThe library is available from the PyPI repository, so may be added easily to a project's\ndependencies via its `requirements.txt` file or similar by referencing the library's\nname, `tiffdata`, or the library may be installed directly onto your local development\nsystem using `pip install` by entering the following command:\n\n\t$ pip install tiffdata\n\n### Introduction\n\nThe TIFFData library provides access to the embedded metadata within TIFF files as well\nas the ability to modify certain metadata values within the file. The library does not\nprovide support for modifying image canvas data held within the file, and some metadata\nfields are considered read-only as they are essential to describing the content of the\nimage data held in the file, and any modifications to those fields could affect the\nability of software, including the TIFFData library, to successfully load the image.\n\nThe TIFFData library supports Standard/Classic TIFF files, as well as Big TIFF files,\nencoded using both big and little endian byte orders.\n\n### TIFF File Format\n\nThe TIFF (Tagged Image File Format) is a flexible, adaptable image file format that is\nwidely used for storing high-quality raster (bitmapped) graphics. The file format was\noriginally developed by Aldus Corporation in the mid-1980s for desktop publishing and\nscanning applications. Aldus was acquired by Adobe in 1994, and Adobe has continued to\nlead development of the TIFF file format in the years since. The current version of the\nTIFF specification, version 6.0, was released in 1992, and was supplemented in 2002, so\nthe format is considered stable and offers many features that help support long term use\nand flexibility for a range of use cases, such as support for custom metadata tags and\nthe ability to add support for additional image compression algorithms as needs arise.\n\n#### Key Features:\n\n* Lossless Compression: The TIFF format supports lossless compression options, including\nthe LZW, ZIP, Deflate, and PackBits algorithms, as well as raw uncompressed data, which\npreserves full image quality without any loss, as well as several lossy compression options\nincluding JPEG compression.\n\n* Multiple Images: The TIFF format can be used to store multiple images within a single\nfile, which is useful for multiple-page documents, such as scanned documents, as well as\ncases where storing multiple resolutions of the same image in a pyramidal arrangement is\nused to support dynamic image derivative generation and viewing.\n\n* Metadata: Uses a system of tags (hence the format name) to describe image attributes,\nsuch as width, height, resolution, color depth, and many properties besides, as well as\nproviding support for embedding metadata payloads of other formats such as IPTC and XMP\ninto the file, which are also recorded using tags.\n\n* Color Support: The TIFF format can handle various color spaces, including:\n\n * Black & White (1-bit)\n * Grayscale\n * Indexed color (palette-based)\n * RGB\n * CMYK\n * YCbCr (used in video and photography)\n\n* Bit Depths: Supports a range of bit depths \u2013 1, 4, 8, 16, 24 or 32 bits per channel.\n\n* Extensibility: Allows for custom tags and metadata, making it a highly extensible file\nformat for specialized applications, such as medical imaging and geospatial data.\n\n#### Common Use Cases:\n\n* Scanning and archiving (due to high image fidelity and lossless storage options).\n\n* Publishing and printing.\n\n* Medical imaging, for example, the DICOM image file format uses the TIFF format internally.\n\n* Geographic Information Systems (GIS), often in the form of GeoTIFF, which is based on the TIFF file format.\n\n#### File Extensions:\n\n * The most common file extensions for TIFF files are `.tif` and `.tiff` \u2013 however, to\n identify TIFF files with certainty it is best to parse the contents of the files to\n ensure the expected TIFF magic number and other required file contents are present.\n\n#### Format Variants:\n\n* Baseline TIFF: A minimal standard that all TIFF readers must support.\n\n* TIFF/EP: Enhanced version used in digital photography as the basis for most camera RAW\n image file formats.\n\n* BigTIFF: Supports files larger than 4 GB by using 64-bit offsets.\n\nTIFF is favored where image quality and flexibility are paramount. However, due to often\nlarge file sizes and limited browser support, TIFFs are not ideal for everyday web use.\n\n#### TIFF File Structure\n\nTIFF files can contain one or more images, and are typically structured as illustrated\nbelow, beginning with the TIFF file header which details the byte order used to encode\ndata structures within the file, followed by the file format specifier and the offset to\nthe first (known as the _zeroth_ or 0th) Image File Directory (IFD). Each IFD contains a\nnumber of Tags and each tag contains data about or relating to the image within the IFD.\n\nThe Tags contain a tag ID, which identifies the type of tag, a data type specifier that\nspecifies the way that the data held within the tag is encoded, as well as a data count\nwhich notes how many values the tag holds, followed by the data itself. As a Tag holds a\nlimited amount of data, four bytes for Standard/Classic TIFF files, and eight bytes for\nBig TIFF files, the data field of a Tag may hold the actual data (if it will fit) or the\noffset to the Tag's data that has been stored elsewhere in the file.\n\nSome of the tags are essential to the IFD, and include information such as the offset of\nthe image data within the IFD, the compression format used, the pixel dimensions and the\nresolution of the image, and much more besides. The values of these tags are considered\nread-only as if changes were made to the data values of these tags without corresponding\nchanges to the associated image canvas data could affect the ability of software to read\nthe TIFF file after it was resaved.\n\nMost IFDs carry metadata and image data, while others carry only metadata. Within a TIFF\nfile, at least one of the IFDs should carry image data, while there may be other IFDs\nsuch as an EXIF IFD or GPS IFD that contain additional image related metadata. While the\n\"Next IFD Offset\" field within an IFD is the main way that subsequent IFDs are specified,\ncertain tags are also used to specify the offsets of other IFDs, effectively supporting\na hierarchical structure of IFDs and tags. The offsets to any EXIF and GPS IFDs within\nthe file are specified in this way.\n\n```\n \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502 TIFF File Header (contains byte order, file format, and first IFD offset) |\n \u2514\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u250c\u2500\u2500\u25bc\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502 Image File Directory \u2502 \u250c\u2500\u2500\u25b6\u2502 Image File Directory \u2502 \u250c\u2500\u2500\u25b6\u2502 Image File Directory \u2502\n \u2514\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502 \u2514\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502 \u2514\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\u250c\u2500\u2500\u2500\u2500\u2500\u2524 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502 \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502 \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 \u251c\u2500\u2500\u25b6 Tag \u2502 \u2502 \u251c\u2500\u2500\u25b6 Tag \u2502 \u2502 \u251c\u2500\u2500\u25b6 Tag \u2502\n\u2502 \u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502 \u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\u250c\u2500\u2500\u2500\u2500\u2500\u2524 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\u2502 \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502 \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\u2502 \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 \u251c\u2500\u2500\u25b6 Tag \u2502 \u2502 \u251c\u2500\u2500\u25b6 Tag \u2502 \u2502\u2502 \u251c\u2500\u2500\u25b6 Tag \u2502\n\u2502 \u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\u250c\u2500\u2500\u2500\u2500\u2500\u2524 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\u2502 \u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\u2502 \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\u2502 \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\u2502 \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 \u251c\u2500\u2500\u25b6 Tag \u2502 \u2502\u2502 \u251c\u2500\u2500\u25b6 Tag \u2502 \u2502\u2502 \u251c\u2500\u2500\u25b6 Tag \u2502\n\u2502 \u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\u2502 \u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\u2502 \u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\u2502 \u250c\u2500\u2500\u25bc\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\u2502 \u250c\u2500\u2500\u25bc\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\u2502 \u250c\u2500\u2500\u25bc\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 \u2502 Next IFD Offset \u2502\u2500\u2500\u2518\u2502 \u2502 Next IFD Offset \u2502\u2500\u2500\u2518\u2502 \u2502 Zero Next IFD Offset \u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2514\u2500\u25b6\u2502 Image Data \u2502 \u2514\u2500\u25b6\u2502 Image Data* \u2502 \u2514\u2500\u25b6\u2502 Image Data* \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n* As noted, some IFDs within a TIFF file only contain metadata tags, so image data may\nnot be present for every IFD.\n\n#### Header Structure\n\nThe header for a valid Classic TIFF file will consist of the following elements:\n\n| Element | Description |\n|:-----------------|:-----------------------------------------------------------------|\n| Byte Order Mark | The byte order mark notes the byte order that the TIFF file uses |\n| Format Marker | The format marker notes the file format used by the TIFF file |\n| First IFD Offset | The first IFD offset contains the offset to the first IFD |\n\n * The byte order mark always occupies the first two bytes of a valid TIFF file and will\n contain either `MM` to denote the file is encoded using big-endian (Motorola) encoding\n or `II` to denote the file is encoded using little-endian (Intel) encoding. The byte\n order mark is always encoded within two single byte ASCII characters.\n\n * The format marker always occupies the next two bytes of a valid TIFF file and will\n contain either the value `42` for Classic TIFF files or `43` for Big TIFF files. The\n format marker value is encoded using an unsigned 16-bit integer, following the byte\n order established by the byte order marker field.\n \n * The first IFD offset notes the absolute offset from the start of the file that the\n first IFD may be found. In a Classic TIFF file, the offset is encoded in an unsigned\n 32-bit integer, following the byte order established by the byte order marker field.\n\nThe header for a valid Big TIFF file will consist of the following elements:\n\n| Element | Description |\n|:-----------------|:-----------------------------------------------------------------|\n| Byte Order Mark | The byte order mark notes the byte order that the TIFF file uses |\n| Format Marker | The format marker notes the file format used by the TIFF file |\n| Offset Size | The offset size notes how many bytes the offset field uses |\n| Reserved | The reserved field is reserved for future use |\n| First IFD Offset | The first IFD offset contains the offset to the first IFD |\n\n * The byte order mark always occupies the first two bytes of a valid TIFF file and will\n contain either `MM` to denote the file is encoded using big-endian (Motorola) encoding\n or `II` to denote the file is encoded using little-endian (Intel) encoding. The byte\n order mark is always encoded within two single byte ASCII characters.\n\n * The format marker always occupies the next two bytes of a valid TIFF file and will\n contain either the value `42` for Classic TIFF files or `43` for Big TIFF files. The\n format marker value is encoded using an unsigned 16-bit integer, following the byte\n order established by the byte order marker field.\n\n * The offset size notes how many bytes the first IFD offset field occupies; its value\n is encoded in an unsigned 16-bit integer, and for Big TIFF files, the value is always\n `8`, following the byte order established by the byte order marker field, while\n offering a path to support even larger TIFF files in the future such as files that\n could encode their offsets using 16 bytes (128-bits).\n\n * The reserved field occupies an unsigned 16-bit integer, and for Big TIFF files, the\n value is always `0`, following the byte order established by the byte order marker\n field, but may be used for other purposes for future variants of TIFF.\n\n * The first IFD offset notes the absolute offset from the start of the file that the\n first IFD may be found. In a Big TIFF file, the offset is encoded in an unsigned\n 64-bit integer, following the byte order established by the byte order marker field.\n\n#### IFD Structure\n\nIFD0 is always the first IFD in a TIFF file and contains the main image data, including\nresolution, color space, and other essential image attributes. It can also store EXIF\nmetadata like camera settings, date, and time, via its associated EXIF IFD.\n\nIFD1 is often used to store information about a thumbnail image, which is a smaller\nversion of the main image, and is included to support faster previews. All tags from\nIFD0 may also be present in IFD1.\n\nIFD2 and onwards, while less common, may exist to store additional image data or\ninformation about related images, such as linked images or other image formats. Within\nmulti-page TIFFs the additional IFDs will store the additional page images, and within\npyramidal TIFFs the additional IFDs will store additional resolutions of the main image.\n\nAll IFDs comprise the following components:\n\n| Element | Description |\n|:-----------------|:----------------------------------------------------------------|\n| Tag Count | Two bytes holding the count of tags that follow. |\n| Tags | One or more byte-encoded IFD Tag values, the length of which can be determined by multiplying the tag count by 12 for Standard/Classic TIFF files, and by 20 for Big TIFF files. |\n| Next Offset | Four or eight bytes holding the pointer to the next IFD or zero if no further IFD follows, depending on the file format; four bytes for Standard/Classic TIFFs and eight bytes for Big TIFF files. |\n\n * The tag count is always stored as a short integer (`UInt16`) comprised of 2 bytes or 16 bits.\n\n * The tags are encoded according to the format specified for an IFD Tag as noted below.\n\n * The next IFD offset is stored as a long integer (`UInt32`) comprised of 4 bytes or 32 bits\n in Standard/Classic TIFF files, or as a long long integer (`UInt64`) comprised of 8 bytes for Big TIFF files.\n\n#### Tag Structure\n\nAn IFD Tag comprises of the following elements, consisting of 12 bytes within Standard/Classic TIFF files and 20 bytes in Big TIFF files:\n\n| Element | Description |\n|:-----------------|:-----------------------------------------------------------------|\n| Tag ID | Two bytes holding the tag ID |\n| Data Type | Two bytes holding the data type indicator (listed below) |\n| Data Count | Four or eight bytes holding the count of values that follow |\n| Data / Offset | Four or eight bytes holding the data or an offset to the data |\n\n * The tag ID is used to identify the purpose of the tag, and its value is always\n encoded as an unsigned 16-bit integer (`UInt16`) regardless of the TIFF file format.\n\n * The data type field of each tag will have one of the following values, encoded using\n an unsigned 16-bit integer (`UInt16`), regardless of the TIFF file format.\n\n * The data count field of each tag is used to note how many values of the given type are\n held by the tag, and its value is encoded using an unsigned 32-bit integer (`UInt32`)\n for Classic TIFF files and an unsigned 64-bit integer (`UInt64`) for Big TIFF files.\n \n * The data / offset field of each tag is used to hold the data of the tag, if the data\n can fit within the available number of bytes (four bytes for Classic TIFF and eight for\n Big TIFF files) or if the data exceeds this length, then the offset to the data will be\n held in the tag instead, and the data will be stored outside of an IFD or Tag elsewhere\n in the file.\n\n#### Tag Data Types\n\nThe data type field of each tag will have one of the following values, encoded using an\nunsigned 16-bit integer, regardless of the TIFF file format:\n\n| Data Type ID | Type | Description |\n|:-------------|:-----------|:--------------------------------------------------------|\n| 0 | Empty | An empty padded tag data value |\n| 1 | Byte | A 8-bit unsigned byte integer |\n| 2 | ASCII | A 8-bit holding 7-bit ASCII code, nul-terminated |\n| 3 | Short | A 16-bit unsigned short integer |\n| 4 | Long | A 32-bit unsigned long integer |\n| 5 | Rational | Two unsigned longs; holding numerator and denominator |\n| 6 | SByte | An 8-bit signed byte integer |\n| 7 | Undefined | A 8-bit byte holding any value per field specs |\n| 8 | SShort | A 16-bit signed short integer |\n| 9 | SLong | A 32-bit signed integer (2's compliment) |\n| 10 | SRational | A signed rational of two signed-longs |\n| 11 | Float | A signed 32-bit float (IEEE-754 single-precision) |\n| 12 | Double | A signed 64-bit float (IEEE-754 double-precision) |\n| 13 | ClassicIFD | A 32-bit unsigned integer for sub IFD offset |\n| 16 | LongLong | A 64-bit unsigned long long integer |\n| 17 | SLongLong | A 64-bit signed long long integer |\n| 18 | BigIFD | A 64-bit unsigned integer for sub IFD offset |\n| 129 | UTF-8 | An 8-bit byte UTF-8 string, nul-terminated |\n\n### Classes, Methods & Properties\n\nThe TIFFData library's main class is the `TIFF` class through which TIFF image files can\nbe loaded, modified via the supported actions, and saved. The library supports reading\nboth Classic TIFF and Big TIFF formatted files, in both big and little endianness.\n\nThe `TIFF` class offers the following methods:\n\n* `TIFF(filepath: str)` - The `TIFF()` class constructor expects an absolute filepath at\na minimum for the TIFF file you wish to open. Upon initializing the class with the file,\nthe library will then attempt to load and parse the file. Assuming that the file is a \nvalid TIFF file, the library will parse the file, identify any IFDs contained within the\nfile, and any tags associated with each of the IFDs, including any embedded metadata and\nany image data, stored either as image strips or image tiles.\n\n* `get(key: int | str, default: object = None)` (`object`) \u2013 The `get()` method can be\nused to obtain the TIFF tag identified by the provided `key`, which can be provided as a\ntag ID, tag name or `TIFFTag` enumeration option. A `default` value can also be provided\nto use as a fallback. If the TIFF does not contain the specified tag, the default will\nbe returned instead. If tag does not exist and no `default` has been set, `None` will be\nreturned.\n\n* `set(key: int | str, value: object)` \u2013 The `set()` method can be used to set the value\nof supported and writable TIFF tags. The tag is identified by the provided `key`, which\ncan be provided as a tag ID, tag name or `TIFFTag` enumeration option, and the provided\nvalue must use a data type supported by the tag being set. The `set()` method returns a\nreference to the `TIFF` class instance's `self` property, so that calls to `set()` can\nbe chained with calls to other `TIFF` class methods.\n\n* `remove(key: int | str)` (`bool`) \u2013 The `remove()` method can be used to remove certain tags\nfrom the TIFF that support removal; certain tags are intrinsic to the TIFF, so cannot be\nremoved, as if they were absent, many applications would be unable to read the TIFF file.\nThe tag is identified by the provided `key` argument, which can be provided as a tag ID,\ntag name or tag enumeration option. The `remove()` method returns `True` if the tag was\nremoved, and returns `False` if the tag does not exist or could not be removed.\n\n* `save(filepath: str = None, order: ByteOrder = None, format: Format = None)` \u2013 the\n`save()` method supports saving the TIFF file back to storage after making any desired\nchanges to the TIFF. The `filepath` argument can be used to specify a destination path\nto save the file to; if no `filepath` has been specified and if the optional `overwrite`\nboolean argument has been set to `True`, the library will attempt to save the TIFF file\nat the file path that it was loaded from, overwriting the original file.\n\n The `save()` method also accepts an optional `order` argument that can be used to change\nthe byte order of the saved file. Note that this option should be used with caution if\nthe TIFF file contains embedded data stored in unrecognised tags or custom data payloads\nwhich the library may not be able to understand, as changing the byte order may affect\nthe ability to read data from those tags from the saved file for software that supports\nparsing the custom data from such tags.\n\n The `save()` method also accepts an optional `format` argument that can be used to change\nthe file format of the saved file, for example through loading a Classic TIFF formatted\nfile and saving it to a Big TIFF formatted file.\n\n The `save()` method also accepts an optional `status` argument that can be used to enable\n save status progress reporting while the save is being performed. The status will be\n printed to the command line while the save is running, allowing progress to be monitored\n and for the save duration to be captured. The length of time needed to save a TIFF file\n depends on the complexity of the source TIFF file and its size, as well as what changes\n if any were made to the TIFF via the library after it was loaded.\n\n Save status progress reporting, if enabled, will look similar to the following:\n \n ```\n > Saving TIFF file to /path/to/file.tiff\n > Saving element 1515/1515 \u2022 100.00% \u2022 352100585/352100585 bytes \u2022 5.880 seconds\n > Saving complete \u2022 5.881 seconds\n ```\n\nThe `TIFF` class offers the following properties:\n\n * `info` (`Information`) \u2013 The `info` property can be used to access the `Information`\n class instance that is created when the `TIFF` class instance is created and the file is\n parsed. The `Information` class instance contains core information about the parsed file\n including the `filepath`, `filesize`, (byte) `order`, `format`, and first IFD offset.\n \n This property is used internally by the class to populate the corresponding top level\n properties of the same names noted below.\n\n * `filepath` (`str`) \u2013 The `filepath` property can be used to get the original file path\n that was specified at the time the class was initialised.\n\n * `filesize` (`int`) \u2013 The `filesize` property can be used to get the original file size\n of the file that was specified at the time the class was initialised.\n\n * `order` (`ByteOrder`) \u2013 The `order` property can be used to determine the byte order\n of the TIFF file. The property will report either `ByteOrder.MSB` for big endian files\n or `ByteOrder.LSB` for little endian files.\n\n * `format` (`Format`) \u2013 The `format` property can be used to determine the file format\n of the TIFF file. The property will report either `Format.ClassicTIFF` for Classic TIFF\n formatted files, or `Format.BigTIFF` for Big TIFF formatted files.\n\n### Example of Use\n\nTo create an instance of the `TIFF` class, import the `TIFF` class from the library and\nspecify the absolute file path to the TIFF file you wish to open as the first argument.\nIf the specified file can be opened successfully, the library will return an instance of\neither the `ClassicTIFF` or the `BigTIFF` subclass, depending on the file format of the\nspecified TIFF file; these classes are subclasses of the library's `TIFF` base class.\n\n<!--pytest.mark.skip-->\n\n```python\nfrom tiffdata import TIFF\n\nfilepath = \"/path/to/file.tiff\"\n\n# Initialize the library with the absolute file path of the TIFF file to load\ntiff = TIFF(filepath=filepath)\n\n# If desired, iterate through the IFDs held within the file, accessing the tags of each\nfor ifd in tiff:\n print(ifd)\n for tag in ifd:\n print(tag.id, tag.name, tag.values)\n\n# Get the value of a specified TIFF tag\nvalue = tiff.get(key=...)\n\n# Set the value of a specified TIFF tag\ntiff.set(key=..., value=...)\n\n# Save the modified TIFF file back to the original file path, overwriting the original;\n# alternatively provide a different file path for saving via the the `filepath` argument\ntiff.save(overwrite=True)\n```\n\nIn addition to the `get()` and `set()` methods, the `TIFF` class also provides access to\ntag values on the first matching IFD via the attribute access pattern:\n\n<!--pytest.mark.skip-->\n\n```python\nfrom tiffdata import TIFF\n\nfilepath = \"/path/to/file.tiff\"\n\n# Initialize the library with the absolute file path of the TIFF file to load\ntiff = TIFF(filepath=filepath)\n\nprint(tiff.imageWidth)\nprint(tiff.imageLength)\n```\n\n### Disclaimer\n\nWhile every effort has been made to ensure that the library works reliably with TIFF\nfiles and embedded metadata, you must ensure that all files are backed up before using\nthe TIFFData library with any files, especially as the library is in early development.\n\nFurthermore, the library may not be able to read nor preserve all metadata or other data\nwithin a TIFF file, especially if manufacturer specific, custom tags, or other \"private\"\ndata are present. As such, it is possible that loss of data could occur if an image is\nloaded and is then overwritten by saving the file back to the same file path.\n\nUse of the library is entirely at your own risk and the authors bear no responsibility\nfor losses of any kind. By using the software you assume all such risk and liability.\n\nTHIS SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,\nINCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR\nPURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE\nLIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE\nOR OTHER DEALINGS IN THE SOFTWARE.\n\n### Credits & References\n\nThe TIFF file format, and the related EXIF, IPTC and XMP metadata model specifications\nwere researched across various sources. Please visit these valuable online resources to\nlearn more about the TIFF file format and related metadata model specifications and to\nsupport these world class organisations and their products:\n\n * TIFF File Format\n * https://www.loc.gov/preservation/digital/formats/fdd/fdd000022.shtml (TIFF)\n * https://www.loc.gov/preservation/digital/formats/fdd/fdd000328.shtml (Big TIFF)\n * https://libtiff.gitlab.io/libtiff/specification/bigtiff.html (Big TIFF)\n * https://en.wikipedia.org/wiki/TIFF (TIFF)\n * https://www.fileformat.info/format/tiff/egff.htm (TIFF and Big TIFF)\n * https://www.itu.int/itudoc/itu-t/com16/tiff-fx/docs/tiff6.pdf (TIFF Specification)\n * https://github.com/DigitalSlideArchive/tifftools (TIFF Tags)\n\n * EXIF Metadata Model & Fields\n * https://www.cipa.jp/e/index.html\n * https://www.loc.gov/preservation/digital/formats/fdd/fdd000146.shtml\n * https://exiftool.org/TagNames/EXIF.html\n * https://www.media.mit.edu/pia/Research/deepview/exif.html\n * https://exiv2.org/tags.html\n\n * IPTC Metadata Model & Fields\n * https://www.iptc.org/std/photometadata/specification/IPTC-PhotoMetadata\n * https://exiftool.org/TagNames/IPTC.html\n\n * XMP Metadata Model & Fields\n * https://www.adobe.com/products/xmp.html\n * https://exiftool.org/TagNames/XMP.html\n\n### Copyright & License Information\n\nCopyright \u00a9 2025 Daniel Sissman; licensed under the MIT License.\n",
"bugtrack_url": null,
"license": null,
"summary": "Streamlined TIFF image metadata parsing and updating.",
"version": "0.5.1",
"project_urls": {
"changelog": "https://github.com/bluebinary/tiffdata/blob/main/CHANGELOG.md",
"documentation": "https://github.com/bluebinary/tiffdata/blob/main/README.md",
"homepage": "https://github.com/bluebinary/tiffdata",
"issues": "https://github.com/bluebinary/tiffdata/issues",
"repository": "https://github.com/bluebinary/tiffdata"
},
"split_keywords": [
"image",
" metadata",
" tiff",
" data"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ca4306bbe54e6f27e7ab11cc16a25301834e63d6ca0de7cfeeb54e17c18e3ac6",
"md5": "47afe024ee00684dc2349fceba9c7cac",
"sha256": "51af159812385425aeada5bd2c575618efa71b0876f8f2aa837bfe0151b932b6"
},
"downloads": -1,
"filename": "tiffdata-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "47afe024ee00684dc2349fceba9c7cac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 69441,
"upload_time": "2025-08-07T06:51:11",
"upload_time_iso_8601": "2025-08-07T06:51:11.614281Z",
"url": "https://files.pythonhosted.org/packages/ca/43/06bbe54e6f27e7ab11cc16a25301834e63d6ca0de7cfeeb54e17c18e3ac6/tiffdata-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ae4da5e2c93c2b8bbeeadc02a72d4f6281683f94c81ea2961c0ac157fad1acfb",
"md5": "3974bc95e5b1b51ee0a63a3fed711f90",
"sha256": "fe123f2540ccbc2f38ccbf2961abf2dcf5b2a297f44b18bae03e4a9c344ea45c"
},
"downloads": -1,
"filename": "tiffdata-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "3974bc95e5b1b51ee0a63a3fed711f90",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 74320,
"upload_time": "2025-08-07T06:51:13",
"upload_time_iso_8601": "2025-08-07T06:51:13.261582Z",
"url": "https://files.pythonhosted.org/packages/ae/4d/a5e2c93c2b8bbeeadc02a72d4f6281683f94c81ea2961c0ac157fad1acfb/tiffdata-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 06:51:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bluebinary",
"github_project": "tiffdata",
"github_not_found": true,
"lcname": "tiffdata"
}
