1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<title>ExifTool Plot Feature</title>
<link rel=stylesheet type='text/css' href='style.css' title='Style'>
<style type="text/css">
<!--
pre { color: #800; margin-left: 4em }
.nr { white-space: nowrap }
.prog { padding: 0.5em; border: 1px solid gray; background: #fee }
.indent { margin-left: 22% }
-->
</style>
</head>
<body>
<h1>The ExifTool Plot Feature</h1>
<p>The <code>-plot</code> option of the exiftool application is used to generate
SVG-format output plot files from the values of tags. This feature has many uses,
including plotting timed metadata when combined with the <code>-ee</code>
(ExtractEmbedded) option, and plotting values of one or more tags across a set of
images.</p>
<p>Any tag with a numerical value may be plotted, including strings and lists of numbers.
Up to 20 datasets (eg. tags) may be plotted together in the same plot, except for
histogram plots which are limited to only one (but the <code>Multi</code> setting may be
used to draw multiple plots at once). Attempting to plot too many tags at once will result
in a warning and the extra datasets will be ignored. The X and Y scales are common to
all datasets within each plot (ie. multiple datasets in a single plot all use the same
scales).</p>
<p>The plot may be viewed by opening the SVG file in your favourite web browser or
SVG-aware image viewer. Most modern web browsers support display of SVG images.</p>
<p>Three basic plot types are provided: Line, Scatter and Histogram. Examples of each
are given in the <a href="#examples">Examples section</a> below.</p>
<h2>Plot Settings</h2>
<p>Plot settings are changed via the <a href="ExifTool.html#Plot">API Plot option</a>.
Multiple options may be set at the same time either by stringing them together in a
comma-separated list, or through multiple API Plot options.</p>
<p>The syntax for each setting is <code><i>NAME</i>=<i>VALUE</i></code>. Case is not
significant for setting names. Using <code><i>NAME</i>=</code> without a value sets the
value to <i>undef</i>. Using <code><i>NAME</i></code> alone sets the value to 1. For
example, to set the plot title and color for the first data line, a command could be:</p>
<pre>exiftool -plot -api plot="title=some title,cols=pink" ...</pre>
<blockquote>
<table class='norm'>
<tr><th colspan=6 bgcolor='#dddddd'><font size='+1'>ExifTool Plot Settings</font></th></tr>
<tr><th>Name</th><th>Description</th><th colspan=2>Value</th><th colspan=2>Default</th></tr>
<tr><td>Type</td><td>Type of plot</td>
<td align=center colspan=2>'Line', 'Scatter' or 'Histogram' <sup>1</sup></td>
<td align=center colspan=2>'Line'</td></tr>
<tr><td>Style</td><td>Style of plot data points</td>
<td align=center colspan=2>String of names: <sup>2,3</sup> 'Line', 'Marker' and/or 'Fill'</td>
<td align=center colspan=2>'Line+Fill' for Histogram plots, or 'Line' otherwise</td></tr>
<tr><td>Title</td><td>Title of the plot</td>
<td align=center colspan=2>Any string <sup>4</sup></td>
<td align=center colspan=2>'' (auto-generated) <sup>5</sup></td></tr>
<tr><td>XLabel</td><td>X-axis label string</td>
<td align=center colspan=2>Any string <sup>4</sup></td>
<td align=center colspan=2>'' (auto-generated) <sup>5</sup></td></tr>
<tr><td>YLabel</td><td>Y-axis label string</td>
<td align=center colspan=2>Any string <sup>4</sup></td>
<td align=center colspan=2>'' (auto-generated) <sup>5</sup></td></tr>
<tr><td>XMin, XMax</td><td>X-axis minimum and maximum for Scatter and Histogram plot types</td>
<td align=center colspan=2>A number</td>
<td align=center colspan=2><i>undef</i> (autoscaling)</td></tr>
<tr><td>YMin, YMax</td><td>Y-axis minimum and maximum (the YMin setting does not apply to Histogram plots)</td>
<td align=center colspan=2>A number</td>
<td align=center colspan=2><i>undef</i> (autoscaling)</td></tr>
<tr><td>NBins</td><td>Number of bins for histogram plot</td>
<td align=center colspan=2>A number</td>
<td align=center colspan=2>'20'</td></tr>
<tr><td>Multi</td><td>Flag to draw multiple plots, one for each dataset</td>
<td align=center colspan=2>Number of plots per row in output image <sup>6</sup></td>
<td align=center colspan=2><i>undef</i></td></tr>
<tr><td>Split</td><td>Split strings of numbers into separate datasets</td>
<td align=center colspan=2>Number of datasets, or 1 to split all <sup>7</sup></td>
<td align=center colspan=2><i>undef</i></td></tr>
<tr><td>Size</td><td>Width and height of output image</td>
<td align=center colspan=2>String of 2 numbers <sup>2</sup></td>
<td align=center colspan=2>'800 600'</td></tr>
<tr><td>Margin</td><td>Left, right, top, bottom margins around plotting area</td>
<td align=center colspan=2>String of 4 numbers <sup>2</sup></td>
<td align=center colspan=2>'60 15 15 30'</td></tr>
<tr><td>Legend</td><td>X and Y shift of legend from default location</td>
<td align=center colspan=2>String of 2 numbers <sup>2</sup></td>
<td align=center colspan=2>'0 0'</td></tr>
<tr><td>TxtPad</td><td>Padding between text and X/Y scales</td>
<td align=center colspan=2>String of 2 numbers <sup>2</sup></td>
<td align=center colspan=2>'10 10'</td></tr>
<tr><td>LineSpacing</td><td>Text line spacing</td>
<td align=center colspan=2>A number</td>
<td align=center colspan=2>'20'</td></tr>
<tr><td>Stroke</td><td>Scaling factor for plot stroke width and marker size</td>
<td align=center colspan=2>A number</td>
<td align=center colspan=2>'1'</td></tr>
<tr><td>Marks</td><td>Marker characteristics for each dataset</td>
<td align=center>String of marker names (or 'none') with optional fill style, color and opacity <sup>2,8</sup></td>
<td rowspan=2 colspan=2><img alt="markers" src="markers.svg" width=90 height=200></td>
<td align=center>'circle square triangle diamond star plus pentagon left down right'</td></tr>
<tr><td>Cols</td><td>Colors of plot lines/markers for each dataset</td>
<td align=center>String of SVG color codes or 'none' for no line or marker border <sup>2</sup></td>
<td align=center>'red green blue black orange gray fuchsia brown turquoise gold'</td></tr>
<tr><td>Grid</td><td>Grid color</td>
<td align=center colspan=2>SVG color code</td>
<td align=center colspan=2>'darkgray'</td></tr>
<tr><td>Text</td><td>Color of text and plot border</td>
<td align=center colspan=2>SVG color code</td>
<td align=center colspan=2>'black'</td></tr>
<tr><td>Bkg</td><td>Background color</td>
<td align=center colspan=2>SVG color code or <i>undef</i></td>
<td align=center colspan=2><i>undef</i> (transparent)</td></tr>
</table>
</blockquote>
<p>Notes:</p>
<blockquote><table class='clear'>
<tr><td valign=top><sup>1</sup></td><td>The scatter plot uses the first specified
tag as the X coordinate and the remaining tags as the datasets for the Y values.</td></tr>
<tr><td valign=top><sup>2</sup></td><td>Strings of names or numbers may use
whitespace, slash (<code>/</code>) or a plus sign (<code>+</code>) as a
delimiter. The numbers themselves should not contain a plus sign. Numbers
may also use '<code>x</code>' as a delimiter (eg. '<code>size=320x200</code>').</td></tr>
<tr><td valign=top><sup>3</sup></td><td>The <code>Fill</code>
style applies only for the <code>Histogram</code> plot style, or when <code>Marker</code>
style is also used. Without <code>Fill</code>, histogram bars and markers are hollow.
<code>Line</code> and <code>Marker</code> may also be used together (eg. '<code>Style=Line+Marker</code>').
For brevity, only the first letter of each setting is required (eg. '<code>Style=L+M</code>').</td></tr>
<tr><td valign=top><sup>4</sup></td><td>Commas in labels must be escaped as either '<code>&#44;</code>'
or '<code>&#x2c;</code>'. No other characters require escaping, but other XML numeric
character references may be used.</td></tr>
<tr><td valign=top><sup>5</sup></td><td>The auto-generation of labels applies only in limited
situations, and may be disabled with <code><i>NAME</i>=</code>.</td></tr>
<tr><td valign=top><sup>6</sup></td><td>Multiple plots are draw together in the same SVG
image with the specified number of columns within the width of the output image. The image
height is adjusted to fit the required number of rows. The X axes of all plots are the
same, but the Y axes are independent. See <a href='#EX5'>example 5</a>.</td></tr>
<tr><td valign=top><sup>7</sup></td><td>For example, if a tag contains a set of N accelerometer
readings, each composed of 3 values (X, Y and Z directions), then these could be plotted
as 3 separate datasets by setting <code>Split=3</code>. See <a href='#EX4'>example 4</a>
for a demonstration of the <code>Split</code> setting.</td></tr>
<tr><td valign=top><sup>8</sup></td><td>A value of 'none' may be used to override the plot
<code>Style</code> <code>Marker</code> setting to disable marks for a specific dataset.
For brevity, only the first letter of the marker name is required, except for 'star',
'pentagon', and 'down' which require 2 letters to distinguish them from 'square', 'plus'
and 'diamond' respectively. An optional fill style, color and opacity may be appended to
the marker name, separated by dashes. The fill style overrides the plot
<code>Style</code> <code>Fill</code> setting for the specific dataset, and may be 'Fill'
(or just 'F') for filled markers, or 'none' for hollow markers. Filled markers may also
specify a fill color and opacity (ranging from 1 to 100 percent). For example, to use a
right-pointing triangle for dataset 1, and the default marker with solid black fill for
dataset 3: '<code>marks=r++-f-black-100</code>'. The default opacity for marker and
histogram fill is 20% if they have a border, or 50% otherwise.</td></tr>
</table></blockquote>
<a name="examples"></a>
<h2>Examples</h2>
<a name="EX1"></a>
<h3>Example 1 - Line Plot</h3>
<p>The first example plots AmbientTemperature and CameraTemperature from a set of
images in a directory. The <code>-fileOrder</code> option is used to order the
files (and hence the data points) chronologically. Here is the command that was used:</p>
<pre>exiftool C:/pics "-*temperature" -plot -fileorder createdate > plot1.svg
</pre>
<p>And this is the resulting SVG plot (plot1.svg):</p>
<blockquote><img src="plot1.svg" alt="SVG-format plot" width=800 height=600></blockquote>
<a name="EX2"></a>
<h3>Example 2 - Histogram Plot</h3>
<p>This example shows a histogram of the number of pictures taken at different
focal lengths for a set of images. It also demonstrates the use of the
<a href="ExifTool.html#Plot">API Plot option</a> to change various plot settings.
The <code>YMax</code> setting was used to limit the Y scale because otherwise the
effect of the autoscaling with the tall 20-25 mm bar would have made the other bars
too small. With this rescaling, the 20-25 mm bar extends off the top of the plot.</p>
<p>The default histogram plot <code>Style</code> is <code>Line+Fill</code>. The fill
is partially transparent, with a default 20% opacity if the <code>Line</code> style is
used, or 50% otherwise, but this may be changed with the <code>Marks</code> setting.</p>
<p>Unlike the other plot types, the histogram type supports plotting of only
a single dataset (ie. only the first tag specified on the command line is used
unless the <code>Multi</code> plot setting is used to generate multiple plots).</p>
<p>The <code>-w</code> option was used to write the output file
(plot2.svg) instead of using shell redirection. Note that when the <code>-plot</code>
option is used, the <code>-w</code> option takes a full file name instead of
just an extension.</p>
<pre>exiftool C:/my_trip -focallength35efl# -w plot2.svg \
-api plot="type=hist,nbins=40,ymax=50,cols=blue"</pre>
<blockquote><img src="plot2.svg" alt="SVG-format plot" width=800 height=600></blockquote>
<a name="EX3"></a>
<h3>Example 3 - Scatter Plot</h3>
<p>This example uses the same data set as example 1, but using the <code>Scatter</code>
plot type to show the correlation betweent CameraTemperature and AmbientTemperature.
The first tag specified on the command line is the independent variable (plotted
along the X axis), and the rest are the dependent variables (Y axis). Note that
the legend doesn't appear in this plot because there is only one dependent
variable, so instead the Y-axis is labelled with its name.</p>
<p>The plot <code>Style</code>
has been changed to <code>Marker</code> to show markers for the data points
instead of connecting them with lines, and <code>Fill</code> has been added to
show filled markers instead of outlines. The fill is partially transparent with a
default opacity of 20%, but this has been changed to 10% via the <code>Marks</code>
setting so points which occur few times in the dataset will show a noticably lighter
color.</p>
<pre>exiftool C:/pics -w plot3.svg "-*temperature" -plot \
-api plot="type=scatter,style=marker+fill,stroke=1.5,marks=---10"</pre>
<blockquote><img src="plot3.svg" alt="SVG-format plot" width=800 height=600></blockquote>
<a name="EX4"></a>
<h3>Example 4 - Splitting Values</h3>
<p>To plot timed accelerometer readings from a video where the Accelerometer values are
strings of numbers, the <code>Split</code> setting of the
<a href="ExifTool.html#Plot">API Plot option</a> must be used to split the values into
separate lines in the plot. Here is an example of the first Accelerometer value in the
file:</p>
<pre><span class='blk'>> </span>exiftool test.mp4 -ee -accelerometer -s2 --a
<span class='blk'>Accelerometer: +0.12 +0.96 -0.09</span></pre>
<p>And this command was used to generate the following plot:</p>
<pre>exiftool test.mp4 -w plot4.svg -ee -accelerometer -plot -api plot="split,legend=30 107" \
-api plot="title=Accelerometer Readings,ylabel=G Force,xlabel=Sample Number"
</pre>
<blockquote><img src="plot4.svg" alt="SVG-format plot" width=800 height=600></blockquote>
<a name="EX5"></a>
<h3>Example 5 - Multi Plots</h3>
<p>This example demonstrates the <code>Multi</code> setting to draw multiple
<code>Histogram</code> plots in 2 columns. The <a href="ExifTool.html#Filter">API Filter</a>
option is used to convert shutter speed from a value like 1/640 to 640 so the denominator
of the value is plotted.</p>
<pre>exiftool C:\my_trip -w! plot5.svg -fnumber -focallength35efl# -shutterspeed -iso -plot \
-api filter="s(1/)()" -api plot="multi=2,type=hist,style=fill,cols=green,ylabel="</pre>
<blockquote><img src="plot5.svg" alt="SVG-format plot" width=800 height=600></blockquote>
<hr>
<i>Created Feb 19, 2025</i><br>
<i>Last revised Mar 1, 2025</i><br>
<p class='lf'><a href="index.html"><-- Back to ExifTool home page</a></p>
</body>
</html>
|
