KExiv2

kexiv2.h
1 /*
2  SPDX-FileCopyrightText: 2006-2015 Gilles Caulier <caulier dot gilles at gmail dot com>
3  SPDX-FileCopyrightText: 2006-2013 Marcel Wiesweg <marcel dot wiesweg at gmx dot de>
4 
5  SPDX-License-Identifier: GPL-2.0-or-later
6 */
7 
8 #ifndef KEXIV2_H
9 #define KEXIV2_H
10 
11 // Std
12 
13 #include <memory>
14 
15 // QT includes
16 
17 #include <QByteArray>
18 #include <QString>
19 #include <QDateTime>
20 #include <QMap>
21 #include <QSharedDataPointer>
22 #include <QStringList>
23 #include <QVariant>
24 #include <QRegExp>
25 #include <QUrl>
26 #include <QImage>
27 
28 // Local includes
29 
30 #include "libkexiv2_export.h"
31 #include "kexiv2data.h"
32 
33 /**
34  * @brief KExiv2Iface - Exiv2 library interface
35  *
36  * @li Exiv2: https://www.exiv2.org
37  * @li Exif : https://www.exif.org/Exif2-2.PDF
38  * @li Iptc : https://www.iptc.org/std/IIM/4.1/specification/IIMV4.1.pdf
39  * @li Xmp : https://www.adobe.com/devnet/xmp.html
40  * https://www.iptc.org/std/Iptc4xmpCore/1.0/specification/Iptc4xmpCore_1.0-spec-XMPSchema_8.pdf
41  * @li Paper: http://www.metadataworkinggroup.com/pdf/mwg_guidance.pdf
42  */
43 namespace KExiv2Iface
44 {
45 
46 /**
47  * @class KExiv2 kexiv2.h <KExiv2/KExiv2>
48  *
49  * KExiv2
50  */
51 class LIBKEXIV2_EXPORT KExiv2
52 {
53 
54 public:
55 
56  /** The image metadata writing mode, between image file metadata and XMP sidecar file, depending on the context.
57  * @sa MetadataWritingMode(), metadataWritingMode()
58  */
60  {
61  /// Write metadata to image file only.
62  WRITETOIMAGEONLY = 0,
63 
64  /// Write metadata to sidecar file only.
65  WRITETOSIDECARONLY = 1,
66 
67  /// Write metadata to image and sidecar files.
68  WRITETOSIDECARANDIMAGE = 2,
69 
70  /// Write metadata to sidecar file only for read only images such as RAW files for example.
71  WRITETOSIDECARONLY4READONLYFILES = 3
72  };
73 
74  /** The image color workspace values given by Exif metadata.
75  */
77  {
78  WORKSPACE_UNSPECIFIED = 0,
79  WORKSPACE_SRGB = 1,
80  WORKSPACE_ADOBERGB = 2,
81  WORKSPACE_UNCALIBRATED = 65535
82  };
83 
84  /** The image orientation values given by Exif metadata.
85  */
87  {
88  ORIENTATION_UNSPECIFIED = 0,
89  ORIENTATION_NORMAL = 1,
90  ORIENTATION_HFLIP = 2,
91  ORIENTATION_ROT_180 = 3,
92  ORIENTATION_VFLIP = 4,
93  ORIENTATION_ROT_90_HFLIP = 5,
94  ORIENTATION_ROT_90 = 6,
95  ORIENTATION_ROT_90_VFLIP = 7,
96  ORIENTATION_ROT_270 = 8
97  };
98 
99  /**
100  * Xmp tag types, used by setXmpTag, only first three types are used
101  */
103  {
104  NormalTag = 0,
105  ArrayBagTag = 1,
106  StructureTag = 2,
107  ArrayLangTag = 3,
108  ArraySeqTag = 4
109  };
110 
111  /** A map used to store Tags Key and Tags Value.
112  */
114 
115  /** A map used to store a list of Alternative Language values.
116  The map key is the language code following RFC3066 notation
117  (like "fr-FR" for French), and the map value the text.
118  */
120 
121  /** A map used to store Tags Key and a list of Tags properties :
122  - name,
123  - title,
124  - description.
125  */
127 
128 public:
129 
130  /** Standard constructor.
131  */
132  KExiv2();
133 
134  /** Copy constructor.
135  */
136  KExiv2(const KExiv2& metadata);
137 
138  /** Constructor to load from parsed data.
139  */
140  KExiv2(const KExiv2Data& data);
141 
142  /** Contructor to Load Metadata from image file.
143  */
144  KExiv2(const QString& filePath);
145 
146  /** Standard destructor
147  */
148  virtual ~KExiv2();
149 
150  /** Create a copy of container
151  */
152  KExiv2& operator=(const KExiv2& metadata);
153 
154 public:
155 
156  //-----------------------------------------------------------------
157  /// @name Static methods
158  //@{
159 
160  /** Return true if Exiv2 library initialization is done properly.
161  This method must be called before using libkexiv2 with multithreading.
162  It initialize several non re-entrancy code from Adobe XMP SDK
163  See B.K.O #166424 for details. Call cleanupExiv2() to clean things up later.
164  */
165  static bool initializeExiv2();
166 
167  /** Return true if Exiv2 library memory allocations are cleaned properly.
168  This method must be called after using libkexiv2 with multithreading.
169  It cleans up memory used by Adobe XMP SDK
170  See B.K.O #166424 for details.
171  */
172  static bool cleanupExiv2();
173 
174  /** Return true if library can handle Xmp metadata
175  */
176  static bool supportXmp();
177 
178  /** Return true if library can write metadata to typeMime file format.
179  */
180  static bool supportMetadataWritting(const QString& typeMime);
181 
182  /** Return a string version of Exiv2 release in format "major.minor.patch"
183  */
184  static QString Exiv2Version();
185 
186  /** Return a string version of libkexiv2 release
187  */
188  static QString version();
189 
190  /** Return the XMP Sidecar file path for a image file path.
191  * If image file path do not include a file name or is empty, this function return a null string.
192  */
193  static QString sidecarFilePathForFile(const QString& path);
194 
195  /** Like sidecarFilePathForFile(), but works for local file path.
196  */
197  static QString sidecarPath(const QString& path);
198 
199  /** Like sidecarFilePathForFile(), but works for remote URLs.
200  */
201  static QUrl sidecarUrl(const QUrl& url);
202 
203  /** Gives a file url for a local path.
204  */
205  static QUrl sidecarUrl(const QString& path);
206 
207  /** Performs a QFileInfo based check if the given local file has a sidecar.
208  */
209  static bool hasSidecar(const QString& path);
210 
211  //@}
212 
213  //-----------------------------------------------------------------
214  /// @name General methods
215  //@{
216 
217  KExiv2Data data() const;
218  void setData(const KExiv2Data& data);
219 
220  /** Load all metadata (Exif, Iptc, Xmp, and JFIF Comments) from a byte array.
221  Return true if metadata have been loaded successfully from image data.
222  */
223  bool loadFromData(const QByteArray& imgData) const;
224 
225  /** Load all metadata (Exif, Iptc, Xmp, and JFIF Comments) from a picture (JPEG, RAW, TIFF, PNG,
226  DNG, etc...). Return true if metadata have been loaded successfully from file.
227  */
228  virtual bool load(const QString& filePath) const;
229 
230  /** Save all metadata to a file. This one can be different than original picture to perform
231  transfert operation Return true if metadata have been saved into file.
232  */
233  bool save(const QString& filePath) const;
234 
235  /** The same than save() method, but it apply on current image. Return true if metadata
236  have been saved into file.
237  */
238  bool applyChanges() const;
239 
240  /** Return 'true' if metadata container in memory as no Comments, Exif, Iptc, and Xmp.
241  */
242  bool isEmpty() const;
243 
244  /** Set the file path of current image.
245  */
246  void setFilePath(const QString& path);
247 
248  /** Return the file path of current image.
249  */
250  QString getFilePath() const;
251 
252  /** Returns the pixel size of the current image. This information is read from the file,
253  * not from the metadata. The returned QSize is valid if the KExiv2 object was _constructed_
254  * by reading a file or image data; the information is not available when the object
255  * was created from KExiv2Data.
256  * Note that in the Exif or XMP metadata, there may be fields describing the image size.
257  * These fields are not accessed by this method.
258  * When replacing the metadata with setData(), the metadata may change; this information
259  * always keeps referring to the file it was initially read from.
260  */
261  QSize getPixelSize() const;
262 
263  /** Returns the mime type of this image. The information is read from the file;
264  * see the docs for getPixelSize() to know when it is available.
265  */
266  QString getMimeType() const;
267 
268  /** Enable or disable writing metadata operations to RAW tiff based files.
269  It requires Exiv2 0.18. By default RAW files are untouched.
270  */
271  void setWriteRawFiles(const bool on);
272 
273  /** Return true if writing metadata operations on RAW tiff based files is enabled.
274  It's require Exiv2 0.18.
275  */
276  bool writeRawFiles() const;
277 
278  /** Enable or disable using XMP sidecar for reading metadata
279  */
280  void setUseXMPSidecar4Reading(const bool on);
281 
282  /** Return true if using XMP sidecar for reading metadata is enabled.
283  */
284  bool useXMPSidecar4Reading() const;
285 
286  /** Set metadata writing mode.
287  * @param mode Metadata writing mode as defined by the #MetadataWritingMode enum.
288  * @sa MetadataWritingMode, metadataWritingMode()
289  */
290  void setMetadataWritingMode(const int mode);
291 
292  /** Return the metadata writing mode.
293  * @returns Metadata writing mode as defined by the #MetadataWritingMode enum.
294  * @sa MetadataWritingMode, setMetadataWritingMode()
295  */
296  int metadataWritingMode() const;
297 
298  /** Enable or disable file timestamp updating when metadata are saved.
299  By default files timestamp are untouched.
300  */
301  void setUpdateFileTimeStamp(bool on);
302 
303  /** Return true if file timestamp is updated when metadata are saved.
304  */
305  bool updateFileTimeStamp() const;
306 
307  //@}
308 
309  //-------------------------------------------------------------------
310  /// @name Metadata image information manipulation methods
311  //@{
312 
313  /** Set Program name and program version in Exif and Iptc Metadata. Return true if information
314  have been changed in metadata.
315  */
316  bool setImageProgramId(const QString& program, const QString& version) const;
317 
318  /** Return the size of image in pixels using Exif tags. Return a null dimmension if size cannot
319  be found.
320  */
321  QSize getImageDimensions() const;
322 
323  /** Set the size of image in pixels in Exif tags. Return true if size have been changed
324  in metadata.
325  */
326  bool setImageDimensions(const QSize& size, bool setProgramName=true) const;
327 
328  /** Return the image orientation set in Exif metadata. The makernotes of image are also parsed to
329  get this information. See ImageOrientation values for details.
330  */
331  KExiv2::ImageOrientation getImageOrientation() const;
332 
333  /** Set the Exif orientation tag of image. See ImageOrientation values for details
334  Return true if orientation have been changed in metadata.
335  */
336  bool setImageOrientation(ImageOrientation orientation, bool setProgramName=true) const;
337 
338  /** Return the image color-space set in Exif metadata. The makernotes of image are also parsed to
339  get this information. See ImageColorWorkSpace values for details.
340  */
341  KExiv2::ImageColorWorkSpace getImageColorWorkSpace() const;
342 
343  /** Set the Exif color-space tag of image. See ImageColorWorkSpace values for details
344  Return true if work-space have been changed in metadata.
345  */
346  bool setImageColorWorkSpace(ImageColorWorkSpace workspace, bool setProgramName=true) const;
347 
348  /** Return the time stamp of image. Exif information are check in first, IPTC in second
349  if image don't have Exif information. If no time stamp is found, a null date is returned.
350  */
351  QDateTime getImageDateTime() const;
352 
353  /** Set the Exif and Iptc time stamp. If 'setDateTimeDigitized' parameter is true, the 'Digitalized'
354  time stamp is set, else only 'Created' time stamp is set.
355  */
356  bool setImageDateTime(const QDateTime& dateTime, bool setDateTimeDigitized=false,
357  bool setProgramName=true) const;
358 
359  /** Return the digitization time stamp of the image. First Exif information is checked, then IPTC.
360  If no digitization time stamp is found, getImageDateTime() is called if fallbackToCreationTime
361  is true, or a null QDateTime is returned if fallbackToCreationTime is false.
362  */
363  QDateTime getDigitizationDateTime(bool fallbackToCreationTime=false) const;
364 
365  /** Return a QImage copy of Iptc preview image. Return a null image if preview cannot
366  be found.
367  */
368  bool getImagePreview(QImage& preview) const;
369 
370  /** Set the Iptc preview image. The thumbnail image must have the right size before (64Kb max
371  with JPEG file, else 256Kb). Look Iptc specification for details. Return true if preview
372  have been changed in metadata.
373  Re-implemente this method if you want to use another image file format than JPEG to
374  save preview.
375  */
376  virtual bool setImagePreview(const QImage& preview, bool setProgramName=true) const;
377 
378  //@}
379 
380  //-----------------------------------------------------------------
381  /// @name Comments manipulation methods
382  //@{
383 
384  /** Return 'true' if Comments can be written in file.
385  */
386  static bool canWriteComment(const QString& filePath);
387 
388  /** Return 'true' if metadata container in memory as Comments.
389  */
390  bool hasComments() const;
391 
392  /** Clear the Comments metadata container in memory.
393  */
394  bool clearComments() const;
395 
396  /** Return a Qt byte array copy of Comments container get from current image.
397  Comments are JFIF section of JPEG images. Look Exiv2 API for more information.
398  Return a null Qt byte array if there is no Comments metadata in memory.
399  */
400  QByteArray getComments() const;
401 
402  /** Return a Qt string object of Comments from current image decoded using
403  the 'detectEncodingAndDecode()' method. Return a null string if there is no
404  Comments metadata available.
405  */
406  QString getCommentsDecoded() const;
407 
408  /** Set the Comments data using a Qt byte array. Return true if Comments metadata
409  have been changed in memory.
410  */
411  bool setComments(const QByteArray& data) const;
412 
413  /** Language Alternative autodetection. Return a QString without language alternative
414  header. Header is saved into 'lang'. If no language alternative is founf, value is returned
415  as well and 'lang' is set to a null string.
416  */
417  static QString detectLanguageAlt(const QString& value, QString& lang);
418 
419  //@}
420 
421  //-----------------------------------------------------------------
422  /// @name Exif manipulation methods
423  //@{
424 
425  /** Return a map of all standard Exif tags supported by Exiv2.
426  */
427  TagsMap getStdExifTagsList() const;
428 
429  /** Return a map of all non-standard Exif tags (makernotes) supported by Exiv2.
430  */
431  TagsMap getMakernoteTagsList() const;
432 
433  /** Return 'true' if Exif can be written in file.
434  */
435  static bool canWriteExif(const QString& filePath);
436 
437  /** Return 'true' if metadata container in memory as Exif.
438  */
439  bool hasExif() const;
440 
441  /** Clear the Exif metadata container in memory.
442  */
443  bool clearExif() const;
444 
445  /** Returns the exif data encoded to a QByteArray in a form suitable
446  for storage in a JPEG image.
447  Note that this encoding is a lossy operation.
448 
449  Set true 'addExifHeader' parameter to add an Exif header to Exif metadata.
450  Returns a null Qt byte array if there is no Exif metadata in memory.
451  */
452  QByteArray getExifEncoded(bool addExifHeader=false) const;
453 
454  /** Set the Exif data using a Qt byte array. Return true if Exif metadata
455  have been changed in memory.
456  */
457  bool setExif(const QByteArray& data) const;
458 
459  /** Return a QImage copy of Exif thumbnail image. Return a null image if thumbnail cannot
460  be found. The 'fixOrientation' parameter will rotate automatically the thumbnail if Exif
461  orientation tags information are attached with thumbnail.
462  */
463  QImage getExifThumbnail(bool fixOrientation) const;
464 
465  /** Fix orientation of a QImage image accordingly with Exif orientation tag.
466  Return true if image is rotated, else false.
467  */
468  bool rotateExifQImage(QImage& image, ImageOrientation orientation) const;
469 
470  /** Set the Exif Thumbnail image. The thumbnail image must have the right dimensions before.
471  Look Exif specification for details. Return true if thumbnail have been changed in metadata.
472  */
473  bool setExifThumbnail(const QImage& thumb, bool setProgramName=true) const;
474 
475  /** Remove the Exif Thumbnail from the image */
476  bool removeExifThumbnail() const;
477 
478  /** Adds a JPEG thumbnail to a TIFF images. Use this instead of setExifThumbnail for TIFF images. */
479  bool setTiffThumbnail(const QImage& thumb, bool setProgramName=true) const;
480 
481  /** Return a QString copy of Exif user comments. Return a null string if user comments cannot
482  be found.
483  */
484  QString getExifComment() const;
485 
486  /** Set the Exif user comments from image. Look Exif specification for more details about this tag.
487  Return true if Exif user comments have been changed in metadata.
488  */
489  bool setExifComment(const QString& comment, bool setProgramName=true) const;
490 
491  /** Get an Exif tags content like a string. If 'escapeCR' parameter is true, the CR characters
492  will be removed. If Exif tag cannot be found a null string is returned.
493  */
494  QString getExifTagString(const char* exifTagName, bool escapeCR=true) const;
495 
496  /** Set an Exif tag content using a string. Return true if tag is set successfully.
497  */
498  bool setExifTagString(const char* exifTagName, const QString& value, bool setProgramName=true) const;
499 
500  /** Get an Exif tag content like a long value. Return true if Exif tag be found.
501  */
502  bool getExifTagLong(const char* exifTagName, long &val) const;
503 
504  /** Get an Exif tag content like a long value. Return true if Exif tag be found.
505  */
506  bool getExifTagLong(const char* exifTagName, long &val, int component) const;
507 
508  /** Set an Exif tag content using a long value. Return true if tag is set successfully.
509  */
510  bool setExifTagLong(const char* exifTagName, long val, bool setProgramName=true) const;
511 
512  /** Get the 'component' index of an Exif tags content like a rational value.
513  'num' and 'den' are the numerator and the denominator of the rational value.
514  Return true if Exif tag be found.
515  */
516  bool getExifTagRational(const char* exifTagName, long int& num, long int& den, int component=0) const;
517 
518  /** Set an Exif tag content using a rational value.
519  'num' and 'den' are the numerator and the denominator of the rational value.
520  Return true if tag is set successfully.
521  */
522  bool setExifTagRational(const char* exifTagName, long int num, long int den, bool setProgramName=true) const;
523 
524  /** Get an Exif tag content like a bytes array. Return an empty bytes array if Exif
525  tag cannot be found.
526  */
527  QByteArray getExifTagData(const char* exifTagName) const;
528 
529  /** Set an Exif tag content using a bytes array. Return true if tag is set successfully.
530  */
531  bool setExifTagData(const char* exifTagName, const QByteArray& data, bool setProgramName=true) const;
532 
533  /** Get an Exif tags content as a QVariant. Returns a null QVariant if the Exif
534  tag cannot be found.
535  For string and integer values the matching QVariant types will be used,
536  for date and time values QVariant::DateTime.
537  Rationals will be returned as QVariant::List with two integer QVariants (numerator, denominator)
538  if rationalAsListOfInts is true, as double if rationalAsListOfInts is false.
539  An exif tag of numerical type may contain more than one value; set component to the desired index.
540  */
541  QVariant getExifTagVariant(const char* exifTagName, bool rationalAsListOfInts=true, bool escapeCR=true, int component=0) const;
542 
543  /** Set an Exif tag content using a QVariant. Returns true if tag is set successfully.
544  All types described for the getExifTagVariant() method are supported.
545  Calling with a QVariant of type ByteArray is equivalent to calling setExifTagData.
546  For the meaning of rationalWantSmallDenominator, see the documentation of the convertToRational methods.
547  Setting a value with multiple components is currently not supported.
548  */
549  bool setExifTagVariant(const char* exifTagName, const QVariant& data,
550  bool rationalWantSmallDenominator=true, bool setProgramName=true) const;
551 
552  /** Remove the Exif tag 'exifTagName' from Exif metadata. Return true if tag is
553  removed successfully or if no tag was present.
554  */
555  bool removeExifTag(const char* exifTagName, bool setProgramName=true) const;
556 
557  /** Return the Exif Tag title or a null string.
558  */
559  QString getExifTagTitle(const char* exifTagName);
560 
561  /** Return the Exif Tag description or a null string.
562  */
563  QString getExifTagDescription(const char* exifTagName);
564 
565  /** Takes a QVariant value as it could have been retrieved by getExifTagVariant with the given exifTagName,
566  and returns its value properly converted to a string (including translations from Exiv2).
567  This is equivalent to calling getExifTagString directly.
568  If escapeCR is true CR characters will be removed from the result.
569  */
570  QString createExifUserStringFromValue(const char* exifTagName, const QVariant& val, bool escapeCR=true);
571 
572  /** Return a map of Exif tags name/value found in metadata sorted by
573  Exif keys given by 'exifKeysFilter'.
574 
575  'exifKeysFilter' is a QStringList of Exif keys.
576  For example, if you use the string list given below:
577 
578  "Iop"
579  "Thumbnail"
580  "Image"
581  "Photo"
582 
583  List can be empty to not filter output.
584 
585  ... this method will return a map of all Exif tags witch :
586 
587  - include "Iop", or "Thumbnail", or "Image", or "Photo" in the Exif tag keys
588  if 'inverSelection' is false.
589  - not include "Iop", or "Thumbnail", or "Image", or "Photo" in the Exif tag keys
590  if 'inverSelection' is true.
591  */
592  KExiv2::MetaDataMap getExifTagsDataList(const QStringList& exifKeysFilter=QStringList(), bool invertSelection=false) const;
593 
594  //@}
595 
596  //-------------------------------------------------------------
597  /// @name IPTC manipulation methods
598  //@{
599 
600  /** Return a map of all standard Iptc tags supported by Exiv2.
601  */
602  KExiv2::TagsMap getIptcTagsList() const;
603 
604  /** Return 'true' if Iptc can be written in file.
605  */
606  static bool canWriteIptc(const QString& filePath);
607 
608  /** Return 'true' if metadata container in memory as Iptc.
609  */
610  bool hasIptc() const;
611 
612  /** Clear the Iptc metadata container in memory.
613  */
614  bool clearIptc() const;
615 
616  /** Return a Qt byte array copy of Iptc container get from current image.
617  Set true 'addIrbHeader' parameter to add an Irb header to Iptc metadata.
618  Return a null Qt byte array if there is no Iptc metadata in memory.
619  */
620  QByteArray getIptc(bool addIrbHeader=false) const;
621 
622  /** Set the Iptc data using a Qt byte array. Return true if Iptc metadata
623  have been changed in memory.
624  */
625  bool setIptc(const QByteArray& data) const;
626 
627  /** Get an Iptc tag content like a string. If 'escapeCR' parameter is true, the CR characters
628  will be removed. If Iptc tag cannot be found a null string is returned.
629  */
630  QString getIptcTagString(const char* iptcTagName, bool escapeCR=true) const;
631 
632  /** Set an Iptc tag content using a string. Return true if tag is set successfully.
633  */
634  bool setIptcTagString(const char* iptcTagName, const QString& value, bool setProgramName=true) const;
635 
636  /** Returns a strings list with of multiple Iptc tags from the image. Return an empty list if no tag is found. */
637  /** Get the values of all IPTC tags with the given tag name in a string list.
638  (In Iptc, there can be multiple tags with the same name)
639  If the 'escapeCR' parameter is true, the CR characters
640  will be removed.
641  If no tag can be found an empty list is returned.
642  */
643  QStringList getIptcTagsStringList(const char* iptcTagName, bool escapeCR=true) const;
644 
645  /** Set multiple Iptc tags contents using a strings list. 'maxSize' is the max characters size
646  of one entry. Return true if all tags have been set successfully.
647  */
648  bool setIptcTagsStringList(const char* iptcTagName, int maxSize,
649  const QStringList& oldValues, const QStringList& newValues,
650  bool setProgramName=true) const;
651 
652  /** Get an Iptc tag content as a bytes array. Return an empty bytes array if Iptc
653  tag cannot be found.
654  */
655  QByteArray getIptcTagData(const char* iptcTagName) const;
656 
657  /** Set an Iptc tag content using a bytes array. Return true if tag is set successfully.
658  */
659  bool setIptcTagData(const char* iptcTagName, const QByteArray& data, bool setProgramName=true) const;
660 
661  /** Remove the all instance of Iptc tags 'iptcTagName' from Iptc metadata. Return true if all
662  tags have been removed successfully (or none were present).
663  */
664  bool removeIptcTag(const char* iptcTagName, bool setProgramName=true) const;
665 
666  /** Return the Iptc Tag title or a null string.
667  */
668  QString getIptcTagTitle(const char* iptcTagName);
669 
670  /** Return the Iptc Tag description or a null string.
671  */
672  QString getIptcTagDescription(const char* iptcTagName);
673 
674  /** Return a map of Iptc tags name/value found in metadata sorted by
675  Iptc keys given by 'iptcKeysFilter'.
676 
677  'iptcKeysFilter' is a QStringList of Iptc keys.
678  For example, if you use the string list given below:
679 
680  "Envelope"
681  "Application2"
682 
683  List can be empty to not filter output.
684 
685  ... this method will return a map of all Iptc tags witch :
686 
687  - include "Envelope", or "Application2" in the Iptc tag keys
688  if 'inverSelection' is false.
689  - not include "Envelope", or "Application2" in the Iptc tag keys
690  if 'inverSelection' is true.
691  */
692  KExiv2::MetaDataMap getIptcTagsDataList(const QStringList& iptcKeysFilter=QStringList(), bool invertSelection=false) const;
693 
694  /** Return a strings list of Iptc keywords from image. Return an empty list if no keyword are set.
695  */
696  QStringList getIptcKeywords() const;
697 
698  /** Set Iptc keywords using a list of strings defined by 'newKeywords' parameter. Use 'getImageKeywords()'
699  method to set 'oldKeywords' parameter with existing keywords from image. The method will compare
700  all new keywords with all old keywords to prevent duplicate entries in image. Return true if keywords
701  have been changed in metadata.
702  */
703  bool setIptcKeywords(const QStringList& oldKeywords, const QStringList& newKeywords,
704  bool setProgramName=true) const;
705 
706  /** Return a strings list of Iptc subjects from image. Return an empty list if no subject are set.
707  */
708  QStringList getIptcSubjects() const;
709 
710  /** Set Iptc subjects using a list of strings defined by 'newSubjects' parameter. Use 'getImageSubjects()'
711  method to set 'oldSubjects' parameter with existing subjects from image. The method will compare
712  all new subjects with all old subjects to prevent duplicate entries in image. Return true if subjects
713  have been changed in metadata.
714  */
715  bool setIptcSubjects(const QStringList& oldSubjects, const QStringList& newSubjects,
716  bool setProgramName=true) const;
717 
718  /** Return a strings list of Iptc sub-categories from image. Return an empty list if no sub-category
719  are set.
720  */
721  QStringList getIptcSubCategories() const;
722 
723  /** Set Iptc sub-categories using a list of strings defined by 'newSubCategories' parameter. Use
724  'getImageSubCategories()' method to set 'oldSubCategories' parameter with existing sub-categories
725  from image. The method will compare all new sub-categories with all old sub-categories to prevent
726  duplicate entries in image. Return true if sub-categories have been changed in metadata.
727  */
728  bool setIptcSubCategories(const QStringList& oldSubCategories, const QStringList& newSubCategories,
729  bool setProgramName=true) const;
730 
731  //@}
732 
733  //------------------------------------------------------------
734  /// @name XMP manipulation methods
735  //@{
736 
737  /** Return a map of all standard Xmp tags supported by Exiv2.
738  */
739  KExiv2::TagsMap getXmpTagsList() const;
740 
741  /** Return 'true' if Xmp can be written in file.
742  */
743  static bool canWriteXmp(const QString& filePath);
744 
745  /** Return 'true' if metadata container in memory as Xmp.
746  */
747  bool hasXmp() const;
748 
749  /** Clear the Xmp metadata container in memory.
750  */
751  bool clearXmp() const;
752 
753  /** Return a Qt byte array copy of XMp container get from current image.
754  Return a null Qt byte array if there is no Xmp metadata in memory.
755  */
756  QByteArray getXmp() const;
757 
758  /** Set the Xmp data using a Qt byte array. Return true if Xmp metadata
759  have been changed in memory.
760  */
761  bool setXmp(const QByteArray& data) const;
762 
763  /** Get a Xmp tag content like a string. If 'escapeCR' parameter is true, the CR characters
764  will be removed. If Xmp tag cannot be found a null string is returned.
765  */
766  QString getXmpTagString(const char* xmpTagName, bool escapeCR=true) const;
767 
768  /** Set a Xmp tag content using a string. Return true if tag is set successfully.
769  */
770  bool setXmpTagString(const char* xmpTagName, const QString& value,
771  bool setProgramName=true) const;
772 
773  /** Set a Xmp tag with a specific type. Return true if tag is set successfully.
774  * This method only accept NormalTag, ArrayBagTag and StructureTag.
775  * Other XmpTagTypes do nothing
776  */
777  bool setXmpTagString(const char* xmpTagName, const QString& value,
778  XmpTagType type,bool setProgramName=true) const;
779 
780  /** Return the Xmp Tag title or a null string.
781  */
782  QString getXmpTagTitle(const char* xmpTagName);
783 
784  /** Return the Xmp Tag description or a null string.
785  */
786  QString getXmpTagDescription(const char* xmpTagName);
787 
788  /** Return a map of Xmp tags name/value found in metadata sorted by
789  Xmp keys given by 'xmpKeysFilter'.
790 
791  'xmpKeysFilter' is a QStringList of Xmp keys.
792  For example, if you use the string list given below:
793 
794  "dc" // Dubling Core schema.
795  "xmp" // Standard Xmp schema.
796 
797  List can be empty to not filter output.
798 
799  ... this method will return a map of all Xmp tags witch :
800 
801  - include "dc", or "xmp" in the Xmp tag keys
802  if 'inverSelection' is false.
803  - not include "dc", or "xmp" in the Xmp tag keys
804  if 'inverSelection' is true.
805  */
806  KExiv2::MetaDataMap getXmpTagsDataList(const QStringList& xmpKeysFilter=QStringList(), bool invertSelection=false) const;
807 
808  /** Get all redondant Alternative Language Xmp tags content like a map.
809  See AltLangMap class description for details.
810  If 'escapeCR' parameter is true, the CR characters will be removed from strings.
811  If Xmp tag cannot be found a null string list is returned.
812  */
813  KExiv2::AltLangMap getXmpTagStringListLangAlt(const char* xmpTagName, bool escapeCR=true) const;
814 
815  /** Set an Alternative Language Xmp tag content using a map. See AltLangMap class
816  description for details. If tag already exist, it wil be removed before.
817  Return true if tag is set successfully.
818  */
819  bool setXmpTagStringListLangAlt(const char* xmpTagName, const KExiv2::AltLangMap& values,
820  bool setProgramName) const;
821 
822  /** Get a Xmp tag content like a string set with an alternative language
823  header 'langAlt' (like "fr-FR" for French - RFC3066 notation)
824  If 'escapeCR' parameter is true, the CR characters will be removed.
825  If Xmp tag cannot be found a null string is returned.
826  */
827  QString getXmpTagStringLangAlt(const char* xmpTagName, const QString& langAlt, bool escapeCR) const;
828 
829  /** Set a Xmp tag content using a string with an alternative language header. 'langAlt' contain the
830  language alternative information (like "fr-FR" for French - RFC3066 notation) or is null to
831  set alternative language to default settings ("x-default").
832  Return true if tag is set successfully.
833  */
834  bool setXmpTagStringLangAlt(const char* xmpTagName, const QString& value,
835  const QString& langAlt, bool setProgramName=true) const;
836 
837  /** Get a Xmp tag content like a sequence of strings. If 'escapeCR' parameter is true, the CR characters
838  will be removed from strings. If Xmp tag cannot be found a null string list is returned.
839  */
840  QStringList getXmpTagStringSeq(const char* xmpTagName, bool escapeCR=true) const;
841 
842  /** Set a Xmp tag content using the sequence of strings 'seq'.
843  Return true if tag is set successfully.
844  */
845  bool setXmpTagStringSeq(const char* xmpTagName, const QStringList& seq,
846  bool setProgramName=true) const;
847 
848  /** Get a Xmp tag content like a bag of strings. If 'escapeCR' parameter is true, the CR characters
849  will be removed from strings. If Xmp tag cannot be found a null string list is returned.
850  */
851  QStringList getXmpTagStringBag(const char* xmpTagName, bool escapeCR) const;
852 
853  /** Set a Xmp tag content using the bag of strings 'bag'.
854  Return true if tag is set successfully.
855  */
856  bool setXmpTagStringBag(const char* xmpTagName, const QStringList& bag,
857  bool setProgramName=true) const;
858 
859  /** Set an Xmp tag content using a list of strings defined by the 'entriesToAdd' parameter.
860  The existing entries are preserved. The method will compare
861  all new with all already existing entries to prevent duplicates in the image.
862  Return true if the entries have been added to metadata.
863  */
864  bool addToXmpTagStringBag(const char* xmpTagName, const QStringList& entriesToAdd,
865  bool setProgramName) const;
866 
867  /** Remove those Xmp tag entries that are listed in entriesToRemove from the entries in metadata.
868  Return true if tag entries are no longer contained in metadata.
869  All other entries are preserved.
870  */
871  bool removeFromXmpTagStringBag(const char* xmpTagName, const QStringList& entriesToRemove,
872  bool setProgramName) const;
873 
874  /** Get an Xmp tag content as a QVariant. Returns a null QVariant if the Xmp
875  tag cannot be found.
876  For string and integer values the matching QVariant types will be used,
877  for date and time values QVariant::DateTime.
878  Rationals will be returned as QVariant::List with two integer QVariants (numerator, denominator)
879  if rationalAsListOfInts is true, as double if rationalAsListOfInts is false.
880  Arrays (ordered, unordered, alternative) are returned as type StringList.
881  LangAlt values will have type Map (QMap<QString, QVariant>) with the language
882  code as key and the contents as value, of type String.
883  */
884  QVariant getXmpTagVariant(const char* xmpTagName, bool rationalAsListOfInts=true, bool stringEscapeCR=true) const;
885 
886  /** Return a strings list of Xmp keywords from image. Return an empty list if no keyword are set.
887  */
888  QStringList getXmpKeywords() const;
889 
890  /** Set Xmp keywords using a list of strings defined by 'newKeywords' parameter.
891  The existing keywords from image are preserved. The method will compare
892  all new keywords with all already existing keywords to prevent duplicate entries in image.
893  Return true if keywords have been changed in metadata.
894  */
895  bool setXmpKeywords(const QStringList& newKeywords, bool setProgramName=true) const;
896 
897  /** Remove those Xmp keywords that are listed in keywordsToRemove from the keywords in metadata.
898  Return true if keywords are no longer contained in metadata.
899  */
900  bool removeXmpKeywords(const QStringList& keywordsToRemove, bool setProgramName=true);
901 
902  /** Return a strings list of Xmp subjects from image. Return an empty list if no subject are set.
903  */
904  QStringList getXmpSubjects() const;
905 
906  /** Set Xmp subjects using a list of strings defined by 'newSubjects' parameter.
907  The existing subjects from image are preserved. The method will compare
908  all new subject with all already existing subject to prevent duplicate entries in image.
909  Return true if subjects have been changed in metadata.
910  */
911  bool setXmpSubjects(const QStringList& newSubjects, bool setProgramName=true) const;
912 
913  /** Remove those Xmp subjects that are listed in subjectsToRemove from the subjects in metadata.
914  Return true if subjects are no longer contained in metadata.
915  */
916  bool removeXmpSubjects(const QStringList& subjectsToRemove, bool setProgramName=true);
917 
918  /** Return a strings list of Xmp sub-categories from image. Return an empty list if no sub-category
919  are set.
920  */
921  QStringList getXmpSubCategories() const;
922 
923  /** Set Xmp sub-categories using a list of strings defined by 'newSubCategories' parameter.
924  The existing sub-categories from image are preserved. The method will compare
925  all new sub-categories with all already existing sub-categories to prevent duplicate entries in image.
926  Return true if sub-categories have been changed in metadata.
927  */
928  bool setXmpSubCategories(const QStringList& newSubCategories, bool setProgramName=true) const;
929 
930  /** Remove those Xmp sub-categories that are listed in categoriesToRemove from the sub-categories in metadata.
931  Return true if subjects are no longer contained in metadata.
932  */
933  bool removeXmpSubCategories(const QStringList& categoriesToRemove, bool setProgramName=true);
934 
935  /** Remove the Xmp tag 'xmpTagName' from Xmp metadata. Return true if tag is
936  removed successfully or if no tag was present.
937  */
938  bool removeXmpTag(const char* xmpTagName, bool setProgramName=true) const;
939 
940 
941  /** Register a namespace which Exiv2 doesn't know yet. This is only needed
942  when new Xmp properties are added manually. 'uri' is the namespace url and prefix the
943  string used to construct new Xmp key.
944  NOTE: If the Xmp metadata is read from an image, namespaces are decoded and registered
945  by Exiv2 at the same time.
946  */
947  static bool registerXmpNameSpace(const QString& uri, const QString& prefix);
948 
949  /** Unregister a previously registered custom namespace */
950  static bool unregisterXmpNameSpace(const QString& uri);
951 
952  //@}
953 
954  //------------------------------------------------------------
955  /// @name GPS manipulation methods
956  //@{
957 
958  /** Make sure all static required GPS EXIF and XMP tags exist
959  */
960  bool initializeGPSInfo(const bool setProgramName);
961 
962  /** Get all GPS location information set in image. Return true if all information can be found.
963  */
964  bool getGPSInfo(double& altitude, double& latitude, double& longitude) const;
965 
966  /** Get GPS location information set in the image, in the GPSCoordinate format
967  as described in the XMP specification. Returns a null string in the information cannot be found.
968  */
969  QString getGPSLatitudeString() const;
970  QString getGPSLongitudeString() const;
971 
972  /** Get GPS location information set in the image, as a double floating point number as in degrees
973  where the sign determines the direction ref (North + / South - ; East + / West -).
974  Returns true if the information is available.
975  */
976  bool getGPSLatitudeNumber(double* const latitude) const;
977  bool getGPSLongitudeNumber(double* const longitude) const;
978 
979  /** Get GPS altitude information, in meters, relative to sea level (positive sign above sea level)
980  */
981  bool getGPSAltitude(double* const altitude) const;
982 
983  /** Set all GPS location information into image. Return true if all information have been
984  changed in metadata.
985  */
986  bool setGPSInfo(const double altitude, const double latitude, const double longitude, const bool setProgramName=true);
987 
988  /** Set all GPS location information into image. Return true if all information have been
989  changed in metadata. If you do not want altitude to be set, pass a null pointer.
990  */
991  bool setGPSInfo(const double* const altitude, const double latitude, const double longitude, const bool setProgramName=true);
992 
993  /** Set all GPS location information into image. Return true if all information have been
994  changed in metadata.
995  */
996  bool setGPSInfo(const double altitude, const QString &latitude, const QString &longitude, const bool setProgramName=true);
997 
998  /** Remove all Exif tags relevant of GPS location information. Return true if all tags have been
999  removed successfully in metadata.
1000  */
1001  bool removeGPSInfo(const bool setProgramName=true);
1002 
1003  /** This method converts 'number' to a rational value, returned in the 'numerator' and
1004  'denominator' parameters. Set the precision using 'rounding' parameter.
1005  Use this method if you want to retrieve a most exact rational for a number
1006  without further properties, without any requirements to the denominator.
1007  */
1008  static void convertToRational(const double number, long int* const numerator,
1009  long int* const denominator, const int rounding);
1010 
1011  /** This method convert a 'number' to a rational value, returned in 'numerator' and
1012  'denominator' parameters.
1013  This method will be able to retrieve a rational number from a double - if you
1014  constructed your double with 1.0 / 4786.0, this method will retrieve 1 / 4786.
1015  If your number is not expected to be rational, use the method above which is just as
1016  exact with rounding = 4 and more exact with rounding > 4.
1017  */
1018  static void convertToRationalSmallDenominator(const double number, long int* const numerator,
1019  long int* const denominator);
1020 
1021  /** Converts a GPS position stored as rationals in Exif to the form described
1022  as GPSCoordinate in the XMP specification, either in the from "256,45,34N" or "256,45.566667N"
1023  */
1024  static QString convertToGPSCoordinateString(const long int numeratorDegrees, const long int denominatorDegrees,
1025  const long int numeratorMinutes, const long int denominatorMinutes,
1026  const long int numeratorSeconds, long int denominatorSeconds,
1027  const char directionReference);
1028 
1029  /** Converts a GPS position stored as double floating point number in degrees to the form described
1030  as GPSCoordinate in the XMP specification.
1031  */
1032  static QString convertToGPSCoordinateString(const bool isLatitude, double coordinate);
1033 
1034  /** Converts a GPSCoordinate string as defined by XMP to three rationals and the direction reference.
1035  Returns true if the conversion was successful.
1036  If minutes is given in the fractional form, a denominator of 1000000 for the minutes will be used.
1037  */
1038  static bool convertFromGPSCoordinateString(const QString& coordinate,
1039  long int* const numeratorDegrees, long int* const denominatorDegrees,
1040  long int* const numeratorMinutes, long int* const denominatorMinutes,
1041  long int* const numeratorSeconds, long int* const denominatorSeconds,
1042  char* const directionReference);
1043 
1044  /** Convert a GPSCoordinate string as defined by XMP to a double floating point number in degrees
1045  where the sign determines the direction ref (North + / South - ; East + / West -).
1046  Returns true if the conversion was successful.
1047  */
1048  static bool convertFromGPSCoordinateString(const QString& gpsString, double* const coordinate);
1049 
1050  /** Converts a GPSCoordinate string to user presentable numbers, integer degrees and minutes and
1051  double floating point seconds, and a direction reference ('N' or 'S', 'E' or 'W')
1052  */
1053  static bool convertToUserPresentableNumbers(const QString& coordinate,
1054  int* const degrees, int* const minutes,
1055  double* const seconds, char* const directionReference);
1056 
1057  /** Converts a double floating point number to user presentable numbers, integer degrees and minutes and
1058  double floating point seconds, and a direction reference ('N' or 'S', 'E' or 'W').
1059  The method needs to know for the direction reference
1060  if the latitude or the longitude is meant by the double parameter.
1061  */
1062  static void convertToUserPresentableNumbers(const bool isLatitude, double coordinate,
1063  int* const degrees, int* const minutes,
1064  double* const seconds, char* const directionReference);
1065 
1066  //@}
1067 
1068 protected:
1069 
1070  /** Re-implement this method to set automatically the Program Name and Program Version
1071  information in Exif and Iptc metadata if 'on' argument is true. This method is called by all methods which
1072  change tags in metadata. By default this method does nothing and returns true.
1073  */
1074  virtual bool setProgramId(bool on=true) const;
1075 
1076 private:
1077 
1078  /** Internal container to store private members. Used to improve binary compatibility
1079  */
1080  std::unique_ptr<class KExiv2Private> const d;
1081 
1082  friend class KExiv2Previews;
1083 };
1084 
1085 } // NameSpace KExiv2Iface
1086 
1087 #endif /* KEXIV2_H */
KExiv2Iface - Exiv2 library interface.
Definition: kexiv2.cpp:16
QMap< QString, QString > AltLangMap
A map used to store a list of Alternative Language values.
Definition: kexiv2.h:119
ImageColorWorkSpace
The image color workspace values given by Exif metadata.
Definition: kexiv2.h:76
ImageOrientation
The image orientation values given by Exif metadata.
Definition: kexiv2.h:86
XmpTagType
Xmp tag types, used by setXmpTag, only first three types are used.
Definition: kexiv2.h:102
KExiv2.
Definition: kexiv2.h:51
QMap< QString, QString > MetaDataMap
A map used to store Tags Key and Tags Value.
Definition: kexiv2.h:113
QMap< QString, QStringList > TagsMap
A map used to store Tags Key and a list of Tags properties :
Definition: kexiv2.h:126
MetadataWritingMode
The image metadata writing mode, between image file metadata and XMP sidecar file, depending on the context.
Definition: kexiv2.h:59
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Tue Dec 7 2021 22:32:53 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.