AGI STK Engine (4DX) Blog

September 21, 2010

Vector Geometry Tool API in STK 9.2 – Part 2

Filed under: C#, STK Object Model, VGT, Vectory Geometry API — Peter @ 11:00 am

In this article I will continue the discussion about the new Vector Geometry Tool API. Last time we talked about the VGT points. Today's topic is the VGT planes.

Vector Geometry Planes

Plane components define 2D planes placed and oriented in 3D space and are one of the fundamental geometric constructs available through the Vector Geometry Tool API. Planes are useful for defining other elements, such as flight path angles, dihedral angles, etc. A plane can be defined using a point and a normal vector to the plane, through three points, or by selecting a quadrant from a reference coordinate system (e.g., XY, XZ, YX, YZ, ZX, ZY).

Vector Geometry Tool API Plane Interfaces

All planes implement the IAgCrdnPlane, IAgCrdn and IAgCrdnTimeProperties interfaces. The IAgCrdnPlane interface provides methods for computing position and orientation of the plane component with respect to reference coordinate system. IAgCrdn interface allows to retrieve the plane’s name, description and type information. At last, the IAgCrdnTimeProperties interface provides methods for accessing the plane’s temporal data.

Getting available VGT planes

Planes can be associated with a central body or STK object. To get a list of available planes, one will need to get a reference to the Vector Geometry Tool provider object. In STK 9.2.1 we have added a new property "Vgt" and a method "IsVgtSupported" to the IAgStkObject interface so you can now check if the object supports the Vector Geometry Tool and get a reference to the object's Vector Geometry Tool provider. To demonstrate, let's look at the following example that utilizes the STK Object Model to get an instance of a satellite and enumerate all of the satellite's available VGT planes:

using AGI.STKObjects;
using AGI.STKVgt;
 
// The root object must be initialized and a scenario must exist.
// AgStkObjectRoot root;
 
IAgStkObject oSat = root.CurrentScenario.Children["Satellite1"];
 
IAgCrdnProvider provider = oSat.Vgt;
 
foreach(IAgCrdnPlane plane in provider.Planes)
{
    Console.WriteLine("Plane: {0}", ((IAgCrdn)plane).Name);
}

Alternatively, you can use the STK Object Root object to achieve the same results:

using AGI.STKObjects;
using AGI.STKVgt;
 
// The root object must be initialized and a scenario must exist.
// AgStkObjectRoot root;
 
IAgCrdnProvider provider = root.VgtRoot.GetProvider("Satellite/Satellite1");
 
foreach(IAgCrdnPlane plane in provider.Planes)
{
    Console.WriteLine("Plane: {0}", ((IAgCrdn)plane).Name);
}

You can also get a list of available planes associated with a central body using the collection of the central bodies exposed by the STK Object Model root object (this is new in STK 9.2.1):

using AGI.STKObjects;
using AGI.STKVgt;
 
// The root object must be initialized and a scenario must exist.
// AgStkObjectRoot root;
 
// Get the Earth's VGT provider
IAgCrdnProvider provider = root.CentralBodies.Earth.Vgt;
 
// Enumerate the VGT planes associated with Earth.
foreach(IAgCrdnPlane plane in provider.Planes)
{
    Console.WriteLine("Plane: {0}", ((IAgCrdn)plane).Name);
}

Let's take a closer look at the types of supported planes available through the Vector Geometry Tool API.

Normal Planes

One of the fundamental ways for defining a plane is by specifying a point and a normal vector to the plane. In STK, such planes are referred to as “Normal”. The following code snippet demonstrates how to define a normal plane:

// The reference to the Vector Geometry root object is assumed to be initialized earlier.
//IAgCrdnRoot root;
 
// The example assumes that a scenario has been loaded and that it contains a propagated satellite “Satellite1”.
 
IAgCrdnProvider provider = root.GetProvider(“Satellite/Satellite1”);
 
IAgCrdnPlaneNormal planeNormal = (IAgCrdnPlaneNormal)provider.Planes.Factory.Create(“MyPlane”,
  string.Empty, AgECrdnPlaneType.eCrdnPlaneTypeNormal);
 
// Set up the plane using specified normal vector and a point
 
planeNormal.NormalVector.SetVector(provider.Vectors["Velocity"]);
 
planeNormal.ReferencePoint.SetPoint(provider.Points["Center"]);
 
planeNormal.ReferenceVector.SetVector(provider.Vectors["Position(Moon)"]);

The projection of the reference vector to the plane defines the alignment of the plane’s X-axis. On the next screenshot the X-axis is aligned along the Moon’s Position vector (the thin purple vector). The dashed line indicates the projection of the reference vector to our plane.

Planes defined using a Quadrant from a Reference Coordinate System

You can define a plane using a quadrant of a reference coordinate system (e.g., XY, XZ, YX, YZ, ZX, ZY). The screenshot below demonstrates the plane defined using the satellite’s “Body” coordinate system and its XY quadrant.

Planes defined through three points

In addition to the normal planes and the planes defined using the reference system quadrants, VGT planes can also be defined through three points. Using VGT API, specify the points A and B and the reference point to fully define a plane:

// AgStkObjectRoot root;
 
IAgCrdnProvider provider = root.CentralBodies.Earth.Vgt;
 
IAgCrdnPlaneTriad plane = (IAgCrdnPlaneTriad) provider.Planes.Factory.Create("ThreePointsPlane", string.Empty, AgECrdnPlaneType.eCrdnPlaneTypeTriad);
 
plane.PointA.SetPoint(provider.Points["Center"]);
plane.PointB.SetPoint(root.CentralBodies.Sun.Vgt.Points["Center"]);
plane.ReferencePoint.SetPoint(root.CentralBodies.Moon.Vgt.Points["Center"]);

Earth is on collision course with the galactic plane in the year 2012...twice!

Well, actually Earth does it twice every year so fear not. The galactic plane is also referred to as the galactic equator - a mid point between the top and the bottom of our Milky Way galaxy. So every year Earth crosses the galactic equator as it travels around the Sun. But when will Earth cross the galactic equator in 2012? Let's figure it out using the VGT API and STK Object Model Data Providers API.
First, we are going to create a couple of vectors we'll need to define the galactic equator. The two vectors we need are the galactic North and galactic Center. Using the known right ascension and declination coordinates for the galactic center, we can define the galactic Center vector as:

// The STK root object must be initialized.
//AgStkObjectRoot root;
root.UnitPreferences.SetCurrentUnit("LongitudeUnit", "HMS");
root.UnitPreferences.SetCurrentUnit("LatitudeUnit", "DMS");
 
IAgCrdnVectorFixedInAxes galacticCenter;
IAgCrdnProvider provider = root.CentralBodies.Earth.Vgt;
 
galacticCenter = (IAgCrdnVectorFixedInAxes) provider.Vectors.Factory.Create("GalacticCenter",
                    string.Empty, AgECrdnVectorType.eCrdnVectorTypeFixedInAxes);
galacticCenter.ReferenceAxes.SetAxes(provider.WellKnownAxes.Earth.J2000);
galacticCenter.Position.AssignSpherical("-28:56:00.0000", "17:45:36.0000", 1.0);

Now, let's create a vector representing the galactic North vector:

// The STK root object must be initialized.
//AgStkObjectRoot root;
root.UnitPreferences.SetCurrentUnit("LongitudeUnit", "HMS");
root.UnitPreferences.SetCurrentUnit("LatitudeUnit", "DMS");
 
galacticNorth = (IAgCrdnVectorFixedInAxes) provider.Vectors.Factory.Create("GalacticNorth",
                    string.Empty, AgECrdnVectorType.eCrdnVectorTypeFixedInAxes);
 
galacticNorth.ReferenceAxes.SetAxes(provider.WellKnownAxes.Earth.J2000);
galacticNorth.Position.AssignSpherical("27:07:00.0000", "12:51:14.0000", 1.0);

Using these two vectors, we can now create a galactic plane:

IAgCrdnPlaneNormal plane = (IAgCrdnPlaneNormal) provider.Planes.Factory.Create("GalacticPlane",
                    string.Empty, AgECrdnPlaneType.eCrdnPlaneTypeNormal);
 
plane.NormalVector.SetVector((IAgCrdnVector)galacticNorth);
plane.ReferencePoint.SetPoint(provider.Points["Center"]);
plane.ReferenceVector.SetVector((IAgCrdnVector)galacticCenter);

Create an angle between the galactic plane and the Earth-Sun vector:

// Create an angle between the Earth-Sun vector and the galactic plane
IAgCrdnAngleToPlane angle = (IAgCrdnAngleToPlane) provider.Angles.Factory.Create("EarthToGalacticPlane",
                    string.Empty, AgECrdnAngleType.eCrdnAngleTypeToPlane);
 
angle.ReferencePlane.SetPlane((IAgCrdnPlane)plane);
angle.ReferenceVector.SetVector(provider.Vectors["Sun"]);

At last, let's change the scenario time to span the entire year:

 ((AgScenario)root.CurrentScenario).SetTimePeriod("1 Jan 2012 12:00:00.000", "31 Dec 2012 12:00:00.000");

At this point, the scenario is fully configured and we can now compute when Earth will cross the galactic plane in 2012 using the STK Object Model Data Providers API:

// Generate a report
IAgDataProviderInfo dpi = root.CurrentScenario.DataProviders["Angles"];
Array columns = new object[] { "Time", ((IAgCrdn)angle).Name + " Angle" };
 
IAgDataPrvTimeVar report = (IAgDataPrvTimeVar)dpi;
IAgDrResult result = report.ExecElements("1 Jan 2012 12:00:00.000", "31 Dec 2012 12:00:00.000", 3600.0, ref columns);

The results returned by the data provider represent a time-ordered table of the angles between the galactic plane and the Earth-Sun vector. All that is left is to find the times when the value of the angle reaches zero. A quick look through the report reveals that Earth will cross the galactic equator on "21 Jun 2012 03:12:09 UTCG" and "21 Dec 2012 15:09:01 UTCG".

Conclusion

As this article shows, by combining the strength and simplicity of the new VGT API with the existing STK Object Model Data Providers API you can perform various interdisciplinary analytical tasks. The VGT planes are a part of the new Vector Geometry Tool API and can be composed out of or can be used to compose other VGT components.

No Comments »

No comments yet.

RSS feed for comments on this post. TrackBack URL

Leave a comment

Powered by WordPress