Change the values of digital timestamps in image metadata using ExifTool. If date/time of images were set incorrectly, they can be corrected easily in batch mode for further analyses. Please, always make a backup of your data before using this function to avoid data loss or damage. This is because ExifTool will make a copy of your images and applies the time shifts to the copies. The file extension of the original images (.JPG) will be renamed to ".JPG_original".
timeShiftImages(
inDir,
hasCameraFolders,
timeShiftTable,
stationCol,
cameraCol,
timeShiftColumn,
timeShiftSignColumn,
undo = FALSE,
ignoreMinorErrors = FALSE
)character. Name of directory containing station directories with images
logical. Do the station directories in inDir
have camera subdirectories (e.g. "inDir/StationA/Camera1")?
data.frame containing information about station-/camera-specific time shifts.
character. name of the column specifying Station ID in
timeShiftTable
character. name of the column specifying Camera ID in
timeShiftTable (optional)
character. The name of the column containing time
shift values in timeShiftTable
character. The name of the column with the
direction of time shifts in timeShiftTable. Can only be "-" or "+".
logical. Undo changes and restore the original images? Please be
careful, this deletes any edited images if TRUE
logical. Ignore minor errors that would cause the function to fail (set TRUE for images with bad MakerNotes, observed in Panthera V4 cameras)
A data.frame containing the information about the processed
directories and the number of images.
timeShiftTable is a data frame with columns for station ID, camera ID
(optional), time shift value and direction of time shift (for an example see
timeShiftTable). Images in inDir must be sorted into
station directories. If hasCameraFolders = TRUE, the function expects
camera subdirectories in the station directories and will only apply time
shifts to the camera subdirectories specified by CameraCol in
timeShiftTable. If hasCameraFolders = FALSE, shifts will be
applied to the whole station directory (including potential subdirectories).
The values of timeShiftColumn must adhere to the following pattern:
"YYYY:mm:dd HH:MM:SS" ("year:month:day hour:minute:second"). Examples:
"1:0:0 0:0:0" is a shift of exactly 1 year and "0:0:0 12:10:01" 12 hours and
10 minutes and 1 second. Note that stating "00" may cause problems, so use
"0" instead if an entry is zero.
timeShiftSignColumn signifies the direction of the time shift. "+"
moves image dates into the future (i.e. the image date lagged behind the
actual date) and "-" moves image dates back (if the image dates were ahead
of actual time).
ExifTool stores the original images as .JPG_original files in the
original file location. By setting undo = TRUE, any JPG files in the
directories specified by timeShiftTable will be deleted and the
original JPEGs will be restored from the JPG_original files. Please make a
backup before using undo.
Years can have 365 or 366 days, and months 28 to 31 days. Here is how the function handles these (from the exiftool help page): "The ability to shift dates by Y years, M months, etc, conflicts with the design goal of maintaining a constant shift for all time values when applying a batch shift. This is because shifting by 1 month can be equivalent to anything from 28 to 31 days, and 1 year can be 365 or 366 days, depending on the starting date. The inconsistency is handled by shifting the first tag found with the actual specified shift, then calculating the equivalent time difference in seconds for this shift and applying this difference to subsequent tags in a batch conversion."
ignoreMinorErrors is useful if image timestamps are not updated
correctly (entries in column "n_images" of the output are "... files weren't
updated due to errors"). This can be caused by bad MakerNotes and so far was
only observed in Panthera V4 and V6 cameras. In that case, set
ignoreMinorErrors to TRUE. This will add the "-m" option to
the Exiftool call, thereby ignoring minor errors and warnings and applying
the time shift nevertheless.
if (FALSE) {
# copy sample images to temporary directory (so we don't mess around in the package directory)
wd_images_ID <- system.file("pictures/sample_images_species_dir", package = "camtrapR")
file.copy(from = wd_images_ID, to = tempdir(), recursive = TRUE)
wd_images_ID_copy <- file.path(tempdir(), "sample_images_species_dir")
data(timeShiftTable)
timeshift_run <- timeShiftImages(inDir = wd_images_ID_copy,
timeShiftTable = timeShiftTable,
stationCol = "Station",
hasCameraFolders = FALSE,
timeShiftColumn = "timeshift",
timeShiftSignColumn = "sign",
undo = FALSE
)
timeshift_undo <- timeShiftImages(inDir = wd_images_ID_copy,
timeShiftTable = timeShiftTable,
stationCol = "Station",
hasCameraFolders = FALSE,
timeShiftColumn = "timeshift",
timeShiftSignColumn = "sign",
undo = TRUE
)
}