Extract metadata info from UAS images

Extracts info from geotagged images taken from a drone

Usage

uas_info(
  img_dirs,
  ext = c("jpg", "jpeg", "tif", "tiff", "raw", "dng")[1:4],
  pattern = 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: File name extension(s)
pattern: A regex expression for files
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

An Image Collection Metadata 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 flight metadata.

Details

This will read the EXIF data from one or more directory(s) of image files and return a list of Image Collection Metadata' object(s) for each directory. The metadata objects will include the centroids of each image, and auto-generated flight metadata. Depending on the arguments used, the metadata objects may also include the estimated ground-footprints of individual images, and custom flight metadata fields (such as the name of the pilot). Extracting image locations requires that the images have embedded coordinates, also called geostamps. This is common with drone images, but some drone platforms require an extra processing step to geostamp the images.

An Image Collection Metadata object requires that all images be from the same sensor (camera). It is ok to have collections with different sensors in a single 'uas_info' object, but each individual collection should be from the same sensor. If you have a directory with mixed images from multiple sensors, there are two arguments you can use to specify which ones to include in the Metadata object. ext should be used to specify the image filename extensions (e.g., 'jpg' or 'tiff'). This will also prevent non-image files, such as text files or videos, from being read. pattern can be used to specify a regex expression that image filenames must match as an additional requirement. Neither ext nor pattern are case sensitive.

To include estimated footprints in the metadata object, pass fp = TRUE. This further requires that 1) the camera parameters are known (see below), and 2) the flight altitude above ground level is either recorded in the EXIF info or provided by alt_agl (in meters). If alt_agl is passed, it will override any altitude data in the EXIF info. Ground-footprints are estimates only. The modeled footprints assume the camera was at nadir (common in mapping work but there are exceptions), and that the above ground altitude is the same as the above launch point altitude (generally true in flat areas, but not hilly areas). Estimated footprints are also only as accurate as the above-launch point altitude recorded in the EXIF data (which is typically the least accurate of the xyz coordinates).

Camera parameters are saved in a csv file called cameras.csv. The package ships with a CSV file containing the parameters for 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 author to add your camera to the database.

uas_info 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/. If you're on Windows, after you download it you should rename the executable file from exiftool(-k).exe to exiftool.exe, and save it somewhere on your system's PATH (e.g., c:\Windows).

If you installed EXIFtool using the exiftoolr package on Windows, and the output includes strange -- press ENTER -- statements, you can ignore them. These messages are generated by the exiftool executable. To get rid of them, find the exiftool executable (try tools::R_user_dir("exiftoolr")) and rename the exiftool(-k).exe' file to 'exiftool.exe' (if you don't see the '.exe.' extensions in File Explorer, you probably have file extensions hidden).

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 saved in the same directory (for details on how to write a pattern expression, see list.files). This is the recommended way to enter metadata, because the little metadata text files move with the images.

If multiple metadata text files match the pattern expression, they will all be read. This allows you for example to have a boilerplate 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.