-
Notifications
You must be signed in to change notification settings - Fork 1
/
README.Rmd
179 lines (135 loc) · 6.3 KB
/
README.Rmd
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
<!-- README.md is generated from README.Rmd by knitr::knit(). Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-"
)
options(width = 85)
```
# ExifTool functionality from R
[](http://www.repostatus.org/#active)
[](http://www.gnu.org/licenses/gpl-2.0.html)
[](http://www.r-pkg.org/pkg/exiftoolr)
[](http://www.r-pkg.org/pkg/exiftoolr)
[ExifTool][ExifTool-home] is a comprehensive open source utility for
reading, writing and editing meta information in a wide variety of
file types. As noted on its [project homepage][ExifTool-home]:
> ExifTool supports many different metadata formats including EXIF, GPS,
> IPTC, XMP, JFIF, GeoTIFF, ICC Profile, Photoshop IRB, FlashPix, AFCP
> and ID3, as well as the maker notes of many digital cameras by Canon,
> Casio, DJI, FLIR, FujiFilm, GE, GoPro, HP, JVC/Victor, Kodak, Leaf,
> Minolta/Konica-Minolta, Motorola, Nikon, Nintendo, Olympus/Epson,
> Panasonic/Leica, Pentax/Asahi, Phase One, Reconyx, Ricoh, Samsung,
> Sanyo, Sigma/Foveon and Sony.
[**exiftoolr**](https://CRAN.R-project.org/package=exiftoolr) wraps a
local installation of ExifTool, giving users easy access to its
functionality from within R. `exif_read()` can be used to read
metadata from one or many files into a `data.frame` with one column
per metadata field and one row per file. `exif_call()`, supports more
general calls to the underlying ExifTool utility, examples of which
are displayed [here][ExifTool-examples].
## Example
Here is a photo taken in the La Sal mountains of southeastern Utah,
USA.
Suppose you would like to annotate it with a bit of text indicating
the time and place at which the photo was taken. You could do that as
follows, using **exiftoolr** to extract the relevant data from the
file, and the
[**magick**](https://CRAN.R-project.org/package=magick) package to
annotate the image:
```{r, photo_annotation, eval = FALSE}
library(exiftoolr)
library(magick)
## Read and extract image metadata
dat <- exif_read("LaSals.jpg")
DateTime <- dat[["CreateDate"]]
Longitude <- dat[["GPSLongitude"]]
Latitude <- dat[["GPSLatitude"]]
## Prepare annotation text
txt <- paste0(DateTime, "\n",
"Longitude: ", round(Longitude, 5), "\n",
"Latitude: ", round(Latitude, 5))
## Annotate image and write to file
out <- image_annotate(image_read(infile), txt,
gravity = "northwest", color = "red",
boxcolor = adjustcolor("black", alpha=0.2),
size = 15, location = "+10+10")
image_write(out, "LaSals_annotated.jpg")
```
# Installation
To install **exiftoolr** from
[CRAN](https://CRAN.R-project.org/package=exiftoolr) do, as usual:
```{r, CRAN-installation, eval = FALSE}
install.packages("exiftoolr")
```
To install the most recent version from GitHub, do this:
```{r, gh-installation, eval = FALSE}
if(!require(devtools)) {install.packages("devtools")}
devtools::install_github("JoshOBrien/exiftoolr")
```
# Setup
**exiftoolr** can be configured to use an existing ExifTool
installation. Alternatively, run `install_exiftool()` once following
package installation to install a copy of ExifTool in the package's
directory tree, where calls to functions in the **exiftoolr** package
will automatically find it:
```{r, exiftool-installation, eval = FALSE}
exiftoolr::install_exiftool()
```
**exiftoolr** makes a reasonable attempt to find local copies of Perl
and ExifTool and, in most cases, will need no hints to find them. For
direct control over which Perl or ExifTool is used, set their paths
either with an explicit call to `configure_exiftool()` or with the
environment variables `"ET_PERL_PATH"` and `"ET_EXIFTOOL_PATH"`.
# Usage
`exif_read()` reads metadata from one or more image files, returning
the results in a plain `data.frame`:
```{r, example}
library(exiftoolr)
image_files <- dir(system.file("images", package = "exiftoolr"),
full.names = TRUE)
exifinfo <- exif_read(image_files)
dim(exifinfo)
names(exifinfo)[1:20] ## Display first 20 metadata fields read by ExifTool
```
To extract only those tags that are actually needed, use the `tags`
argument:
```{r}
exif_read(image_files, tags = c("filename", "imagesize"))
```
The `tags` argument also accepts simple regular expressions. For
instance, to extract all fields with names containing the substring
`"GPS"`, you could use the following call:
```{r}
exif_read(image_files[1], tags = "*GPS*")
```
To access more general ExifTool functionality (many examples of which
are shown [here][ExifTool-examples]), use the `exif_call()`
function. For example, the call just above, if run using
`exif_call()`, would look something like this:
```{r, eval=FALSE}
exif_call(args = c("-n", "-j", "-q", "-*GPS*"), path = image_files[1])
```
# Why another R package for reading image file metadata?
Several R packages can read EXIF metadata from image files. The
[**exif**](https://CRAN.R-project.org/package=exif) and
[**magick**](https://CRAN.R-project.org/package=magick) packages both
include functions (`exif::read_exif()`, and
`magick::image_attributes()`, respectively) that extract files' EXIF
data. Often, though, EXIF tags comprise only a subset of the metadata
in a file. Despite its name, ExifTool reads data stored in many
additional metadata formats.
The [**exifr**](https://CRAN.R-project.org/package=exifr) package --
also a thin wrapper around ExifTool -- is much more similar in the
functionality that it provides. The packages differ mainly in their
support for easy installation and configuration on all operating
systems. **exiftoolr**, in particular, was designed to make it as easy
for Windows users -- even those without Perl installations -- to
access ExifTool functionality as it is for *NIX and Mac
users. Relative to **exifr**, **exiftoolr** also makes it easier to
update ExifTool to its most current version.
[ExifTool-home]: https://exiftool.org/
[ExifTool-examples]: https://exiftool.org/examples.html