exiv2._image

Image & ImageFactory classes.

Functions

enableBMFF

Enable BMFF support.

Classes

`Image`	Abstract base class defining the interface for an image.
`ImageFactory`	Returns an Image instance of the specified type.
`ImageType`	Supported image formats.

class Image

Bases: SwigPyObject

Abstract base class defining the interface for an image. This is the top-level interface to the Exiv2 library.

Image has containers to store image metadata and subclasses implement read and save metadata from and to specific image formats.

Most client apps will obtain an Image instance by calling a static ImageFactory method. The Image class can then be used to to read, write, and save metadata.

byteOrder(): Return the byte order in which the Exif metadata of the image is encoded. Initially, it is not set (invalidByteOrder).

checkMode()

Returns the access mode, i.e., the metadata functions, which this image supports for the metadata type metadataId.

Parameters:: metadataId (MetadataId) – The metadata identifier.
Return type:: AccessMode
Returns:: Access mode for the requested image type and metadata identifier.

clearComment(): Erase any buffered comment. Comment is not removed from the actual image until the writeMetadata() method is called.

clearExifData(): Erase any buffered Exif data. Exif data is not removed from the actual image until the writeMetadata() method is called.

clearIccProfile(): Erase iccProfile. the profile is not removed from the actual image until the writeMetadata() method is called.

clearIptcData(): Erase any buffered IPTC data. IPTC data is not removed from the actual image until the writeMetadata() method is called.

clearMetadata(): Erase all buffered metadata. Metadata is not removed from the actual image until the writeMetadata() method is called.

clearXmpData()

Erase any buffered XMP data. XMP data is not removed from the actual image until the writeMetadata() method is called.

This has the same effect as clearXmpPacket() but operates on the buffered parsed XMP data.

Subsequent calls to writeMetadata() encode the XMP data to a raw XMP packet and write the newly encoded packet to the image. In the process, the buffered raw XMP packet is updated. In order to write directly from the raw XMP packet, use writeXmpFromPacket(true) or setXmpPacket().

clearXmpPacket()

Erase the buffered XMP packet. XMP data is not removed from the actual image until the writeMetadata() method is called.

This has the same effect as clearXmpData() but operates on the buffered raw XMP packet only, not the parsed XMP data.

Subsequent calls to writeMetadata() write the XMP packet from the buffered raw XMP packet rather than from buffered parsed XMP data. In order to write from parsed XMP data again, use either writeXmpFromPacket(false) or setXmpData().

comment(): Return a copy of the image comment. May be an empty string.

exifData()

Returns an ExifData instance containing currently buffered Exif data.

The contained Exif data may have been read from the image by a previous call to readMetadata() or added directly. The Exif data in the returned instance will be written to the image when writeMetadata() is called.

Return type:: ExifData
Returns:: modifiable ExifData instance containing Exif values

good()

Check if the Image instance is valid. Use after object construction.

Return type:: bool
Returns:: true if the Image is in a valid state.

iccProfile(): return iccProfile

iccProfileDefined(): Returns the status of the ICC profile in the image instance

imageType(): set type support for this image format

io()

Return a reference to the BasicIo instance being used for Io.

This reference is particularly useful to reading the results of operations on a MemIo instance. For example after metadata has been modified and the writeMetadata() method has been called, this method can be used to get access to the modified image.

Return type:: BasicIo
Returns:: BasicIo instance that can be used to read or write image data directly.

Note

If the returned BasicIo is used to write to the image, the Image class will not see those changes until the readMetadata() method is called.

iptcData()

Returns an IptcData instance containing currently buffered IPTC data.

The contained IPTC data may have been read from the image by a previous call to readMetadata() or added directly. The IPTC data in the returned instance will be written to the image when writeMetadata() is called.

Return type:: IptcData
Returns:: modifiable IptcData instance containing IPTC values

mimeType(): Return the MIME type of the image.

Note

For each supported image format, the library knows only one MIME type. This may not be the most specific MIME type for that format. In particular, several RAW formats are variants of the TIFF format with the same magic as TIFF itself. Class TiffImage handles most of them and thus they all have MIME type “image/tiff”, although a more specific MIME type may exist (e.g., “image/x-nikon-nef”).

pixelHeight(): Return the pixel height of the image.

pixelWidth(): Return the pixel width of the image.

readMetadata()

Read all metadata supported by a specific image format from the image. Before this method is called, the image metadata will be cleared.

This method returns success even if no metadata is found in the image. Callers must therefore check the size of individual metadata types before accessing the data.

Raises:: Exiv2Error if opening or reading of the file fails or the image data is not valid (does not look like data of the specific image type).

setByteOrder()

Set the byte order to encode the Exif metadata in.

The setting is only used when new Exif metadata is created and may not be applicable at all for some image formats. If the target image already contains Exif metadata, the byte order of the existing data is used. If byte order is not set when writeMetadata() is called, little-endian byte order (II) is used by default.

setComment(): Set the image comment. The comment is written to the image when writeMetadata() is called.

setExifData()

Assign new Exif data. The new Exif data is not written to the image until the writeMetadata() method is called.

Parameters:: exifData (ExifData) – An ExifData instance holding Exif data to be copied

setIccProfile()

Set the image iccProfile. The new profile is not written to the image until the writeMetadata() method is called.

Parameters:

iccProfile (DataBuf) – DataBuf containing profile (binary)
bTestValid (bool, optional) –
- tests that iccProfile contains credible data

setIptcData()

Assign new IPTC data. The new IPTC data is not written to the image until the writeMetadata() method is called.

Parameters:: iptcData (IptcData) – An IptcData instance holding IPTC data to be copied

setMetadata()

Copy all existing metadata from source Image. The data is copied into internal buffers and is not written to the image until the writeMetadata() method is called.

Parameters:: image (Image) – Metadata source. All metadata types are copied.

setTypeSupported(): set type support for this image format

setXmpData()

Assign new XMP data. The new XMP data is not written to the image until the writeMetadata() method is called.

Subsequent calls to writeMetadata() encode the XMP data to a raw XMP packet and write the newly encoded packet to the image. In the process, the buffered raw XMP packet is updated. In order to write directly from the raw XMP packet, use writeXmpFromPacket(true) or setXmpPacket().

Parameters:: xmpData (XmpData) – An XmpData instance holding XMP data to be copied

setXmpPacket()

Assign a raw XMP packet. The new XMP packet is not written to the image until the writeMetadata() method is called.

Subsequent calls to writeMetadata() write the XMP packet from the buffered raw XMP packet rather than from buffered parsed XMP data. In order to write from parsed XMP data again, use either writeXmpFromPacket(false) or setXmpData().

Parameters:: xmpPacket (str) – A string containing the raw XMP packet.

supportsMetadata(): Check if image supports a particular type of metadata. This method is deprecated. Use checkMode() instead.

writeMetadata()

Write metadata back to the image.

All existing metadata sections in the image are either created, replaced, or erased. If values for a given metadata type have been assigned, a section for that metadata type will either be created or replaced. If no values have been assigned to a given metadata type, any exists section for that metadata type will be removed from the image.

Raises:: Exiv2Error if the operation fails

writeXmpFromPacket()

Overload 1:

Determine the source when writing XMP.

Depending on the setting of this flag, writeMetadata() writes XMP from the buffered raw XMP packet or from parsed XMP data. The default is to write from parsed XMP data. The switch is also set by all functions to set and clear the buffered raw XMP packet and parsed XMP data, so using this function should usually not be necessary.

If Exiv2 was compiled without XMP support, the default for this flag is true and it will never be changed in order to preserve access to the raw XMP packet.

Overload 2:

Return the flag indicating the source when writing XMP metadata.

xmpData()

Returns an XmpData instance containing currently buffered XMP data.

The contained XMP data may have been read from the image by a previous call to readMetadata() or added directly. The XMP data in the returned instance will be written to the image when writeMetadata() is called.

Return type:: XmpData
Returns:: modifiable XmpData instance containing XMP values

xmpPacket(): Return a modifiable reference to the raw XMP packet.

class ImageFactory

Bases: SwigPyObject

Returns an Image instance of the specified type.

The factory is implemented as a static class.

static checkMode()

Returns the access mode or supported metadata functions for an image type and a metadata type.

Parameters:

type (ImageType) – The image type.
metadataId (MetadataId) – The metadata identifier.

Return type:

AccessMode

Returns:

Access mode for the requested image type and metadata identifier.

Raises:

Exiv2Error (kerUnsupportedImageType) if the image type is not supported.

static checkType()

Determine if the content of io is an image of type.

The advance flag determines if the read position in the stream is moved (see below). This applies only if the type matches and the function returns true. If the type does not match, the stream position is not changed. However, if reading from the stream fails, the stream position is undefined. Consult the stream state to obtain more information in this case.

Parameters:

type (ImageType) – Type of the image.
io (BasicIo) – BasicIo instance to read from.
advance (bool) – Flag indicating whether the position of the io should be advanced by the number of characters read to analyse the data (true) or left at its original position (false). This applies only if the type matches.

Return type:

bool

Returns:

true if the data matches the type of this class;

false if the data does not match

static create()

Overload 1:

Create an Image subclass of the requested type by creating a new image file. If the file already exists, it will be overwritten.

Parameters:

type (ImageType) – Type of the image to be created.
path (str) – Image file to create. File extension is ignored.

Return type:

Image

Returns:

An auto-pointer that owns an Image instance of the requested type.

Raises:

Exiv2Error If the image type is not supported.

Overload 2:

Create an Image subclass of the requested type by creating a new image in memory.

Parameters:: type (ImageType) – Type of the image to be created.
Return type:: Image
Returns:: An auto-pointer that owns an Image instance of the requested type.
Raises:: Exiv2Error If the image type is not supported

static createIo()

Create the appropriate class type implemented BasicIo based on the protocol of the input.

“-” path implies the data from stdin and it is handled by StdinIo. Http path can be handled by either HttpIo or CurlIo. Https, ftp paths are handled by CurlIo. Ssh, sftp paths are handled by SshIo. Others are handled by FileIo.

Parameters:

path (str) – Image file.
useCurl (bool, optional) – Indicate whether the libcurl is used or not. If it’s true, http is handled by CurlIo. Otherwise it is handled by HttpIo.

Return type:

BasicIo

Returns:

An auto-pointer that owns an BasicIo instance.

Raises:

Exiv2Error If the file is not found or it is unable to connect to the server to read the remote file.

static getType()

Overload 1:

Returns the image type of the provided file.

Parameters:: path (str) – Image file. The contents of the file are tested to determine the image type. File extension is ignored.
Return type:: ImageType
Returns:: Image type or Image::none if the type is not recognized.

Overload 2:

Returns the image type of the provided data buffer.

Parameters:

data (bytes-like object) – Pointer to a data buffer containing an image. The contents of the memory are tested to determine the image type.
size – Number of bytes pointed to by data.

Return type:

ImageType

Returns:

Image type or Image::none if the type is not recognized.

Overload 3:

Returns the image type of data provided by a BasicIo instance. The passed in io instance is (re)opened by this method.

Parameters:: io (BasicIo) – A BasicIo instance that provides image data. The contents of the image data are tested to determine the type.
Return type:: ImageType
Returns:: Image type or Image::none if the type is not recognized.

static open()

Overload 1:

Create an Image subclass of the appropriate type by reading the specified file. Image type is derived from the file contents.

Parameters:

path (str) – Image file. The contents of the file are tested to determine the image type. File extension is ignored.
useCurl (bool, optional) – Indicate whether the libcurl is used or not. If it’s true, http is handled by CurlIo. Otherwise it is handled by HttpIo.

Return type:

Image

Returns:

An auto-pointer that owns an Image instance whose type matches that of the file.

Raises:

Exiv2Error If opening the file fails or it contains data of an unknown image type.

Overload 2:

Create an Image subclass of the appropriate type by reading the provided memory. Image type is derived from the memory contents.

Parameters:

data (bytes-like object) – Pointer to a data buffer containing an image. The contents of the memory are tested to determine the image type.
size – Number of bytes pointed to by data.

Return type:

Image

Returns:

An auto-pointer that owns an Image instance whose type matches that of the data buffer.

Raises:

Exiv2Error If the memory contains data of an unknown image type.

class ImageType

Bases: IntEnum

Supported image formats.

arw = 1

asf = 2

bmff = 4

bmp = 5

cr2 = 6

crw = 7

dng = 8

eps = 9

exv = 10

gif = 11

jp2 = 12

jpeg = 13

mkv = 31

mrw = 14

nef = 15

none = 0

orf = 16

pgf = 19

png = 18

psd = 20

qtime = 29

raf = 21

riff = 30

rw2 = 22

sr2 = 23

srw = 24

tga = 25

tiff = 26

webp = 27

xmp = 28

enableBMFF()

Enable BMFF support.

If libexiv2 has been built with BMFF support included it can be enabled by calling enableBMFF(True).

Parameters:: enable (bool, optional) – Set to True to enable BMFF file access.
Return type:: bool
Returns:: True if libexiv2 has been built with BMFF support.