Tutorial

This topic contains the following sections:

Pre-requisites
Add References
Implementation
Run the Plugin
Next Steps

This tutorial provides a step-by-step guide for creating an example STK UI Plugin using the STK Parallel Computing Desktop API. The application built in this section is a toolbar button that, when clicked, will create a number of tasks that compute the sum of two integers and submit them to be computed in parallel.

A sample Visual Studio project containing the completed Add Example from the tutorial is located in the included Examples folder. See the README.txt file for instructions on how to install and run it.

Pre-requisites

Prior to beginning, make sure you:

have an installed version of STK.
follow the online tutorial for creating and registering an STK UI Plugin.

Add References

After the STK UI Plugin Visual Studio project has been created, add references to the STK Parallel Computing Plugin libraries:

In the Solution Explorer, right click References and select "Add References..."
Browse to the install location for STK Parallel Computing (typically "C:\Program Files\AGI\STK Parallel Computing 12") and select the AGI.STKParallel.PluginCore.dll and AGI.STKParallel.PluginServices.dll files from the "bin\STK 12" folder.
After the DLLs have been added as references, set the Copy Local property for each to False.

Implementation

Add a GUI Element

Continue following the STK UI Plugin tutorial to add a toolbar button, e.g.

Copy

public void OnInitializeToolbar(IAgUiPluginToolbarBuilder ToolbarBuilder)
{
  ToolbarBuilder.AddButton("AGI.TestUiPlugin.AddExample", "Parallel Add Example", "Run the parallel Add Example", AgEToolBarButtonOptions.eToolBarButtonOptionAlwaysOn, null);
}

When this button is clicked, it will create a job composed of tasks and submits the job for execution in parallel. To do so, we must first create the type of task to be executed.

Implement a Concrete ScenarioTask

ScenarioTask is an abstract class. To create a custom task, inherit from ScenarioTask and provide an implementation for the Execute function. It's important that the new class is marked with the [Serializable] attribute.

Add a new class to the Visual Studio solution, e.g. AddTask.cs, with the following implementation:

Copy

namespace TestUiPlugin
{
  using System;

  using AGI.STKObjects;
  using AGI.STKParallel.PluginCore;

  [Serializable]
  public class AddTask : ScenarioTask
  {
      private int A;
      private int B;

      public AddTask(int a, int b)
      {
          this.A = a;
          this.B = b;
      }

      public override void Execute(IAgStkObjectRoot root, IReportProgress progress, ILogger logger, Func<bool> checkIsCancelling)
      {
          this.Result = this.A + this.B;
      }
  }
}

Create the UI Plugin Exec Function

Continuing to follow the STK UI Plugin tutorial, create an Exec method that checks for the corresponding command sent from the previously added toolbar button:

Copy

public void Exec(string CommandName, IAgProgressTrackCancel TrackCancel, IAgUiPluginCommandParameters Parameters)
{
  if (string.Compare(CommandName, "AGI.TestUiPlugin.AddExample", true) == 0)
  {
    // STK Parallel Computing Plugin API code to create and execute a ScenarioJob goes here
  }
}

Create and Execute a Scenario Job

Fill in the body of the Exec function with the code below that uses the STK Parallel Computing Plugin API to construct a ScenarioJob, add ScenarioTasks to it, and executes it using the ScenarioJobExecutionService.

Copy

ScenarioJob job = new ScenarioJob();
job.Description = "Add UI Plugin Example";

int numTasks = 100;
for (int i = 0; i < numTasks; i++)
{
	job.AddTask(new AddTask(i, i + 1));
}

IJobExecutionService submitter = ScenarioJobExecutionService.GetInstance();
submitter.ExecuteJob(job);

The call to ExecuteJob will block until the job finishes. After this point, use the Status property to inspect if the job failed, was cancelled, or successfully completed.

Run the Plugin

Make sure the XML manifest file for the UI Plugin has been copied to one of the three locations where STK will see it:

the STK User Config Plugins directory (usually My Documents\STK 12\Config\Plugins)
the All Users Application folder (e.g. C:\ProgramData\AGI\STK 12\Plugins)
the STK install directory (usually C:\Program Files\AGI\STK 12\Plugins)

If using a COM UI plugin, make sure the plugin DLL has been successfully registered using the Windows Assembly Registration Tool (Regasm.exe).

Launch STK. If the application has found the plugin, the plugin's name will appear in the list on the Edit/Preferences/UI Plugins page and have a checkbox in the Active column.

Select the plugin's name under the View/Toolbars menu to make the plugin created toolbar visible. Click the button in the plugin toolbar to execute the parallel job.

Next Steps

A more in-depth sample application is located within the Examples/ComputeAccesses directory. This example project creates another STK UI Plugin that computes accesses between all pairs of facility and satellite objects found in the currently loaded STK scenario. This example provides a better demonstration of how to subdivide an STK computation into smaller tasks, similar to what is done when coverage, deck access, chains, or volumetrics are computed in parallel. For example, when chains are computed in parallel, each task computes accesses for one strand of the chain. When coverage is computed in parallel, each task computes accesses for a sub-region of the coverage grid.