API for Images¶

The Images Class¶

class digikamdb.images.Images(digikam)[source]¶

Bases: DigikamTable

Offers access to the images in the Digikam instance.

Images represents all images present in the Digikam database. It is usually accessed through the Digikam property images.

Usage:

dk = Digikam(...)
myimage = dk.images.find('/path/to/my/image.jpg')[0]  # by name
myimage = dk.images[42]                               # by id
for img in dk.images:                                 # iterate
    print(img.name)

Parameters:: digikam (Digikam) – Digikam object for access to database and other classes.

The Image Class (mapped)¶

class _sqla.Image(**kwargs)¶

Bases: DigikamObject

Represents a row in the table Images.

The image’s album can be accessed by album.

Digikam splits metadata (Exif and own) in several tables. Image has the corresponding properties:

captions and titles
copyright
imagemeta (for pictures)
information
position
properties
tags
videometa (for movies)

See also

Class Images

property abspath: str | None¶

The absolute path of the image file (read-only)

Changed in version 0.3.5:

Converted to lowercase for case-insensitive roots (except mountpoint).
Returns None if image has no album (e.g. for deleted images).

property album: Album¶

The album object to which the image belongs (read-only)

This corresponds to the directory the image file where the image file resides.

property caption: str | None¶

The image’s default caption

The default caption has ‘x-default’ as language and None as author. For comments in other languages or from other authors, use captions.

Changed in version 0.2.0: Returns a string instead of a tuple.

property captions: ImageCaptions¶

The image’s captions object

This property contains all the image’s captions. To access the default caption, you can also use the caption property. See Captions for a more detailed description.

property category: ImageCategory¶: The image’s category (read-only)

property copyright: ImageCopyright¶: The image’s copyright data (no setter)

property fileSize: int¶: The image file’s size (read-only)

property history: ImageHistory¶: The image’s history (no setter)

property id: int¶: The image’s id (read-only)

property imagemeta: ImageMetadata¶: The image’s photographic metadata (no setter)

property information: ImageInformation¶: Part of the image’s metadata (no setter)

property manualOrder: int¶

The image’s manual order in its album (read-only)

Raises:: DigikamVersionError – If DBVersion < 10

Changed in version 0.2.2: Raises DigikamVersionError for low DB versions.

property modificationDate: datetime¶: The image file’s modification date (read-only)

property name: str¶: The image’s file name (read-only)

property position: Tuple | None¶

The image’s GPS location data

The value is a tuple with latitude, longitude and altitude. When setting the property, latitude and longitude can be given as a signed float, as a stringified float or as a string containing the absolute value followed by N, S, W or E. The altitude can be omitted, in this case it is not changed if already present. To remove an existing altitude, give the position as (latitude, longitude, None)

When position is set to None, the row in ImagePositions will be deleted.

property properties: ImageProperties¶

The image’s properties (no setter)

See ImageProperties for more information.

property status: ImageStatus¶

The image’s status

The status can be undefined, visible, hidden, trashed or obsolete.

property tags: Iterable[Tag]¶

The image’s tags (no setter)

Tags can be changed by modifying the list.

property title: str¶

The image’s title in default language (‘x-default’)

For comments in other languages, use titles.

property titles: ImageTitles¶

The image’s titles (no setter)

Digikam supports multilingual titles. To access the title in a specific language, use the [] operator:

french = img.titles['fr-FR']
default = img.titles['x-default']    # default language

titles[''] or titles[None] will return the default language (x-default)

property uniqueHash: str¶: The image’s unique (MD5) hash (read-only)

property videometa: VideoMetadata¶: Metadata for video files (no setter)

Image Comments¶

class digikamdb.image_comments.ImageComments(parent, type_)[source]¶

Encapsulates ImageComments (caption and title).

Parameters:

parent (Image) – Corresponding Image object
type_ (int) – Comment type (1 for caption, 3 for title)

class digikamdb.image_comments.ImageTitles(parent)[source]¶

Bases: ImageComments

Enables access to multilingual image titles.

Objects of this type are normally accessed through an Image object, see titles. In general, it is not necessary to call the constructor directly.

Titles can be multilingual. Individual languages can be retrieved from the Titles object like from a dict where the key is a string containing the language. The language can be given as None or as an empty string, both are replaced internally by x-default.

c1 = img.titles['']             # Default language
c2 = img.titles['es-ES']        # Spanish
c3 = img.titles[None]           # Default language

img.titles[''] = 'Some text'    # sets the default title

Parameters:: parent (Image) – Image object the title belongs to.

class digikamdb.image_comments.ImageCaptions(parent)[source]¶

Bases: ImageComments

Contains an image’s captions.

An Image can have multiple captions: by different authors and in different languages. Individual captions can be retrieved from the Captions object like from a dict where the keys are either a string (containing the language, the author defaults to None in this case) or a tuple containing language and author. The language can be given as None or as an empty string, both are replaced internally by x-default.

c1 = img.captions[('', 'Fred')]         # Default language, author Fred
c2 = img.captions['es-ES']              # Spanish, no author
c3 = img.captions[None]                 # Default language, no author
c4 = img.captions[('de-DE', 'Ralph')]   # German, author Ralph

img.captions[''] = 'Some text'          # sets the default caption

The caption’s value is a tuple containing the caption text and the caption’s date. When setting the value, just the text can be given, and the date will be set to None

Parameters:: parent (Image) – Image object the title belongs to.

Image Properties¶

class digikamdb.image_helpers.ImageProperties(parent)[source]¶

Bases: BasicProperties

Image Properties

Objects of this type are normally accessed through an Image object, see properties. In general, it is not necessary to call the constructor directly.

Individual properties can be retrieved and set dict-like vie the [] operator. The method items() iterates over all properties and yields (key, value) tuples.

Parameters:: parent (DigikamObject) – Image object the properties belong to.

Copyright¶

class digikamdb.image_helpers.ImageCopyright(parent)[source]¶

Bases: BasicProperties

Encapsulates ImageCopyright.

Individual copyright entries can be accessed similar to a dict. Values can be:

A string that is copied to the value column, the extravalue column will be None in this case.
A sequence of (value, extravalue) pairs.

If extraValue is set, a tuple is returned, else a str. If no row with a given key exists, None is returned.

Parameters:: parent (DigikamObject) – The corresponding Image object.

items()[source]¶

Returns the properties as an iterable yielding (key, value) tuples.

Return type:: Iterable

remove(prop)[source]¶

Removes the given property.

Parameters:: prop (str | int | Iterable) – Property to remove.

Other Metadata (mapped)¶

class _sqla.ImageHistory(**kwargs)¶

Bases: DigikamObject

Digikam Image History

property history: str¶

The image’s history data (read-only)

If not None, this field contains XML data describing previous versions of the image.

property uuid: str¶

class _sqla.ImageInformation(**kwargs)¶

Bases: DigikamObject

Represents a row of the ImageInformation table.

This data comes from the image file and should not be changed, with the exception of rating.

property colorDepth: int¶: The image’s color depth (read-only)

property colorModel: ImageColorModel | int | None¶: The image’s color model (read-only)

Changed in version 0.3.2: Return numeric value if it is not a valid ExifColorModel

property creationDate: datetime¶: The image’s creation date (read-only)

property digitizationDate: datetime¶: The image’s digitization date (read-only)

property format: str¶: The image’s file format (read-only)

property height: int¶: The image’s height (read-only)

property orientation: ExifOrientation | None¶: The image’s orientation (read-only)

property rating: int¶: The image’s rating (from -1 to 5)

property width: int¶: The image’s width (read-only)

class _sqla.ImageMetadata(**kwargs)¶

Bases: DigikamObject

Represents a row of the ImageMetadata table.

This object contains Exif information of the corresponding image.

property aperture: float | None¶: The image’s aperture value/f-number (read-only)

property exposureMode: ExifExposureMode | None¶: The image’s exposure mode (read-only)

property exposureProgram: ExifExposureProgram | None¶: The image’s exposure program (read-only)

property exposureTime: float | None¶: The image’s exposure time (read-only)

property flash: ExifFlash | None¶: Information about flash usage

property focalLength: float | None¶: The image’s focal length (read-only)

property focalLength35: float | None¶: The image’s 35mm-equivalent focal length (read-only)

property lens: str | None¶: Lens model

property make: str | None¶: Camera’s manufacturer

property meteringMode: ExifMeteringMode | None¶: The image’s metering mode

property model: str | None¶: Camera model

property sensitivity: int | None¶: Photographic sensitivity (ISO number)

property subjectDistance: float | None¶: Distance to subject, as measured by the camera

property subjectDistanceCategory: ExifSubjectDistanceRange | None¶: Exif SubjectDistanceRange attribute

property whiteBalance: ExifWhiteBalance | None¶: White balance mode

property whiteBalanceColorTemperature: int | None¶: Color temperature for manual white balance

class _sqla.VideoMetadata(**kwargs)¶

Bases: DigikamObject

Digikam Video Metadata

This object contains Video metadata of the corresponding Image object.

property aspectRatio: str¶

property audioBitRate: str¶

property audioChannelType: str¶

property audioCompressor: str¶

property duration: str¶

property exposureProgram: int¶

property frameRate: str¶

property videoCodec: str¶

Types of special properties¶

class digikamdb.types.ImageCategory(value)[source]¶

Bases: IntEnum

Class for Image.category

UndefinedCategory = 0¶

Image = 1¶

Video = 2¶

Audio = 3¶

Other = 4¶

class digikamdb.types.ImageStatus(value)[source]¶

Bases: IntEnum

Class for Image.status

UndefinedStatus = 0¶

Visible = 1¶

Hidden = 2¶

Trashed = 3¶

Obsolete = 4¶

class digikamdb.types.ImageColorModel(value)[source]¶

Bases: IntEnum

Digikam Color Model

Used by ImageInformation.colorModel

COLORMODELUNKNOWN = 0¶

RGB = 1¶

GRAYSCALE = 2¶

MONOCHROME = 3¶

INDEXED = 4¶

YCBCR = 5¶

CMYK = 6¶

CIELAB = 7¶

COLORMODELRAW = 8¶

class digikamdb.types.ExifExposureMode(value)[source]¶

Bases: ExifEnum

Exif ExposureMode Tag

Used by ImageMetadata.exposureMode

Changed in version 0.3.0: More readable string representation

AUTO_EXPOSURE = 0¶

MANUAL_EXPOSURE = 1¶

AUTO_BRACKET = 2¶

class digikamdb.types.ExifExposureProgram(value)[source]¶

Bases: ExifEnum

Exif ExposureProgram Tag

Used by ImageMetadata.exposureProgram

Changed in version 0.3.0: More readable string representation

Changed in version 0.3.2: Added BULB mode (non-official, but used by Canon)

NOT_DEFINED = 0¶

MANUAL = 1¶

NORMAL_PROGRAM = 2¶

APERTURE_PRIORITY = 3¶

SHUTTER_PRIORITY = 4¶

CREATIVE_PROGRAM = 5¶

ACTION_PROGRAM = 6¶

PORTRAIT_MODE = 7¶

LANDSCAPE_MODE = 8¶

BULB = 9¶

class digikamdb.types.ExifFlash(value)[source]¶

Bases: object

Exif Flash Tag

Used by ImageMetadata.flash. To get the numeric value of the flash tag, use int(flash_tag)

Parameters:: value (int | Mapping) – The int value of flash tag, or a dict containing the flash information.

Changed in version 0.3.0: * For more consistency with the Exif standard, flash_function has been replaced by no_flash_function (its logical negation). The numeric representation has not changed and always conformed to the standard. * __repr__ shows the fields’ names * More readable __str__

property flash_fired: bool¶: Indicates if the flash fired.

property flash_return: ExifFlashReturn¶: Status of returned light

property flash_mode: ExifFlashMode¶: Flash mode

property no_flash_function: bool¶: Flash function supported?

property red_eye_reduction: bool¶: Red eye reduction supported?

class digikamdb.types.ExifFlashMode(value)[source]¶

Bases: ExifEnum

Exif Flash Mode (part of ExifFlash Tag)

Changed in version 0.3.0: More readable string representation

UNKNOWN = 0¶

COMPULSORY_FLASH_FIRING = 1¶

COMPULSORY_FLASH_SUPPRESSION = 2¶

AUTO_MODE = 3¶

class digikamdb.types.ExifFlashReturn(value)[source]¶

Bases: ExifEnum

Exif Flash Return (part of ExifFlash Tag)

Changed in version 0.3.0: More readable string representation

NO_STROBE_RETURN_DETECTION_FUNCTION = 0¶

RESERVED = 1¶

STROBE_RETURN_LIGHT_DETECTED = 2¶

STROBE_RETURN_LIGHT_NOT_DETECTED = 3¶

class digikamdb.types.ExifMeteringMode(value)[source]¶

Bases: ExifEnum

Exif MeteringMode Tag

Used by ImageMetadata.meteringMode

Changed in version 0.3.0: More readable string representation

UNKNOWN = 0¶

AVERAGE = 1¶

CENTER_WEIGHTED_AVERAGE = 2¶

SPOT = 3¶

MULTI_SPOT = 4¶

PATTERN = 5¶

PARTIAL = 6¶

OTHER = 255¶

class digikamdb.types.ExifOrientation(value)[source]¶

Bases: ExifEnum

Exif ImageOrientation Tag

The constants describe the position of row 0 and column 0 in the visual image, as specified in the Exif documentation. The mirrored orientations will usually not show up in digital photos.

Used by ImageInformation.orientation

Changed in version 0.3.0: More readable string representation

TOP_LEFT = 1¶: Landscape, camera held upright

TOP_RIGHT = 2¶: 1 mirrored

BOTTOM_RIGHT = 3¶: Landscape, camera held upside down

BOTTOM_LEFT = 4¶: 3 mirrored

LEFT_TOP = 5¶: 6 mirrored

RIGHT_TOP = 6¶: Portrait, camera turned right

RIGHT_BOTTOM = 7¶: 8 mirrored

LEFT_BOTTOM = 8¶: Portrait, camera turned left

class digikamdb.types.ExifWhiteBalance(value)[source]¶

Bases: ExifEnum

Exif WhiteBalance Tag

Used by ImageMetadata.whiteBalance

Changed in version 0.3.0: More readable string representation

AUTO = 0¶

MANUAL = 1¶

API for Images¶

The Images Class¶

The Image Class (mapped)¶

Image Comments¶

Image Properties¶

Copyright¶

Other Metadata (mapped)¶

Types of special properties¶

Table of Contents

Related Topics

This Page