MapTime—ArcGIS AllSource

Summary

The MapTime object provides access to time management operations when time-enabled layers are displayed in a MapFrame on a Layout.

Discussion

The MapTime class allows you to filter features in a map using a number of available time settings that correspond to controls on the Time tab and the Time Slider on an activated map frame on a layout in ArcGIS AllSource. Changing map time properties only applies to a map associated with a MapFrame on a Layout and currently is not applied to a map view.

The currentStartTime and currentEndTime properties are used to specify a time span. The timeInclusion property controls whether features are included within a time span. The property is set using the setTimeInclusion method.

Tip:

The currentStartTime property cannot be greater than the currentEndTime property. Conversely, the currentEndTime property cannot be less than the currentStartTime property. If you are changing to a new future time span, it is best to set currentEndTime before setting currentStartTime.

The timeStep method can be used to calculate new currentStartTime and currentEndTime values. To create a temporal map series, use the timeStep method to iterate through time values. For a code sample, see example 3 below.

Time can be enabled on newly added layers to a map frame's map, allowing you to perform time analysis, create temporal map books, and so on. For code samples, see examples 2 and 3 below.

Properties

Property	Explanation	Data Type
currentTimeEnd (Read and Write)	The current end date and time for a map frame's current time span.	DateTime
currentTimeSpan (Read Only)	The current time span that represents the difference between start and end times for a map frame's time span.	Double
currentTimeSpanUnits (Read Only)	A string representing the units for the currentTimeSpan value. The supported values are as follows: MILLISECONDS SECONDS MINUTES HOURS DAYS WEEKS MONTHS YEARS DECADES CENTURIES	String
currentTimeStart (Read and Write)	The current start date and time for a map frame's time span.	DateTime
isTimeEnabled (Read and Write)	A Boolean that determines whether time is enabled for a map frame. The isTimeEnabled property must be True to modify the other MapTime properties. Time can be disabled for a map frame even if the map frame contains time-enabled layers.	Boolean
timeInclusion (Read Only)	A string that controls whether the currentTimeStart and the currentTimeEnd are included in the current time span. The valid list of values are as follows: EXCLUDE_START_AND_END INCLUDE_ONLY_END INCLUDE_ONLY_START INCLUDE_START_AND_END	String
timeStepInterval (Read Only)	Indicates the time the start and end times will be offset by on each time step.	Double
timeStepIntervalUnits (Read Only)	The units used by timeStepInterval. A list of valid values are as follows: MILLISECONDS SECONDS MINUTES HOURS DAYS WEEKS MONTHS YEARS DECADES CENTURIES	String

Method Overview

Method	Explanation
setTimeInclusion (time_inclusion)	The setTimeInclusion method controls how the currentTimeStart and the currentTimeEnd are included in the current time span.
timeStep (reference_time, interval, interval_units)	The timeStep method returns a new time based on a given reference time and a time interval.

Methods

setTimeInclusion (time_inclusion)

Parameter	Explanation	Data Type
time_inclusion	A string that specifies a valid time inclusion value. INCLUDE_START_AND_END—Include both start and end times. INCLUDE_ONLY_START—Include start time, exclude end time. INCLUDE_ONLY_END—Exclude start time, include end time. EXCLUDE_START_AND_END—Exclude both start and end times.	String

The data displayed based on the currentTimeStart and currentTimeEnd values can be further modified by excluding one or both values in the time span—for example, if you are displaying a time span of one year where the start time is 1/1/2020 and the end time is 1/1/2021. If you do not want data from 1/1/2021 to be included in any analysis, you would set time_inclusion to be INCLUDE_ONLY_START.

timeStep (reference_time, interval, interval_units)

Parameter	Explanation	Data Type
reference_time	A Python DateTime object. The interval and interval_units will be added to the reference_time. Tip: The reference_time can be any Python DateTime object. For example, you can set the reference_time to be the currentStartTime or currentEndTime values.	DateTime
interval	A double that defines a time interval. Tip: Positive or negative intervals can be used.	Double
interval_units	A string that specifies a valid interval unit. MILLISECONDS—Milliseconds SECONDS—Seconds MINUTES—Minutes HOURS—Hours DAYS—Days WEEKS—Weeks MONTHS—Months YEARS—Years DECADES—Decades CENTURIES—Centuries	String

Return Value

Data Type	Explanation
DateTime	The new DateTime value calculated from the reference_time, interval, and interval_units.

The timeStep method returns a new time based on a given reference time and a time interval. The Python datetime object that is returned from the timeStep method can be used to set the currentTimeEnd and currentTimeStart properties. To create a temporal map series, use the timeStep method to iterate through time values.

Code sample

MapTime example 1

The following script sets the initial start and end times for the map frame and then iterates over one-month intervals for a year. Each month is exported to a PDF file.

import arcpy, os
path = r"C:\Projects\Time\Ships"

#Reference a project, layout, and a map frame
p = arcpy.mp.ArcGISProject(os.path.join(path, "ships.aprx"))
lyt = p.listLayouts('ships')[0]
mf = lyt.listElements('MAPFRAME_ELEMENT', 'ShipsWithTimeMF')[0]

if not mf.time is None:
  #Get the map frame time, set the initial time window and inclusion settings
  t = mf.time
  t.currentTimeStart = datetime.datetime(1776, 1, 1, 0, 0)
  t.currentTimeEnd = datetime.datetime(1776, 2, 1, 0, 0)
  t.setTimeInclusion('INCLUDE_ONLY_START')

  for x in range(1,13):
    #Export to PDF
    outPDF = os.path.join(path, "Output", f"1776-{x}.pdf")
    lyt.exportToPDF(outPDF)
    
    #Change the time window to the next 1 month interval
    t.currentTimeStart = t.timeStep(t.currentTimeStart, 1, "months")
    t.currentTimeEnd = t.timeStep(t.currentTimeEnd, 1, "months")

MapTime example 2

The following script adds a time-aware layer from a layer file to a map frame's map. In this workflow, the map frame is not time aware. The script then zooms to the extent of the added layer. Time is enabled on the map frame by setting isTimeEnabled to True. Finally, the script defines an initial time span by setting currentStartTime, currentEndTime, and setTimeInclusion.

import arcpy, os
path = r"C:\Projects\Time\Ships"

#Reference a project, layout, and a map frame
p = arcpy.mp.ArcGISProject(os.path.join(path, "ships.aprx"))
lyt = p.listLayouts('Ships')[0]
mf = lyt.listElements('MAPFRAME_ELEMENT', 'NoTimeMF')[0]

#Reference the map frame's map and add a time enabled layer from a layerfile
m = mf.map
m.addDataFromPath(os.path.join(path, "ShipPositions.lyrx"))

#Zoom to the layer
l = m.listLayers()[0]
mf.camera.setExtent(mf.getLayerExtent(l))

#Enable time on the map and set its time window
mt = mf.time
mt.isTimeEnabled = True
mt.currentTimeEnd = datetime.datetime(1900, 1, 1, 0, 0)
mt.currentTimeStart = datetime.datetime(1800, 1, 1, 0, 0)
mt.setTimeInclusion('INCLUDE_ONLY_START')

#Export the layout
lyt.exportToPDF(os.path.join(path, output, "ShipPositions_1800s.pdf"))

MapTime example 3

The following script adds a time-aware layer from a layer file to a map frame's map. Time is then enabled on the layer and the map. The timeStep method is used to iterate through a series of time spans. Each time span is exported to a PDF file. To create a complete map book experience, the PDFDocument class is used to add a title page and end page to the temporal map book.

import arcpy, os

basedir = r"C:\Project\Time"

# Create the output pdf file 
pdfPath = os.path.join(basedir, "output", "HistoricalBoundaries.pdf")
pdfDoc = arcpy.mp.PDFDocumentCreate(pdfPath)

# Reference project, layout, map frame and map
aprx = arcpy.mp.ArcGISProject(os.path.join(basedir, "Tokyo.aprx"))
layout = aprx.listLayouts('Historical Boundaries')[0]
mfTokyo = layout.listElements('MAPFRAME_ELEMENT', 'Tokyo Map Frame')[0]
mTokyo = mfTokyo.map

# Add a layer that contains time values to the map
lyrTokyo = mTokyo.addLayer(arcpy.mp.LayerFile(os.path.join(basedir, 'Tokyo_Historic_Boundaries.lyrx')), 'TOP')[0]

# Enable time on the newly added layer
lyrTokyo.enableTime(startTimeField='Year', endTimeField='YearEnd')

# Enable Map Time
mtTokyo = mfTokyo.time
mtTokyo.isTimeEnabled = True

# Access Map Time properties for use in the MapTime.timeStep() method
interval = mtTokyo.currentTimeSpan
unit = mtTokyo.currentTimeSpanUnits

# Use the MapTime.timeStep() method to get the first time span
start = lyrTokyo.time.startTime
end = mtTokyo.timeStep(start, interval, unit)

# Loop through time spans 
while end < lyrTokyo.time.endTime:
    
    # Update the map frame with the time span
    mtTokyo.currentTimeStart = start
    mtTokyo.currentTimeEnd = end
    
    # Export the time span to pdf
    output_pdf_file = os.path.join(basedir, "output", f"HistoricalBoundaries_{start.year}_to_{end.year}.pdf")
    layout.exportToPDF(os.path.join(basedir, "output", output_pdf_file))
    
    # Appened the time step pdf to the output pdf
    pdfDoc.appendPages(output_pdf_file)
    
    # Use the MapTime.timeStep() method to proceed to the next time span
    start = end
    end = mtTokyo.timeStep(end, interval, unit)    

# Add title and end pages to create a complete map book
pdfDoc.insertPages(os.path.join(basedir, 'Title Page.pdf'), 1)
pdfDoc.appendPages(os.path.join(basedir, 'End Page.pdf'))

# Save the output pdf      
pdfDoc.saveAndClose()

Feedback on this topic?

Summary

Discussion

Tip:

Properties

Method Overview

Methods

Tip:

Tip:

Code sample

In this topic