Built-in Python

From ANVEL Wiki
Jump to: navigation, search

Introduction

The built-in Python interpreter includes a full implementation of the Python Scripting language and the standard Python library. Common tasks with the built-in Python include setting up complex scenarios, logging or updating simulation properties, and automation of simulations. The utility of the built-in Python spans from setting simulation properties in an interactive shell to adding custom behaviors to any object.

Anvel-new-icon.png Python 3 use with the built-in Python is a new feature in ANVEL 3.5

ANVEL 3.5 is compatible with Python 3 for the built-in Python interpreter. Users can continue using Python 2.7 or elect to modify their ANVEL configuration to use Python 3.

The built-in Python is distinct from the ANVEL External API, despite the External API including the Python language as an option. The built-in Python has a lower-level connection with a specific running instance of ANVEL. Hence, it can directly access more simulation states. Mastering the advanced commands of built-in Python requires more in-depth knowledge of the simulation, but offers more control. However, even a novice user of ANVEL may use the feature to set simulation properties.

Python Method Remote Operation Commands Python 2 Python 3
Built-in Python No ANVELCommands and Modules yes yes
External API with Python Yes, but not necessary EXTERNALAPI yes to be supported in a future release

Python Console

The Python Console presents the interactive shell utility. Standard interactive functions, such as dir and help are supported along with autocompletion with the Tab key.

Beyond the standard Python library included with the ANVEL, additional Python modules can be loaded by adding them to the <user_data>\Scripts folder.

PythonConsole examples.png


Exported ANVEL Commands

Upon application launch, all registered ANVEL commands within the Anvel module export to Python scripts. They are organized by command category within the <user_data>\Scripts directory.

To call the command CreateInstance under the Assets category, use the following Python code:

Anvel.Assets.CreateInstance("MyObject", "MyObjectName", parentObjectID, position, orientation, scale, False);

Examples:

  • Place a Generic 4x4 into the center of the current environment in the default asset orientation:
Anvel.Assets.CreateInstance('Generic 4x4', 'Generic 4x4', 0, (7.84125, -1.58044, 0.724999890578), (1, 0, 0, 0), (1, 1, 1), False);

Rotate the vehicle in the above example by changing the specified orientation from (1, 0, 0, 0) to:

  • 90-degree clockwise rotation: (0.7071, 0, 0, -0.7071)
  • 90-degree counterclockwise rotation: (0.7071, 0, 0, 0.7071)
  • Any rotation using valid quaternion values

Commonly Used Commands

To add a Python library location to the system path:

sys.path.append('C:\\SomeFolder\\LibraryFolder')

To run a Python script:

exec (open(filename).read())

where filename includes the full path to the script file.

Example:

exec (open('/usr/PythonScriptFolder/Hello.py').read())

or

exec (open('C:/PythonScriptFolder/Hello.py').read())



The contents of Hello.py:

import Anvel

print ("Hello ANVEL")
# Create a Pine tree
Anvel.Assets.CreateInstance('Pine', 'My Tree1', 0, (-28.1, -16, -2.1), (1, 0, 0, 0), (1, 1, 1), False);
# Create a Pine tree and capture the object ID
myTreeID = Anvel.Assets.CreateInstance('Pine', 'My Tree2', 0, (0, 0, 0), (1, 0, 0, 0), (1, 1, 1), False);

Anvel.Simulation.Resume()
Anvel.Simulation.Pause()
print ("Good-bye ANVEL")

The captured object ID can be used to retrieve object properties.

Example:

myProperty = Anvel.GetPropertyByName(myTreeID,'Orientation')

Startup Scripts

Upon application launch, ANVEL attempts to locate the "AnvelUserStartupScript.py" file. If this file exists, it executes after the initial simulation has been loaded. By default, this file is found at <user_data>\Scripts\AnvelStartupScripts.

This can be used for loading additional custom scripts, calling user-specified commands, or for the user to provide additional initialization.

Anvel Module Methods

The Anvel module includes a number of custom methods exported only to the built-in Python interpreter. These commands supplement the normal collection of commands by providing additional convenience for regularly-used functionality.

  • Anvel.Version: Get the current ANVEL version.
  • Anvel.QueueCommand: Call any ANVEL command, through the normal command queue process.
  • Anvel.Command: Call any ANVEL command immediately. Normally, Anvel.QueueCommand should be used instead.
  • Anvel.Log: Logs 'string' to the ANVEL Log.
  • Anvel.RegisterCommand : Registers a command that will be processed with a Python function
  • Anvel.GetProperty: Gets the value of a property from the given ID and property index
  • Anvel.GetPropertyByName: Gets the value of a property from the given ID with the given property name
  • Anvel.SetPropertyByName: Sets the value of a property on the given ID to the value specified
  • Anvel.GetPropertyNames: Gets the set of properties available for a given type or object
  • Anvel.GetIdsByTypeName: Retrieves the active IDs for a given type
  • Anvel.GetTypeIdByName: Gets the ID of a type with the given name.

Detailed information on these methods is available.

Python Menu

Users can access the built-in Python interpreter through the Python menu.

Python menu.png

Export Python Interface: exports the current set of ANVEL commands to Python scripts, to the specified directory. This is called automatically on start up, writing the scripts to <user_data>\Scripts.

Execute Script: allows users to execute a Python script stored in a file.

See Also

Built-in Python Anvel Module
Built-in Python AnvelTypes Module
Built-in Python Anvel.Scripting Module
ANVELCommands
ANVEL External API
PythonScript Component
Setting Properties in Built-In Python