Much like many objects in RT3, the STK Object Model Broker exposes the IAgEntityCollection interface to enable the insertion and removal of entity objects. Unlike other objects, though, the STK Object Model Broker handles all of its tracks via batch processing. Since the STK Engine is single threaded and the STK Object Model Broker is multi-threaded, the STK Object Model Broker will automatically batch up changes to entities and process them on a user defined interval in order to process entities efficiently and provide the best performance. By default, the STK Object Model Broker will process data at the same rate as the STK scenario animation refresh delta, caused by having the ProcessRateIsRefreshDelta and AutoProcessCommands property set to true. Setting ProcessRateIsRefreshDelta to false will cause the STK Object Model Broker to process at the rate determined by the AutoProcessRate property. Optionally, you can set AutoProcessCommands to false and the STK Object Model Broker will never do anything until you manually call the ProcessCommandQueue method.
A side affect of this batching is that just because you call Add or Remove on the STK Object Model Broker, it does not mean the entity has been added or removed when the function returns; that will not happen until the next update. For example, the following code - which tries to get the STK object path to the STK object currently representing the entity - will fail:
Broker.Add(Entity);
string STKPath = Broker.GetStkPathFromEntity(Entity);
The example above fails because any code immediately following Add cannot assume that the STK equivalent object has been created yet. However, if you must access the object immediately, you can simply call ProcessCommandQueue to force processing:
Broker.Add(Entity);
Broker.ProcessCommandQueue();
string STKPath = Broker.GetStkPathFromEntity(Entity);
Every entity inserted into the STK Object Model Broker - whether it came from RT3 or was directly inserted - has an STK object equivalent created for visualization. By default, the STK Object Model Broker creates two MTO objects, one for dynamic tracks named Broker_Dynamic_Tracks and another for static tracks named Broker_Static_Stracks. As you saw in the previous example, you can get the STK path of the currently represented MTO track or heavy object by calling the GetStkPathFromEntity method. Alternatively, if you have an STK path, you can get the Entity associated with it by calling GetEntityFromStkPath.
MTOs are great for visualizing large volumes of data, but cannot be used for analysis and do not have attitude data or the ability to attach child objects, such as sensors. Therefore, if access to any of these features is needed, the MTO track must be promoted to a heavy object. This is accomplished using the PromoteAndLockObject and UnlockObject commands. For example, assume you wanted to perform access between two entities, Entity1 and Entity2, which cannot be done with an MTO.
using AGI.STKObjects;
using AGI.STKObjects.Broker;
string Aircraft1ObjectPath = Broker.PromoteAndLockObject(Entity1,
AgESTKObjectType.eAircraft);
string Aircraft2ObjectPath = Broker.PromoteAndLockObject(Entity2,
AgESTKObjectType.eAircraft);
//Perform calculations
Broker.UnlockObject(Aircraft1ObjectPath);
Broker.UnlockObject(Aircraft2ObjectPath);
Calling UnlockObject does not guarantee that an object will be demoted - it only makes it eligible for demotion. The reason for this is simple: if you used a feature of the aircraft that was not available in the MTO - for example, adding a sensor - the STK Object Model Broker will detect this and keep it promoted.
There are two cases when the STK Object Model Broker will automatically promote an MTO track to a heavy object. The first is if an entity contains attitude data. By default the track will be promoted to an aircraft, but this can be controlled by whomever is inserting the entity; see Broker Specific Entity Metadata page of this guide for complete details. The second case is when a call is made to LoadChildObject. This broker method takes an entity as a parameter and loads - as a child of the object in STK - the provided STK object file. For example, if you have a configured sensor that you would like to attach to an object named Entity1:
Broker.LoadChildObject(Entity1, "C:\\PathToMySensor.sn");
If Entity1 is already being represented as a heavy object, then the sensor is simply loaded. If the entity needs to be promoted, though, it will happen automatically.
As with promotion, the STK Object Model Broker can choose to demote any object it considers unnecessarily promoted to improve performance. For example, if the sensor loaded onto Entity1 was deleted, the STK Object Model Broker might demote the heavy object back to an MTO track. The STK Object Model Broker will never automatically demote an object promoted with PromoteAndLockObject until UnlockObject is called. See RT3 Object Model Reference. and the STK help system for more information about MTO tracks and other STK objects.
STK Programming Interface 11.0.1