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

KDE's Doxygen guidelines are available online.