![]() |
digiKam Developer Documentation
Professional Photo Management with the Power of Open Source
|
Public Types | |
enum | ANGLE { ROT90 = 0 , ROT180 , ROT270 , ROTNONE } |
enum | COLORMODEL { COLORMODELUNKNOWN = 0 , RGB , GRAYSCALE , MONOCHROME , INDEXED , YCBCR , CMYK , CIELAB , COLORMODELRAW } |
enum | FLIP { HORIZONTAL = 0 , VERTICAL } |
enum | FORMAT { NONE = 0 , JPEG , PNG , TIFF , JP2K , PGF , HEIF , RAW , QIMAGE } |
enum | PrepareMetadataFlag { RemoveOldMetadataPreviews = 1 << 0 , CreateNewMetadataPreview = 1 << 1 , ResetExifOrientationTag = 1 << 2 , CreateNewImageHistoryUUID = 1 << 3 , PrepareMetadataFlagsAll } |
When saving, several changes to the image metadata are necessary before it can safely be written to the new file. More... | |
typedef QFlags< PrepareMetadataFlag > | PrepareMetadataFlags |
Public Member Functions | |
DImg () | |
Create null image. | |
DImg (const DImg &image) | |
Copy image: Creates a shallow copy that refers to the same shared data. | |
DImg (const QByteArray &filePath, DImgLoaderObserver *const observer=nullptr, const DRawDecoding &rawDecodingSettings=DRawDecoding()) | |
Load image using QByteArray as file path. | |
DImg (const QImage &image) | |
Copy image: Creates a copy of a QImage object. | |
DImg (const QString &filePath, DImgLoaderObserver *const observer=nullptr, const DRawDecoding &rawDecodingSettings=DRawDecoding()) | |
Load image using QString as file path. | |
DImg (uint width, uint height, bool sixteenBit, bool alpha=false, uchar *const data=nullptr, bool copyData=true) | |
Create image from data. | |
void | addAsReferredImage (const HistoryImageId &id) |
HistoryImageId | addAsReferredImage (const QString &filePath, HistoryImageId::Type type=HistoryImageId::Intermediate) |
If you have saved this DImg to filePath, and want to continue using this DImg object to add further changes to the image history, you can call this method to add to the image history a reference to the just saved image. | |
void | addCurrentUniqueImageId (const QString &uuid) |
In the history, adjusts the UUID of the ImageHistoryId of the current file. | |
void | addFilterAction (const FilterAction &action) |
QVariant | attribute (const QString &key) const |
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) |
Blend src image on this image (this is dest) with the specified composer and multiplication flags. | |
void | bitBlendImageOnColor (const DColor &color) |
void | bitBlendImageOnColor (const DColor &color, int x, int y, int w, int h) |
void | bitBlendImageOnColor (DColorComposer *const composer, const DColor &color, int x, int y, int w, int h, DColorComposer::MultiplicationFlags multiplicationFlags=DColorComposer::NoMultiplication) |
For the specified region, blend this image on the given color with the specified composer and multiplication flags. | |
void | bitBltImage (const DImg *const src, int dx, int dy) |
Copy a region of pixels from a source image to this image. | |
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) |
uchar * | bits () const |
int | bitsDepth () const |
int | bytesDepth () const |
void | convertDepth (int depth) |
Convert depth of image. | |
void | convertToDepthOfImage (const DImg *const otherImage) |
void | convertToEightBit () |
QPixmap | convertToPixmap () const |
QPixmap | convertToPixmap (IccTransform &monitorICCtrans) const |
void | convertToSixteenBit () |
Wrapper methods for convertDepth. | |
DImg | copy () const |
DImg | copy (const QRect &rect) const |
DImg | copy (const QRectF &relativeRect) const |
DImg | copy (int x, int y, int w, int h) const |
uchar * | copyBits () const |
DImg | copyImageData () const |
DImg | copyMetaData () const |
QImage | copyQImage () const |
QImage wrapper methods. | |
QImage | copyQImage (const QRect &rect) const |
QImage | copyQImage (const QRectF &relativeRect) const |
QImage | copyQImage (int x, int y, int w, int h) const |
QImage | copyQImage32 () const |
HistoryImageId | createHistoryImageId (const QString &filePath, HistoryImageId::Type type) |
Create a HistoryImageId for this image already saved at the given file path. | |
QByteArray | createImageUniqueId () |
This method creates a new 256-bit UUID meant to be globally unique. | |
void | crop (const QRect &rect) |
Crop image to the specified region. | |
void | crop (int x, int y, int w, int h) |
void | detach () |
Detaches from shared data and makes sure that this image is the only one referring to the data. | |
FORMAT | detectedFormat () const |
QString | embeddedText (const QString &key) const |
int | exifOrientation (const QString &filePath) |
Retrieves the Exif orientation, either from the LoadSaveThread info provider if available, or from the metadata. | |
bool | exifRotate (const QString &filePath) |
QVariant | fileOriginData () const |
When loaded from a file, some attributes like format and isReadOnly still depend on this originating file. | |
void | fill (const DColor &color) |
Fill whole image with specified color. | |
void | flip (FLIP direction) |
QString | format () const |
IccProfile | getIccProfile () const |
DImageHistory & | getItemHistory () |
const DImageHistory & | getItemHistory () const |
MetaEngineData | getMetadata () const |
Metadata manipulation methods. | |
DImageHistory | getOriginalImageHistory () const |
DColor | getPixelColor (uint x, uint y) const |
Access a single pixel of the image. | |
DColor | getSubPixelColor (float x, float y) const |
DColor | getSubPixelColorFast (float x, float y) const |
QByteArray | getUniqueHash () |
This methods return a 128-bit MD5 hex digest which is meant to uniquely identify the file. | |
QByteArray | getUniqueHashVersion (int version) |
Version 2: This methods return a 128-bit MD5 hex digest which is meant to uniquely identify the file. | |
bool | hasAlpha () const |
bool | hasAttribute (const QString &key) const |
bool | hasImageHistory () const |
bool | hasTransparentPixels () const |
If the image has an alpha channel, check if there exist pixels which actually have non-opaque color, that is alpha < 1.0. | |
uint | height () const |
void | imageSavedAs (const QString &savePath) |
It is common that images are not directly saved to the destination path. | |
void | insertAsReferredImage (int afterHistoryStep, const HistoryImageId &otherImagesId) |
bool | isNull () const |
bool | isReadOnly () const |
QVariant | lastSavedFileOriginData () const |
QString | lastSavedFilePath () const |
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, DImgLoaderObserver *const observer=nullptr, const DRawDecoding &rawDecodingSettings=DRawDecoding()) |
bool | load (const QString &filePath, int loadFlags, DImgLoaderObserver *const observer, const DRawDecoding &rawDecodingSettings=DRawDecoding()) |
bool | loadItemInfo (const QString &filePath, bool loadMetadata=true, bool loadICCData=true, bool loadUniqueHash=true, bool loadImageHistory=true) |
Loads most parts of the meta information, but never the image data. | |
quint64 | numBytes () const |
quint64 | numPixels () const |
DImg & | operator= (const DImg &image) |
Equivalent to the copy constructor. | |
bool | operator== (const DImg &image) const |
int | orientation () const |
int | originalBitDepth () const |
COLORMODEL | originalColorModel () const |
QString | originalFilePath () const |
QSize | originalRatioSize () const |
QSize | originalSize () const |
void | prepareMetadataToSave (const QString &intendedDestPath, const QString &destMimeType, bool resetExifOrientationTag) |
For convenience: Including all flags, except for ResetExifOrientationTag which can be selected. | |
void | prepareMetadataToSave (const QString &intendedDestPath, const QString &destMimeType, const QString &originalFileName=QString(), PrepareMetadataFlags flags=PrepareMetadataFlagsAll) |
void | prepareSubPixelAccess () |
QImage | pureColorMask (ExposureSettingsContainer *const expoSettings) const |
void | putImageData (uchar *const data, bool copyData=true) |
Overloaded function, provided for convenience, behaves essentially like the function above if data is not nullptr. | |
void | putImageData (uint width, uint height, bool sixteenBit, bool alpha, uchar *const data, bool copyData=true) |
Replaces image data of this object. | |
DRawDecoding | rawDecodingSettings () const |
void | removeAlphaChannel () |
void | removeAlphaChannel (const DColor &destColor) |
If the image has an alpha channel and transparent pixels, it will be blended on the specified color and the alpha channel will be removed. | |
void | removeAttribute (const QString &key) |
void | reset () |
Reset metadata and image data to null image. | |
void | resetMetaData () |
Reset metadata, but do not change image data. | |
void | resize (int w, int h) |
Set width and height of this image, smoothScale it to the given size. | |
bool | reverseExifRotate (const QString &filePath) |
Reverses the previous function. | |
bool | reverseRotateAndFlip (int orientation) |
Reverses the previous function. | |
void | rotate (ANGLE angle) |
bool | rotateAndFlip (int orientation) |
Rotates and/or flip the DImg according to the given DMetadata::Orientation, so that the current state is orientation and the resulting step is normal orientation. | |
bool | save (const QString &filePath, const QString &format, DImgLoaderObserver *const observer=nullptr) |
bool | save (const QString &filePath, FORMAT frm, DImgLoaderObserver *const observer=nullptr) |
QString | savedFormat () const |
uchar * | scanLine (uint i) const |
void | setAttribute (const QString &key, const QVariant &value) |
void | setEmbeddedText (const QString &key, const QString &text) |
void | setFileOriginData (const QVariant &data) |
void | setHistoryBranch (bool isBranch=true) |
void | setHistoryBranchAfter (const DImageHistory &historyBeforeBranch, bool isBranch=true) |
Sets a step in the history to constitute the beginning of a branch. | |
void | setHistoryBranchForLastSteps (int numberOfLastHistorySteps, bool isBranch=true) |
void | setIccProfile (const IccProfile &profile) |
void | setItemHistory (const DImageHistory &history) |
void | setMetadata (const MetaEngineData &data) |
void | setPixelColor (uint x, uint y, const DColor &color) |
bool | sixteenBit () const |
QSize | size () const |
DImg | smoothScale (const QSize &destSize, Qt::AspectRatioMode aspectRatioMode=Qt::IgnoreAspectRatio) const |
DImg | smoothScale (int width, int height, Qt::AspectRatioMode aspectRatioMode=Qt::IgnoreAspectRatio) const |
DImg | smoothScaleClipped (const QSize &destSize, const QRect &clip, bool smooth=true) const |
DImg | smoothScaleClipped (int width, int height, int clipx, int clipy, int clipwidth, int clipheight, bool smooth=true) const |
Executes the same scaling as smoothScale(width, height), but from the result of this call, returns only the section specified by clipx, clipy, clipwidth, clipheight. | |
DImg | smoothScaleSection (const QRect &sourceRect, const QSize &destSize) const |
DImg | smoothScaleSection (int sx, int sy, int sw, int sh, int dw, int dh) const |
Take the region specified by the rectangle sx|sy, width and height sw * sh, and scale it to an image with size dw * dh. | |
uchar * | stripImageData () |
void | switchOriginToLastSaved () |
bool | transform (int transformAction) |
Rotates and/or flip the DImg according to the given transform action, which is a MetaEngineRotation::TransformAction. | |
bool | wasExifRotated () |
Utility to make sure that an image is rotated according to Exif tag. | |
uint | width () const |
Static Public Member Functions | |
static QString | colorModelToString (COLORMODEL colorModel) |
Helper method to translate enum values to user presentable strings. | |
static FORMAT | fileFormat (const QString &filePath) |
Identify file format. | |
static QString | formatToMimeType (FORMAT frm) |
static QByteArray | getUniqueHash (const QString &filePath) |
static QByteArray | getUniqueHashVersion (const QString &filePath, int version) |
static bool | isAnimatedImage (const QString &filePath) |
Friends | |
class | DImgLoader |
This method updates the stored meta engine object in preparation to a subsequent call to save() with the same target file. 'intendedDestPath' is the finally intended file name. Do not give the temporary file name if you are going to save() to a temp file. 'destMimeType' is destination type mime. In some cases, metadata is updated depending on this value. 'originalFileName' is the original file's name, for simplistic history tracking in metadata. This is completely independent from the DImageHistory framework. For the 'flags' see below. Not all steps are optional and can be controlled with flags.
Digikam::DImg::DImg | ( | ) |
DImg is a framework to support 16bits color depth image.
it doesn't aim to be a complete imaging library; it uses QImage/ImageMagick for load/save files which are not supported natively by it. some of the features:
for 8 bits images: you can access individual color components like this:
uchar* const pixels = image.bits();
for (int i = 0 ; i < image.width() * image.height() ; ++i) { pixel[0] // blue pixel[1] // green pixel[2] // red pixel[3] // alpha
pixel += 4; // go to next pixel }
and for 16 bits images:
ushort* const pixels = (ushort*)image.bits();
for (int i = 0 ; i < image.width() * image.height() ; ++i) { pixel[0] // blue pixel[1] // green pixel[2] // red pixel[3] // alpha
pixel += 4; // go to next pixel }
The above is true for both big and little endian platforms. What this also means is that the pixel format is different from that of QImage for big endian machines. Functions are provided if you want to get a copy of the DImg as a QImage.
Digikam::DImg::DImg | ( | const DImg & | image | ) |
|
explicit |
If the QImage is null, a null DImg will be created.
Digikam::DImg::DImg | ( | uint | width, |
uint | height, | ||
bool | sixteenBit, | ||
bool | alpha = false , |
||
uchar *const | data = nullptr , |
||
bool | copyData = true |
||
) |
If data is 0, a new buffer will be allocated, otherwise the given data will be used: If copydata is true, the data will be copied to a newly allocated buffer. If copyData is false, this DImg object will take ownership of the data pointer. If there is an alpha channel, the data shall be in non-premultiplied form (unassociated alpha).
HistoryImageId Digikam::DImg::addAsReferredImage | ( | const QString & | filePath, |
HistoryImageId::Type | type = HistoryImageId::Intermediate |
||
) |
First call updateMetadata(), then call save(), then call addAsReferredImage(). Do not call this directly after loading, before applying any changes: The history is correctly initialized when loading. If you need to insert the referred file to an entry which is not the last entry, which may happen if the added image was saved after this image's history was created, you can use insertAsReferredImage. The added id is returned.
void Digikam::DImg::addCurrentUniqueImageId | ( | const QString & | uuid | ) |
Call this if you have associated a UUID with this file which is not written to the metadata. If there is already a UUID present, read from metadata, it will not be replaced.
void Digikam::DImg::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 |
||
) |
See documentation of DColorComposer for more info. For the other arguments, see documentation of bitBltImage above.
void Digikam::DImg::bitBlendImageOnColor | ( | DColorComposer *const | composer, |
const DColor & | color, | ||
int | x, | ||
int | y, | ||
int | w, | ||
int | h, | ||
DColorComposer::MultiplicationFlags | multiplicationFlags = DColorComposer::NoMultiplication |
||
) |
See documentation of DColorComposer for more info. Note that the result pixel is again written to this image, which is, for the blending, source.
void Digikam::DImg::bitBltImage | ( | const DImg *const | src, |
int | dx, | ||
int | dy | ||
) |
Parameters: sx|sy Coordinates in the source image of the rectangle to be copied w h Width and height of the rectangle (Default, or when both are -1: whole source image) dx|dy Coordinates in this image of the rectangle in which the region will be copied (Default: 0|0) The bit depth of source and destination must be identical.
int Digikam::DImg::bitsDepth | ( | ) | const |
int Digikam::DImg::bytesDepth | ( | ) | const |
void Digikam::DImg::convertDepth | ( | int | depth | ) |
Depth is bytesDepth * bitsDepth. If depth is 32, converts to 8 bits, if depth is 64, converts to 16 bits.
DImg Digikam::DImg::copy | ( | ) | const |
DImg Digikam::DImg::copy | ( | const QRect & | rect | ) | const |
DImg Digikam::DImg::copyImageData | ( | ) | const |
DImg Digikam::DImg::copyMetaData | ( | ) | const |
QByteArray Digikam::DImg::createImageUniqueId | ( | ) |
The UUID will be returned as a 64-byte hexadecimal string. At least 128bits of the UUID will be created by the platform random number generator. The rest may be created from a content-based hash similar to the uniqueHash, see above. This method only generates a new UUID for this image without in any way changing this image object or saving the UUID anywhere.
void Digikam::DImg::detach | ( | ) |
If multiple images share common data, this image makes a copy of the data and detaches itself from the sharing mechanism. Nothing is done if there is just a single reference.
DImg::FORMAT Digikam::DImg::detectedFormat | ( | ) | const |
QVariant Digikam::DImg::fileOriginData | ( | ) | const |
When saving in a different format to a different file, you may wish to switch these attributes to the new file.
For example, an image loaded from a RAW and saved to PNG will be read-only and format RAW. After calling
void Digikam::DImg::fill | ( | const DColor & | color | ) |
The bit depth of the color must be identical to the depth of this image.
QString Digikam::DImg::format | ( | ) | const |
DColor Digikam::DImg::getPixelColor | ( | uint | x, |
uint | y | ||
) | const |
QByteArray Digikam::DImg::getUniqueHash | ( | ) |
The hash is calculated on parts of the file and the file metadata. It cannot be used to find similar images. It is not calculated from the image data. The hash will be returned as a 32-byte hexadecimal string.
If you already have a DImg object of the file, use the member method. The object does not need to have the full image data loaded, but it shall at least have been loaded with loadItemInfo with loadMetadata = true, or have the metadata set later with setComments, setExif, setIptc, setXmp. If the object does not have the metadata loaded, a non-null, but invalid hash will be returned! In this case, use the static method. If the image has been loaded with loadUniqueHash = true, the hash can be retrieved with the member method.
You do not need a DImg object of the file to retrieve the unique hash; Use the static method and pass just the file path.
QByteArray Digikam::DImg::getUniqueHashVersion | ( | int | version | ) |
The hash is calculated on parts of the file. It cannot be used to find similar images. It is not calculated from the image data. The hash will be returned as a 32-byte hexadecimal string.
Version 3: This methods return a 128-bit MD5 hex digest which is meant to uniquely identify the file. It cannot be used to find similar images. The hash is calculated from 6 blocks distributed across the file, the first block has a size of 100 kB (capture metadata), all other possible 5 blocks up to 25 kB. The hash will be returned as a 32-byte hexadecimal string.
If you already have a DImg object loaded from the file, use the member method. If the image has been loaded with loadUniqueHash = true, the hash will already be available.
You do not need a DImg object of the file to retrieve the unique hash; Use the static method and pass just the file path and version.
bool Digikam::DImg::hasTransparentPixels | ( | ) | const |
Note that all pixels are scanned to reach a return value of "false". If hasAlpha() is false, always returns false.
void Digikam::DImg::imageSavedAs | ( | const QString & | savePath | ) |
For this reason, save() does not call addAsReferredImage(), and the stored save path may be wrong. Call this method after save() with the final destination path. This path will be stored in the image history as well.
|
static |
bool Digikam::DImg::isReadOnly | ( | ) | const |
QString Digikam::DImg::lastSavedFilePath | ( | ) | const |
bool Digikam::DImg::loadItemInfo | ( | const QString & | filePath, |
bool | loadMetadata = true , |
||
bool | loadICCData = true , |
||
bool | loadUniqueHash = true , |
||
bool | loadImageHistory = true |
||
) |
If loadMetadata is true, the metadata will be available with getComments, getExif, getIptc, getXmp . If loadICCData is true, the ICC profile will be available with getICCProfile.
bool Digikam::DImg::operator== | ( | const DImg & | image | ) | const |
int Digikam::DImg::orientation | ( | ) | const |
int Digikam::DImg::originalBitDepth | ( | ) | const |
DImg::COLORMODEL Digikam::DImg::originalColorModel | ( | ) | const |
QString Digikam::DImg::originalFilePath | ( | ) | const |
QSize Digikam::DImg::originalRatioSize | ( | ) | const |
QSize Digikam::DImg::originalSize | ( | ) | const |
void Digikam::DImg::prepareMetadataToSave | ( | const QString & | intendedDestPath, |
const QString & | destMimeType, | ||
bool | resetExifOrientationTag | ||
) |
Uses originalFilePath() to fill the original file name.
QImage Digikam::DImg::pureColorMask | ( | ExposureSettingsContainer *const | expoSettings | ) | const |
void Digikam::DImg::putImageData | ( | uchar *const | data, |
bool | copyData = true |
||
) |
Uses current width, height, sixteenBit, and alpha values. If data is nullptr, the current data are deleted and the image is set to null (But metadata are unchanged).
void Digikam::DImg::putImageData | ( | uint | width, |
uint | height, | ||
bool | sixteenBit, | ||
bool | alpha, | ||
uchar *const | data, | ||
bool | copyData = true |
||
) |
Metadata are unchanged. Parameters like constructor above.
DRawDecoding Digikam::DImg::rawDecodingSettings | ( | ) | const |
void Digikam::DImg::removeAlphaChannel | ( | const DColor & | destColor | ) |
This is a no-op if hasTransparentPixels() is false, but this method can be expensive, therefore it is not checked inside removeAlphaChannel(). (the trivial hasAlpha() is checked)
bool Digikam::DImg::rotateAndFlip | ( | int | orientation | ) |
QString Digikam::DImg::savedFormat | ( | ) | const |
void Digikam::DImg::setHistoryBranchAfter | ( | const DImageHistory & | historyBeforeBranch, |
bool | isBranch = true |
||
) |
Use setHistoryBranch() to take getOriginalImageHistory() and set the first added step as a branch. Use setHistoryBranchForLastSteps(n) to start the branch before the last n steps in the history. (Assume the history had 3 steps and you added 2, call setHistoryBranchForLastSteps(2)) Use setHistoryBranchAfter() if have a copy of the history before branching, the first added step on top of that history will be made a branch.
DImg Digikam::DImg::smoothScale | ( | int | width, |
int | height, | ||
Qt::AspectRatioMode | aspectRatioMode = Qt::IgnoreAspectRatio |
||
) | const |
DImg Digikam::DImg::smoothScaleClipped | ( | int | width, |
int | height, | ||
int | clipx, | ||
int | clipy, | ||
int | clipwidth, | ||
int | clipheight, | ||
bool | smooth = true |
||
) | const |
This is thus equivalent to calling Dimg scaled = smoothScale(width, height); scaled.crop(clipx, clipy, clipwidth, clipheight); but potentially much faster. In smoothScaleSection, you specify the source region, here, the result region. It will often not be possible to find integer source coordinates for a result region!
uchar * Digikam::DImg::stripImageData | ( | ) |
bool Digikam::DImg::transform | ( | int | transformAction | ) |
bool Digikam::DImg::wasExifRotated | ( | ) |
Detects if an image has previously already been rotated: You can call this method more than one time on the same image.