Extracts info from geotagged images taken from a drone
Usage
uas_info(
img_dirs,
ext = NULL,
alt_agl = NULL,
fp = FALSE,
fwd_overlap = fp,
cameras = NULL,
metadata = "metadata.*\\.txt",
path2name_fun = NULL,
use_exiftoolr = TRUE,
exiftool = NULL,
exif_csv = NULL,
cache = TRUE,
update_cache = FALSE,
quiet = FALSE
)Arguments
- img_dirs
Directory(s) where the image files reside
- ext
An optional file extension
- alt_agl
The elevation above ground level in meters (optional for images with the relevative altitude saved)
- fp
Compute image foot prints, T/F
- fwd_overlap
Whether or not to compute the amount of overlap between one image and the next, T/F
- cameras
Location of the cameras.csv file. Is NULL the package csv file will be used.
- metadata
A filename pattern for a metadata file, or a metadata list object (see Details)
- path2name_fun
A function to generate the default short name (see Details)
- use_exiftoolr
Whether to use the exiftoolr package, logical
- exiftool
The path to the exiftool command line tool (omit if on the OS path). Ignored if use_exiftoolr = TRUE.
- exif_csv
The file name of a new csv file where the exif data will be saved (omit to make a temp one)
- cache
Logical or a directory where EXIF data should be cached (see Details)
- update_cache
Whether to update the cache
- quiet
Don't show messages
Value
A UAS Image Collection object. This is a named list with elements for image centroids (as a sf data frame), footprints, total area, minimum convex polygon, total directory size, the data flown, and external metadata.
Details
This will read the EXIF header data from a directory of image files, and extract
the centroids and estimated ground-footprints. Extracting the image locations requires that the images have
geostamps (common in most drone images but some drones require an extra processing step to geostamp the images).
To index a specific file type, you can pass a file extension to ext (not case sensitive).
Estimating the ground-footprints (fp = TRUE) further requires that the camera parameters are known,
the flight elevation about ground level is either saved in the EXIF info or provided in
the alt_agl argument (in meters). If alt_agl is passed, it will override any elevation data
in the EXIF info. Ground-footprints are estimates only. They assume the camera was at nadir (common in
mapping work but there are exceptions) and only as accurate as the provided altitude (which is typically the least
accurate GPS coordinate).
Camera parameters are saved in a csv file called cameras.csv. The package ships with a CSV file containing
many popular drone cameras. If your drone camera is not in the database, you can create your own
cameras.csv file (see uas_cameras for details) and pass the file name as the
cameras argument. Or contact the package maintainer
to add your camera to the database.
This function uses a free command line tool called EXIFtool to read the EXIF data. You can install this by
running install_exiftool. Alternately you can download exiftool
from http://www.sno.phy.queensu.ca/~phil/exiftool/. After you download it, rename the executable file,
'exiftool(-k).exe' to 'exiftool.exe', and save it somewhere on your system's PATH (e.g., c:\Windows).
metadata is an optional argument to pass supplemental flight metadata that can not be extracted from the
images (e.g., location name, pilot). For details, see the Vignette on Flight Metadata
vignette("flight_metadata", package = "uasimg").
metadata can also be a named list containing
metadata fields / values. For supported field names, see vignette("flight_metadata", package = "uasimg").
metadata can also be a filename regular expression (pattern) for a metadata text file
(for details on how to write a pattern expression, see list.files). This is the recommended
way to enter metadata, because the little text files move with the images.
If multiple files match the pattern expression, they will all be read. This allows you for example to have a file called
metadata_org.txt with organizational info (such as a contact person), and another called metadata.txt with info
about that specific flight (e.g., the pilot or wind conditions).
Metadata text files should be plain text in YAML format (the easiest way to create new metadata text files
is using uas_metadata_make.) Each line should contain a key:value pair (with no quotes or delimiters).
Lines starting with a hash or forward slash will be ignored. Example:
name_short: hrec_wtrshd2_flt03
name_long: Hopland Research and Extension Center, Watershed II Flight 3
data_url: https://ucdavis.box.com/s/dp0sdfssxxxxxsdf
pilot: Andy Lyons
description: These data were collected as part of a restoration monitoring program.
notes: We had to pause the mission about half way through as a hawk was getting close, hence there is a time lapse
of about 45 seconds. Pix4Dcapture was used as the mission planning software with an overlap of 75
path2name_fun can be a function to generate a default short name for the flight. The function should
be written to accept one and only one argument - a directory path. This can be useful if the default
short names should be constructed from pieces of the image directory path. See also uas_path2name_fun.
cache can be a logical value or the name of a directory where EXIF data gets cached.
If cache = TRUE, the default cache directory will be used (~/.R/uasimg). The only information
that gets cached is image metadata. Flight metadata is never cached (see the Vignette on Flight Metadata
for a discussion of image and flight metadata). Cached EXIF data is linked
to a directory of images based on the directory name and total size of all image files.
So if images are added or removed from the directory, the cache will be automatically rebuilt
the next time the function is run. update_cache is a logical value
which forces an update of cached data when TRUE.