imageRename | R Documentation |
The function renames and copies raw camera trap images into a new location where they can be identified. Images are renamed with camera trap station ID, camera ID (optional), creation date and a numeric identifier for images taken within one minute of each other at a given station. Station ID and camera ID are derived from the raw image directory structure. The creation date is extracted from image metadata using ExifTool.
imageRename(
inDir,
outDir,
hasCameraFolders,
keepCameraSubfolders,
stationIDposition = NULL,
cameraIDposition = NULL,
createEmptyDirectories = FALSE,
copyImages = FALSE,
writecsv = FALSE
)
inDir |
character. Directory filepath containing 'Station' directories.
It must either contain images in species subdirectories (e.g.
"inDir/StationA/SpeciesA") or images with species metadata tags instead of
'Species' directories (e.g. "inDir/StationA"). Only include path up to
root/parent folder in which the 'Station'/'Site' subfolders are located
(e.g. "C:/Documents/CamProject" ...). 'Station' folders would be next in the
file path but are not included when defining |
outDir |
character. Directory to save .csv file to. If NULL and
|
hasCameraFolders |
Do the station directories in |
keepCameraSubfolders |
logical. Should camera directories be preserved as
subdirectories of |
stationIDposition |
integer. The numeric position within the
filepath/directory structure of the 'Station' directories (e.g.
"C:/Documents/CamProject/Region/Site/Transect/Station/Camera/Species/...",
the 'Station' directory position = 6).Only need to use this argument when
information from one or more directories (i.e. folders) before the 'Station'
level directory are to be used to populate columns within the record table
(e.g. "SurveyPeriod/Region/Site/Transect/Station/..."). If this argument is
missing, the function assumes the 'Station' directory is next in the
filepath as specified in |
cameraIDposition |
integer. The numeric position of the 'Camera'
directories within the filepath/directory structure (e.g.
"C:/Documents/CamProject/Region/Site/Transect/Station/Camera/Species,...",
the camera ID directory position = 7). Only need to use this argument when
|
createEmptyDirectories |
logical. If station or camera directories are
empty, should they be copied nevertheless (causing empty directories in
|
copyImages |
logical. Copy images to |
writecsv |
logical. Save a data frame with a summary as a .csv? |
Setting up the correct raw image directory structure is necessary for running
the function successfully. inDir
is the main directory that contains
camera trap station subdirectories (e.g. inDir/StationA). If one camera was
deployed per station and no camera subdirectories are used within station
directories, hasCameraFolders
can be set to FALSE
. If more than
one camera was deployed at stations, there must be subdirectories for the
individual camera traps within the station directories (e.g.
"inDir/StationA/CameraA1" and "inDir/StationA/CameraA2"). Even if only some
stations had multiple cameras, all station will need camera subdirectories.
The argument hasCameraFolders
must be TRUE
. Within the camera
subdirectories, the directory structure is irrelevant.
Renaming of images follows the following pattern: If hasCameraFolders
is TRUE, it is: "StationID__CameraID__Date__Time(Number).JPG", e.g.
"StationA__CameraA1__2015-01-31__18-59-59(1).JPG". If hasCameraFolders
is FALSE, it is: "StationID__Date__Time(Number).JPG", e.g.
"StationA__2015-01-31__18-59-59(1).JPG".
The purpose of the number in parentheses is to prevent assigning identical
file names to images taken at the same station (and camera) in the same
second, as can happen if cameras take sequences of images. It is a consecutive
number given to all images taken at the same station by the same camera within
one minute. The double underscore "__" in the image file names is for
splitting and extracting information from file names in other functions (e.g.
for retrieving camera IDs in recordTable
if camera
subdirectories are not preserved (keepCameraSubfolders = FALSE
)).
The function finds all JPEG images and extracts the image timestamp from the
image metadata using ExifTool and copies the images (with new file names) into
outDir
, where it will set up a directory structure based on the station
IDs and, if required by keepCameraSubfolders = TRUE
, camera IDs (e.g.
outDir/StationA/ or outDir/StationA/CameraA1).
copyImages
can be set to FALSE to simulate the renaming and check the
file names of the renamed images without copying. If you are handling large
number of images (>e.g., 100,000), the function may take some time to run.
NOTE: This function assumes that camera folders, if present, are within the station folders.
A data.frame
with original directory and file names, new
directory and file names and an indicator for whether images were copied
successfully.
Phil Harvey's ExifTool http://www.sno.phy.queensu.ca/~phil/exiftool/
### "trial" run. create a table with file names after renaming, but don't copy images.
# first, find sample image directory in package directory:
wd_images_raw <- system.file("pictures/raw_images", package = "camtrapRdeluxe")
if (Sys.which("exiftool") != ""){ # only run this example if ExifTool is available
# because copyImages = FALSE, outDir does not need to be defined
renaming.table <- imageRename(inDir = wd_images_raw,
hasCameraFolders = FALSE,
copyImages = FALSE,
writecsv = FALSE
)
} else {
message("ExifTool is not available. Cannot test function")
}
## Not run:
# define image directories
# raw image location
wd_images_raw <- system.file("pictures/raw_images", package = "camtrapRdeluxe")
# destination for renamed images
wd_images_raw_renamed <- file.path(tempdir(), "raw_images_renamed")
if (Sys.which("exiftool") != ""){ # only run this example if ExifTool is available
# now we have to set outDir because copyImages = TRUE
renaming.table2 <- imageRename(inDir = wd_images_raw,
outDir = wd_images_raw_renamed,
hasCameraFolders = FALSE,
copyImages = TRUE,
writecsv = FALSE
)
}
list.files(wd_images_raw_renamed, recursive = TRUE)
## End(Not run)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.