The AgStkObjectRoot Object
The AgStkObjectRoot object resides at the apex of the Object Model. The AgStkObjectRoot object provides methods and properties to load scenarios, create new ones and access the Object Model Unit preferences. From the AgStkObjectRoot object, users can access all other objects and collections exposed by the Object Model.
Hierarchy Navigation
Objects in STK are accessed directly or indirectly by navigating the object hierarchy. AgStkObjectRoot is the only object that can be created directly; the rest of the object model hierarchy can only be accessed indirectly. Users can navigate down the object hierarchy by using collections of sub-objects, and are able to navigate back up by using Parent or Root properties. It is also possible to jump to a particular object using the GetObjectFromPath method on the AgStkObjectRoot object, eliminating the need to navigate through the object hierarchy.
Object Model navigation relies upon the following objects and interfaces: AgStkObjectRoot, IAgStkObject and AgStkObjectCollection.
The IAgStkObject Interface
The IAgStkObject interface exposes methods and properties, and allows you to navigate up and down the object hierarchy, learn about the object's name, type, path and subordinate objects, perform access and coverage computations, and invoke the object's data providers.
The following example demonstrates a simple navigation scenario:
Dim root As AgStkObjectRoot
...
' Navigate to the scenario's object "Satellite1"
Set sat = root.CurrentScenario.Children ("Satellite1")
...
' Release the reference to the satellite object
Set sat = Nothing
...
'
To navigate back up the Object Model using the Parent and Root properties:
Dim root As AgStkObjectRoot
...
' Navigate to the scenario's object "Satellite1"
Set sat = root.CurrentScenario.Children ("Satellite1")
' Navigate to the scenario object using the Parent property
Set scenario = sat.Parent
' Close the scenario using the Root property
scenario.Root.CloseScenario
...
' Release the references to the satellite and scenario objects
Set sat = Nothing
Set scenario = Nothing
The AgStkObjectCollection Object
AgStkObjectCollection object holds the children objects of a particular object. The collection object exposes properties and methods to iterate or enumerate children, create new objects or unload existing ones.
Users can access the AgStkObjectCollection object via the Children property exposed by the IAgStkObject interface.
The following code iterates through the collection of objects using a for-loop:
Dim root As AgStkObjectRoot
...
For I = 0 To root.Children.Count -1
Dim oObject As IAgStkObject
Set oObject = root.Children(I)
..
Set oObject = Nothing
Next
The following code uses standard COM enumeration interfaces to iterate through the collection of objects:
Dim oObject As IAgStkObject
Dim root As AgStkObjectRoot
...
For Each oObject in root.Children
Set oObject = Nothing
Next
Units Preferences
The AgStkObjectRoot object exposes a property UnitPreferences to let developers control the formatting of data that is entered and returned through the Object Model. The Object Model maintains its own set of unit preferences that are independent of the unit preferences used in STK and STK Reports. The following example will ensure that all data that uses the TimeUnit dimension will return the time in days and will expect the time to be entered in day units.
Dim root As AgStkObjectRoot
...
root.UnitPreferences("TimeUnit").SetCurrentUnit("day")
Click here for a list of available dimension names and unit abbreviations for the SetCurrentUnit() method.
Isolating Instances of the Root
In a large application involving multiple users and points of access, or in the limited cases where STK Plugins are allowed to access the STK Object Model, you may find it necessary to set unit preferences that apply to a defined operation or area without affecting others in the application. Having multiple instances of the root is not sufficient to accomplish this. Thus, in the following C# example, the two instances of the root will share the same unit preference, and the Assert test will fail:
//IAgStkObjectRoot root
root.UnitPreferences.SetCurrentUnit("DistanceUnit", "km");//IAgStkObjectRoot root2
root2.UnitPreferences.SetCurrentUnit("DistanceUnit", "nm");String distance = root.UnitPreferences.GetCurrentUnitAbbrv("DistanceUnit"); String distance2 = root2.UnitPreferences.GetCurrentUnitAbbrv("DistanceUnit"); System.Diagnostics.Debug.Assert(distance != distance2);
The Isolate() method of the AgStkObjectRoot class lets us set the unit preferences in each instance of the root independently. The Assert test in the following code will succeed.
//IAgStkObjectRoot root
root.UnitPreferences.SetCurrentUnit("DistanceUnit", "km"); root.Isolate();//IAgStkObjectRoot root2
root2.UnitPreferences.SetCurrentUnit("DistanceUnit", "nm");String distance = root.UnitPreferences.GetCurrentUnitAbbrv("DistanceUnit"); String distance2 = root2.UnitPreferences.GetCurrentUnitAbbrv("DistanceUnit"); System.Diagnostics.Debug.Assert(distance != distance2);
Here we have isolated the first instance of the root; unit preference settings in other parts of the application will not affect its settings (and vice versa).
Data Providers
The IAgStkObject interface exposes the DataProviders property to access the data providers associated with the object.
The DataProviderCollection interface provides methods and properties to access the information provided by an object's Data Provider Tools. There are three different ways to compute the data, depending on the data provider type. The first method requires a time interval and step size; the second requires only a time interval; the third is independent of time.
See the Data Provider help system for further information on AGI data providers.
The following is an example of the first type of data provider, which requires you to use a start time, stop time and time step in the Exec command. The returned data can be accessed through the IAgDrResult interface.
Dim sa As STKObjects.IAgStkObject
Dim dataPrvComp As STKObjects.IAgDataProviderGroup
Dim timeFunc As STKObjects.IAgDataPrvTimeVar
Dim result As STKObjects.IAgDrResult
Set sa = stkApp.CurrentScenario.Children ("Satellite1")
Set dataPrvComp = sa.DataProviderCollection ("Cartesian Position")
Set dataPrv = dataPrvComp.Group("Fixed")
Set timeFunc = dataPrv
Set result = timeFunc.Exec(0, 3600, 240)
The following is an example of the second type of data provider, which just requires the start and stop times:
Dim fa As STKObjects.IAgStkObject
Dim dataPrvComp As STKObjects.IAgDataProviderGroup
Dim dataPrv As STKObjects.IAgDataProvider
Dim intvlFunc As STKObjects.IAgDataPrvInterval
Dim result As STKObjects.IAgDrResult
Set fa = stkApp.CurrentScenario.Children ("Facility1")
Set dataPrvComp = fa.DataProviderCollection ("Lighting Times")
Set dataPrv = dataPrvComp.Group ("Sunlight")
Set intvlFunc = dataPrv
Set result = intvlFunc.Exec(0, 86400)
The following is an example of the third type of data provider, which does not require any parameters:
Dim fa As STKObjects.IAgStkObject
Dim dataPrv As STKObjects.IAgDataProvider
Dim fixedFunc As STKObjects.IAgDataPrvFixed
Dim result As STKObjects.IAgDrResult
Set fa = stkApp.CurrentScenario.Children("Facility1")
Set dataPrv = fa.DataProviderCollection("Cartesian Position")
Set fixedFunc = dataPrv
Set result = fixedFunc.Exec
Once the IAgDrResult interface is attained, you must first determine what type of data was returned, and cast it to the appropriate interface. This is done by using the Category property of the IAgDrResult interface, which returns an enumeration describing the interface. The Value property is then cast to one of three interfaces, depending on the Category enumeration: IAgDrIntervalCollection, IAgDrSubSectionCollection, or IAgDrTextMessage.
IAgDrIntervalCollection
Dim intList As STKObjects.IAgDrIntervalCollection
Dim intvl As STKObjects.IAgDrInterval
Dim ds As STKObjects.IAgDrDataSet
Dim values
Set intList = result.Value
ForEach intvl In intList
'Print CStr(intvl.StartTime)
'Print CStr(intvl.StopTime)
'Iterate through the datasets stored in the interval
ForEach ds In intvl.DataSets
'Print CStr(ds.Count)
'Print CStr(ds.UnitType)
'Print CStr(ds.ElementName)
'Print CStr(ds.ElementType)
' Get the values stored in the data set
values = ds.GetValues()
' Iterate through the array of values
For I = LBound(values) To UBound(values)
'Print values(I)
Next
Next
Next
IAgDrSubSectionCollection
Dim sections As STKObjects.IAgDrSubSectionCollection
Dim section As STKObjects.IAgDrSubSection
Dim intvl As STKObjects.IAgDrInterval
Set sections = result.Value
ForEach section In sections
' Print section.Title
'Iterate through the interval stored in the section
ForEach intvl In section.Intervals
...
Next
Next
IAgDrTextMessage
Dim msgContainer As STKObjects.IAgDrTextMessage
Set msgContainer = result.Value
For i = 0 To msgContainer.Count - 1
Dim msg As String
msg = msgContainer(i)
...Next
Computing Access Between Objects
The base interface IAgStkObject provides methods to calculate access intervals between two objects and control the display of access graphics. To compute access, the user must provide an object by specifying the object's symbolic path or by using the object reference itself.
Following are the methods used to compute access:
IsAccessSupported - Returns True if the access computation is supported.
GetAccess - Computes access between the current object and the object identified by the path specified as the argument. The method returns a reference to the IAgStkAccess interface used to compute the access, get the access intervals, and configure the display of access graphics.
GetAccessToObject - Works similarly to GetAccess, except that it allows passing a reference to the object, instead of the object's symbolic path.
Batch Updates
To improve STK graphics performance, especially when manipulating a large number of objects or updating many properties of a single object, sometimes it is necessary to control whether the updates to STK occur immediately or should be delayed. The AgStkObjectRoot object exposes the methods BeginUpdate and EndUpdate that are used to delay and resume graphics updates, respectively. When updates are delayed, the changes to STK properties are accumulated and registered internally to STK. The changes are not reflected until EndUpdate method is called.
Users access the Batch Update capabilities via the AgStkObjectRoot object. The following code delays the graphics updates, makes multiple changes to the 3D properties of the satellite object and then resumes the graphics updates:
Dimroot As AgStkObjectRoot
Dim sat As IAgSatellite
...
' Delay graphics updates root.BeginUpdate
...
Set sat = root.CurrentScenario.Children("Satellite1")
sat.VO.EvelContours.IsVisible = True
sat.Fill = True
sat.IsConesVisible = True
' Resume graphics updates
root.EndUpdate
Events
Automation Events offer a mechanism to notify clients of any changes occurring within STK, such as the events that occur whenever objects are destroyed or created, or when an existing object is renamed.
Events can be logically grouped into the following categories:
- Object Tree Hierarchy Events
- Scenario Events
- Animation Events
- Logging Events
Exception Handling
Exception handling in the STK Object Model offers developers a consistent strategy for processing exceptions that occur within the scope of the Object Model. The exceptions are triggered during normal or erroneous execution.
Normal execution exceptions are used to notify users of failures that are within a normal range of expectations. For example, specifying a path to the file that does not exist will generate an exception.
Erroneous execution exceptions are used to notify users of mistakes caused by an inappropriate or unexpected argument, or an invalid context. For example, specifying a null pointer (Nothing in VB) to the IAgStkObject.GetAccessToObject () method will cause an erroneous execution exception.
Access to any property or method exposed by the Object Model can potentially generate an exception, and to handle such exceptions, users should leverage exception handling techniques supported by their programming environments.
Use of Variants
There are 3 reasons why we use Variants in the STK Object Model:
- In collections we use Variants to index various items. These Variants can take either a string name or an integer to index a particular item.
- For properties or methods that use the DateFormat dimension, the Variant can be either a string or a double. This depends on whether the DateFormat in UnitPreferences is set to a string representation(e.g. UTCG) or double (e.g. Epsec).
- Variants in AngleUnit, LatitudeUnit, LongitudeUnit, DurationUnit, MissionModelerBearingAngleUnit, MissionModelerAngleOfAttackUnit or MissionModelerAttitudeAngleUnit can be either a double or a string. If DMS or HMS is set in the UnitPreferences, these parameters accept strings; otherwise they accept doubles.