ArcGIS API for Windows Phone - 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 Windows Phone 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.

You can use the API to build applications that perform temporal queries, filter layers using time definitions, set the map's time extent, and render the data based on the timestamps.

This topic covers the following time-aware processes:

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.

Screen shot of the Layer Properties dialog box showing enabling time on a layer.

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:

Screen shot of the Mosaic Dataset Properties dialog box showing enabling time on a mosaic dataset.

Retrieving the TimeExtent of a time-aware layer

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 layerTimeExtent = (MyMap.Layers["MyFeatureLayer"] as FeatureLayer).TimeExtent;

Note:

The above code assumes the following:

Your application has a reference to the ESRI.ArcGIS.Client assembly.
Your code-behind has a using statement for the ESRI.ArcGIS.Client namespace.
Your applications has a map named MyMap.
Your map has a time-aware layer named MyFeatureLayer.
MyFeatureLayer has been initialized. The TimeExtent property is not populated until after the layer has been initialized.

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 your Windows Phone application. The platform has a DateTime class to define a specific time and 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("2010-01-29T17:33:46.0000000",
    System.Globalization.CultureInfo.CurrentCulture,
    System.Globalization.DateTimeStyles.AdjustToUniversal);

Filtering data using the Map control's TimeExtent property

To visualize time-aware layers in mapping applications, use the TimeExtent property on the Map control, which acts as a filter for time-aware layers. The TimeExtent property can be set on the Map control after it loads. In the following code example, only data that falls within the input time extent definition of June 2, 2005, 0:00 UTC through June 2, 2010, 0:00 UTC appears.

Tip:

If the TimeExtent has not already been set on the Map control, 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("2005-06-02T00:00:00.0000000Z",
        System.Globalization.CultureInfo.CurrentCulture,
        System.Globalization.DateTimeStyles.AdjustToUniversal);
    timeExtent.End = DateTime.Parse("2010-06-02T00:00:00.0000000Z",
        System.Globalization.CultureInfo.CurrentCulture,
        System.Globalization.DateTimeStyles.AdjustToUniversal); 
    MyMap.TimeExtent = timeExtent;
}

To set the TimeExtent to a single instant in time instead, pass the desired DateTime into the TimeExtent constructor. In the following code example, only data from June 2, 2005, 0:00 UTC will appear on the map:

private void MyMap_Loaded(object sender, RoutedEventArgs e)
{
    TimeExtent timeExtent = new ESRI.ArcGIS.Client.TimeExtent(
        DateTime.Parse("2005-06-02T00:00:00.0000000Z",
            System.Globalization.CultureInfo.CurrentCulture,
            System.Globalization.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.

Rendering temporal data

When a time-aware layer is added to the map, you can have each feature rendered a bit differently based on its timestamp. A TemporalRenderer can be used to customize the symbology of a FeatureLayer, incorporating time information. It can specify changes to the symbols with time, as well as symbology for each of the observations, including a unique symbol for the most recent observation as determined by the Map's TimeExtent. In addition, it can be used to make a path connecting the observations in temporal order.

The following properties of the TemporalRenderer are used to customize the display:

ObservationRenderer—Default symbology of the features. This can be a SimpleRenderer, ClassBreaksRenderer, or UniqueValueRenderer.
LatestObservationRenderer—Default symbology for the most recent observation.
SymbolAger—Overrides the default symbology of the ObservationRenderer to show change over time. This can be a RampInterpolator or a TimeClassBreaksAger.
- RampInterpolator—Specifies a range of color, opacity, size, or a combination of them, and applies them as a gradient over the entire TimeExtent of the Map. The symbology of the ObservationRenderer that is not overridden still displays. For example, the color of the ObservationRenderer is visible if only an opacity RampInterpolator is specified.
- TimeClassBreaksAger—Modifies the rendering of the observations by grouping them into ranges of values by their age, and specifying color, size, and/or opacity. As with a RampInterpolator, any properties unchanged by the TimeClassBreaksAger will display the properties of the ObservationRenderer. In addition, if there are features temporally outside the classes of the TimeClassBreaksAger, the ObservationRenderer will be used for those features.
TrackRenderer—Symbol used for the path connecting observations to show their temporal order.

A FeatureLayer can contain a number of distinct temporal tracks. For example, in a layer of hurricane data, each hurricane has a set of temporal points associated with it that are related to each other, but independent of the points associated with other hurricanes in the layer.

The TrackIdField property on the TemporalRenderer specifies a field (included in the FeatureLayer's OutFields) that should be used to group related temporal events into a single track of events. If a TrackIdField is provided to the TemporalRenderer, the LatestObservationRenderer is used to symbolize the last time-based feature returned pursuant to the TrackIdField property. In addition, when a TrackIdField is provided, the TrackRenderer is applied to each of the distinct tracks in the data, connected related observations. Without a TrackIdField, the TrackRenderer will connect all the observations in the FeatureLayer as part of a single track.

Note:

A TemporalRenderer only renders graphics from a FeatureLayer that has time-based data explicitly specified by an ArcGIS Server web service.
The Map containing the FeatureLayer must have its TimeExtent set, or the TemporalRenderer will not be applied.

1/23/2012