File indexing completed on 2025-01-19 03:53:37
0001 /* ============================================================ 0002 * 0003 * This file is a part of digiKam project 0004 * https://www.digikam.org 0005 * 0006 * Date : 2005-04-21 0007 * Description : Handling access to one item and associated data 0008 * 0009 * SPDX-FileCopyrightText: 2005 by Renchi Raju <renchi dot raju at gmail dot com> 0010 * SPDX-FileCopyrightText: 2007-2013 by Marcel Wiesweg <marcel dot wiesweg at gmx dot de> 0011 * SPDX-FileCopyrightText: 2009-2024 by Gilles Caulier <caulier dot gilles at gmail dot com> 0012 * SPDX-FileCopyrightText: 2013 by Michael G. Hansen <mike at mghansen dot de> 0013 * 0014 * SPDX-License-Identifier: GPL-2.0-or-later 0015 * 0016 * ============================================================ */ 0017 0018 #ifndef DIGIKAM_ITEM_INFO_H 0019 #define DIGIKAM_ITEM_INFO_H 0020 0021 // Qt includes 0022 0023 #include <QUrl> 0024 #include <QList> 0025 #include <QSize> 0026 #include <QString> 0027 #include <QDateTime> 0028 #include <QExplicitlySharedDataPointer> 0029 0030 // Local includes 0031 0032 #include "digikam_export.h" 0033 #include "coredbalbuminfo.h" 0034 #include "coredburl.h" 0035 #include "coredbfields.h" 0036 #include "iteminfolist.h" 0037 0038 namespace Digikam 0039 { 0040 0041 class DImageHistory; 0042 class HistoryImageId; 0043 class ItemComments; 0044 class ImageCommonContainer; 0045 class ItemCopyright; 0046 class ItemExtendedProperties; 0047 class ItemInfoData; 0048 class ItemListerRecord; 0049 class ImageMetadataContainer; 0050 class VideoMetadataContainer; 0051 class ItemPosition; 0052 class ItemTagPair; 0053 class PhotoInfoContainer; 0054 class VideoInfoContainer; 0055 class Template; 0056 class ThumbnailIdentifier; 0057 class ThumbnailInfo; 0058 0059 /** 0060 * The ItemInfo class contains provides access to the database for a single image. 0061 * The properties can be read and written. Information will be cached. 0062 * 0063 * NOTE: access rules for all methods in this class: 0064 * ItemInfoData members shall be accessed only under CoreDbAccess lock. 0065 * The id and albumId are the exception to this rule, as they are 0066 * primitive and will never change during the lifetime of an object. 0067 */ 0068 class DIGIKAM_DATABASE_EXPORT ItemInfo 0069 { 0070 public: 0071 0072 typedef DatabaseFields::Hash<QVariant> DatabaseFieldsHashRaw; 0073 0074 public: 0075 0076 /** 0077 * Constructor 0078 * Creates a null image info 0079 */ 0080 ItemInfo(); 0081 0082 /** 0083 * Constructor. Creates an ItemInfo object without any cached data initially. 0084 * @param ID the unique ID for this image 0085 */ 0086 explicit ItemInfo(qlonglong ID); 0087 0088 /** 0089 * Constructor. Creates an ItemInfo object where the provided information 0090 * will initially be available cached, without database access. 0091 */ 0092 explicit ItemInfo(const ItemListerRecord& record); 0093 0094 /** 0095 * Copy constructor. 0096 */ 0097 ItemInfo(const ItemInfo& info); 0098 0099 /** 0100 * Destructor 0101 */ 0102 ~ItemInfo(); 0103 0104 /** 0105 * Creates an ItemInfo object from a file url. 0106 */ 0107 static ItemInfo fromLocalFile(const QString& path); 0108 static ItemInfo fromUrl(const QUrl& url); 0109 0110 /** 0111 * Create an ItemInfo object from the given combination, which 0112 * must be cleaned and corresponding to the values in the database 0113 */ 0114 static ItemInfo fromLocationAlbumAndName(int locationId, const QString& album, const QString& name); 0115 0116 ItemInfo& operator=(const ItemInfo& info); 0117 0118 bool operator==(const ItemInfo& info) const; 0119 bool operator!=(const ItemInfo& info) const; 0120 bool operator<(const ItemInfo& info) const; 0121 0122 /** 0123 * Copy database information of this item to a newly created item 0124 * @param dstAlbumID destination album id 0125 * @param dstFileName new filename 0126 * @return an ItemInfo object of the new item 0127 */ 0128 ItemInfo copyItem(int dstAlbumID, const QString& dstFileName); 0129 0130 /** 0131 * Returns true if this is a valid ItemInfo, 0132 * and the location of the image is currently available 0133 * (information freshly obtained from CollectionManager) 0134 */ 0135 bool isLocationAvailable() const; 0136 0137 public: 0138 0139 // ----------------------------------------------------------------------------- 0140 0141 /** @name Operations with Properties 0142 */ 0143 0144 //@{ 0145 0146 /** 0147 * Returns if this objects contains valid data 0148 */ 0149 bool isNull() const; 0150 0151 /** 0152 * @return the name of the image 0153 */ 0154 QString name() const; 0155 0156 /** 0157 * @return the datetime of the image 0158 */ 0159 QDateTime dateTime() const; 0160 0161 /** 0162 * @return the modification datetime of the image 0163 */ 0164 QDateTime modDateTime() const; 0165 0166 /** 0167 * @return the filesize of the image 0168 */ 0169 qlonglong fileSize() const; 0170 0171 /** 0172 * @return the dimensions of the image (valid only if dimensions 0173 * have been requested) 0174 */ 0175 QSize dimensions() const; 0176 0177 /** 0178 * Returns the file:// url. 0179 * This is equivalent to QUrl::fromLocalFile(filePath()) 0180 */ 0181 QUrl fileUrl() const; 0182 0183 /** 0184 * Returns the file path to the image 0185 */ 0186 QString filePath() const; 0187 0188 /** 0189 * Returns the relative path part to the image 0190 */ 0191 QString relativePath() const; 0192 0193 /** 0194 * @return the unique image id for this item 0195 */ 0196 qlonglong id() const; 0197 0198 /** 0199 * @return the id of the PAlbum to which this item belongs 0200 */ 0201 int albumId() const; 0202 0203 /** 0204 * The album root id 0205 */ 0206 int albumRootId() const; 0207 0208 /** 0209 * @return the id of the Aspect Ratio for this item 0210 */ 0211 double aspectRatio() const; 0212 0213 /** 0214 * Returns the manual sort order 0215 */ 0216 qlonglong manualOrder() const; 0217 0218 /** 0219 * Returns the category of the item: Image, Audio, Video 0220 */ 0221 DatabaseItem::Category category() const; 0222 0223 /** 0224 * Returns the image format / mimetype as a standardized 0225 * string (see project/documents/DBSCHEMA.ODS). 0226 */ 0227 QString format() const; 0228 0229 /** 0230 * Returns true if the image is marked as visible in the database. 0231 */ 0232 bool isVisible() const; 0233 0234 /** 0235 * Returns true if the corresponding file was not deleted. 0236 */ 0237 bool isRemoved() const; 0238 0239 /** 0240 * Returns the orientation of the image, 0241 * (MetaEngine::ImageOrientation, EXIF standard) 0242 */ 0243 int orientation() const; 0244 0245 /** 0246 * @return the default title for this item 0247 */ 0248 QString title() const; 0249 0250 /** 0251 * @return the default comment for this item 0252 */ 0253 QString comment() const; 0254 0255 /** 0256 * @return the number of Faces in this item. 0257 */ 0258 int faceCount() const; 0259 0260 /** 0261 * @return the number of Unconfirmed Faces in this item. 0262 */ 0263 int unconfirmedFaceCount() const; 0264 0265 /** 0266 * @return the map of Tag Region (in XML form) to Suggested Names for all 0267 * Faces in the Image. 0268 * Used to categorize images based on Face Suggestions. 0269 */ 0270 QMap<QString, QString> getSuggestedNames() const; 0271 0272 /** 0273 * Set the name (write it to database) 0274 * @param newName the new name. 0275 */ 0276 void setName(const QString& newName); 0277 0278 /** 0279 * Set the date and time (write it to database) 0280 * @param dateTime the new date and time. 0281 */ 0282 void setDateTime(const QDateTime& dateTime); 0283 0284 /** 0285 * Set the modification date and time (write it to database) 0286 * @param dateTime the new modification date and time. 0287 */ 0288 void setModDateTime(const QDateTime& dateTime); 0289 0290 /** 0291 * Set the manual sorting order for the item 0292 */ 0293 void setManualOrder(qlonglong value); 0294 0295 /** 0296 * Set the orientation for the item 0297 */ 0298 void setOrientation(int value); 0299 0300 /** 0301 * Set the visibility flag - triggers between Visible and Hidden 0302 */ 0303 void setVisible(bool isVisible); 0304 0305 /** 0306 * @todo Supports only VideoMetadataField and ImageMetadataField values for now. 0307 */ 0308 DatabaseFieldsHashRaw getDatabaseFieldsRaw(const DatabaseFields::Set& requestedSet) const; 0309 QVariant getDatabaseFieldRaw(const DatabaseFields::Set& requestedField) const; 0310 0311 //@} 0312 0313 public: 0314 0315 // ----------------------------------------------------------------------------- 0316 0317 /** @name Operations with Geolocation 0318 */ 0319 0320 //@{ 0321 0322 /** 0323 * Retrieve the ItemPosition object for this item. 0324 */ 0325 ItemPosition imagePosition() const; 0326 0327 /** 0328 * Retrieves the coordinates and the altitude. 0329 * Returns 0 if hasCoordinates(), or hasAltitude resp, is false. 0330 */ 0331 double longitudeNumber() const; 0332 double latitudeNumber() const; 0333 double altitudeNumber() const; 0334 bool hasCoordinates() const; 0335 bool hasAltitude() const; 0336 0337 //@} 0338 0339 public: 0340 0341 // ----------------------------------------------------------------------------- 0342 0343 /** @name Operations with History 0344 */ 0345 0346 //@{ 0347 0348 /** 0349 * Retrieves and sets the image history from the database. 0350 * Note: The image history retrieved here does typically include all 0351 * steps from the original to this image, but does not reference this image 0352 * itself. 0353 */ 0354 DImageHistory imageHistory() const; 0355 void setItemHistory(const DImageHistory& history); 0356 bool hasImageHistory() const; 0357 0358 /** 0359 * Retrieves and sets this' images UUID 0360 */ 0361 QString uuid() const; 0362 void setUuid(const QString& uuid); 0363 0364 /** 0365 * Constructs a HistoryImageId with all available information for this image. 0366 */ 0367 HistoryImageId historyImageId() const; 0368 0369 /** 0370 * Retrieve information about images from which this image 0371 * is derived (ancestorImages) and images that have been derived 0372 * from this images (derivedImages). 0373 */ 0374 bool hasDerivedImages() const; 0375 bool hasAncestorImages() const; 0376 0377 QList<ItemInfo> derivedImages() const; 0378 QList<ItemInfo> ancestorImages() const; 0379 0380 /** 0381 * Returns the cloud of all directly or indirectly related images, 0382 * derived images or ancestors, in from of "a derived from b" pairs. 0383 */ 0384 QList<QPair<qlonglong, qlonglong> > relationCloud() const; 0385 0386 /** 0387 * Add a relation to the database: 0388 * This image is derived from the ancestorImage. 0389 */ 0390 void markDerivedFrom(const ItemInfo& ancestorImage); 0391 0392 //@} 0393 0394 public: 0395 0396 // ----------------------------------------------------------------------------- 0397 0398 /** @name Operations with Groups 0399 */ 0400 0401 //@{ 0402 0403 /** 0404 * The image is grouped in the group of another (leading) image. 0405 */ 0406 bool isGrouped() const; 0407 /** 0408 * The image is the leading image of a group, 0409 * there are other images grouped behind this one. 0410 */ 0411 bool hasGroupedImages() const; 0412 int numberOfGroupedImages() const; 0413 0414 /** 0415 * Returns the leading image of the group. 0416 * Returns a null image if this image is not grouped (isGrouped()) 0417 */ 0418 ItemInfo groupImage() const; 0419 qlonglong groupImageId() const; 0420 0421 /** 0422 * Returns the list of images grouped behind this image (not including this 0423 * image itself) and an empty list if there is none. 0424 */ 0425 QList<ItemInfo> groupedImages() const; 0426 0427 /** 0428 * Group this image behind the given image 0429 */ 0430 void addToGroup(const ItemInfo& info); 0431 0432 /** 0433 * This image is grouped behind another image: 0434 * Remove this image from its group 0435 */ 0436 void removeFromGroup(); 0437 0438 /** 0439 * This image hasGroupedImages(): Split up the group, 0440 * remove all groupedImages() from this image's group. 0441 */ 0442 void clearGroup(); 0443 0444 //@} 0445 0446 public: 0447 0448 // ----------------------------------------------------------------------------- 0449 0450 /** @name Operations with Containers 0451 */ 0452 0453 //@{ 0454 0455 /** 0456 * Retrieve information about the image, 0457 * in form of numbers and user presentable strings, 0458 * for certain defined fields of information (see databaseinfocontainers.h) 0459 */ 0460 ImageCommonContainer imageCommonContainer() const; 0461 ImageMetadataContainer imageMetadataContainer() const; 0462 VideoMetadataContainer videoMetadataContainer() const; 0463 PhotoInfoContainer photoInfoContainer() const; 0464 VideoInfoContainer videoInfoContainer() const; 0465 0466 /** 0467 * Retrieve metadata template information about the image. 0468 */ 0469 Template metadataTemplate() const; 0470 0471 /** 0472 * Set metadata template information (write it to database) 0473 * @param t the new template data. 0474 */ 0475 void setMetadataTemplate(const Template& t); 0476 0477 /** 0478 * Remove all template info about the image from database. 0479 */ 0480 void removeMetadataTemplate(); 0481 0482 /** 0483 * Retrieve the ItemComments object for this item. 0484 * This object allows full read and write access to all comments 0485 * and their properties. 0486 * You need to hold CoreDbAccess to ensure the validity. 0487 * For simple, cached read access see comment(). 0488 */ 0489 ItemComments imageComments(const CoreDbAccess& access) const; 0490 0491 /** 0492 * Retrieve the ItemCopyright object for this item. 0493 * This object allows full read and write access to all copyright 0494 * values. 0495 */ 0496 ItemCopyright imageCopyright() const; 0497 0498 /** 0499 * Retrieve the ItemExtendedProperties object for this item. 0500 * This object allows full read and write access to all extended properties 0501 * values. 0502 */ 0503 ItemExtendedProperties imageExtendedProperties() const; 0504 0505 //@} 0506 0507 public: 0508 0509 // ----------------------------------------------------------------------------- 0510 0511 /** @name Operations with Tags 0512 */ 0513 0514 //@{ 0515 0516 /** 0517 * Adds a tag to the item (writes it to database) 0518 * @param tagID the ID of the tag to add 0519 */ 0520 void setTag(int tagID); 0521 0522 /** 0523 * Adds tags in the list to the item. 0524 * Tags are created if they do not yet exist 0525 */ 0526 void addTagPaths(const QStringList& tagPaths); 0527 0528 /** 0529 * Remove a tag from the item (removes it from database) 0530 * @param tagID the ID of the tag to remove 0531 */ 0532 void removeTag(int tagID); 0533 0534 /** 0535 * Remove all tags from the item (removes it from database) 0536 */ 0537 void removeAllTags(); 0538 0539 /** 0540 * Retrieve an ItemTagPair object for a single tag, or for all 0541 * image/tag pairs for which properties are available 0542 * (not necessarily the assigned tags) 0543 */ 0544 ItemTagPair imageTagPair(int tagId) const; 0545 QList<ItemTagPair> availableItemTagPairs() const; 0546 0547 /** 0548 * @return a list of IDs of tags assigned to this item 0549 * @see tagNames 0550 * @see tagPaths 0551 * @see Album::id() 0552 */ 0553 QList<int> tagIds() const; 0554 0555 private: 0556 0557 void loadTagIds() const; 0558 0559 //@} 0560 0561 public: 0562 0563 // ----------------------------------------------------------------------------- 0564 0565 /** 0566 * @name Operations with Labels 0567 */ 0568 0569 //@{ 0570 0571 /** 0572 * Returns the Pick Label Id (see PickLabel values in globals.h) 0573 */ 0574 int pickLabel() const; 0575 0576 /** 0577 * Returns the Color Label Id (see ColorLabel values in globals.h) 0578 */ 0579 int colorLabel() const; 0580 0581 /** 0582 * Returns the rating 0583 */ 0584 int rating() const; 0585 0586 /** 0587 * Set the pick Label Id for the item (see PickLabel values from globals.h) 0588 */ 0589 void setPickLabel(int value); 0590 0591 /** 0592 * Set the color Label Id for the item (see ColorLabel values from globals.h) 0593 */ 0594 void setColorLabel(int value); 0595 0596 /** 0597 * Set the rating for the item 0598 */ 0599 void setRating(int value); 0600 0601 //@} 0602 0603 public: 0604 0605 // ----------------------------------------------------------------------------- 0606 0607 /** 0608 * @name Operations with Thumbnails 0609 */ 0610 0611 //@{ 0612 0613 /** 0614 * Fills a ThumbnailIdentifier / ThumbnailInfo from this ItemInfo 0615 */ 0616 ThumbnailIdentifier thumbnailIdentifier() const; 0617 ThumbnailInfo thumbnailInfo() const; 0618 static ThumbnailIdentifier thumbnailIdentifier(qlonglong id); 0619 0620 //@} 0621 0622 public: 0623 0624 // ----------------------------------------------------------------------------- 0625 0626 /** 0627 * @name Operations with Similarity 0628 */ 0629 0630 //@{ 0631 0632 double similarityTo(const qlonglong imageId) const; 0633 double currentSimilarity() const; 0634 0635 /** 0636 * Returns the id of the current fuzzy search reference image. 0637 */ 0638 qlonglong currentReferenceImage() const; 0639 0640 /** 0641 * Return a signature for the item. 0642 */ 0643 uint hash() const; 0644 0645 /** 0646 * Scans the database for items with the given signature. 0647 */ 0648 QList<ItemInfo> fromUniqueHash(const QString& uniqueHash, qlonglong fileSize); 0649 0650 /** 0651 * @return the unique hash signature as string of the image. 0652 */ 0653 QString uniqueHash() const; 0654 0655 //@} 0656 0657 private: 0658 0659 friend class ItemInfoCache; 0660 friend class ItemInfoList; 0661 0662 QExplicitlySharedDataPointer<ItemInfoData> m_data; 0663 }; 0664 0665 inline uint qHash(const ItemInfo& info) 0666 { 0667 return info.hash(); 0668 } 0669 0670 //! qDebug() stream operator. Writes property @a info to the debug output in a nicely formatted way. 0671 DIGIKAM_DATABASE_EXPORT QDebug operator<<(QDebug stream, const ItemInfo& info); 0672 0673 } // namespace Digikam 0674 0675 Q_DECLARE_TYPEINFO(Digikam::ItemInfo, Q_MOVABLE_TYPE); 0676 Q_DECLARE_METATYPE(Digikam::ItemInfo) 0677 0678 #endif // DIGIKAM_ITEM_INFO_H