In this topic
- About the GraphicTracker
- Suspending display updates
- Controlling drawing characteristics
- 2D display
- Considerations when using the GraphicTracker
About the GraphicTracker
The GraphicTracker provides a simplified application programming interface (API) that allows you to easily add, remove, and move graphics smoothly within a map, dynamic map, or globe.
The GraphicTracker removes the need to manually refresh the display when a graphic is added, changed, or moved. Only geometries that support IPoint, IPolyline, and IPolygon can be added to a GraphicTracker with corresponding point, line, or area symbols. You can create as many GraphicTrackers as you need, but each GraphicTracker must be initialized to use a map or globe. See the following code example:
[C#] IGraphicTracker graphicTracker=new GraphicTrackerClass();
graphicTracker.Initialize(theForm.axMapControl1.Map as IBasicMap);
Dim graphicTracker As IGraphicTracker=New GraphicTrackerClass()
graphicTracker.Initialize(TryCast(theForm.axMapControl1.Map, IBasicMap))
If you have a form with a GlobeControl and a MapControl displaying moving graphics, two GraphicTrackers must be initialized - one for each control - and changes made to both.
Each graphic within a GraphicTracker is made up of a symbol (IGraphicTrackerSymbol) and a geometry (IGeometry). The graphic is stored as a copy of the geometry and symbol that was supplied to it. Making changes to the original geometry or symbol object does not change the graphic.
To create a graphic, create a geometry, then create a symbol that corresponds to that geometry.
GraphicTracker symbols can be created in one of the following ways:
-
Create a symbol and pass that symbol into the IGraphicTracker.CreateSymbol method.
-
Create a symbol from a file using the IGraphicTracker.CreateSymbolFromPath method.
Each GraphicTracker symbol can have a two-dimensional (2D) and three-dimensional (3D) symbol, which are used in their respective displays. It is not necessary to supply a 3D symbol if the GraphicTracker is only used in 2D mode; however, if the same GraphicTracker is used in 3D, the graphics will not display.
To add a graphic, call the IGraphicTracker.Add method and pass in the geometry and the associated symbol. The Add method returns an integer that references the added graphic. This id is very important as it can then be used to manage the graphics properties. See the following code example:
[C#] IGraphicTrackerSymbol myPointSymbol=graphicTracker.CreateSymbol(symbol, null);
int id=graphicTracker.Add(myPointGeometry, myPointSymbol);
Dim myPointSymbol As IGraphicTrackerSymbol=graphicTracker.CreateSymbol(symbol, Nothing)
Dim id As Integer=graphicTracker.Add(myPointGeometry, myPointSymbol)
If the application needs to use the same GraphicTrackerSymbol more than once, it is most efficient to maintain a collection of 2D and 3D GraphicTrackerSymbols. This avoids unnecessary resources being used to create duplicate IGraphicTrackerSymbols. The RSS weather GraphicTracker sample code for RSSWeather.GetSymbol shows how such a collection can be maintained.
The Add() method returns an identifier that is a contiguous zero-based integer. However, it is good practice not to rely on this fact and to store each identifier against the application-specific object that the added graphic represents.
It is possible to change a graphic's geometry or symbol using the IGraphicTracker.Replace method. The following code example illustrates how to replace the geometry and symbol of a graphic:
[C#] IGraphicTrackerSymbol myPointSymbol2=CreateSymbol(symbol2, null);
graphicTracker.Replace(id, myPointGeometry2, myPointSymbol2);
Dim myPointSymbol2 As IGraphicTrackerSymbol=CreateSymbol(symbol2, Nothing)
graphicTracker.Replace(id, myPointGeometry2, myPointSymbol2)
Graphics can be updated using the IGraphicTracker.MoveTo method. This moves the centroid of the graphic to the specified coordinate.
The coordinates that you use in the MoveTo method must be in the same coordinate system as the data frame.
If a GraphicTracker is no longer required, release the Component Object Model (COM) object for the GraphicTracker. See Releasing COM references for details.
Suspending display updates
The SuspendUpdate property is false by default. This means the GraphicTracker will automatically refresh the display after each graphic is changed. Some applications require graphics to move or change independently of each other - not all at the same time. In this case, a false SuspendUpdate value is preferable. In other applications, having a false SuspendUpdate value can affect performance. For example, if 50 graphics are to be moved periodically on a timer call, the GraphicTracker will have to refresh the display 50 times at each instance.
To address this, set the SuspendUpdate property to true, move the graphics, then set SuspendUpdate to false. This will result in one refresh call and draw all graphics at once. In a dynamic map, the SuspendUpdate property is not relevant.
If you're moving hundreds of graphics periodically when a timer is called, the timer should be called at longer intervals than when only moving tens of graphics. For example, in a 2D map with one thousand graphics, moving all of the graphics every second will produce smoother feedback than moving them every half second. Of course, the timer rate that is easiest to view depends on the graphics card being used as well as the number of graphics used.
Controlling drawing characteristics
Each graphic can be assigned a text label and optional text symbol. The default text symbol is Tahoma, bold, 10 points in size with a vertical offset of 12 points. See the following code example:
[C#] graphicTracker.SetTextSymbol(id, textSymbol);
graphicTracker.SetLabel(id, "my graphic's label");
...
//To remove the label.
graphicTracker.SetLabel(id, "");
graphicTracker.SetTextSymbol(id, textSymbol)
graphicTracker.SetLabel(id, "my graphic's label")
...
'To remove the label.
graphicTracker.SetLabel(id, "")
Programmatically control other drawing characteristics using the following methods and properties:
- SetElevationMode - A symbol's elevation can be floating based on the geometry's z-values or clamped to the ground (3D only).
- SetOrientationMode - A symbol's orientation can be set to be billboarded or controlled by the values of the SetPointOrientation method.
- SetPointOrientation - A point symbol's pitch, roll, and yaw values. In 2D, only the yaw value is used.
- SetScaleMode - A symbol's scale can be fixed based on the symbol's size or automatically shrunk as the display becomes larger in scale.
See the following code example:
[C#] graphicTracker.SetElevationMode(id, esriGTElevation.esriGTElevationClampToGround);
graphicTracker.SetOrientationMode(id, esriGTOrientation.esriGTOrientationAutomatic);
graphicTracker.SetPointOrientation(id, 90, 180, 90);
graphicTracker.SetScaleMode(id, esriGTScale.esriGTScaleFixed);
graphicTracker.SetElevationMode(id, esriGTElevation.esriGTElevationClampToGround)
graphicTracker.SetOrientationMode(id, esriGTOrientation.esriGTOrientationAutomatic)
graphicTracker.SetPointOrientation(id, 90, 180, 90)
graphicTracker.SetScaleMode(esriGTScale.esriGTScaleFixed)
The first graphic added will appear underneath subsequent graphics if they have overlapping display areas.
2D display
In a 2D display, such as the MapControl, the following properties of a graphic are irrelevant:
- Z-value of the geometry and any movement in the z-axis.
- The esriGTElevation value supplied to the SetElevationMode method; 2D graphics are always clamped to the ground.
- Pitch and roll values supplied to the SetPointOrientation() method.
Considerations when using the GraphicTracker
This section discusses some important areas to consider when working with the GraphicTracker.
Performance
The following four major factors can impact the performance of the GraphicTracker:
- Number of graphics - This is especially important in a 2D application in standard display mode. The more graphics there are on the screen, the longer it will take for the graphics to refresh.
- Complexity of the graphics symbol - Some GraphicTracker symbols perform better than others. For example, a symbol created using the CreateSymbolFromPath method takes longer to refresh then a simple marker symbol.
- Underlying data - The underlying data and complexity of the basemap will have an impact on the update rate when panning and zooming a map. Consider using a BasemapLayer to improve this performance.
- Update interval - Each time the GraphicTracker is updated there may be a slight pause as the display is refreshed. (This depends, of course, on the number of graphics and the complexity of the symbols). Frequent updates can have an impact on the responsiveness of the application.
To create a well-performing GraphicTracker application, a balance must be struck between these factors. It is possible to update thousands of graphics at an extremely fast update interval; however, complex symbols and user interface responsiveness may be sacrificed.
Timers
Be careful when developing applications with .NET timers. The System.Timers.Timer and System.Threading.Timer classes operate in separate threads. When using these classes, be sure the application follows the guidelines set forth in Writing multithreaded ArcObjects code. The RSS weather GraphicTracker sample demonstrates updating a GraphicTracker in a multithreaded environment. To keep the updates in the same thread, use the System.Windows.Forms.Timer since this timer will operate in the main thread. An example of this is shown in the GraphicTracker with the map sample.
It is recommended to not use labels when using the GraphicTracker to display moving points. For performance reasons the Graphics in the GraphicTracker draw in the same phase as labels. Therefore labels may conflict with the graphics, cause flickering, and slowdown the overall performance of the GraphicTracker.
The GraphicTracker is not just for moving points. It can also be used for quickly and easily adding graphics to any display mode.
See Also:
GraphicTracker with the mapRSS weather GraphicTracker
To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):
| Development licensing | Deployment licensing |
|---|---|
| Engine Developer Kit | Engine |
| ArcGIS Desktop Basic | ArcGIS Desktop Basic |
| ArcGIS Desktop Standard | ArcGIS Desktop Standard |
| ArcGIS Desktop Advanced | ArcGIS Desktop Advanced |