| 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 field from the input table that indicates when each row was captured or created. The field must be of type date; it cannot be of type string or numeric. | Field |
Output Table
| The output table containing the object ID values from the input table that match a photo, and the matching photo path. Only object ID values from the input table that 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) |
| 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 value 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. A new table is created that contains the object ID values from the input rows and their matching photo paths. You can also use this tool to add 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 the following 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 by the Time Difference Unit parameter.
While shapefile and dBASE data are supported for the input table, it is recommended that you 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 value (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 object ID value of the input. When the output table has multiple rows with the same IN_FID field value (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 of type date. To convert text or numeric fields to a field of type date, 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, 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, and 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 the number of 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 field from the input table that indicates when each row was captured or created. The field must be of type date; it cannot be of type string or numeric. | Field |
Output_Table | The output table containing the object ID values from the input table that match a photo, and the matching photo path. Only object ID values from the input table that 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 whether the photo files will be added to the rows of the input table as geodatabase attachments. Note:Adding attachments requires that the output feature class be in a version 10 or later 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 value of 15. | Double |
Code sample
The following Python window snippet demonstrates how to use the MatchPhotosToRowsByTime function.
import arcpy
arcpy.management.MatchPhotosToRowsByTime(
"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 function.
"""
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
# Run MatchPhotosToRowsByTime and JoinField
arcpy.management.MatchPhotosToRowsByTime(inFolder, inFC, timeField, outTable,
outUnmatched, attachmentsOption,
timeDiff, timeOffset)
arcpy.management.JoinField(inFC, "OBJECTID", outTable, "IN_FID",
["Photo_Path", "Photo_Name", "Match_Diff"])