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 uses the EsriTimeDelta class. The EsriTimeDelta class is an alternative to the core python datetime.timedelta and uses internal Esri time units for intervals that can't be handled by the core python timedelta object (such as months, weeks, etc.) The timeStepInterval can be used to loop through dates and times. If you want to use a different time interval within a loop, create a new python timedelta object or an EsriTimeDelta object (see example 3 below). Be aware that if the timeWindowUnits are modified and saved, it will affect the timeStepInterval.
To embed a time stamp within an image when exporting a data frame, use time text.
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) | 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) | 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) | 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 EsriTimeDelta object and is used to iterate over a period of time (e.g., 2 days, 1 month, and so on). | EsriTimeDelta |
timeWindow (Read and Write) | 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) | 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
resetTimeExtent ()
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
DataFrameTime example 1
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
import os
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, os.path.join(r"C:\Project\Output", fileName), df)
df.time.currentTime = df.time.currentTime + df.time.timeStepInterval
del mxd
DataFrameTime example 2
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. Alternatively, the EsriTimeDelta class could also be used to create time deltas.
import arcpy
import datetime
import os
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, os.path.join(r"C:\Project\Output", fileName), df)
df.time.currentTime = df.time.currentTime + interval
del mxd
DataFrameTime example 3
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. In this example, the time interval is set using the EsriTimeDelta class. Alternatively, the Python datetime module could be used to create the time delta.
import arcpy
import datetime
import os
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 = arcpy.time.EsriTimeDelta(1, 'weeks')
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, os.path.join(r"C:\Project\Output", fileName))
df.time.currentTime = df.time.currentTime + interval
del mxd, timeLayer