imageRename: Copy and rename images based on camera trap station ID and...

In carlopacioni/camtrapRdeluxe: A R package that builds on camtrapR to provide more functionalities and flexibility

Copy and rename images based on camera trap station ID and creation date

Description

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.

Usage

imageRename(
  inDir,
  outDir,
  hasCameraFolders,
  keepCameraSubfolders,
  stationIDposition = NULL,
  cameraIDposition = NULL,
  createEmptyDirectories = FALSE,
  copyImages = FALSE,
  writecsv = FALSE
)

Arguments

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 inDir.
outDir	character. Directory to save .csv file to. If NULL and writecsv = TRUE, recordTable will be written to inDir.
hasCameraFolders	Do the station directories in inDir have camera subdirectories (e.g. "inDir/StationA/Camera1")?
keepCameraSubfolders	logical. Should camera directories be preserved as subdirectories of outDir (e.g. "outDir/StationA/CameraA1")?
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 inDir.
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 cameraIDfrom = "directory" and there are one or more directories (i.e. folders) after the 'Species' level directory (e.g. "SurveyPeriod/Region/Site/Transect/Station/Species/Counts/...").
createEmptyDirectories	logical. If station or camera directories are empty, should they be copied nevertheless (causing empty directories in inDir, but preserving the whole directory structure)?
copyImages	logical. Copy images to outDir?
writecsv	logical. Save a data frame with a summary as a .csv?

Details

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.

Value

A data.frame with original directory and file names, new directory and file names and an indicator for whether images were copied successfully.

References

Phil Harvey's ExifTool http://www.sno.phy.queensu.ca/~phil/exiftool/

Examples

### "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)

carlopacioni/camtrapRdeluxe documentation built on Nov. 29, 2023, 3:37 a.m.