metaengine.h

Go to the documentation of this file.

/* ============================================================
 *
 * This file is a part of digiKam project
 * https://www.digikam.org
 *
 * Date        : 2006-09-15
 * Description : Exiv2 library interface
 *               Exiv2: https://www.exiv2.org
 *               Exif : https://www.exif.org/Exif2-2.PDF
 *               Iptc : https://www.iptc.org/std/IIM/4.1/specification/IIMV4.1.pdf
 *               Xmp  : https://www.adobe.com/devnet/xmp/pdfs/xmp_specification.pdf
 *                      https://www.iptc.org/std/Iptc4xmpCore/1.0/specification/Iptc4xmpCore_1.0-spec-XMPSchema_8.pdf
 *               Paper: www.metadataworkinggroup.com/pdf/mwg_guidance.pdf
 *
 * Copyright (C) 2006-2022 by Gilles Caulier <caulier dot gilles at gmail dot com>
 * Copyright (C) 2006-2013 by Marcel Wiesweg <marcel dot wiesweg at gmx dot de>
 *
 * This program is free software; you can redistribute it
 * and/or modify it under the terms of the GNU General
 * Public License as published by the Free Software Foundation;
 * either version 2, or (at your option)
 * any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * ============================================================ */
 
#ifndef DIGIKAM_META_ENGINE_H
#define DIGIKAM_META_ENGINE_H
 
// QT includes
 
#include <QByteArray>
#include <QString>
#include <QDateTime>
#include <QMap>
#include <QSharedDataPointer>
#include <QStringList>
#include <QVariant>
#include <QRegularExpression>
#include <QUrl>
#include <QImage>
 
// Local includes
 
#include "metaengine_data.h"
#include "digikam_export.h"
 
namespace Digikam
{
 
// TODO: merge with DMetadata class.
 
class DIGIKAM_EXPORT MetaEngine
{
 
public:
 
    enum MetadataWritingMode
    {
        WRITE_TO_FILE_ONLY                        = 0,
 
        WRITE_TO_SIDECAR_ONLY                     = 1,
 
        WRITE_TO_SIDECAR_AND_FILE                 = 2,
 
        WRITE_TO_SIDECAR_ONLY_FOR_READ_ONLY_FILES = 3
    };
 
    enum ImageColorWorkSpace
    {
        WORKSPACE_UNSPECIFIED  = 0,
        WORKSPACE_SRGB         = 1,
        WORKSPACE_ADOBERGB     = 2,
        WORKSPACE_UNCALIBRATED = 65535
    };
 
    enum ImageOrientation
    {
        ORIENTATION_UNSPECIFIED  = 0,
        ORIENTATION_NORMAL       = 1,
        ORIENTATION_HFLIP        = 2,
        ORIENTATION_ROT_180      = 3,
        ORIENTATION_VFLIP        = 4,
        ORIENTATION_ROT_90_HFLIP = 5,
        ORIENTATION_ROT_90       = 6,
        ORIENTATION_ROT_90_VFLIP = 7,
        ORIENTATION_ROT_270      = 8
    };
 
    enum XmpTagType
    {
        NormalTag    = 0,
        ArrayBagTag  = 1,
        StructureTag = 2,
        ArrayLangTag = 3,
        ArraySeqTag  = 4
    };
 
    enum Backend
    {
        Exiv2Backend       = 0,   
        LibRawBackend,            
        LibHeifBackend,           
        ImageMagickBackend,       
        FFMpegBackend,            
        NoBackend                 
    };
 
    typedef QMap<QString, QString> MetaDataMap;
 
    typedef QMap<QString, QString> AltLangMap;
 
    typedef QMap<QString, QStringList> TagsMap;
 
public:
 
    MetaEngine();
 
    explicit MetaEngine(const MetaEngineData& data);
 
    explicit MetaEngine(const QString& filePath);
 
    virtual ~MetaEngine();
 
public:
 
    //-----------------------------------------------------------------
 
 
    static bool initializeExiv2();
 
    static bool supportXmp();
 
    static bool supportBmff();
 
    static bool supportMetadataWriting(const QString& typeMime);
 
    static QString Exiv2Version();
 
 
    //-----------------------------------------------------------------
 
 
    MetaEngineData data() const;
    void setData(const MetaEngineData& data);
 
    bool loadFromData(const QByteArray& imgData);
 
    bool isEmpty() const;
 
    QSize getPixelSize() const;
 
    QString getMimeType() const;
 
    void setWriteRawFiles(const bool on);
 
    bool writeRawFiles() const;
 
    void setWriteDngFiles(const bool on);
 
    bool writeDngFiles() const;
 
    void setUseXMPSidecar4Reading(const bool on);
 
    bool useXMPSidecar4Reading() const;
 
    void setUseCompatibleFileName(const bool on);
 
    bool useCompatibleFileName() const;
 
    void setMetadataWritingMode(const int mode);
 
    int metadataWritingMode() const;
 
    void setUpdateFileTimeStamp(bool on);
 
    bool updateFileTimeStamp() const;
 
 
    //-------------------------------------------------------------------
 
 
    void setFilePath(const QString& path);
 
    QString getFilePath() const;
 
    static QString sidecarFilePathForFile(const QString& path, bool useLR = false);
 
    static QString sidecarPath(const QString& path);
 
    static QUrl sidecarUrl(const QUrl& url);
 
    static QUrl sidecarUrl(const QString& path);
 
    static bool hasSidecar(const QString& path);
 
    static QString backendName(Backend t);
 
    bool load(const QString& filePath, Backend* backend = nullptr);
 
    bool loadFromSidecarAndMerge(const QString& filePath);
 
    bool save(const QString& filePath, bool setVersion = false) const;
 
    bool applyChanges(bool setVersion = false) const;
 
    bool exportChanges(const QString& exvTmpFile, QStringList& removedTags) const;
 
 
    //-------------------------------------------------------------------
 
 
    bool setItemProgramId(const QString& program, const QString& version) const;
 
    QSize getItemDimensions() const;
 
    bool setItemDimensions(const QSize& size) const;
 
    MetaEngine::ImageOrientation getItemOrientation() const;
 
    bool setItemOrientation(ImageOrientation orientation) const;
 
    MetaEngine::ImageColorWorkSpace getItemColorWorkSpace() const;
 
    bool setItemColorWorkSpace(ImageColorWorkSpace workspace) const;
 
    QDateTime getItemDateTime() const;
 
    bool setImageDateTime(const QDateTime& dateTime, bool setDateTimeDigitized = false) const;
 
    QDateTime getDigitizationDateTime(bool fallbackToCreationTime = false) const;
 
    bool getItemPreview(QImage& preview) const;
 
    bool setItemPreview(const QImage& preview) const;
 
 
    //-----------------------------------------------------------------
 
 
    static bool canWriteComment(const QString& filePath);
 
    bool hasComments() const;
 
    bool clearComments() const;
 
    QByteArray getComments() const;
 
    QString getCommentsDecoded() const;
 
    bool setComments(const QByteArray& data) const;
 
    static QString detectLanguageAlt(const QString& value, QString& lang);
 
 
    //-----------------------------------------------------------------
 
 
    TagsMap getStdExifTagsList() const;
 
    TagsMap getMakernoteTagsList() const;
 
    static bool canWriteExif(const QString& filePath);
 
    bool hasExif() const;
 
    bool clearExif() const;
 
    QByteArray getExifEncoded(bool addExifHeader = false) const;
 
    bool setExif(const QByteArray& data) const;
 
    QImage getExifThumbnail(bool fixOrientation) const;
 
    bool rotateExifQImage(QImage& image, ImageOrientation orientation) const;
 
    bool setExifThumbnail(const QImage& thumb) const;
 
    bool removeExifThumbnail() const;
 
    bool setTiffThumbnail(const QImage& thumb) const;
 
    QString getExifComment(bool readDescription = true) const;
 
    bool setExifComment(const QString& comment, bool writeDescription = true) const;
 
    QString getExifTagString(const char* exifTagName, bool escapeCR = true) const;
 
    bool setExifTagString(const char* exifTagName, const QString& value) const;
 
    bool getExifTagLong(const char* exifTagName, long &val) const;
 
    bool getExifTagLong(const char* exifTagName, long &val, int component) const;
 
    bool setExifTagLong(const char* exifTagName, long val) const;
 
    bool getExifTagRational(const char* exifTagName, long int& num, long int& den, int component = 0) const;
 
    bool setExifTagRational(const char* exifTagName, long int num, long int den) const;
 
    QByteArray getExifTagData(const char* exifTagName) const;
 
    bool setExifTagData(const char* exifTagName, const QByteArray& data) const;
 
    QVariant getExifTagVariant(const char* exifTagName, bool rationalAsListOfInts = true,
                               bool escapeCR = true, int component = 0) const;
 
    bool setExifTagVariant(const char* exifTagName, const QVariant& data,
                           bool rationalWantSmallDenominator = true) const;
 
    bool removeExifTag(const char* exifTagName) const;
 
    QString getExifTagTitle(const char* exifTagName);
 
    QString getExifTagDescription(const char* exifTagName);
 
    QString createExifUserStringFromValue(const char* exifTagName, const QVariant& val, bool escapeCR = true);
 
    MetaEngine::MetaDataMap getExifTagsDataList(const QStringList& exifKeysFilter = QStringList(),
                                                bool invertSelection = false,
                                                bool extractBinary = true) const;
 
 
    //-------------------------------------------------------------
 
 
    MetaEngine::TagsMap getIptcTagsList() const;
 
    static bool canWriteIptc(const QString& filePath);
 
    bool hasIptc() const;
 
    bool clearIptc() const;
 
    QByteArray  getIptc(bool addIrbHeader = false) const;
 
    bool setIptc(const QByteArray& data) const;
 
    QString getIptcTagString(const char* iptcTagName, bool escapeCR = true) const;
 
    bool setIptcTagString(const char* iptcTagName, const QString& value) const;
 
    QStringList getIptcTagsStringList(const char* iptcTagName, bool escapeCR = true) const;
 
    bool setIptcTagsStringList(const char* iptcTagName, int maxSize,
                               const QStringList& oldValues, const QStringList& newValues) const;
 
    QByteArray getIptcTagData(const char* iptcTagName) const;
 
    bool setIptcTagData(const char* iptcTagName, const QByteArray& data) const;
 
    bool removeIptcTag(const char* iptcTagName) const;
 
    QString getIptcTagTitle(const char* iptcTagName);
 
    QString getIptcTagDescription(const char* iptcTagName);
 
    MetaEngine::MetaDataMap getIptcTagsDataList(const QStringList& iptcKeysFilter = QStringList(),
                                                bool invertSelection = false) const;
 
    QStringList getIptcKeywords() const;
 
    bool setIptcKeywords(const QStringList& oldKeywords, const QStringList& newKeywords) const;
 
    QStringList getIptcSubjects() const;
 
    bool setIptcSubjects(const QStringList& oldSubjects, const QStringList& newSubjects) const;
 
    QStringList getIptcSubCategories() const;
 
    bool setIptcSubCategories(const QStringList& oldSubCategories, const QStringList& newSubCategories) const;
 
 
    //------------------------------------------------------------
 
 
    MetaEngine::TagsMap getXmpTagsList() const;
 
    static bool canWriteXmp(const QString& filePath);
 
    bool hasXmp() const;
 
    bool clearXmp() const;
 
    QByteArray getXmp() const;
 
    bool setXmp(const QByteArray& data) const;
 
    QString getXmpTagString(const char* xmpTagName, bool escapeCR = true) const;
 
    bool setXmpTagString(const char* xmpTagName, const QString& value) const;
 
    bool setXmpTagString(const char* xmpTagName, const QString& value,
                         XmpTagType type) const;
 
    QString getXmpTagTitle(const char* xmpTagName);
 
    QString getXmpTagDescription(const char* xmpTagName);
 
    MetaEngine::MetaDataMap getXmpTagsDataList(const QStringList& xmpKeysFilter = QStringList(),
                                               bool invertSelection = false) const;
 
    MetaEngine::AltLangMap getXmpTagStringListLangAlt(const char* xmpTagName,
                                                      bool escapeCR = true) const;
 
    bool setXmpTagStringListLangAlt(const char* xmpTagName, const MetaEngine::AltLangMap& values) const;
 
    QString getXmpTagStringLangAlt(const char* xmpTagName, const QString& langAlt, bool escapeCR) const;
 
    bool setXmpTagStringLangAlt(const char* xmpTagName, const QString& value,
                                const QString& langAlt) const;
 
    QStringList getXmpTagStringSeq(const char* xmpTagName, bool escapeCR = true) const;
 
    bool setXmpTagStringSeq(const char* xmpTagName, const QStringList& seq) const;
 
    QStringList getXmpTagStringBag(const char* xmpTagName, bool escapeCR) const;
 
    bool setXmpTagStringBag(const char* xmpTagName, const QStringList& bag) const;
 
    bool addToXmpTagStringBag(const char* xmpTagName, const QStringList& entriesToAdd) const;
 
    bool removeFromXmpTagStringBag(const char* xmpTagName, const QStringList& entriesToRemove) const;
 
    QVariant getXmpTagVariant(const char* xmpTagName, bool rationalAsListOfInts = true, bool stringEscapeCR = true) const;
 
    QStringList getXmpKeywords() const;
 
    bool setXmpKeywords(const QStringList& newKeywords) const;
 
    bool removeXmpKeywords(const QStringList& keywordsToRemove);
 
    QStringList getXmpSubjects() const;
 
    bool setXmpSubjects(const QStringList& newSubjects) const;
 
    bool removeXmpSubjects(const QStringList& subjectsToRemove);
 
    QStringList getXmpSubCategories() const;
 
    bool setXmpSubCategories(const QStringList& newSubCategories) const;
 
    bool removeXmpSubCategories(const QStringList& categoriesToRemove);
 
    bool removeXmpTag(const char* xmpTagName, bool family = false) const;
 
    static bool registerXmpNameSpace(const QString& uri, const QString& prefix);
 
    static bool unregisterXmpNameSpace(const QString& uri);
 
 
    //------------------------------------------------------------
 
 
    bool initializeGPSInfo();
 
    bool getGPSInfo(double& altitude, double& latitude, double& longitude) const;
 
    QString getGPSLatitudeString()  const;
    QString getGPSLongitudeString() const;
 
    bool getGPSLatitudeNumber(double* const latitude)   const;
    bool getGPSLongitudeNumber(double* const longitude) const;
 
    bool getGPSAltitude(double* const altitude) const;
 
    bool setGPSInfo(const double altitude, const double latitude, const double longitude);
 
    bool setGPSInfo(const double* const altitude, const double latitude, const double longitude);
 
    bool setGPSInfo(const double altitude, const QString& latitude, const QString& longitude);
 
    bool removeGPSInfo();
 
    static void convertToRational(const double number,
                                  long int* const numerator,
                                  long int* const denominator,
                                  const int rounding);
 
    static void convertToRationalSmallDenominator(const double number,
                                                  long int* const numerator,
                                                  long int* const denominator);
 
    static double convertDegreeAngleToDouble(double degrees, double minutes, double seconds);
 
 
    static QString convertToGPSCoordinateString(const long int numeratorDegrees,
                                                const long int denominatorDegrees,
                                                const long int numeratorMinutes,
                                                const long int denominatorMinutes,
                                                const long int numeratorSeconds,
                                                const long int denominatorSeconds,
                                                const char directionReference);
 
    static QString convertToGPSCoordinateString(const bool isLatitude,
                                                double coordinate);
 
    static bool convertFromGPSCoordinateString(const QString& coordinate,
                                               long int* const numeratorDegrees,
                                               long int* const denominatorDegrees,
                                               long int* const numeratorMinutes,
                                               long int* const denominatorMinutes,
                                               long int* const numeratorSeconds,
                                               long int* const denominatorSeconds,
                                               char* const directionReference);
 
    static bool convertFromGPSCoordinateString(const QString& gpsString,
                                               double* const coordinate);
 
    static bool convertToUserPresentableNumbers(const QString& coordinate,
                                                int* const degrees,
                                                int* const minutes,
                                                double* const seconds,
                                                char* const directionReference);
 
    static void convertToUserPresentableNumbers(const bool isLatitude,
                                                double coordinate,
                                                int* const degrees,
                                                int* const minutes,
                                                double* const seconds,
                                                char* const directionReference);
 
 
protected:
 
    bool setProgramId() const;
 
private:
 
    // Disable copy constructor and operator to prevent potential slicing with this class, reported by Clazy static analyzer.
    // https://github.com/KDE/clazy/blob/master/docs/checks/README-copyable-polymorphic.md
    // This methods was implemented to be able to pass this class or a derived version to signals and slots. This is very
    // Dangerous as virtual methods are present in this polymorphic class and is copyable.
    // Instead to use this class in signals and slots, use MetaEngineData container.
    // TODO: remove legacy implementations for these methods later if no side effect.
    MetaEngine(const MetaEngine& metadata);
    MetaEngine& operator=(const MetaEngine& metadata);
 
private:
 
    class Private;
    Private* const d;
 
    friend class MetaEnginePreviews;
};
 
} // namespace Digikam
 
#endif // DIGIKAM_META_ENGINE_H