Image Metadata¶
Thumbor uses py3exiv2 to read and write image metadata.
If the Py3exif2 Python library is available, the PIL engine also stores image metadata
in engine.metadata
.
Reading and writing Metadata¶
This part is copied from the py3exiv2 Tutorial
Let’s retrieve a list of all the available EXIF tags available in the image:
>>> engine.metadata.exif_keys
['Exif.Image.ImageDescription',
'Exif.Image.XResolution',
'Exif.Image.YResolution',
'Exif.Image.ResolutionUnit',
'Exif.Image.Software',
'Exif.Image.DateTime',
'Exif.Image.Artist',
'Exif.Image.Copyright',
'Exif.Image.ExifTag',
'Exif.Photo.Flash',
'Exif.Photo.PixelXDimension',
'Exif.Photo.PixelYDimension']
Each of those tags can be accessed with the []
operator on the metadata,
much like a python dictionary:
>>> tag = metadata[b'Exif.Image.DateTime']
The value of an ExifTag
object can be accessed in two different ways:
with the raw_value
and with the value
attributes:
>>> tag.raw_value
'2004-07-13T21:23:44Z'
>>> tag.value
datetime.datetime(2004, 7, 13, 21, 23, 44)
The raw value is always a byte string, this is how the value is stored in the file. The value is lazily computed from the raw value depending on the EXIF type of the tag, and is represented as a convenient python object to allow easy manipulation.
Note that querying the value of a tag may raise an ExifValueError
if the
format of the raw value is invalid according to the EXIF specification (may
happen if it was written by other software that implements the specification in
a broken manner), or if pyexiv2 doesn’t know how to convert it to a convenient
python object.
Accessing the value of a tag as a python object allows easy manipulation and formatting:
>>> tag.value.strftime('%A %d %B %Y, %H:%M:%S')
'Tuesday 13 July 2004, 21:23:44'
Now let’s modify the value of the tag and write it back to the file:
>>> import datetime
>>> tag.value = datetime.datetime.today()
>>> engine.metadata.write()
Similarly to reading the value of a tag, one can set either the
raw_value
or the value
(which will be automatically converted to
a correctly formatted byte string by pyexiv2).
You can also add new tags to the metadata by providing a valid key and value pair (see exiv2’s documentation for a list of valid EXIF tags):
>>> key = 'Exif.Photo.UserComment'
>>> value = 'This is a useful comment.'
>>> engine.metadata[key] = pyexiv2.ExifTag(key, value)
As a handy shortcut, you can always assign a value for a given key regardless of whether it’s already present in the metadata. If a tag was present, its value is overwritten. If the tag was not present, one is created and its value is set:
>>> engine.metadata[key] = value
The EXIF data may optionally embed a thumbnail in the JPEG or TIFF format. The thumbnail can be accessed, set from a JPEG file or buffer, saved to disk and erased:
>>> thumb = engine.metadata.exif_thumbnail
>>> thumb.set_from_file('/tmp/thumbnail.jpg')
>>> thumb.write_to_file('/tmp/copy')
>>> thumb.erase()
>>> engine.metadata.write()
Installation¶
Pyexiv2 depends on the following libraries:
boost.python (http://www.boost.org/libs/python/doc/index.html)
exiv2 (http://www.exiv2.org/)
On OSX you can use homebrew to install the dependencies:
brew install boost --with-python
brew install boost-python
brew install exiv2
pip install py3exiv2
If you are updating thumbor and already have an existing virtualenv, then you have to recreate it. If you have both a System Python and a Homebrew Python with the same version, then make sure the Virtualenv uses the Homebrew Python binary.
On Linux Pyexiv2 can be installed with apt-get:
apt-get install python-all-dev libboost-python-dev libexiv2-dev pip install py3exiv2
pyexiv2.metadata API reference¶
-
class
pyexiv2.metadata.
ImageMetadata
(filename)[source]¶ A container for all the metadata embedded in an image.
It provides convenient methods for the manipulation of EXIF, IPTC and XMP metadata embedded in image files such as JPEG and TIFF files, using Python types. It also provides access to the previews embedded in an image.
-
__delitem__
(key)[source]¶ Delete a metadata tag for a given key.
Raise KeyError if the tag with the given key doesn’t exist
Args: key – the metadata key in the dotted form
familyName.groupName.tagName
wherefamilyName
may be one ofexif
,iptc
orxmp
.
-
__getitem__
(key)[source]¶ Return a metadata tag for a given key.
Raise KeyError if the tag doesn’t exist
Args: key – metadata key in the dotted form
familyName.groupName.tagName
wherefamilyName
may be one ofexif
,iptc
orxmp
.
-
__setitem__
(key, tag_or_value)[source]¶ Set a metadata tag for a given key.
If the tag was previously set, it is overwritten. As a handy shortcut, a value may be passed instead of a fully formed tag. The corresponding tag object will be instantiated.
Raise KeyError if the key is invalid
Args: key – metadata key in the dotted form
familyName.groupName.tagName
wherefamilyName
may be one ofexif
,iptc
orxmp
.- tag_or_value – an instance of the corresponding family of metadata
tag or a value Type: pyexiv2.exif.ExifTag instance or
pyexiv2.iptc.IptcTag instance or pyexiv2.xmp.XmpTag instance or any valid value type
-
property
buffer
¶ The image buffer as a string. If metadata has been modified, the data won’t be up-to-date until
write()
has been called.
-
property
comment
¶ The image comment.
-
copy
(other, exif=True, iptc=True, xmp=True, comment=True)[source]¶ Copy the metadata to another image.
The metadata in the destination is overridden. In particular, if the destination contains e.g. EXIF data and the source doesn’t, it will be erased in the destination, unless explicitly omitted.
Args: other – the destination metadata to copy to (it must have been
read beforehand) Type: pyexiv2.metadata.ImageMetadata instance
exif – whether to copy the EXIF metadata, default True iptc – whether to copy the IPTC metadata, default True xmp – whether to copy the XMP metadata, default True comment – whether to copy the image comment, default True
-
property
dimensions
¶ A tuple containing the width and height of the image, expressed in pixels.
-
property
exif_keys
¶ Return the list of the keys of the available EXIF tags.
-
classmethod
from_buffer
(buffer_)[source]¶ Instantiate an image container from an image memoryview.
Args: buffer_ – a memoryview containing image data as bytes
-
property
iptc_charset
¶ An optional character set the IPTC data is encoded in.
-
property
iptc_keys
¶ Return the list of the keys of the available IPTC tags.
-
property
mime_type
¶ The mime type of the image, as a string.
-
property
previews
¶ List of the previews available in the image, sorted by increasing size.
-
read
()[source]¶ Read the metadata embedded in the associated image.
It is necessary to call this method once before attempting to access the metadata (an exception will be raised if trying to access metadata before calling this method).
-
write
(preserve_timestamps=False)[source]¶ Write the metadata back to the image.
Args: preserve_timestamps – whether to preserve the file’s original
timestamps (access time and modification time) Type: boolean
-
property
xmp_keys
¶ Return the list of the keys of the available XMP tags.
-