Skip to content

Latest commit

 

History

History
660 lines (446 loc) · 22.6 KB

README-SAMPLES.md

File metadata and controls

660 lines (446 loc) · 22.6 KB
Travis AppVeyor GitLab Codecov Repology Chat
Build Status Build status pipeline status codecov Packaging status #exiv2-chat on matrix.org

Exiv2

Exiv2 Sample Applications

Exiv2 is a C++ library and a command line utility to read, write, delete and modify Exif, IPTC, XMP and ICC image metadata. Exiv2 also features a collection of sample and test command-line programs. Please be aware that while the program exiv2 enjoys full support from Team Exiv2, the other programs have been written for test, documentation or development purposes. You are expected to read the code to discover the specification of programs other than exiv2.

Sample Programs Test Programs

Sample Programs

The following programs are build and installed in /usr/local/bin.

Name Purpose More information Code
addmoddel Demonstrates Exiv2 library APIs to add, modify or delete metadata addmoddel addmoddel.cpp
exifcomment Set Exif.Photo.UserComment in an image exifcomment exifcomment.cpp
exifdata Prints Exif metadata in different formats in an image exifdata exifdata.cpp
exifprint Print Exif metadata in images
Miscellaneous other features
exifprint exifprint.cpp
exifvalue Prints the value of a single Exif tag in a file exifvalue exifvalue.cpp
exiv2 Utility to read and write image metadata, including Exif, IPTC, XMP, image comments, ICC Profile, thumbnails, image previews and many vendor makernote tags.
This is the primary test tool used by Team Exiv2 and can exercise almost all code in the library. Due to the extensive capability of this utility, the APIs used are usually less obvious for casual code inspection.
exiv2 manpage
https://exiv2.org/sample.html
exiv2json Extracts data from image in JSON format.
This program also contains a parser to recursively parse Xmp metadata into vectors and objects.
exiv2json exiv2json.cpp
geotag Reads GPX data and updates images with GPS Tags geotag geotag.cpp
iptceasy Demonstrates read, set or modify IPTC metadata iptceasy iptceasy.cpp
iptcprint Demonstrates Exiv2 library APIs to print Iptc data iptceasy iptcprint.cpp
metacopy Demonstrates copying metadata from one image to another metacopy metacopy.cpp
mrwthumb Sample program to extract a Minolta thumbnail from the makernote mrwthumb mrwthumb.cpp
taglist Print a simple comma separated list of tags defined in Exiv2 taglist
xmpdump Sample program to dump the XMP packet of an image xmpdump
xmpparse Read an XMP packet from a file, parse it and print all (known) properties. xmpparse xmpparse.cpp
xmpprint Read an XMP from a file, parse it and print all (known) properties.. xmpprint xmpprint.cpp
xmpsample Demonstrates Exiv2 library high level XMP classes xmpsample xmpsample.cpp

Sample Programs Test Programs

Test Programs

As Exiv2 is open source, we publish all our materials. The following programs are actively used in our test harness. Some were written during feature development of features and their on-going use may be limited, or even obsolete. In general these programs are published as source and Team Exiv2 will not provide support to users.

Name Kind More information
conntest Test http/https/ftp/ssh/sftp connection conntest
convert-test Conversion test driver convert-test
easyaccess-test Sample program using high-level metadata access functions easyaccess-test
getopt-test Sample program to test getopt() getopt-test
ini-test Shows simple usage of the INIReader class ini-test
iotest Test programs for BasicIo functions. iotest
iptctest Sample program test Iptc reading and writing. iptctest
key-test Key unit tests key-test
largeiptc-test Test for large (>65535 bytes) IPTC buffer largeiptc-test
mmap-test Simple mmap tests mmap-test
path-test Test path IO path-test
prevtest Test access to preview images prevtest
remotetest Tester application for testing remote i/o. remotetest
stringto-test Test conversions from string to long, float and Rational types. stringto-test
tiff-test Simple TIFF write test tiff-test
write-test ExifData write unit tests write-test
write2-test ExifData write unit tests for Exif data created from scratch write2-test
xmpparser-test Read an XMP packet from a file, parse and re-serialize it. xmpparser-test

Sample Programs Test Programs

2 Sample Program Descriptions

addmoddel

Usage: addmoddel file

Demonstrates Exiv2 library APIs to add, modify or delete metadata. Code: addmoddel.cpp

Sample Programs Test Programs

exifcomment

Usage: exifcomment file

This is a simple program that demonstrates how to set Exif.Photo.UserComment in an image. Code: exifcomment.cpp

Sample Programs Test Programs

exifdata

Usage: exifdata file format
formats: csv | json | wolf | xml

This is a simple program to demonstrate dumping Exif metadata in common formats. Code: exifdata.cpp

Sample Programs Test Programs

exifprint

Usage: exifprint [ [--lint] path | --version | --version-test ]
Arguments Description
path Path to image
--lint path Path to image. Type metadata test
--version Print version information from build
--version-test Tests Exiv2 VERSION API

This program demonstrates how to print Exif metadata in an image. This program is also discussed in the platform ReadMe.txt file included in a build bundle. The option --version was added to enable the user to build a test application which dumps the build information. The option --version-test was added to test the macro EXIV2_TEST_VERSION() in include/exiv2/version.hpp.

You can process the metadata in two different ways. The default prints the metadata. The option --lint instructs exifprint to compare the type of the metadata to the standard.

There is another unique feature of this program. It is the only test/sample program which can use the EXV_UNICODE_PATH build feature of Exiv2 on Windows.

Code: exifprint.cpp

Sample Programs Test Programs

exifvalue

Usage: exifvalue file tag

Prints the value of a single Exif tag in a file. Code: exifvalue.cpp

Sample Programs Test Programs

exiv2json

Usage: exiv2json [-option] file
Option: all | exif | iptc | xmp | filesystem
Arguments Description
all All metadata
filesystem Filesystem metadata
exif Exif metadata
iptc Iptc metadata
xmp Xmp metadata
file path to image

This program dumps metadata from an image in JSON format. Code: exiv2json.cpp

exiv2json has a recursive parser to encode XMP into Vectors and Objects. XMP data is XMP and can contain XMP Bag and Seq which are converted to JSON Objects and Arrays. Exiv2 presents data in the format: Family.Group.Tagname. For XMP, results in "flat" output such as:

$ curl --silent -O https://clanmills.com/Stonehenge.jpg
$ exiv2 --print x Stonehenge.jpg
Xmp.xmp.Rating                               XmpText     1  0
Xmp.xmp.ModifyDate                           XmpText    25  2015-07-16T20:25:28+01:00
Xmp.cm2e.Father                              XmpText    11  Robin Mills
Xmp.cm2e.Family                              XmpBag      0
Xmp.dc.description                           LangAlt     1  lang="x-default" Classic View
Xmp.dc.Family                                XmpBag      1  Robin

exiv2json parses the Exiv2 Family.Group.Tagname data and restores the structure of the original data in JSON. Code: exiv2json.cpp

$ exiv2json -xmp http://clanmills.com/Stonehenge.jpg
{
  "Xmp": {
    "xmp": {
      "Rating": "0",
      "ModifyDate": "2015-07-16T20:25:28+01:00"
    },
    "dc": {
      "description": {
        "lang": {
          "x-default": "Classic View"
        }
      }
    },
    "xmlns": {
      "dc": "http:\/\/purl.org\/dc\/elements\/1.1\/",
      "xmp": "http:\/\/ns.adobe.com\/xap\/1.0\/"
    }
  }
}
$

Sample Programs Test Programs

geotag

Usage: geotag {-help|-version|-dst|-dryrun|-ascii|-verbose|-adjust value|-tz value|-delta value}+ path+

Geotag reads one or more GPX files and adds GPS Tags to images. Code: geotag.cpp

If the path is a directory, geotag will read all the files in the directory. It constructs a time dictionary of position data, then updates every image with GPS Tags.

Arguments Description
-help print usage statement
-version prints data and time of compiling geotag.cpp
-dst Apply 1 hour adjustment for daylight saving time.
-dryrun Read arguments and print report. Does not modify images.
-ascii Output in ascii (not UTF8). Prints deg instead of °.
-verbose Report progress.
-adjust value Add/subtract time from image data.
-tz value Specify time zone. For example PST = -8:00
-delta value Correction between Image DataTime and GPS time.
path+ One or more directories, image paths or gpx paths. Directories are searched for gpx and images

I use this program frequently. I have a little Canon camera which I take when I run. My Samsung Galaxy Watch uploads my runs to Strava and I download the GPX. If I'm in another time-zone and have forgotten to change the time setting in the camera, I use -adjust to alter the images. The GPX time is always correct, however the camera is normally off by seconds or minutes. This option enables you to correct for inaccuracy in the setting of the camera time.

Sample Programs Test Programs

iptceasy

Usage: iptceasy file
Reads and writes raw metadata. Use -h option for help.

Demonstrates read, set or modify IPTC metadata. Code: iptceasy.cpp

Sample Programs Test Programs

iptcprint

Usage: iptcprint file
Reads and writes raw metadata. Use -h option for help.

Demonstrates Exiv2 library APIs to print Iptc data. Code: iptcprint.cpp

Sample Programs Test Programs

metacopy

Usage: metacopy [-iecxaph] readfile writefile
Reads and writes raw metadata. Use -h option for help.

Metacopy is used to copy a complete metadata block from one file to another. Code: metacopy.cpp

Please note that some metadata such as Exif.Photo.PixelXDimension is considered to be part of the image and will not be copied.

Sample Programs Test Programs

mrwthumb

Usage: mrwthumb file

Sample program to extract a Minolta thumbnail from the makernote. Code: mrwthumb.cpp

Sample Programs Test Programs

xmpparse

Usage: xmpparse file

Read an XMP packet from a file, parse it and print all (known) properties. Code: xmpparse.cpp

Sample Programs Test Programs

xmpprint

Usage: xmpprint file

Read an XMP from a file, parse it and print all (known) properties. Code: xmpprint.cpp

Sample Programs Test Programs

xmpsample

Usage: xmpsample file

Demonstrates Exiv2 library high level XMP classes. Code: xmpsample.cpp

Sample Programs Test Programs

3 Test Program Descriptions

conntest

Usage: conntest url {-http1_0}

Test http/https/ftp/ssh/sftp connection

Sample Programs Test Programs

convert-test

Usage: convert-test file

Conversion test driver

Sample Programs Test Programs

easyaccess-test

Usage: ..\build\bin\easyaccess-test.exe file [category [category ...]]
Categories: Orientation | ISOspeed | DateTimeOriginal | FlashBias | ExposureMode | SceneMode |
            MacroMode | ImageQuality | WhiteBalance | LensName | Saturation | Sharpness |
            Contrast | SceneCaptureType | MeteringMode | Make | Model | ExposureTime | FNumber |
            ShutterSpeed | Aperture | Brightness | ExposureBias | MaxAperture | SubjectDistance |
            LightSource | Flash | SerialNumber | FocalLength | SubjectArea | FlashEnergy |
            ExposureIndex | SensingMethod | AFpoint

Sample program using high-level metadata access functions. Without specification of a category, metadata for all categories are shown.

Sample Programs Test Programs

getopt-test

Usage: getopt-test

This program is used to test the function getopt(). Prior to Exiv2 v0.27, the sample programs used the platform's C Runtime Library function getopt(). Visual Studio builds used code in src/getopt.cpp. Due to differences in the platform getopt(), the code in src/getopt.cpp was modified and adopted on every platforms. This test program was added for test and debug purpose. Please note that src/getopt.cpp is compiled and linked into the sample application and is not part of the Exiv2 library.

Sample Programs Test Programs

ini-test

Usage: ini-test

This program is used to test reading the file ini-test. This program was added in Exiv2 v0.26 when the ~/.exiv2 file was added to the Exiv2 architecture.

Sample Programs Test Programs

iotest

Usage: iotest filein fileout1 fileout2 [remote [blocksize]]
copy filein to fileout1 and copy filein to fileout2
fileout1 and fileout2 are overwritten and should match filein exactly

You may optionally provide the URL of a remote file to be copied to filein
If you use `remote`, you may optionally provide a blocksize for the copy buffer (default 10k)

Test programs for BasicIo functions.

Sample Programs Test Programs

iptctest

Usage: iptctest image
Commands read from stdin.

Sample program test Iptc reading and writing.

Sample Programs Test Programs

key-test

Usage: key-test

Key unit tests

Sample Programs Test Programs

largeiptc-test

Usage: largeiptc-test image datafile

Test for large (>65535 bytes) IPTC buffer

Sample Programs Test Programs

mmap-test

Usage: mmap-test file

Simple mmap tests

Sample Programs Test Programs

path-test

Usage: path-test file

Test path IO

Sample Programs Test Programs

prevtest

Usage: prevtest file

Test access to preview images

Sample Programs Test Programs

remotetest

Usage: remotetest file {--nocurl | --curl}

Tester application for testing remote i/o.

Sample Programs Test Programs

stringto-test

Usage: stringto-test

Test conversions from string to long, float and Rational types.

Sample Programs Test Programs

taglist

$ taglist --help
Usage: taglist [--help]
           [--group name|
            Groups|Exif|Canon|CanonCs|CanonSi|CanonCf|Fujifilm|Minolta|Nikon1|Nikon2|Nikon3|Olympus|
            Panasonic|Pentax|Sigma|Sony|Iptc|
            dc|xmp|xmpRights|xmpMM|xmpBJ|xmpTPg|xmpDM|pdf|photoshop|crs|tiff|exif|aux|iptc|all|ALL
           ]
Print Exif tags, MakerNote tags, or Iptc datasets

Print a simple comma separated list of tags defined in Exiv2

This program encodes the library's tag definitions in ascii. The data from this program is formatted as HTML on the web-site. https://exiv2.org/metadata.html

For example, to show the binary definition of Group Nikon3:

$ taglist Nikon3
Version,    1,  0x0001, Nikon3, Exif.Nikon3.Version,    Undefined,  Nikon Makernote version
ISOSpeed,   2,  0x0002, Nikon3, Exif.Nikon3.ISOSpeed,   Short,  ISO speed setting
ColorMode,  3,  0x0003, Nikon3, Exif.Nikon3.ColorMode,  Ascii,  Color mode
Quality,    4,  0x0004, Nikon3, Exif.Nikon3.Quality,    Ascii,  Image quality setting
WhiteBalance,   5,  0x0005, Nikon3, Exif.Nikon3.WhiteBalance,   Ascii,  White balance
Sharpening, 6,  0x0006, Nikon3, Exif.Nikon3.Sharpening, Ascii,  Image sharpening setting
Focus,  7,  0x0007, Nikon3, Exif.Nikon3.Focus,  Ascii,  Focus mode
FlashSetting,   8,  0x0008, Nikon3, Exif.Nikon3.FlashSetting,   Ascii,  Flash setting
FlashDevice,    9,  0x0009, Nikon3, Exif.Nikon3.FlashDevice,    Ascii,  Flash device
...

We can see those tags being used:

$ curl --silent -O https://clanmills.com/Stonehenge.jpg
$ exiv2 --print a --grep Nikon3 Stonehenge.jpg
Exif.Nikon3.Version                          Undefined   4  2.11
Exif.Nikon3.ISOSpeed                         Short       2  200
...

This information is formatted (search Nikon (format 3) MakerNote Tags): https://exiv2.org/tags-nikon.html

taglist all

These options are provided to list every tag known to Exiv2. The option all prints the Group.Tagnames for every Exif tag. The option ALL prints the Group.Tagnames for every Exif tag, followed by the TagInfo for that tag. For example:

$ taglist all | grep ISOSpeed$
Photo.ISOSpeed
PanasonicRaw.ISOSpeed
CanonCs.ISOSpeed
CanonSi.ISOSpeed
Casio2.ISOSpeed
MinoltaCs5D.ISOSpeed
MinoltaCs7D.ISOSpeed
Nikon1.ISOSpeed
Nikon2.ISOSpeed
Nikon3.ISOSpeed
Olympus.ISOSpeed
Olympus2.ISOSpeed
$ taglist ALL | grep ISOSpeed,
Photo.ISOSpeed,	34867,	0x8833,	Photo,	Exif.Photo.ISOSpeed,	Long,	This tag indicates the ISO speed value of a camera or input device that is defined in ISO 12232. When recording this tag, the PhotographicSensitivity and SensitivityType tags shall also be recorded.
PanasonicRaw.ISOSpeed,	23,	0x0017,	PanasonicRaw,	Exif.PanasonicRaw.ISOSpeed,	Short,	ISO speed setting
CanonCs.ISOSpeed,	16,	0x0010,	CanonCs,	Exif.CanonCs.ISOSpeed,	SShort,	ISO speed setting
CanonSi.ISOSpeed,	2,	0x0002,	CanonSi,	Exif.CanonSi.ISOSpeed,	Short,	ISO speed used
Casio2.ISOSpeed,	20,	0x0014,	Casio2,	Exif.Casio2.ISOSpeed,	Short,	ISO Speed
MinoltaCs5D.ISOSpeed,	38,	0x0026,	MinoltaCs5D,	Exif.MinoltaCs5D.ISOSpeed,	Short,	ISO speed setting
MinoltaCs7D.ISOSpeed,	28,	0x001c,	MinoltaCs7D,	Exif.MinoltaCs7D.ISOSpeed,	Short,	ISO speed setting
Nikon1.ISOSpeed,	2,	0x0002,	Nikon1,	Exif.Nikon1.ISOSpeed,	Short,	ISO speed setting
Nikon2.ISOSpeed,	6,	0x0006,	Nikon2,	Exif.Nikon2.ISOSpeed,	Short,	ISO speed setting
Nikon3.ISOSpeed,	2,	0x0002,	Nikon3,	Exif.Nikon3.ISOSpeed,	Short,	ISO speed setting
Olympus.ISOSpeed,	4097,	0x1001,	Olympus,	Exif.Olympus.ISOSpeed,	SRational,	ISO speed value
Olympus2.ISOSpeed,	4097,	0x1001,	Olympus,	Exif.Olympus.ISOSpeed,	SRational,	ISO speed value
Sony1MltCs7D.ISOSpeed,	28,	0x001c,	MinoltaCs7D,	Exif.MinoltaCs7D.ISOSpeed,	Short,	ISO speed setting

Sample Programs Test Programs

tiff-test

Usage: tiff-test file

Simple TIFF write test

Sample Programs Test Programs

write-test

Usage: write-test file case
where case is an integer between 1 and 11

ExifData write unit tests

Sample Programs Test Programs

write2-test

Usage: write2-test file

ExifData write unit tests for Exif data created from scratch

Sample Programs Test Programs

xmpdump

Usage: xmpdump file

Sample program to dump the XMP packet of an image

Sample Programs Test Programs

xmpparser-test

Usage: xmpparser-test file

Read an XMP packet from a file, parse and re-serialize it.

Sample Programs Test Programs

Robin Mills
[email protected]
Revised: 2021-09-21