DataFrameTime
Summary
The DataFrameTime object provides access to time management operations for time-enabled layers in a data frame.
Discussion
The DataFrameTime object provides capabilities for two basic scenarios. The first scenario is for map documents that have already been published with time-enabled layers where settings were established via the Time Slider Options dialog box and saved with the map document. With this scenario, those existing properties can be used for automating output. Examples 1 and 2 below are examples for this first scenario. The second scenario deals with map documents that don't have any time-enabled layers but that time-enabled layers are added by a script and therefore the time slider options need to be set so that the desired output can be automated. Example 3 below represents this second scenario.
The timeStepInterval in arcpy.mapping is implemented slightly different than in the Time Slider Options within ArcMap so that it can be used more easily within loops as a timedelta object. In ArcMap the timeStepInterval is really built from two parameters: a double representing a length and a string that represents units. The property cannot be set due to potential problems with converting this arcpy.mapping timedelta property back into the appropriate double and string parameters found within the Time Slider Options dialog box. For this reason, timeStepInterval is a read-only property. If you want to use a different time interval within a loop then simply create a new timedelta object (see example 3 below). Be aware that if the timeWindowUnits are modified and saved, it will affect the timeStepInterval.
Currently, there is no option to embed a time stamp within an image when exporting a data frame. A suggested solution is to set the DataFrame_Class object to be the same size as the page layout and then insert a dynmic text element onto the page layout that represents the current time.
There are numerous help articles concerning time in ArcGIS. Here are a few that are most related to the methods and properties on the DataFrameTime object:
Properties
| Property | Explanation | Data Type |
| currentTime (Read and Write) |
Gets or sets the current date and time for a data frame with time-enabled layers. The same property can be found in the Time Slider Options dialog box in ArcMap. | DateTime |
| endTime (Read and Write) |
Gets or sets the end date and time for a data frame with time-enabled layers. The same property can be found in the Time Slider Options dialog box in ArcMap. | DateTime |
| startTime (Read and Write) |
Gets or sets the start date and time for a data frame with time-enabled layers. The same property can be found in the Time Slider Options dialog box in ArcMap. | DateTime |
| timeStepInterval (Read Only) |
Returns the time step interval that has been set via the Time Slider Options dialog box in ArcMap. This value is a Python timedelta object and is used to iterate over a period of time (e.g., 2 days, 1 month, and so on). | timedelta |
| timeWindow (Read and Write) |
Gets or sets the time window that controls how many units (e.g., days) of time-enabled data appear prior to and including the current time. For example, if timeWindow is set to 1 and timeWindowUnits is set to weeks, then the time window will be 2 weeks. | Double |
| timeWindowUnits (Read and Write) |
Gets or sets the units that are used with the TimeStepInterval and the TimeWindow properties. The valid units are:
| String |
Method Overview
| Method | Explanation |
| resetTimeExtent () |
Resets the time extent to the time window extent of all time-enabled layers in a data frame |
Methods
This performs the same operation as clicking the Min Time and Max Time buttons on the Time Slider Options dialog box in ArcMap.
Code Sample
The following script uses time settings (start time, end time, and time interval) published in an existing map document to export a series of images. Each output image is given a unique name using the parsed date information from the time stamp.
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "Traffic Analysis")[0]
df.time.currentTime = df.time.startTime
while df.time.currentTime <= df.time.endTime:
#An example str(newTime) would be: "2008-12-29 02:19:59"
#The following line splits the string at the space and takes the first
#item in the resulting string.
fileName = str(df.time.currentTime).split(" ")[0] + ".png"
arcpy.mapping.ExportToPNG(mxd, r"C:\Project\Output\\" + fileName, df)
df.time.currentTime = df.time.currentTime + df.time.timeStepInterval
del mxd
The following script is identical to example 1 above but uses a modified start time, end time, and interval that are different from the existing settings that were published in a time-enabled data frame within a map document. The Python datetime module is used to create times and time deltas.
import arcpy, datetime
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "Traffic Analysis")[0]
df.time.currentTime = datetime.datetime(2008, 10, 1)
endTime = datetime.datetime(2008, 10, 31)
interval = datetime.timedelta(days=7)
while df.time.currentTime <= endTime:
#An example str(newTime) would be: "2008-01-29 02:19:59"
#The following line splits the string at the space and takes the first
# item in the resulting string.
fileName = str(df.time.currentTime).split(" ")[0] + ".png"
arcpy.mapping.ExportToPNG(mxd, r"C:\Project\Output\\" + fileName, df)
df.time.currentTime = df.time.currentTime + interval
del mxd
The following script represents a scenario in which a new time-enabled layer file is added to a new data frame that is not time aware; therefore, the time slider properties are not set within the map document. This script adds a time-enabled layer to the data frame using the AddLayer function and then sets the appropriate time settings similar to the scripts above.
import arcpy, datetime
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "New Data Frame")[0]
timeLayer = arcpy.mapping.Layer(r"C:\Project\Data\Accidents.lyr")
arcpy.mapping.AddLayer(df, timeLayer, "AUTO_ARRANGE")
df.time.resetTimeExtent()
df.time.timeWindowUnits = "DAYS"
df.time.timeWindow = 7
df.time.currentTime = datetime.datetime(2008, 10, 1)
endTime = datetime.datetime(2008, 10, 31)
interval = datetime.timedelta(days=7)
while df.time.currentTime <= df.time.endTime:
#An example str(newTime) would be: "2008-01-29 02:19:59"
#The following line splits the string at the space and takes the first
# item in the resulting string.
fileName = str(df.time.currentTime).split(" ")[0] + ".png"
arcpy.mapping.ExportToPNG(mxd, r"C:\Project\Output\\" + fileName)
df.time.currentTime = df.time.currentTime + interval
del mxd, timeLayer