Using Python Plugin Points

STK Premium (Air), STK Premium (Space), or STK Enterprise
You can obtain the necessary licenses for this tutorial by contacting AGI Support at support@agi.com or 1-800-924-7244.

This tutorial requires STK 12.9 or newer to complete in its entirety. If you have an earlier version of STK, you can view a legacy version of this lesson.

The results of the tutorial may vary depending on the user settings and data enabled (online operations, terrain server, dynamic Earth data, etc.). It is acceptable to have different results.

Capabilities Covered

This lesson covers the following STK Capabilities:

  • STK Pro
  • Analysis Workbench
  • STK Integration

Problem Statement

Engineers and operators need to customize their mission or their analysis. They can use plugins to meet that need.

Solution

Native python plugin points have been added to STK for Access Constraints and Vector Geometry Tool (VGT) calc scalar. The python plugin points allow you to specify a python file to be used as a plugin. The benefit is that you do not have to worry about COM registration of the Active Scripting engine. In this lesson, we will use two installed example scripts to explore this new feature.

What You Will Learn

Upon completion of this tutorial, you will be able to:

  • Navigate to and explore the example .py files
  • Assign a plugin script as an access constraint
  • Assign a plugin script in STK's Analysis Workbench capability
  • Use plugins in scenario analysis

Requirements

The Python plugin points require the following to be installed:

  • Local install of Python 3.x (at least version 3.6)
  • Install of the Python API
    • The STK Python API is packaged as a wheel file that can be installed using pip. The wheel file is included with the STK install in the bin/AgPythonAPI directory.
    • Installation steps can be found here: STK Python API

Exploring Installed Python Plugin Files

Files for this lesson are available in the STK 12.4 install directory.

  • <STK install folder>\CodeSamples\CodeSamples\Extend\Constraints\Python\RangeExample.py
  • <STK install folder>\CodeSamples\CodeSamples\Extend\VGT.Plugins\Python\CalcScalar\CalcScalar_Plugin_Example.py

Before beginning the lesson, you will view the .py files using your preferred method. It is beneficial to know where the files are located and how they are formatted so you can develop your own plugins. These examples are simple in nature, but you can use the files as reference or duplicate and modify for your own mission analysis. The intent of the files is to show you the functionality of the plugin points.

Unzipping CodeSamples.zip

Before viewing the python files, you need to unzip the CodeSamples folder.

  1. Navigate to <STK install folder>\CodeSamples\ (e.g. STK 12: C:\Program Files\AGI\STK 12\CodeSamples).
  2. Extract the contents of CodeSamples.zip.

    3. If you are unable to extract the contents of CodeSamples.zip, create a folder on your Desktop and copy the two files there.

Viewing RangeExample.py

Explore the RangeExample.py file.

  1. Navigate to the location of RangeExample.py.
  2. Open the file using your preferred method (e.g. python, jupyternotebooks, notepad++).
  3. Review the file.
  4. At the top, note the modules that are loaded in. You will need to have the Python API installed in order to import the modules.
  5. Scroll through and identify the target object: Satellite, Aircraft, Facility, and Ground Vehicle. These are the default objects, but the file can be modified to use for other objects in the scenario.
  6. The script will evaluate an access between two objects with a user defined minimum and maximum range value (either or both can be set).
  7. Close the file.

Viewing CalcScalar_Plugin_Example.py

Explore the CalcScalar_Plugin_Example.py file.

  1. Navigate to the location of CalcScalar_Plugin_Example.py.
  2. Open the file using your preferred method (e.g. python, jupyternotebooks, notepad++).
  3. Review the file.
  4. At the top, note the modules that are loaded in. You will need to have the Python API installed in order to import the modules.
  5. Scroll down and note the plugin configuration properties line.
  6. Continue to scroll down and note the variables (e.g. MyDouble, MyString). These are properties the user can modify and load into their scenarios.
  7. Scroll down and note the simple calculation called Evaluate. It is an addition of the object's Cartesian X and Cartesian Z components. While not a particularly meaningful result, the intention is to highlight that calculations can be set in one place (the plugin script) and then can be used in the scenario
  8. Close the file.

Adding the PATH environment variable

STK must link directly to the Python libraries. The Python directory containing python3.dll must be added to the PATH environment variable. If you are using Linux, the location of libpython3.so must be included in LD_LIBRARY_PATH. If using Windows, users can set the Environment Variables in the System properties.

Set up your PATH environment variable now based on your operating system.

STK locates Python modules (including STK the Python API) following the rule that the Python interpreter uses. STK searches for the modules in the following order:

  1. PYTHONPATH environment variable
  2. A Python Virtual environment implemented using the venv module (virtual environments other than venv are not supported)
  3. PYTHONHOME environment variable
  4. PATH (or LD_LIBRARY_PATH on Linux) environment variable, searching for the first Python 3 installation

Upon instantiating a Python plugin, STK displays a message specifying the Python module search paths that are used in the Message Viewer. We will see that later in this lesson.

Creating a New Scenario

Create a new scenario with a run time of 1 day:

  1. Launch STK ().
  2. Click Create a Scenario () in the Welcome to STK window.
  3. Enter the following in the STK: New Scenario Wizard:
    4. Option Value
    Name Exploring_Plugin_Points
    Start Default
    Stop Default
  4. Click OK when you finish.
  5. Click Save () when the scenario loads. A folder with the same name as your scenario is created for you in the location specified above.
  6. Verify the scenario name and location.
  7. Click Save.

Save Often!

Examining Message Viewer

Before continuing the mission development, confirm that STK can find the python path. This will be shown in the message viewer.

  1. Extend the View menu.
  2. Select Message Viewer.
  3. Confirm that STK has found the python installation. It will state "Found Python installation at C:\<file path>".
  4. Close () the Message Viewer.

Loading in the Constraint Plugin

The first plugin point we will use is the RangeExample.py constraint plugin. Load the plugin into STK.

  1. Extend the Edit menu.
  2. Select Preferences.
  3. Select the Python Plugins page.
  4. Click Add.
  5. Navigate to the RangeExample.py file from the install directory.
  6. Click Open.
  7. Click OK.

Reopening the Scenario

Application level plugins must be configured before creating or loading the scenario. Now that the plugin is loaded into the scenario, we need to save the scenario, close it, and reopen it

  1. Save () the scenario.
  2. Close () STK.
  3. Launch STK ().
  4. Click Open a Scenario () in the Welcome to STK window.
  5. Navigate to your saved scenario file.
  6. Click Open.

    7. You can now use the RangeExample.py plugin.

Modeling an Aircraft

We'll model a simple mission. Begin with an aircraft object flying from one side of the continental US to the other. The steps below insert exact values for the aircraft's () route. The exact values are not necessary. We can alternatively use 2D or 3D Object Editing to define the aircraft's () route. Simply place one point on the west coast of the US and the second point on the east coast.

  1. Select Aircraft () in the Insert STK Objects tool.
  2. Select the Define Properties () method.
  3. Click Insert....
  4. Click Insert Point twice on the Basic - Route page.
  5. Enter the following. Press the Enter key on the keyboard after each entry:
    6. Option Value
    Waypoint 1 - Latitude 47.4493 deg
    Waypoint 1 - Longitude -122.308 deg
    Waypoint 2 - Latitude 25.796 deg
    Waypoint 2 - Longitude -80.2869 deg
  6. Click OK.
  7. Rename Aircraft1 () Flight.

Modeling a Satellite

Now we will model a satellite which we will compute Access with the aircarft.

  1. Select Satellite () in the Insert STK Objects tool.
  2. Select the Orbit Wizard () method.
  3. Select Show All Objects in the Graphics section of the Orbit Wizard.
  4. Set the following in the Orbit Wizard:
    5. Option Value
    Type Orbit Designer
    Satellite Name SimpleSat
    Semi-major Axis 7000 km
    Eccentricity 0
    Inclination 45 deg
    Argument of Perigee 0 deg
    RAAN Adjust the RAAN value, so the satellite will be overhead of the aircraft's route at the beginning of the scenario. This will ensure Access between the satellite and aircraft.
    True Anomaly 45 deg
  5. Click OK.

Access

Now that the aircraft and satellite are in the scenario, we will compute access between the two objects. The plugin we loaded in (but haven't set yet) will be an access constraint. Let's first understand the access interval before we add the access constraint into the calculation.

Computing Access

Compute access between the satellite and aircraft.

  1. Right-click on SimpleSat () in the Object Browser.
  2. Select Access ().
  3. Set the Access for object to SimpleSat
  4. Select Flight () from the Associated Objects list.
  5. Click Compute.

Generating an Access report

Generate Access report to confirm you have at least one access interval.

  1. Click Access.... in the Reports section of the Access Tool.
  2. Confirm that you have at least one access interval.
  3. If you do not have at least one access, you will adjust the satellite’s RAAN in the next section.
  4. Close () the Access report.

Adjusting the satellite's RAAN

If you have at least one access, skip to the next section. If you don't, follow the steps below to adjust the satellite's RAAN.

  1. Right-click on SimpleSat () in the Object Browser.
  2. Select Satellite.
  3. Select Orbit Wizard...
  4. Adjust the RAAN value, so the satellite will be overhead of the aircraft's route at the beginning of the scenario.
  5. Click Apply.
  6. Look at the Timeline View at the bottom of STK GUI.
  7. Determine if you have at least one access interval.

    8. Continue to adjust the RAAN until you have at least one access interval.

  8. Click OK when access is achieved.

Generating an AER report

Generate an AER report. AER stands for Azimuth, Elevation, and Range.

  1. Return to the Access Tool.
  2. Click AER. in the Reports section.
  3. Review the Range column. With the current setup, the range values are between 650 km - 2800 km.
  4. Leave the report open.

Using the Constraint Plugin

We now know what the access is without range constraints. Let's now use the constraint plugin to set a minimum and maximum limit for the range.

Adding constraint plugin

Add the constraint plugin to the aircraft's properties.

  1. Open Flight's () properties ().
  2. Select the Constraints - Active page.
  3. Click Add new constraints () in the Active Constraints toolbar.
  4. Select PythonRangeExample in the Constraint Name list when the Select Constraints to Add dialog box opens.
  5. Click Add.
  6. Click Close to close the Select Constraints to Add dialog box.
  7. PythonRangeExample is listed under Constraint Name since we loaded the plugin earlier in the lesson.

Setting range constraints

Set the min and max range constraint.

  1. Select the Min check box.
  2. Select the Max check box.
  3. Enter the following values, starting with the maximum:
    4. Option Value
    Max 1000000 m
    Min 700000 m

    Note that we are setting the maximum value first to keep the values within a valid range. We also need to include the units (m).

  4. Click Apply.

Examining the Range Constraint

With range constraints set, reexamine the AER report.

  1. Refresh () the AER report.
  2. Notice the duration of the access intervals has been shortened and the range values are now between 700 km - 1000 km

Using this plugin, users can define a custom range constraint for their access intervals.

Removing the Range Constraint

Remove the range constraint from the aircraft.

  1. Return to Flight's () Contraints - Plugin properties () page.
  2. Clear Min.
  3. Clear Max.
  4. Click OK to accept the changes and close the Proerties Browser.

CalcScalar Plugin

The second plugin point we will examine is in Analysis Workbench Tools. Scenario level plugins are configured for each plugin point that is created within a scenario. We'll use the sample CalcScalar_Plugin_Example.py in this section.

Opening Analysis Workbench

Navigate to the Analysis Workbench's Calculation Tool.

  1. Extend the Analysis menu.
  2. Select Analysis Workbench ().
  3. Select the Calculation tab.

Creating a Scalar

Start by creating a new Scalar Calculation () for the satellite with set the Type to Plugin.

  1. Select SimpleSat () in the Object list.
  2. Click Create new Scalar Calculation ().
  3. Click Select... next to the Type field.
  4. Select Plugin in the Select Component Type list.
  5. Click OK.
  6. Enter CalcScalarExample in the Name: field.

Setting the Plugin

Set the new scalar calculation to be the sample CalcScalar_Plugin_Example.py file.

  1. Select Python in the Select Plugin Name list.
  2. Click Plugin Settings....
  3. Click click to edit in the Filename Value field.
  4. Navigate to the CalcScalar_Plugin_Example.py file in the install directory.
  5. Click Open.

    6. You should now see the Properties filled in with the MyDouble & MyString variables. If there is a configuration, as in this case, you will see it under Properties. This example is simple and users can reference it when developing their own plugins.

  6. Click OK to close the CalcScalar Plugin Settings window.
  7. Click OK to close the Edit Component Properties window.

Examining the Plugin

This plugin also had a simple calculation: adding the Cartesian X and Cartesian Z components. Let's take a look at the result.

  1. Return to the Analysis Workbench () window.
  2. Right-click on CalcScalarExample () in the Components for: SimpleSat list.
  3. Select Report/Graph...
  4. Hold the Ctrl key down on the keyboard.
  5. Select CalcScalarExample & CalcScalarExample Rate in the Select Report Elements list.
  6. Click Create Report.
  7. Review the results.

While not a significant result, the intention is to show how python plugins can be loaded in and used in analysis and reports.

Saving Your Work

  1. Close any open reports, properties and tools which are still open.
  2. Save () your work.

Summary

This scenario walked you through using the new python plugin points. We began by exploring the files from the install directory. Then we built the scenario, loaded in the plugin files, and demonstrated ways they can be used for analysis.

On Your Own

There are many ways to use plugins with STK and we've explored a few examples. On your own, modify the existing plugins or create your own and further develop your mission.