Accessing the VGT API | VGT Points Description | Base Interfaces and Naming Conventions| Using VGT Points | Creating and Visualizing VGT Points | Examples

STK VGT (Analysis Workbench) Library

The VGT Object Model provides a simple, consistent, and hierarchical approach to constructing and manipulating the following that can be utilized in custom Engine applications or in UI Plugins:

Configuring a C# Project to Access the VGT API

To access the VGT API, add a reference to the library (C# project) or import the library using the “#import” directive (C++). The name of the library is AGI VGT 10.

To use the VGT API and its components, you will need to use the root object. To get the VGT root, use the VgtRoot property of the IAgStkObjectRoot interface:

IAgCrdnRoot crdnRoot = root.VgtRoot;  

where root is a reference to IAgStkObjectRoot

Using the instance of the root object, you now are able to access the Vector Geometry Tool components associated with STK objects and central bodies.

You can then configure the unit preferences using the Vector Geometry Tool root object. The root object exposes a property "UnitPreferences" through which you can set up the units:

// Configure the unit preferences
root.UnitPreferences.SetCurrentUnit(“DateFormat”, “UTCG”);
root.UnitPreferences.SetCurrentUnit(“DistanceUnit”, “m”);

Vector Geometry Tool Points

Points represent one of the basic Vector Geometry Tool components and can be used as standalone components as well as for composing vectors, planes, systems or other points. The VGT API allows you to create new points using one of the available point types, modify and enumerate/iterate existing points, and perform various analytical tasks.

Note: To add, modify, or delete custom components using the VGT API, you must have the Analysis Workbench license.

All point types creatable through STK can also be created using the VGT API, although the VGT API, unlike STK, does not make a distinction between advanced, template-based and regular points, and enables you to access any point using the same semantics.

All Vector Geometry Tool points can return their position and velocity. When querying the point's position or velocity, you must specify the system in which you want the position or velocity to be returned.

// Configure the unit preferences
 root.UnitPreferences.SetCurrentUnit(“DateFormat”, “UTCG”);
// Get the satellite's vector geometry provider
IAgCrdnProvider provider = root.GetProvider(“Satellite/Satellite1”);
IAgCrdnPoint ptCenter = provider.Points[“Center”];
IAgCrdnSystem sysFixed = crdnRoot.WellKnownSystems.Earth.Fixed;
IAgCrdnPointLocateInSystemResult result = ptCenter.LocateInSystem(“27 Apr 2010 12:00:00.000”, sysFixed);
if (result.IsValid)
{
    double x = Result.Position.X;
    double y = Result.Position.Y;
    double z = Result.Position.Z;
}

The Points property exposed by the Vector Geometry Tool providers returns a collection (or group) of all existing points associated with an STK object or a central body. The elements of the collection can be accessed using an index or a name of the component. The elements can also be enumerated or iterated. The following example demonstrates how to enumerate existing points:

foreach(IAgCrdnPoint point in provider.Points)
{
    IAgCrdn crdn = (IAgCrdn)point;
    string pointName = crdn.Name;
}

Here is how existing points can be iterated using an index:

IAgCrdnPointGroup points = provider.Points;
for (int i = 0; i < points.Count; i++)
{
    IAgCrdnPoint point = points[i];
    IAgCrdn crdn = (IAgCrdn)point;
    string pointName = crdn.Name;
}

Base Interfaces and Naming Conventions

Interfaces exposed with the Vector Geometry Tool Object Model use the common prefix "IAgCrdn" and the enumeration types are prefixed with "AgECrdn", where "Crdn" stands for "coordinates". All points implement IAgCrdnPoint, IAgCrdn and IAgCrdnTimeProperties interfaces. IAgCrdn interface is implemented by all Vector Geometry Tool components, whereas IAgCrdnPoint interface is implemented by point types only. IAgCrdnTimeProperties interface exposes GetAvailability and GetSpecialTimes methods to get component's availability and times.

The Vector Geometry Tool Object Model uses the following naming convention: the interface name of a concrete point type is a concatenation of the base interface name and the type name (without whitespaces); for example, the interface representing the “Fixed In System” point type is named IAgCrdnPointFixedInSystem.

Using Vector Geometry Tool Points : How to Determine an Altitude Above Terrain

The following example, which determines an altitude above the terrain of an aircraft using custom surface point, demonstrates some of the Vector Geometry Tool features. The example creates a new scenario, adds an aircraft and creates a custom vector which is then used to compute the altitude of the aircraft above terrain. Note that the scenario example does not include terrain, but you can experiment on your own. The example assumes that the STK Engine has already been started. The code can also be used, with some minor modifications, in an application using an out-of-process instance of STK:

// The example assumes the instance of STK Object Model root object
// has been initialized somewhere else.
// AgStkObjectRoot root;

// The example assumes that the scenario contains a valid aircraft and the aircraft has a valid route.
// AgAircraft aircraft;
 
// Create an instance of the root object, where root is a reference to IAgStkObjectRoot
IAgCrdnRoot crdnRoot = root.VgtRoot;

// The string contains a short path to the aircraft
string path = string.Format(“{0}/{1}”, aircraft.ClassName, aircraft.InstanceName);
 
// Get the elements associated with the aircraft.
IAgCrdnProvider provider = crdnRoot.GetProvider(path);
 
// Create a surface popint
IAgCrdnPointOnSurface surfacePoint = (IAgCrdnPointOnSurface)provider.Points.Factory.Create("Point(Terrain)",
    "A point on terrain", AgECrdnPointType.eCrdnPointTypeOnSurface);
surfacePoint.ReferenceShape = AgECrdnReferenceShapeType.eCrdnReferenceShapeTerrain;
surfacePoint.SurfaceType = AgECrdnSurfaceType.eCrdnSurfaceDetic;
 
// Get the aircraft’s vector factory
IAgCrdnVectorFactory factory = provider.Vectors.Factory;
 
// Create a displacement vector. The new vector is initialized
// with default values (see Create-Set-Call pattern).
IAgCrdnVectorDisplacement displacementVector = (IAgCrdnVectorDisplacement)factory.Create("AltAboveTerrain(Detic)",
    "A vector to get the altitude above terrain",
    AgECrdnVectorType.eCrdnVectorTypeDisplacement);
 
// Use the "Center" point as vector's origin.
displacementVector.Origin.SetPoint(provider.Points["Center"]);
 
// Use our custom point on terrain as vector's destination.
displacementVector.Destination.SetPoint((IAgCrdnPoint)surfacePoint);
 
// Turn the apparent position flag off.
displacementVector.Apparent = false;
 
// Compute in Earth's Fixed frame
IAgCrdnVector vector = (IAgCrdnVector)displacementVector;
IAgCrdnVectorFindInAxesResult result = vector.FindInAxes(root.CurrentTime, crdnRoot.WellKnownAxes.Earth.Fixed);
if (result.IsValid)
{
    // Calculate the vector’s norm. The vector’s norm is the altitude
    // of the aircraft above terrain. The altitude is in meters.
    double altitude = Math.Sqrt(
        result.Vector.X * result.Vector.X +
        result.Vector.Y * result.Vector.Y +
        result.Vector.Z * result.Vector.Z);
}

Creating and Visualizing Vector Geometry Tool Points

The Vector Geometry Tool Object Model offers a plethora of existing points that are always available and ready to be used. However, no two problems are alike and in some cases creating and customizing a new point might better facilitate the solution to your problem. Creating a point using VGT API is simple and straightforward:

Examples

Getting the Earth’s Center Point

IAgCrdnProvider provider = root.GetProvider(“CentralBody/Earth”);
IAgCrdnPoint ptCenter = provider.Points[“Center”];

Computing the Point's Position in Earth's ICRF Frame

// AgCrdnRoot crdnRoot;
// The example assumes that there an existing instance of satellite named "Satellite1"
IAgCrdnSystem icrf = crdnRoot.WellKnownSystems.Earth.ICRF;
 
IAgCrdnProvider provider = crdnRoot.GetProvider("Satellite/Satellite1");
 
IAgCrdnPoint point = provider.Points["Center"];
 
IAgCrdnPointLocateInSystemResult result = point.LocateInSystem("28 Apr 16:00:00.000", icrf);
if (result.IsValid)
{
    Trace.WriteLine(string.Format("Position of the satellite's center in Earth's ICRF (cartesian): {{x,y,z}} :
       {{{0},{1},{2}}}", result.Position.X, result.Position.Y, result.Position.Y));

STK Programming Interface 11.0.1