| Label | Explanation | Data Type |
Input Folder
| The folder where photo files (.jpg or .tif) are located. This folder is scanned recursively for photo files; any photos in the base level of the folder, as well as in any subfolders, will be added to the output. | Folder |
Input Table
| The table or feature class whose rows will be matched with photo files. The input table will typically be a point feature class representing GPS recordings. | Table View |
Time Field
| The date/time field from the input table that indicates when each row was captured or created. Must be a date field; cannot be a string or numeric field. | Field |
Output Table
| The output table containing the OBJECTIDs from the input table that match a photo, and the matching photo path. Only OBJECTIDs from the input table that are found to match a photo are included in the output table. | Table |
Unmatched Photos Table
(Optional) | The optional output table that will list any photo files in the input folder with an invalid time stamp or any photos that cannot be matched because there is no input row within the time tolerance. If no path is specified, this table will not be created. | Table |
Add Photos As Attachments (Optional) | Specifies if photo files will be added to the rows of the input table as geodatabase attachments. The input table must be stored in a version 10 or later geodatabase for photo files to be added as attachments.
| Boolean |
Time Tolerance
(Optional) | The maximum difference (in seconds) between the date/time of an input row and a photo file that will be matched. If an input row and a photo file have time stamps that are different by more than this tolerance, no match will occur. To match a photo file to a row with the closest time stamp, regardless of how large the date/time difference might be, set the tolerance to 0. The sign of this value (- or +) is irrelevant; the absolute value of the number specified will be used. Do not use this parameter to adjust for consistent shifts or offsets between the times recorded by the GPS and the digital camera. Use the Clock Offset parameter, or the Convert Time Zone tool to shift the time stamps of the input rows to match those of the photos. | Double |
Clock Offset
(Optional) | The difference (in seconds) between the internal clock of the digital camera used to capture the photos and the GPS unit. If the clock of the digital camera is behind the clock of the GPS unit, use a positive value; if the clock of the digital camera is ahead of the clock of the GPS unit, use a negative value. For example, if a photo with a time stamp of 11:35:17 should match a row with a time stamp of 11:35:32, use a Clock Offset of 15. | Double |
Summary
Matches photo files to table or feature class rows according to the photo and row time stamps. The row with the time stamp closest to the capture time of a photo will be matched to that photo. Creates a new table containing the ObjectIDs from the input rows and their matching photo paths. Optionally adds matching photo files to the rows of the input table as geodatabase attachments.
Illustration
Usage
This tool can be used to match GPS-captured features to digital photographs taken at the same time the GPS feature was captured.
The output table will contain four attribute fields:
- IN_FID: The object ID of an input row whose time stamp matches the time stamp of a photo.
- Photo_Path: The full path to a photo file whose time stamp matches the time stamp of the input row identified in the IN_FID field.
- Photo_Name: The short name of the photo file.
- Match_Diff: The difference between the time stamps of a photo file and the matching input row. This numeric value is in the unit specified in the Time Difference Unit parameter.
While shapefile and dBASE data is supported for the input table, it is recommended to use geodatabase data, because a Date field in a shapefile or dBASE table cannot store both date and time information.
Since a single input row may have a time stamp that matches the time stamp of multiple photographs, the output table may have multiple rows that have the same IN_FID (each row in the output refers to a match between one photo and one input row).
The output table can be joined to the input table using the output IN_FID field and the OBJECTID of the input. In the case where the output table has multiple rows with the same IN_FID (one input row matches multiple photos), use a relate or a relationship class to link the output to the input.
The time field must be type Date. To convert your text or numeric fields to a Date field, use the Convert Time Field tool.
Even if a GPS point and a digital photograph are captured at exactly the same time, the times recorded by the devices may be in different time zones. For example, GPS devices often record times in Coordinated Universal Time (UTC), or Greenwich Mean Time (GMT), while digital cameras often record times in a local time zone. To reconcile time-stamp differences resulting from different time zones, use the Convert Time Zone tool to change the time field of the input table to match the time zone of the photo file time stamp.
Likewise, the clock of the GPS may be out of sync with the clock of the digital camera. To make a good match between the photo and GPS point when these clocks are out of sync, determine the difference between the two clocks, then use this value with the Clock Offset parameter.
The Time Tolerance and Clock Offset parameters must be specified in seconds. There are a number of utilities on the Internet for calculating how many seconds a different unit of time equals. For example, 3 minutes and 12 seconds is equal to 192 seconds.
Parameters
arcpy.management.MatchPhotosToRowsByTime(Input_Folder, Input_Table, Time_Field, Output_Table, {Unmatched_Photos_Table}, {Add_Photos_As_Attachments}, {Time_Tolerance}, {Clock_Offset})| Name | Explanation | Data Type |
Input_Folder | The folder where photo files (.jpg or .tif) are located. This folder is scanned recursively for photo files; any photos in the base level of the folder, as well as in any subfolders, will be added to the output. | Folder |
Input_Table | The table or feature class whose rows will be matched with photo files. The input table will typically be a point feature class representing GPS recordings. | Table View |
Time_Field | The date/time field from the input table that indicates when each row was captured or created. Must be a date field; cannot be a string or numeric field. | Field |
Output_Table | The output table containing the OBJECTIDs from the input table that match a photo, and the matching photo path. Only OBJECTIDs from the input table that are found to match a photo are included in the output table. | Table |
Unmatched_Photos_Table (Optional) | The optional output table that will list any photo files in the input folder with an invalid time stamp or any photos that cannot be matched because there is no input row within the time tolerance. If no path is specified, this table will not be created. | Table |
Add_Photos_As_Attachments (Optional) | Specifies if photo files will be added to the rows of the input table as geodatabase attachments. License:Adding attachments requires at minimum an ArcGIS Desktop Standard license, and the output feature class must be in a version 10 or higher geodatabase.
| Boolean |
Time_Tolerance (Optional) | The maximum difference (in seconds) between the date/time of an input row and a photo file that will be matched. If an input row and a photo file have time stamps that are different by more than this tolerance, no match will occur. To match a photo file to a row with the closest time stamp, regardless of how large the date/time difference might be, set the tolerance to 0. The sign of this value (- or +) is irrelevant; the absolute value of the number specified will be used. Do not use this parameter to adjust for consistent shifts or offsets between the times recorded by the GPS and the digital camera. Use the Clock Offset parameter, or the Convert Time Zone tool to shift the time stamps of the input rows to match those of the photos. | Double |
Clock_Offset (Optional) | The difference (in seconds) between the internal clock of the digital camera used to capture the photos and the GPS unit. If the clock of the digital camera is behind the clock of the GPS unit, use a positive value; if the clock of the digital camera is ahead of the clock of the GPS unit, use a negative value. For example, if a photo with a time stamp of 11:35:17 should match a row with a time stamp of 11:35:32, use a Clock Offset of 15. | Double |
Code sample
The following Python window snippet demonstrates how to use the MatchPhotosToRowsByTime tool.
import arcpy
arcpy.MatchPhotosToRowsByTime_management(
"c:/data/photos", "c:/data/city.gdb/gps_points", "DateTime",
"c:/data/city.gdb/output_table", "", "ADD_ATTACHMENTS", "", 20)The following script demonstrates how to use the MatchPhotosToRowsByTime tool.
"""
Name: GeoTaggedPhotosToPoints example
Description: Find the points that match photo time stamps, then join the output table
to the input to see which photos match which points
"""
# Import system modules
import arcpy
# Set environment settings
arcpy.env.workspace = "C:/data"
# Set local variables
inFolder = "photos"
inFC = "city.gdb/gps_points"
timeField = "DateTime"
outTable = "city.gdb/output_table"
outUnmatched = "city.gdb/unmatched_photos"
attachmentsOption = "ADD_ATTACHMENTS"
timeDiff = 0
timeOffset = 20
# Execute MatchPhotosToRowsByTime and JoinField
arcpy.MatchPhotosToRowsByTime_management(inFolder, inFC, timeField, outTable,
outUnmatched, attachmentsOption,
timeDiff, timeOffset)
arcpy.JoinField_management(inFC, "OBJECTID", outTable, "IN_FID",
"Photo_Path;Photo_Name;Match_Diff")