STKObjectRoot#

class ansys.stk.core.stkobjects.STKObjectRoot#

Bases: ISTKObject, ILifetimeInformation, IAnimation

Top-level object in the Object Model Hierarchy.

Overview#

Methods

`execute_command`	Execute a custom CONNECT action. The method throws an exception if the command has failed.
`load_scenario`	Use Load method. Loads a scenario using the specified path. The method throws an exception if there is a scenario already loaded.
`close_scenario`	Close the scenario. The method throws an exception if no scenario has been loaded.
`new_scenario`	Create a new scenario. User must close a scenario before creating a new one; otherwise an exception will occur.
`save_scenario`	Use Save method. Saves the changes made to the scenario.
`save_scenario_as`	Use SaveAs method. Saves the changes made to the scenario to a specified path and file name.
`load_custom_marker`	Add a custom marker to Application.
`get_object_from_path`	Get the object instance that matches the path provided.
`all_instance_names_in_xml`	Return an XML representation of AllInstanceNames.
`begin_update`	Signals the object that the batch update is starting.
`end_update`	Signals the object that the batch update is complete.
`execute_multiple_commands`	Execute multiple CONNECT actions. The behavior of the method when encountering an exception varies depending on the setting of the Action parameter. See the help for ExecuteMultipleCommandsMode.
`isolate`	Make the unit preferences of the current instance isolated.
`load_vdf`	Load a vdf using the specified path. The method throws an exception if there is a scenario already loaded. If the password isn’t needed, enter an empty string.
`object_exists`	Check whether a currently loaded scenario contains an object with the given path.
`get_licensing_report`	Return a formatted string that contains the license names and their states. The string is formatted as an XML document.
`save_vdf_as`	Save the changes made to the scenario to a specified path and file name as a vdf file.
`load`	Load a scenario/vdf using the specified path. The method throws an exception if there is a scenario already loaded.
`save`	Save the changes made to the scenario/vdf.
`save_as`	Save the changes made to the scenario/vdf to a specified path and file name.
`load_vdf_from_sdf`	Do not use this method, as it is deprecated. SDF functionality has been removed and this will be removed in the next major release. Loads a vdf from SDF using the specified path. The method throws an exception if there is a scenario already loaded.
`load_vdf_from_sdf_with_version`	Do not use this method, as it is deprecated. SDF functionality has been removed and this will be removed in the next major release. Loads a vdf from SDF using the specified path. The method throws an exception if there is a scenario already loaded.
`save_vdf_to_sdf`	Do not use this method, as it is deprecated. SDF functionality has been removed and this will be removed in the next major release. Saves a vdf to SDF at the specified location. The method throws an exception if the VDF creation or upload fails.
`subscribe`	“””Return an ISTKObjectRootEventHandler that is subscribed to handle events associated with this instance of STKObjectRoot.”””

Properties

`units_preferences`	Provide access to the Global Unit table.
`current_scenario`	Return a Scenario object or null if no scenario has been loaded yet.
`isolated`	Return whether the instance is isolated.
`conversion_utility`	Return the conversion utility interface.
`military_standard_2525b_symbols`	Return the interface that enables creating 2525b symbols.
`available_features`	Allow the user to inquiry about the available features.
`analysis_workbench_components_root`	Return an instance of VGT root object.
`central_bodies`	Return a collection of available central bodies.
`notification_filter`	Temporarily disable only the root events to prevent them from being raised. The event filtering can be used to improve client application performance.
`preferences`	Configures STK preferences.
`rf_channel_modeler`	Return an RF Channel Modeler object.

Examples#

Extract data from Connect results

result = root.execute_command('Report_RM */Place/MyPlace Style "Cartesian Position"')

for i in range(0, result.count):
    cmdRes = result.item(i)
    print(cmdRes)

Use arrays to send and retrieve data with Connect

from ansys.stk.core.stkutil import ExecuteMultipleCommandsMode

connect_cmds = ["GetStkVersion /", "New / Scenario ExampleScenario"]
results = root.execute_multiple_commands(connect_cmds, ExecuteMultipleCommandsMode.CONTINUE_ON_ERROR)

first_message = results.item(0)
also_first_message = results[0]

for message in results:
    print(message.count)

Execute multiple Connect commands

commandList = [["New / */Place MyPlace"], ["SetPosition */Place/MyPlace Geodetic 37.9 -75.5 0.0"]]
root.execute_multiple_commands(commandList, ExecuteMultipleCommandsMode.EXCEPTION_ON_ERROR)

Execute a Connect command

root.execute_command("New / */Target MyTarget")

Attach to an already running STK Runtime instance and get a reference to the STK object root

# 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()

Start STK Runtime and get a reference to the STK object root

# 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()

Start STK Desktop and get a reference to the STK object root

# 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

# ...

# Clean-up when done
stk.shutdown()

Get a reference to the STK object root using a running STK desktop application instance

# 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

Initialize STK Engine in no graphics mode and get a reference to the STK object root

# 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()

Initialize STK Engine with graphics and get a reference to the STK object root

# 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()

Set unit preferences for the Object Model

# STKObjectRoot root: STK Object Model Root
root.units_preferences.item("DateFormat").set_current_unit("UTCG")
root.units_preferences.item("Distance").set_current_unit("km")

Create a new Scenario

# STKObjectRoot root: STK Object Model Root
root.new_scenario("Example_Scenario")

Manage STK Desktop application events

from ansys.stk.core.stkdesktop import STKDesktop
from ansys.stk.core.stkobjects import STKObjectType


def on_stk_object_added_custom_callback(path: str):
    print(f"{path} has been added.")


stk = STKDesktop.start_application(visible=True)
root = stk.root
root.new_scenario("ExampleScenario")
stk_object_root_events = root.subscribe()
stk_object_root_events.on_stk_object_added += on_stk_object_added_custom_callback
scenario = root.current_scenario

# on_stk_object_added_custom_callback is successfully called when the next line is executed
facility = scenario.children.new(STKObjectType.FACILITY, "Exton")

# Now switch control to the desktop application and create another facility.
# The user interface becomes unresponsive.

# Now open a tkinter window that processing Windows messages.
from tkinter import Tk

window = Tk()
window.mainloop()

Manage STK Engine events

# STKObjectRoot root: STK Object Model Root
def on_scenario_new_custom_callback(path: str):
    print(f"Scenario {path} has been created.")


stk_object_root_events = root.subscribe()
stk_object_root_events.on_scenario_new += on_scenario_new_custom_callback

root.new_scenario("ExampleScenario")
# callback should be executed now

# remove the callback from the handler
stk_object_root_events.on_scenario_new -= on_scenario_new_custom_callback

# all finished with events, unsubscribe
stk_object_root_events.unsubscribe()

Close an open Scenario

# STKObjectRoot root: STK Object Model Root
root.close_scenario()

Open a Viewer Data File

# STKObjectRoot root: STK Object Model Root
if os.name == "nt":
    installPath = r"C:\Program Files\AGI\STK 12"
else:
    installPath = os.environ["STK_INSTALL_DIR"]
vdfPath = "Data", "ExampleScenarios", "Intro_STK_Space_Systems.vdf"
root.load_vdf(os.path.join(installPath, *vdfPath), "")

Import detail#

from ansys.stk.core.stkobjects import STKObjectRoot

Property detail#

property STKObjectRoot.units_preferences: IUnitPreferencesDimensionCollection#

Provide access to the Global Unit table.

Examples#

Set unit preferences for the Object Model

# STKObjectRoot root: STK Object Model Root
root.units_preferences.item("DateFormat").set_current_unit("UTCG")
root.units_preferences.item("Distance").set_current_unit("km")

property STKObjectRoot.current_scenario: ISTKObject#: Return a Scenario object or null if no scenario has been loaded yet.

property STKObjectRoot.isolated: bool#: Return whether the instance is isolated.

property STKObjectRoot.conversion_utility: ConversionUtility#: Return the conversion utility interface.

property STKObjectRoot.military_standard_2525b_symbols: MilitaryStandard2525bSymbols#: Return the interface that enables creating 2525b symbols.

property STKObjectRoot.available_features: AvailableFeatures#: Allow the user to inquiry about the available features.

property STKObjectRoot.analysis_workbench_components_root: IAnalysisWorkbenchRoot#: Return an instance of VGT root object.

property STKObjectRoot.central_bodies: CentralBodyCollection#: Return a collection of available central bodies.

property STKObjectRoot.notification_filter: None#: Temporarily disable only the root events to prevent them from being raised. The event filtering can be used to improve client application performance.

property STKObjectRoot.preferences: Preferences#: Configures STK preferences.

property STKObjectRoot.rf_channel_modeler: Any#: Return an RF Channel Modeler object.

Method detail#

STKObjectRoot.execute_command(self, connect_command: str) → ExecuteCommandResult#

Execute a custom CONNECT action. The method throws an exception if the command has failed.

Parameters:: connect_command : str
Returns:: ExecuteCommandResult

STKObjectRoot.load_scenario(self, path: str) → None#

Use Load method. Loads a scenario using the specified path. The method throws an exception if there is a scenario already loaded.

Parameters:: path : str
Returns:: None

STKObjectRoot.close_scenario(self) → None#

Close the scenario. The method throws an exception if no scenario has been loaded.

Returns:: None

Examples#

Close an open Scenario

# STKObjectRoot root: STK Object Model Root
root.close_scenario()

STKObjectRoot.new_scenario(self, scenario_name: str) → None#

Create a new scenario. User must close a scenario before creating a new one; otherwise an exception will occur.

Parameters:: scenario_name : str
Returns:: None

Examples#

Create a new Scenario

# STKObjectRoot root: STK Object Model Root
root.new_scenario("Example_Scenario")

STKObjectRoot.save_scenario(self) → None#

Use Save method. Saves the changes made to the scenario.

Returns:: None

STKObjectRoot.save_scenario_as(self, sc_file_name: str) → None#

Use SaveAs method. Saves the changes made to the scenario to a specified path and file name.

Parameters:: sc_file_name : str
Returns:: None

STKObjectRoot.load_custom_marker(self, filename: str) → None#

Add a custom marker to Application.

Parameters:: filename : str
Returns:: None

STKObjectRoot.get_object_from_path(self, object_path: str) → ISTKObject#

Get the object instance that matches the path provided.

Parameters:: object_path : str
Returns:: ISTKObject

STKObjectRoot.all_instance_names_in_xml(self) → str#

Return an XML representation of AllInstanceNames.

Returns:: str

STKObjectRoot.begin_update(self) → None#

Signals the object that the batch update is starting.

Returns:: None

STKObjectRoot.end_update(self) → None#

Signals the object that the batch update is complete.

Returns:: None

STKObjectRoot.execute_multiple_commands(self, connect_commands: list, action: ExecuteMultipleCommandsMode) → ExecuteMultipleCommandsResult#

Execute multiple CONNECT actions. The behavior of the method when encountering an exception varies depending on the setting of the Action parameter. See the help for ExecuteMultipleCommandsMode.

Parameters:

connect_commands : list

action : ExecuteMultipleCommandsMode

Returns:

ExecuteMultipleCommandsResult

STKObjectRoot.isolate(self) → None#

Make the unit preferences of the current instance isolated.

Returns:: None

STKObjectRoot.load_vdf(self, path: str, password: str) → None#

Load a vdf using the specified path. The method throws an exception if there is a scenario already loaded. If the password isn’t needed, enter an empty string.

Parameters:

path : str

password : str

Returns:

None

Examples#

Open a Viewer Data File

# STKObjectRoot root: STK Object Model Root
if os.name == "nt":
    installPath = r"C:\Program Files\AGI\STK 12"
else:
    installPath = os.environ["STK_INSTALL_DIR"]
vdfPath = "Data", "ExampleScenarios", "Intro_STK_Space_Systems.vdf"
root.load_vdf(os.path.join(installPath, *vdfPath), "")

STKObjectRoot.object_exists(self, object_path: str) → bool#

Check whether a currently loaded scenario contains an object with the given path.

Parameters:: object_path : str
Returns:: bool

STKObjectRoot.get_licensing_report(self) → str#

Return a formatted string that contains the license names and their states. The string is formatted as an XML document.

Returns:: str

STKObjectRoot.save_vdf_as(self, vdf_file_name: str, password: str, description: str, window_id: str) → None#

Save the changes made to the scenario to a specified path and file name as a vdf file.

Parameters:

vdf_file_name : str

password : str

description : str

window_id : str

Returns:

None

STKObjectRoot.load(self, path: str) → None#

Load a scenario/vdf using the specified path. The method throws an exception if there is a scenario already loaded.

Parameters:: path : str
Returns:: None

STKObjectRoot.save(self) → None#

Save the changes made to the scenario/vdf.

Returns:: None

STKObjectRoot.save_as(self, file_name: str) → None#

Save the changes made to the scenario/vdf to a specified path and file name.

Parameters:: file_name : str
Returns:: None

STKObjectRoot.load_vdf_from_sdf(self, vdf_path: str, password: str) → None#

Do not use this method, as it is deprecated. SDF functionality has been removed and this will be removed in the next major release. Loads a vdf from SDF using the specified path. The method throws an exception if there is a scenario already loaded.

Parameters:

vdf_path : str

password : str

Returns:

None

STKObjectRoot.load_vdf_from_sdf_with_version(self, vdf_path: str, password: str, version: float) → None#

Do not use this method, as it is deprecated. SDF functionality has been removed and this will be removed in the next major release. Loads a vdf from SDF using the specified path. The method throws an exception if there is a scenario already loaded.

Parameters:

vdf_path : str

password : str

version : float

Returns:

None

STKObjectRoot.save_vdf_to_sdf(self, sdf_path: str) → None#

Do not use this method, as it is deprecated. SDF functionality has been removed and this will be removed in the next major release. Saves a vdf to SDF at the specified location. The method throws an exception if the VDF creation or upload fails.

Parameters:: sdf_path : str
Returns:: None