ArcGIS API for WPF - Time-aware layers

ArcGIS 10 includes support for time-aware layers, which store information about the changing state of a dataset over time. Time-aware layers allow you to step through periods of time, revealing patterns and trends in your data. For example, you can accomplish the following using time-aware layers:

Track hurricane paths and other meteorological events.
Explore historic patterns in data through time, such as population or land-use changes.
Monitor changes in well production or status.
Map the progression of a wildfire or flood.
Visualize the spread of disease over time.

When time-aware layers are present in an ArcGIS API for WPF application, the map is considered time aware and the map's time extent is set. The time extent defines the time period for which the layers' data is displayed in the map. Setting the map's time extent is similar to setting the spatial extent because once the time extent is set, the map display updates automatically to conform to the change. Each time the map's time extent is changed, all time-aware layers update to reflect the new extent.

There are several ways to work with time-aware layers. The simplest is to use the TimeSlider control in the Toolkit because it handles the process of updating the map's time extent for you. Alternatively, you can use the API to build applications that perform temporal queries, filter layers using time definitions, and set the map's time extent.

Making layers time-aware

To make your layers time-aware, use the Layer Properties dialog box in ArcMap by right-clicking the layer in ArcMap and choosing Properties. The Layer Properties dialog box is shown in the following screen shot.

Note:

The Time Field must be of type date.

The time information is preserved and accessible through a map service when you publish your map to ArcGIS Server. After publishing, you can work with a time-aware map or feature service using the ArcGISDynamicMapServiceLayer or FeatureLayer class to perform temporal queries and view changes in data over time.

For image services, time awareness is supported for mosaic datasets. Time information must be present in the attributes for the rasters that make up the mosaic dataset. To define time properties, use ArcMap or ArcCatalog and use the Defaults tab in the Mosaic Dataset Properties dialog box for the mosaic dataset. After publishing, you can work with the ArcGISImageServiceLayer to leverage time-aware content in your image service.

The Mosaic Dataset Properties dialog box is shown in the following screen shot:

All time-aware layers have a TimeExtent property that provides access to the TimeExtent class. The TimeExtent class provides detailed information about the layer's time properties including the time range and time reference. The following code snippet retrieves the time extent for a layer:

TimeExtent timeExtent = (MyMap.Layers["MyFeatureLayer"] as FeatureLayer).TimeExtent;

Creating dates and times to use with time-aware layers

When working with time-aware layers, you may need to create dates and times in WPF. The platform has a DateTime class to define a specific time and a TimeSpan class to define a duration. Either can be used when creating a time extent to apply to a map or to use to query a layer. When creating a new DateTime, always specify Coordinated Universal Time (UTC) for the time zone. UTC is a time standard based on atomic time and is functionally equivalent to Greenwich Mean Time (GMT). UTC is denoted by adding a "Z" to the end of the time string. For example, 2008-11-01T19:35:00.0000000Z represents Saturday, 01 Nov 2008 19:35:00 UTC.

If no time zone is specified, the ArcGIS Server REST API returns the date string without time zone information. If you use a date without a time zone in a temporal query, the time zone may default to the current local time. This can result in dates that are off by several hours. The following example illustrates how to create a new TimeExtent instance and define a start time using a UTC date:

TimeExtent timeExtent = new ESRI.ArcGIS.Client.TimeExtent(); 
timeExtent.Start = DateTime.Parse("2002-01-01T17:33:46.0000000",
                                  CultureInfo.CurrentCulture,
                                  DateTimeStyles.AdjustToUniversal);

Working with time in the ArcGIS API for WPF

The ArcGIS API for WPF provides a TimeSlider control in the Toolkit library (ESRI.ArcGIS.Client.Toolkit.dll) that simplifies the process of visualizing temporal data. Using the time slider, you can filter the map to display cumulative data up to a point in time, a single point in time, or data that falls within a time range. The benefit of using the time slider is that it handles setting the map's time extent, which filters time-aware layers to only display data for the current time extent.

To set up the time slider, add a time-aware map or feature service to the map using the ArcGISDynamicMapService or FeatureLayer class in XAML. Next, associate the value (time extent) of the TimeSlider with the time extent of the map using element binding. Then create the number of tics (or stops) the slider displays (requires code-behind).

In the following code example, a feature layer represents a feature service that contains earthquakes at a specific time and location. The TimeSlider's minimum and maximum values are bound to the start and end time for features in the layer. The map's time extent is bound to the value (time extent) of the TimeSlider. When the feature layer is initialized, it has the information it needs to establish intervals for the TimeSlider. The initialize event is used to calculate and apply time intervals.

<esri:Map x:Name="MyMap" TimeExtent="{Binding ElementName=MyTimeSlider, Path=Value}">
    <esri:ArcGISTiledMapServiceLayer ID="BaseLayer"
        Url="http://server.arcgisonline.com/ArcGIS/rest/services/ESRI_Imagery_World_2D/MapServer" />
    <esri:FeatureLayer ID="Earthquakes 1970 - 2004"
        Initialized="FeatureLayer_Initialized"
        Url="http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Earthquakes/Since_1970/MapServer/0" />       
</esri:Map>

<esri:TimeSlider x:Name="MyTimeSlider" Height="20" TimeMode="CumulativeFromStart"
    MinimumValue="{Binding ElementName=MyMap, Path=Layers[1].TimeExtent.Start, Mode=OneWay}" 
    MaximumValue="{Binding ElementName=MyMap, Path=Layers[1].TimeExtent.End, Mode=OneWay}">
</esri:TimeSlider>

private void FeatureLayer_Initialized(object sender, EventArgs e) 
{
  List<DateTime> intervals = new List<DateTime>();
  DateTime dt = MyTimeSlider.MinimumValue; 
  while (dt < MyTimeSlider.MaximumValue) 
  {
    intervals.Add(dt); 
    dt =dt.AddYears(2); 
  } 
  MyTimeSlider.Intervals = intervals; 
}

Slider thumbs denote a location on the slider and are specified using the TimeMode property of the TimeSlider. The TimeMode property valid values are CumulativeFromStart, TimeInstant, and TimeExtent. By default, the TimeSlider contains one thumb (TimeInstant) that enables the user to define a time extent that ranges from the minimum value (earliest date) to a later date up to the maximum value. If two thumbs (TimeExtent) are included, the user can drag the thumbs to represent a time range or an instant on the slider. The CumulativeFromStart value of the TimeMode property has one non-visible thumb locked to the start of the TimeSlider and one visible thumb that is moveable. A set of buttons and members on the TimeSlider also enable you to automate the display of time extents by iterating through a sequence of ranges or intervals. The control contains a play button to automatically step through the sequence, and a forward and rewind button to move the thumbs. A set of methods and properties enable you to control and manage the automation.

Note:

You should not use the TimeSlider with feature layers in the "on demand" mode because it can result in too many requests to the server. If you're not working with a large amount of data, you can use a feature layer in snapshot mode. If your dataset is large, consider using an ArcGISDynamicMapServiceLayer instead.

Filtering data using the Map control's TimeExtent property

In addition to the TimeSlider, there are other techniques for visualizing time-aware layers in mapping applications. The Map has a TimeExtent property that acts as a filter for time-aware layers. The TimeExtent property can be set on the Map after it loads. In the following code example, only data that meets the input time definition of June 2, 2009, 0:00 UTC appears.

Tip:

If the TimeExtent has not already been set on the Map, you must specify both the Start and End values of the TimeExtent.

private void MyMap_Loaded(object sender, RoutedEventArgs e) 
{
  TimeExtent timeExtent = new ESRI.ArcGIS.Client.TimeExtent();
  timeExtent.Start = DateTime.Parse("2009-06-02T00:00:00.0000000Z",
                                    CultureInfo.CurrentCulture, 
                                    DateTimeStyles.AdjustToUniversal);
  timeExtent.End = DateTime.Parse("2010-6-30T17:33:46.0000000Z",
                                  CultureInfo.CurrentCulture,
                                  DateTimeStyles.AdjustToUniversal);

  MyMap.TimeExtent = timeExtent; 
}

All time-aware layers will display features for the time extent defined by the Map. The TimeExtent property on time-aware layers cannot be set explicitly since it is defined by the map, feature, or image service.

1/23/2012