Documentation for IFD Changes

This commit is contained in:
wiredfool 2015-09-14 07:01:57 -07:00
parent 9286c9e460
commit 1614f2fdb5
5 changed files with 124 additions and 41 deletions

View File

@ -231,24 +231,36 @@ class ImageFileDirectory_v2(collections.MutableMapping):
"""This class represents a TIFF tag directory. To speed things up, we """This class represents a TIFF tag directory. To speed things up, we
don't decode tags unless they're asked for. don't decode tags unless they're asked for.
Exposes a dictionary interface of the tags in the directory Exposes a dictionary interface of the tags in the directory::
ImageFileDirectory[key] = value ifd = ImageFileDirectory_v2()
value = ImageFileDirectory[key] ifd[key] = 'Some Data'
ifd.tagtype[key] = 2
print(ifd[key])
'Some Data'
Individual values are returned as the strings or numbers, sequences are
returned as tuples of the values.
Also contains a dictionary of tag types as read from the tiff image file, The tiff metadata type of each item is stored in a dictionary of
'ImageFileDirectory.tagtype' tag types in
`~PIL.TiffImagePlugin.ImageFileDirectory_v2.tagtype`. The types
are read from a tiff file, guessed from the type added, or added
manually.
Data Structures: Data Structures:
'public'
* self.tagtype = {} Key: numerical tiff tag number * self.tagtype = {}
Value: integer corresponding to the data type from
`TiffTags.TYPES` * Key: numerical tiff tag number
* Value: integer corresponding to the data type from `~PIL.TiffTags.TYPES`
.. versionadded:: 3.0.0
""" """
""" """
Documentation: Documentation:
'internal' 'internal' data structures:
* self._tags_v2 = {} Key: numerical tiff tag number * self._tags_v2 = {} Key: numerical tiff tag number
Value: decoded data, as tuple for multiple values Value: decoded data, as tuple for multiple values
* self._tagdata = {} Key: numerical tiff tag number * self._tagdata = {} Key: numerical tiff tag number
@ -259,11 +271,13 @@ class ImageFileDirectory_v2(collections.MutableMapping):
Tags will be found in the private attributes self._tagdata, and in Tags will be found in the private attributes self._tagdata, and in
self._tags_v2 once decoded. self._tags_v2 once decoded.
If legacy_api is true, then decoded tags will be populated into both Self.legacy_api is a value for internal use, and shouldn't be
_tags_v1 and _tags_v2. _Tags_v2 will be used if this IFD is used in changed from outside code. In cooperation with the
the TIFF save routine. ImageFileDirectory_v1 class, if legacy_api is true, then decoded
tags will be populated into both _tags_v1 and _tags_v2. _Tags_v2
Tags will be read from tags_v1 if legacy_api == true. will be used if this IFD is used in the TIFF save routine. Tags
should be read from tags_v1 if legacy_api == true.
""" """
def __init__(self, ifh=b"II\052\0\0\0\0\0", prefix=None): def __init__(self, ifh=b"II\052\0\0\0\0\0", prefix=None):
@ -273,9 +287,9 @@ class ImageFileDirectory_v2(collections.MutableMapping):
magic header to the constructor. To only set the endianness, pass it magic header to the constructor. To only set the endianness, pass it
as the 'prefix' keyword argument. as the 'prefix' keyword argument.
:ifh: One of the accepted magic headers (cf. PREFIXES); also sets :param ifh: One of the accepted magic headers (cf. PREFIXES); also sets
endianness. endianness.
:prefix: Override the endianness of the file. :param prefix: Override the endianness of the file.
""" """
if ifh[:4] not in PREFIXES: if ifh[:4] not in PREFIXES:
raise SyntaxError("not a TIFF file (header %r not valid)" % ifh) raise SyntaxError("not a TIFF file (header %r not valid)" % ifh)
@ -310,12 +324,19 @@ class ImageFileDirectory_v2(collections.MutableMapping):
return str(dict(self)) return str(dict(self))
def as_dict(self): def as_dict(self):
"""Return a dictionary of the image's tags.""" """Return a dictionary of the image's tags.
use `dict(ifd)` instead.
.. deprecated:: 3.0.0
"""
# FIXME Deprecate: use dict(self) # FIXME Deprecate: use dict(self)
return dict(self) return dict(self)
def named(self): def named(self):
""" """
:returns: dict of name|key: value
Returns the complete tag dictionary, with named tags where possible. Returns the complete tag dictionary, with named tags where possible.
""" """
return dict((TAGS_V2.get(code, TagInfo()).name, value) return dict((TAGS_V2.get(code, TagInfo()).name, value)
@ -625,6 +646,23 @@ del _load_dispatch, _write_dispatch, idx, name
#Legacy ImageFileDirectory support. #Legacy ImageFileDirectory support.
class ImageFileDirectory_v1(ImageFileDirectory_v2): class ImageFileDirectory_v1(ImageFileDirectory_v2):
"""This class represents the **legacy** interface to a TIFF tag directory.
Exposes a dictionary interface of the tags in the directory::
ifd = ImageFileDirectory_v1()
ifd[key] = 'Some Data'
ifd.tagtype[key] = 2
print ifd[key]
('Some Data',)
Also contains a dictionary of tag types as read from the tiff image file,
`~PIL.TiffImagePlugin.ImageFileDirectory_v1.tagtype'.
Values are returned as a tuple.
.. deprecated:: 3.0.0
"""
def __init__(self, *args, **kwargs): def __init__(self, *args, **kwargs):
ImageFileDirectory_v2.__init__(self, *args, **kwargs) ImageFileDirectory_v2.__init__(self, *args, **kwargs)
self._legacy_api=True self._legacy_api=True
@ -635,11 +673,15 @@ class ImageFileDirectory_v1(ImageFileDirectory_v2):
@classmethod @classmethod
def from_v2(cls, original): def from_v2(cls, original):
""" returns: ImageFileDirectory_v1 """ Returns an
:py:class:`~PIL.TiffImagePlugin.ImageFileDirectory_v1`
instance with the same data as is contained in the original
:py:class:`~PIL.TiffImagePlugin.ImageFileDirectory_v2`
instance.
Returns an ImageFileDirectory_v1 instance with the same :returns: :py:class:`~PIL.TiffImagePlugin.ImageFileDirectory_v1`
data as is contained in the original ImageFileDirectory_v2
instance """ """
ifd = cls(prefix=original.prefix) ifd = cls(prefix=original.prefix)
ifd._tagdata = original._tagdata ifd._tagdata = original._tagdata
@ -648,10 +690,15 @@ class ImageFileDirectory_v1(ImageFileDirectory_v2):
return ifd return ifd
def to_v2(self): def to_v2(self):
""" returns: ImageFileDirectory_v2 """ Returns an
:py:class:`~PIL.TiffImagePlugin.ImageFileDirectory_v2`
instance with the same data as is contained in the original
:py:class:`~PIL.TiffImagePlugin.ImageFileDirectory_v1`
instance.
Returns an ImageFileDirectory_v2 instance with the same :returns: :py:class:`~PIL.TiffImagePlugin.ImageFileDirectory_v2`
data as is contained in this ImageFileDirectory_v1 instance """
"""
ifd = ImageFileDirectory_v2(prefix=self.prefix) ifd = ImageFileDirectory_v2(prefix=self.prefix)
ifd._tagdata = dict(self._tagdata) ifd._tagdata = dict(self._tagdata)

View File

@ -296,3 +296,20 @@ _populate()
# Map type numbers to type names -- defined in ImageFileDirectory. # Map type numbers to type names -- defined in ImageFileDirectory.
TYPES = {} TYPES = {}
# was:
# TYPES = {
# 1: "byte",
# 2: "ascii",
# 3: "short",
# 4: "long",
# 5: "rational",
# 6: "signed byte",
# 7: "undefined",
# 8: "signed short",
# 9: "signed long",
# 10: "signed rational",
# 11: "float",
# 12: "double",
# }

View File

@ -144,14 +144,6 @@ can be found here.
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
:mod:`TiffTags` Module
----------------------
.. automodule:: PIL.TiffTags
:members:
:undoc-members:
:show-inheritance:
:mod:`WalImageFile` Module :mod:`WalImageFile` Module
-------------------------- --------------------------

View File

@ -438,17 +438,37 @@ The :py:meth:`~PIL.Image.Image.open` method sets the following
**compression** **compression**
Compression mode. Compression mode.
.. versionadded:: 2.0.0
**dpi** **dpi**
Image resolution as an (xdpi, ydpi) tuple, where applicable. You can use Image resolution as an ``(xdpi, ydpi)`` tuple, where applicable. You can use
the :py:attr:`~PIL.Image.Image.tag` attribute to get more detailed the :py:attr:`~PIL.Image.Image.tag` attribute to get more detailed
information about the image resolution. information about the image resolution.
.. versionadded:: 1.1.5 .. versionadded:: 1.1.5
In addition, the :py:attr:`~PIL.Image.Image.tag` attribute contains a **resolution**
dictionary of decoded TIFF fields. Values are stored as either strings or Image resolution as an ``(xres, yres)`` tuple, where applicable. This is a
tuples. Note that only short, long and ASCII tags are correctly unpacked by measurement in whichever unit is specified by the file.
this release.
.. versionadded:: 1.1.5
The :py:attr:`~PIL.Image.Image.tag_v2` attribute contains a dictionary of
TIFF metadata. The keys are numerical indexes from `~PIL.TiffTags.TAGS_V2`.
Values are strings or numbers for single items, multiple values are returned
in a tuple of values. Rational numbers are returned as a single value.
.. versionadded:: 3.0.0
For compatibility with legacy code, the
:py:attr:`~PIL.Image.Image.tag` attribute contains a dictionary of
decoded TIFF fields as returned prior to version 3.0.0. Values are
returned as either strings or tuples of numeric values. Rational
numbers are returned as a tuple of ``(numerator, denominator)``.
.. deprecated:: 3.0.0
Saving Tiff Images Saving Tiff Images
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
@ -456,17 +476,23 @@ Saving Tiff Images
The :py:meth:`~PIL.Image.Image.save` method can take the following keyword arguments: The :py:meth:`~PIL.Image.Image.save` method can take the following keyword arguments:
**tiffinfo** **tiffinfo**
A :py:class:`~PIL.TiffImagePlugin.ImageFileDirectory` object or dict A :py:class:`~PIL.TiffImagePlugin.ImageFileDirectory_v2` object or dict
object containing tiff tags and values. The TIFF field type is object containing tiff tags and values. The TIFF field type is
autodetected for Numeric and string values, any other types autodetected for Numeric and string values, any other types
require using an :py:class:`~PIL.TiffImagePlugin.ImageFileDirectory` require using an :py:class:`~PIL.TiffImagePlugin.ImageFileDirectory_v2`
object and setting the type in object and setting the type in
:py:attr:`~PIL.TiffImagePlugin.ImageFileDirectory.tagtype` with :py:attr:`~PIL.TiffImagePlugin.ImageFileDirectory_v2.tagtype` with
the appropriate numerical value from the appropriate numerical value from
``TiffTags.TYPES``. ``TiffTags.TYPES``.
.. versionadded:: 2.3.0 .. versionadded:: 2.3.0
For compatibility with legacy code, a
`~PIL.TiffImagePlugin.ImageFileDirectory_v1` object may be passed
in this field. This will be deprecated in a future version.
..versionadded:: 3.0.0
**compression** **compression**
A string containing the desired compression method for the A string containing the desired compression method for the
file. (valid only with libtiff installed) Valid compression file. (valid only with libtiff installed) Valid compression

View File

@ -26,6 +26,7 @@ Reference
ImageTk ImageTk
ImageWin ImageWin
ExifTags ExifTags
TiffTags
OleFileIO OleFileIO
PSDraw PSDraw
PixelAccess PixelAccess