Important Concepts in the Development of the STK Object Model

In my previous blog post, I discussed the History of the STK Object Model through various versions of STK. In this blog post, I am going to expand a bit more and talk about a few more important concepts.

Using the STK Desktop as a Guideline when Creating Object Model Code

Since the object model closely follows the workflow of the user interface you can use it, up to a point, as a guideline when writing code. For example, if you change the label for facility, the IAgFacility interface contains the Graphics property, which in turn contains the LabelName property. According to the STK Programming Interface help, the LabelName property is a string type and a read-write property. So, the following line should work:

facility.Graphics.LabelName = "Facility Name";

Your code will compile, but when you actually run the code, you will get the error, “LabelName is read only property.” 

To change the label, you have to disable the “Use Instance Name as Label” checkbox. Since OM follows the same logic as the user interface, the correct code is:

facility.Graphics.UseInstNameLabel = false;
facility.Graphics.LabelName = "Facility Name";

Another example are vehicle propagators. If you take a look at satellite properties in STK Desktop application, the Orbit section allows users to select between thirteen propagators. Some propagators are very similar to each other, while others are completely different. However, they perform the same function, which is defining the satellite's orbit. STK is designed to except new propagators as long as they follow the same interface pattern. As long as the propagator implements the correct interface, STK will accept the propagator as a valid option. This concept is more obvious when working with external plugins. I will discuss this paradigm more when explaining Factory and Casing concepts.

Important Concepts

Units

STK is a very versatile application. We accept and report data using many unit types. As result, the object model has to be able to pass through values of various data types. For example, the Facility object contains the Position object. The first time user would expect to see “Latitude” and “Longitude” properties of numeric type as part of the Position object. But, if you take a look at the documentation, the Position object implements IAgPosition interface. The interface does not contain Latitude and Longitude properties, but several assign and query methods. Here is the code to get latitude and longitude:

object latitude = 0, longitude = 0; double altitude = 0; facility.Position.QueryPlanetodetic(out latitude, out longitude, out altitude);

You will notice that latitude and longitude are of the type object while altitude is numeric type. Again, we cannot assume that latitude and longitude are numeric because STK accepts units like DMS (degrees, minutes, seconds) as a valid angle unit. In that case, the default latitude (angle) value would be 40:02:18.9960. So, in your code, you need to make sure that you know the units before you get/set values. Imagine that the return value comes in a box of the type object. You can “unbox” the value to a proper numeric type.

Reference Parameters

STK OM passes objects by reference. That means if you assign an object to a variable, the variable contains pointer to original object. Modifying the variable will also affect the original object. We will come back to this concept repeatiatly. The reason why we are discussing the concept now is the previous example:

facility.Position.QueryPlanetodetic(out latitude, out longitude, out altitude);

The code above is written in C#. In C# the keyword “out” marks latitude, longitude, and altitude variables as reference parameters. The method call will modify the variable. The reference parameters that are not available is the scripting languages. If you take a look again at IAgPosition interface documentation, you will see that each “query” method has two versions: one that uses reference parameters and one that returns values in one dimensional array.

Casting

Another important concept is casting (changing object type). The STK Object Model follows C/C++ inheritance logic. This concept might be foreign to .net/Java developers. AgFacility class inherits from both IAgStkObject and IAgFacility interfaces. However, in order to pass object of type AgFacility to method that accepts IAgStkObject, you have to cast the object back to IAgStkObject otherwise you will get a compile error. The scripting languages like JavaScript and MATLAB do not require casting. However, you still need to be careful when modifying your code. You can create breaking changes if you change object type without updating the rest of the code.

In general, the common methods and properties are located in the parent interface. For example, IAgStkObject is the parent interface for STK objects, IAgGraphicsPrimitive for graphics primitives, and IAgCrdn for Analysis Workbench.

Factory

Factory is object oriented programming concept. It describes an object for creating new objects. The factory object was hidden in previous versions of the STK, but with introductions of the Graphics Primitives and Vector Geometry (Analysis Workbench), the factory method of creating a new object was made public. For example, the vector factory is used to create any new vector. The factory creates object of the type IAgCrdnVector. In order to use the new vector, you need to cast the vector to the appropriate subtype. The principle is the same as "New" method of the IAgStkObject's Children property.

The factory concept is used to support extensibility of STK Desktop application. It allows us to create new objects and interfaces without interfering with the existing objects. As STK OM closely follows desktop application, STK OM works on the same principle. And following the principle is the main reason why STK OM has so much casting.

Now that you are on fire with knowledge about the history of the Object Model, you can join me in the Virtual Classroom. I am teaching two virtual trainings. One Virtual Training is on STK User Interface Plugins using C# and is on May 25. The other Virtual Training is on STK Engine Applications with C# and Java on May 31. You can register for those on our training page. I hope to "see" you virtually!