Built-in Python

From ANVEL Wiki
Jump to: navigation, search

Introduction

The built-in Python interpreter includes a full implementation of the Python programming language and Python Standard 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 4.0 is compatible with Python 3 for the built-in Python interpreter. Users can continue using the default Python 2.7 or elect to modify their configuration to use Python 3.

Built-in Python functionality is distinct from API applications written in Python. The built-in Python provides lower-level access to the ANVEL core for a specific running instance of ANVEL, providing more control over simulation behavior but also requiring more advanced software development.

ANVEL Feature Interfaces Commands Python 2 Support Python 3 Support
Built-in Python Yes Yes
External API with a remote application written in Python
  • Local (loopback) applications
  • Remote network applications
Yes Partial

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.

To load a custom script using "AnvelUserStartupScript.py", follow the exec syntax for running a Python script.

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.

PythonScripts

Source: Python Interpreter Plugin
Python2.7 Script Manager

Name Description Type Attributes Unit
ScriptAppUpdateTime real ReadOnly s
SimUpdateTime Time spent updating script's OnSimUpdate method. real ReadOnly s
RenderUpdateTime real ReadOnly s
NumberSimUpdates Number of scripts registered with an OnSimUpdate method. uint32 ReadOnly
AverageSimUpdateTime Average OnSimUpdate time per script. real ReadOnly s

Python Script Properties

PythonScript

Source: Python Interpreter Plugin
Python2.7 Script Component

Name Description Type Attributes Unit
ScriptFile Script file name string
Data Script data namevaluelist ReadOnly
LastError Last error reported on this script string ReadOnly
CustomProperties Custom properties defined for this script namevaluelist
State uint32

See Also

Built-in Python Anvel Module

Built-in Python AnvelTypes Module

Built-in Python Anvel.Scripting Module

ANVELCommands

ANVEL External API

Configuration Parameters

PythonScript Component

Setting Properties in Built-In Python