Migration Guide
If you have existing code that uses win32com or comtypes to exercise STK, your existing code should be compatible with the new library once you update the initialization code.
Update your existing code using win32com or comtypes to initialize STK with the corresponding code for each use case:
Starting new STK Desktop instance
| [Python - win32com] |
# Start new instance of STK using win32com
from win32com.client import Dispatch
stk = Dispatch('STK12.Application')
stk.Visible = True
# Get the IAgStkObjectRoot interface
root = stk.Personality2
|
|
| [Python - comtypes] |
# Start new instance of STK using comtypes
from comtypes.client import CreateObject
stk = CreateObject('STK12.Application')
stk.Visible = True
# Get the IAgStkObjectRoot interface
root = stk.Personality2
|
|
| [Python - STK API] |
# Start new instance of STK using the new API
from agi.stk12.stkdesktop import STKDesktop
stk = STKDesktop.StartApplication(visible=True)
# Get the IAgStkObjectRoot interface
root = stk.Root
|
|
Attaching to running instance of STK Desktop
| [Python - win32com] |
# Attach to running instance of STK using win32com
from win32com.client import GetActiveObject
stk = GetActiveObject('STK12.Application')
stk.Visible = True
# Get the IAgStkObjectRoot interface
root = stk.Personality2
|
|
| [Python - comtypes] |
# Get reference to running STK instance using comtypes
from comtypes.client import GetActiveObject
stk = GetActiveObject('STK12.Application')
stk.Visible = True
# Get the IAgStkObjectRoot interface
root = stk.Personality2
|
|
| [Python - STK API] |
# Get reference to running STK instance using the new API
from agi.stk12.stkdesktop import STKDesktop
stk = STKDesktop.AttachToApplication()
# Get the IAgStkObjectRoot interface
root = stk.Root
|
|
Starting STK Engine
| [Python - win32com] |
# Start new instance of STK Engine using win32com
from win32com.client import Dispatch
stk = Dispatch('STKX12.Application')
# optionally, stk.NoGraphics = True
# Get the IAgStkObjectRoot interface
root = Dispatch('AgStkObjects12.AgStkObjectRoot')
|
|
| [Python - comtypes] |
# Start new instance of STK Engine using comtypes
from comtypes.client import CreateObject
stk = CreateObject('STKX12.Application')
# optionally, stk.NoGraphics = True
# Get the IAgStkObjectRoot interface
root = CreateObject('AgStkObjects12.AgStkObjectRoot')
|
|
| [Python - STK API] |
# Start new instance of STK Engine using the new API
from agi.stk12.stkengine import STKEngine
stk = STKEngine.StartApplication(noGraphics=False) # optionally, noGraphics = True
# Get the IAgStkObjectRoot interface
root = stk.NewObjectRoot()
|
|
Refactoring comtypes QueryInterface calls
In order to access the properties and methods on another interface, comtypes requires the use of the QueryInterface method. Without this call those properties and methods are not accessible. This constraint does not exist with the new API. When an object implements multiple interfaces, all the methods and properties from those interfaces are directly accessible at runtime.
Note that you can optionally explicitly navigate interfaces exposed by the same object. This helps your IDE in providing better auto-completion hints. The IDE auto-completion engines need to determinate statically the type of a variable. Certain methods such as IAgStkObjectCollection.New return an IAgStkObject interface but it may be desirable for IDE code completion to work on the underlying object type (e.g. AgFacility, AgSatellite). Without the explicit cast, the IDE will not be able to know which object has been returned, although runtime method availability will be unaffected by the choice of whether or not to explicitly cast.
| [Python - comtypes] |
facilityObj = root.CurrentScenario.Children.New(STKObjects.eFacility, 'facility') # New returns IAgStkObject interface
print(facilityObj.InstanceName)
facility = facilityObj.QueryInterface(STKObjects.IAgFacility) # Switches to the IAgFacility interface
print(facility.UseTerrain)
|
|
STK API, option 1 - explicit cast, best for IDE code completion:
| [Python - STK API] |
facility = AgFacility(root.CurrentScenario.Children.New(AgESTKObjectType.eFacility, 'facility')) # facility variable's static type is AgFacility
print(facility.InstanceName) # InstanceName is suggested by the IDE as AgFacility exposes that method
print(facility.UseTerrain) # UseTerrain is also suggested by the IDE as AgFacility exposes that method
|
|
STK API, option 2 - limited IDE code completion:
| [Python - STK API] |
facility = root.CurrentScenario.Children.New(AgESTKObjectType.eFacility, 'facility') # facility variable's static type is IAgStkObject
print(facility.InstanceName) # InstanceName is suggested by the IDE as IAgStkObject exposes that property
print(facility.UseTerrain) # UseTerrain is not suggested by the IDE as it is a property of IAgFacility and not of IAgStkObject
|
|
OleColor to Color
In win32com and comtypes you had to pass the OleColor value to properties and methods. You can now use the predefined colors from agi.stk12.utilities.colors.Colors class. Alternatively, use the below method to convert the OleColor value to RGB values (for example, OleColor 16776960 yields r,g,b = 0, 255, 255 or Cyan). You can then use the agi.stk12.utilities.colors.Color.FromRGB method.
| Method |
|
red = oleValue % 256
green = (oleValue / 256) % 256
blue = ((oleValue / (256*256)) % 256
|
Enumeration Migration
With the STK Python API, Enumerations are now class types. In win32com and comtypes you passed the int value for enumerations. To migrate old code search for the enumeration class in the help to get a table showing what each int value is. If you do not know the enumeration class type then find the method, property or interface in the help and it should link to the enumeration class.
| [Python - win32com] |
fac1 = scenario.Children.New(8, 'fac1')
|
|