dimg.h

Go to the documentation of this file.

/* ============================================================
 *
 * This file is a part of digiKam project
 * https://www.digikam.org
 *
 * Date        : 2005-06-14
 * Description : digiKam 8/16 bits image management API
 *
 * Copyright (C) 2005      by Renchi Raju <renchi dot raju at gmail dot com>
 * Copyright (C) 2005-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_DIMG_H
#define DIGIKAM_DIMG_H
 
// Qt includes
 
#include <QExplicitlySharedDataPointer>
#include <QByteArray>
#include <QFileInfo>
#include <QFlags>
#include <QSize>
#include <QRect>
#include <QVariant>
 
// Local includes
 
#include "digikam_export.h"
#include "drawdecoding.h"
#include "dcolor.h"
#include "dcolorcomposer.h"
#include "historyimageid.h"
#include "iccprofile.h"
#include "metaengine_data.h"
 
class QImage;
class QPixmap;
 
namespace Digikam
{
 
class ExposureSettingsContainer;
class DImageHistory;
class FilterAction;
class IccTransform;
class DImgLoaderObserver;
 
class DIGIKAM_EXPORT DImg
{
public:
 
    enum FORMAT
    {
        NONE = 0,
        JPEG,
        PNG,
        TIFF,
        JP2K,
        PGF,
        HEIF,
        // Others file formats.
        RAW,
        QIMAGE  
    };
 
    enum ANGLE
    {
        ROT90 = 0,
        ROT180,
        ROT270,
        ROTNONE
    };
 
    enum FLIP
    {
        HORIZONTAL = 0,
        VERTICAL
    };
 
    enum COLORMODEL
    {
        COLORMODELUNKNOWN = 0,
        RGB,
        GRAYSCALE,
        MONOCHROME,
        INDEXED,
        YCBCR,
        CMYK,
        CIELAB,
        COLORMODELRAW
    };
 
public:
 
    static FORMAT fileFormat(const QString& filePath);
 
    static QString formatToMimeType(FORMAT frm);
 
public:
 
    class Private;
 
public:
 
    DImg();
 
    explicit DImg(const QByteArray& filePath, DImgLoaderObserver* const observer = nullptr,
                  const DRawDecoding& rawDecodingSettings = DRawDecoding());
 
    explicit DImg(const QString& filePath, DImgLoaderObserver* const observer = nullptr,
                  const DRawDecoding& rawDecodingSettings = DRawDecoding());
 
    DImg(const DImg& image);
 
    explicit DImg(const QImage& image);
 
    DImg(uint width, uint height, bool sixteenBit, bool alpha = false, uchar* const data = nullptr, bool copyData = true);
 
    ~DImg();
 
    DImg&      operator=(const DImg& image);
 
    void       detach();
 
    bool        operator==(const DImg& image) const;
 
    void        putImageData(uint width, uint height, bool sixteenBit, bool alpha, uchar* const data, bool copyData = true);
 
    void        putImageData(uchar* const data, bool copyData = true);
 
    void        reset();
 
    void        resetMetaData();
 
    uchar*      stripImageData();
 
    bool        load(const QString& filePath, DImgLoaderObserver* const observer = nullptr,
                     const DRawDecoding& rawDecodingSettings = DRawDecoding());
 
    bool        load(const QString& filePath,
                     bool loadMetadata, bool loadICCData, bool loadUniqueHash, bool loadHistory,
                     DImgLoaderObserver* const observer = nullptr,
                     const DRawDecoding& rawDecodingSettings = DRawDecoding());
 
    bool        load(const QString& filePath, int loadFlags, DImgLoaderObserver* const observer,
                     const DRawDecoding& rawDecodingSettings = DRawDecoding());
 
    bool        save(const QString& filePath, FORMAT frm, DImgLoaderObserver* const observer = nullptr);
    bool        save(const QString& filePath, const QString& format, DImgLoaderObserver* const observer = nullptr);
 
    void        imageSavedAs(const QString& savePath);
 
    bool        loadItemInfo(const QString& filePath, bool loadMetadata = true,
                             bool loadICCData = true, bool loadUniqueHash = true,
                             bool loadImageHistory = true);
 
    bool        isNull()         const;
    uint        width()          const;
    uint        height()         const;
    QSize       size()           const;
    uchar*      copyBits()       const;
    uchar*      bits()           const;
    uchar*      scanLine(uint i) const;
    bool        hasAlpha()       const;
    bool        sixteenBit()     const;
    quint64     numBytes()       const;
    quint64     numPixels()      const;
 
    int         bytesDepth() const;
 
    int         bitsDepth()  const;
 
    QString     originalFilePath() const;
 
    QString     lastSavedFilePath() const;
 
    COLORMODEL  originalColorModel() const;
 
    int         originalBitDepth() const;
 
    QSize       originalSize() const;
 
    QSize       originalRatioSize() const;
 
    FORMAT      detectedFormat() const;
 
    QString     format() const;
 
    QString     savedFormat() const;
 
    DRawDecoding rawDecodingSettings() const;
 
    DColor      getPixelColor(uint x, uint y) const;
    void        setPixelColor(uint x, uint y, const DColor& color);
    void        prepareSubPixelAccess();
    DColor      getSubPixelColor(float x, float y) const;
    DColor      getSubPixelColorFast(float x, float y) const;
 
    bool        hasTransparentPixels() const;
 
    bool       isReadOnly()        const;
 
    MetaEngineData getMetadata()   const;
    IccProfile getIccProfile()     const;
    void       setMetadata(const MetaEngineData& data);
    void       setIccProfile(const IccProfile& profile);
 
    void       setAttribute(const QString& key, const QVariant& value);
    QVariant   attribute(const QString& key)    const;
    bool       hasAttribute(const QString& key) const;
    void       removeAttribute(const QString& key);
 
    void       setEmbeddedText(const QString& key, const QString& text);
    QString    embeddedText(const QString& key) const;
 
    const DImageHistory& getItemHistory() const;
    DImageHistory&       getItemHistory();
    void                 setItemHistory(const DImageHistory& history);
    bool                 hasImageHistory() const;
    DImageHistory        getOriginalImageHistory() const;
    void                 addFilterAction(const FilterAction& action);
 
    void                 setHistoryBranchAfter(const DImageHistory& historyBeforeBranch, bool isBranch = true);
    void                 setHistoryBranchForLastSteps(int numberOfLastHistorySteps, bool isBranch = true);
    void                 setHistoryBranch(bool isBranch = true);
 
    enum PrepareMetadataFlag
    {
        RemoveOldMetadataPreviews = 1 << 0,
        CreateNewMetadataPreview  = 1 << 1,
        ResetExifOrientationTag   = 1 << 2,
        CreateNewImageHistoryUUID = 1 << 3,
 
        PrepareMetadataFlagsAll   = RemoveOldMetadataPreviews |
                                    CreateNewMetadataPreview  |
                                    ResetExifOrientationTag   |
                                    CreateNewImageHistoryUUID
    };
    Q_DECLARE_FLAGS(PrepareMetadataFlags, PrepareMetadataFlag)
 
    void prepareMetadataToSave(const QString& intendedDestPath,
                               const QString& destMimeType,
                               const QString& originalFileName = QString(),
                               PrepareMetadataFlags flags      = PrepareMetadataFlagsAll);
 
    void prepareMetadataToSave(const QString& intendedDestPath,
                               const QString& destMimeType,
                               bool           resetExifOrientationTag);
 
    HistoryImageId createHistoryImageId(const QString& filePath, HistoryImageId::Type type);
 
    HistoryImageId addAsReferredImage(const QString& filePath, HistoryImageId::Type type = HistoryImageId::Intermediate);
    void           addAsReferredImage(const HistoryImageId& id);
    void           insertAsReferredImage(int afterHistoryStep, const HistoryImageId& otherImagesId);
 
    void addCurrentUniqueImageId(const QString& uuid);
 
    int exifOrientation(const QString& filePath);
 
    QVariant    fileOriginData()          const;
    void        setFileOriginData(const QVariant& data);
    QVariant    lastSavedFileOriginData() const;
    void        switchOriginToLastSaved();
 
    DImg       copy() const;
 
    DImg       copyImageData() const;
 
    DImg       copyMetaData() const;
 
    DImg       copy(const QRect& rect)          const;
    DImg       copy(const QRectF& relativeRect) const;
    DImg       copy(int x, int y, int w, int h) const;
 
    void       bitBltImage(const DImg* const src, int dx, int dy);
    void       bitBltImage(const DImg* const src, int sx, int sy, int dx, int dy);
    void       bitBltImage(const DImg* const src, int sx, int sy, int w, int h, int dx, int dy);
    void       bitBltImage(const uchar* const src, int sx, int sy, int w, int h, int dx, int dy,
                           uint swidth, uint sheight, int sdepth);
 
    void       bitBlendImage(DColorComposer* const composer, const DImg* const src,
                             int sx, int sy, int w, int h, int dx, int dy,
                             DColorComposer::MultiplicationFlags multiplicationFlags =
                                 DColorComposer::NoMultiplication);
 
    void       bitBlendImageOnColor(DColorComposer* const composer, const DColor& color,
                                    int x, int y, int w, int h,
                                    DColorComposer::MultiplicationFlags multiplicationFlags =
                                    DColorComposer::NoMultiplication);
    void       bitBlendImageOnColor(const DColor& color, int x, int y, int w, int h);
    void       bitBlendImageOnColor(const DColor& color);
 
    QImage     copyQImage()                           const;
    QImage     copyQImage(const QRect& rect)          const;
    QImage     copyQImage(const QRectF& relativeRect) const;
    QImage     copyQImage(int x, int y, int w, int h) const;
 
    void       crop(const QRect& rect);
    void       crop(int x, int y, int w, int h);
 
    void       resize(int w, int h);
 
    void       removeAlphaChannel(const DColor& destColor);
    void       removeAlphaChannel();
 
    DImg       smoothScale(int width, int height, Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio) const;
    DImg       smoothScale(const QSize& destSize, Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio) const;
 
    DImg smoothScaleClipped(int width, int height, int clipx, int clipy, int clipwidth, int clipheight) const;
    DImg smoothScaleClipped(const QSize& destSize, const QRect& clip) const;
 
    DImg       smoothScaleSection(int sx, int sy, int sw, int sh, int dw, int dh) const;
    DImg       smoothScaleSection(const QRect& sourceRect, const QSize& destSize) const;
 
    void       rotate(ANGLE angle);
    void       flip(FLIP direction);
 
    bool       rotateAndFlip(int orientation);
 
    bool       reverseRotateAndFlip(int orientation);
 
    bool       wasExifRotated();
    bool       exifRotate(const QString& filePath);
 
    bool       reverseExifRotate(const QString& filePath);
 
    int        orientation() const;
 
    bool       transform(int transformAction);
 
    QPixmap    convertToPixmap()                              const;
    QPixmap    convertToPixmap(IccTransform& monitorICCtrans) const;
 
    QImage     pureColorMask(ExposureSettingsContainer* const expoSettings) const;
 
    void       convertDepth(int depth);
 
    void       convertToSixteenBit();
    void       convertToEightBit();
    void       convertToDepthOfImage(const DImg* const otherImage);
 
    void       fill(const DColor& color);
 
    QByteArray getUniqueHash();
    static QByteArray getUniqueHash(const QString& filePath);
 
    QByteArray getUniqueHashV2();
    static QByteArray getUniqueHashV2(const QString& filePath);
 
    QByteArray createImageUniqueId();
 
    static QString colorModelToString(COLORMODEL colorModel);
 
    static bool isAnimatedImage(const QString& filePath);
 
private:
 
    DImg(const DImg& image, uint w, uint h);
 
    void copyMetaData(const QExplicitlySharedDataPointer<Private>& src);
    void copyImageData(const QExplicitlySharedDataPointer<Private>& src);
    void setImageData(bool null, uint width, uint height, bool sixteenBit, bool alpha);
    void setImageDimension(uint width, uint height);
    size_t allocateData() const;
 
    bool clipped(int& x, int& y, int& w, int& h, uint width, uint height) const;
 
    QDateTime         creationDateFromFilesystem(const QFileInfo& fileInfo) const;
 
    static QByteArray createUniqueHash(const QString& filePath, const QByteArray& ba);
    static QByteArray createUniqueHashV2(const QString& filePath);
 
    void bitBlt(const uchar* const src, uchar* const dest,
                int sx, int sy, int w, int h, int dx, int dy,
                uint swidth, uint sheight, uint dwidth, uint dheight,
                bool sixteenBit, int sdepth, int ddepth);
    void bitBlend(DColorComposer* const composer, uchar* const src, uchar* const dest,
                  int sx, int sy, int w, int h, int dx, int dy,
                  uint swidth, uint sheight, uint dwidth, uint dheight,
                  bool sixteenBit, int sdepth, int ddepth,
                  DColorComposer::MultiplicationFlags multiplicationFlags);
    void bitBlendOnColor(DColorComposer* const composer, const DColor& color,
                         uchar* data, int x, int y, int w, int h,
                         uint width, uint height, bool sixteenBit, int depth,
                         DColorComposer::MultiplicationFlags multiplicationFlags);
    bool normalizeRegionArguments(int& sx, int& sy, int& w, int& h, int& dx, int& dy,
                                  uint swidth, uint sheight, uint dwidth, uint dheight) const;
 
private:
 
    QExplicitlySharedDataPointer<Private> m_priv;
 
    friend class DImgLoader;
};
 
} // namespace Digikam
 
Q_DECLARE_OPERATORS_FOR_FLAGS(Digikam::DImg::PrepareMetadataFlags)
 
#endif // DIGIKAM_DIMG_H