Initialization#

This topic explains how to establish a connection and prepare PySTK for usage with Ansys STK® application interfaces and runnable programs.

Configurations#

To get started, determine the configuration that you want to use:

Configuration	Available options
Windows	STK desktop, STK Engine, STK Engine NoGraphics, STKRuntime
Linux	STK Engine, STK Engine NoGraphics, STKRuntime
Jupyter Notebook with 3D and 2D widgets	STK Engine

Initialize with the STK desktop application#

This section describes how to use PySTK with the STK desktop application.

The start_application() and attach_to_application() methods are available to obtain the STKDesktopApplication class and begin interacting with STK through the UiApplication API. From the application interface, the most common way to begin working with STK software is to use the StkObjectRoot class, which is accessible as the root property of the STKDesktopApplication object.

Start a new STK desktop application instance#

Use the start_application() method to start a new STK desktop application session:

# Start new instance of STK Desktop
from ansys.stk.core.stkdesktop import STKDesktop

stk = STKDesktop.start_application(visible=True)  # using optional visible argument

# Get the STK Object Root interface
root = stk.root

The start_application() method has optional arguments to control if the application should be visible, if it should exit when the Python script ends, and to switch to gRPC for communicating with the STK desktop application (instead of Windows automation by default).

Note

To learn more about gRPC see https://grpc.io/

Attach to a running STK desktop application instance#

Use the attach_to_application() method to attach to a running STK desktop application:

# Get reference to running STK Desktop instance
from ansys.stk.core.stkdesktop import STKDesktop

stk = STKDesktop.attach_to_application()

# Get the STK Object Root interface
root = stk.root

The attach_to_application() method has additional arguments to specify the Process ID (PID) if more than one STK application is running, as well as switching to gRPC for communicating with STK the desktop application (instead of Windows automation by default).

Initialize with STK Engine#

This section describes how to use PySTK with STK Engine. The STK Engine API is supported on both Windows and Linux, although some features are not supported on Linux. STK Engine runs in-process in your Python script, so unlike the STK desktop application, only one instance of engine is possible, which is started using start_application(), returning the STKEngineApplication class and giving access to the STKXApplication API. Unlike STKDesktopApplication, the object model root is not a property and a new root object may be obtained from the new_object_root() method on the STKEngineApplication object.

Initialize STK Engine with graphics#

To select this mode, do not specify any argument when calling start_application(), as by default the no_graphics argument is False.

# Initialize STK Engine with graphics in the current process
from ansys.stk.core.stkengine import STKEngine

stk = STKEngine.start_application(no_graphics=False)

# Get the STK Object Root interface
root = stk.new_object_root()

Initialize STK Engine without graphics#

If your use case consists of using STK Engine as a computational tool and does not require 2D/3D visualization (for instance, if your application is running as a service on a compute node without direct user interaction), skipping graphics mode results in faster load times and a lighter memory footprint. When graphics are not loaded, all 2D and 3D graphics support is skipped, and the code and libraries related to graphics do not get loaded into memory. Graphics cannot be used when running on hardware that does not have hardware or software support for OpenGL or X11 on Linux. It needs to be turned on during initialization and cannot be changed afterwards. The 2D, 3D and Graphics Analysis controls are not available. To avoid loading graphics, pass the no_graphics=True argument when initializing STK Engine:

# Initialize STK Engine without graphics in the current process
from ansys.stk.core.stkengine import STKEngine

stk = STKEngine.start_application(no_graphics=True)

# Get the STK Object Root interface
root = stk.new_object_root()

The NoGraphics mode also alters the way scenarios are saved and loaded. When an engine application in NoGraphics mode loads a scenario coming from the STK desktop application, the 2D and 3D information serialized as part of the scenario is ignored. If that scenario is then saved, all 2D and 3D information is lost. If the scenario is then loaded into the STK desktop application, default graphics options are used.

Finish your work with STK Engine#

STKEngineApplication provides a shutdown() method that is the recommended way to stop the connection to STK and free up resources. After calling that method, it is no longer valid to start a new engine application in the current process.

Tkinter globe control, map control, and graphics analysis control#

This section describes how to use PySTK with the Tkinter GlobeControl, MapControl, and GfxAnalysisControl classes.

Create a Tkinter window with a map control and a globe control#

from tkinter import Tk, BOTH, YES, LEFT
from ansys.stk.core.stkengine.tkcontrols import GlobeControl, MapControl

self.window = Tk()
self.globeControl = GlobeControl(self.window, width=320, height=200)
self.globeControl.pack(fill=BOTH, expand=YES, side=LEFT)
self.mapControl = MapControl(self.window, width=320, height=200)
self.mapControl.pack(fill=BOTH, expand=YES, side=LEFT)
self.window.update()

Initialize STKRuntime#

STKRuntime is an executable that serves STK Engine capabilities via gRPC. Use the stkruntime module to start or attach to a running STKRuntime application. Once the STKRuntimeApplication object is obtained, interact with STKRuntime, via StkObjectRoot obtained from calling new_object_root(). Shutting down the remote STKRuntime process is possible by calling shutdown(), or using the user_control=False option when starting the application.

Start a new STKRuntime instance#

STKRuntime may be started on the local machine using start_application(). While STKRuntime offers STK Engine capabilities similar to the STKEngine module, there are a few key differences, including:

STK Engine runs STK in-process with Python, whereas STKRuntime is out-of-process using gRPC to communicate.
STKRuntime does not offer visualizations at this time.

# Start new instance of STK Runtime
from ansys.stk.core.stkruntime import STKRuntime

stk = STKRuntime.start_application()

# Get the STK Object Root interface
root = stk.new_object_root()

The attach_to_application() method has additional arguments to control if the application should exit when the Python script ends, to enable the NoGraphics mode, and to customize the gRPC connection.

Attach to a running STKRuntime instance#

To attach to a running STKRuntime application via gRPC, you can use attach_to_application(). To shut down the STK Runtime application, shutdown() must be called.

# Attach to already running instance of STK Runtime
from ansys.stk.core.stkruntime import STKRuntime

stk = STKRuntime.attach_to_application()

# Get the STK Object Root interface
root = stk.new_object_root()

If you need to configure the gRPC connection with STKRuntime, the attach_to_application() method provides additional arguments such as the gRPC host, port, and timeout.