camtrapR (version 3.0.0)

imageRename: 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,
  createEmptyDirectories = FALSE,
  copyImages = FALSE,
  writecsv = FALSE,
  video
)

Value

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

Arguments

inDir

character. Directory containing camera trap images sorted into station subdirectories (e.g. inDir/StationA/)

outDir

character. Directory into which the renamed images will be copied

hasCameraFolders

logical. 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")?

createEmptyDirectories

logical. If station or camera directories are empty, should they be copied nevertheless (causing empty directories in outDir, but preserving the whole directory structure)?

copyImages

logical. Copy images to outDir?

writecsv

logical. Save a data frame with a summary as a .csv? The csv will be saved in outDir.

video

list. Contains information on how to handle video data (optional). See details.

Author

Juergen Niedballa

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 (optionally, also videos) and extracts the image timestamp from the image metadata using ExifTool (digiKam database for videos) 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.

Argument video is a named list 4 items (file_formats, dateTimeTag, (db_directory, db_filename). Video date/time is read from video metadata stored in the digiKam database. Hence, inDir must be in your digiKam database.

The items of argument video are:

file_formats	The video formats to extract (include "jpg" if you want .JPG image metadata)
dateTimeTag	the metadata tag to extract date/time from (use exifTagNames to find out which tag is suitable)
db_directory	The directory containing digiKam database
db_filename	The digiKam database file in db_directory

See the examples in recordTable for for how to specify the argument video.

References

Phil Harvey's ExifTool https://exiftool.org/

Examples

  if (FALSE) {
  
### "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 = "camtrapR")

# because copyImages = FALSE, outDir does not need to be defined
renaming.table <- imageRename(inDir               = wd_images_raw,     
                              hasCameraFolders = FALSE,
                              copyImages          = FALSE,
                              writecsv            = FALSE
  )


  
### a real example in which images are copied and renamed 

  # define raw image location
wd_images_raw <- system.file("pictures/raw_images", package = "camtrapR") 

  # define destination for renamed images
wd_images_raw_renamed <- file.path(tempdir(), "raw_images_renamed")       


  # now we have to define outDir because copyImages = TRUE
renaming.table2 <- imageRename(inDir               = wd_images_raw,
                               outDir              = wd_images_raw_renamed,       
                               hasCameraFolders    = FALSE,
                               copyImages          = TRUE,
                               writecsv            = FALSE
  )
  
  # show output files
  list.files(wd_images_raw_renamed, recursive = TRUE)
  
  # output table
  renaming.table2
  
  }