Vue 6 Infinite Python Documentation

Welcome to the online Python documentation of Vue 6 Infinite!

Python is the industry standard, cross-platform, object-oriented application scripting language. It is both sufficiently easy to use and powerful to let you develop complex scripts and expand the capabilities of Vue 6 Infinite.
Included on the Vue 6 Infinite CD's are a selection of sample Python scripts that demonstrate typical effects that can be achieved with Python. These scripts are fully documented and we recommend that you take a look at the way they are written for a good example of Python scripting. You can find them in the Python/Scripts folder of the Application CD.
There are many online documents and tutorials about Python on the internet. If you are not familiar with Python scripting, we recommend that you read general documentation on Python before delving into the intricacies of Vue 6 Infinite Python implementation. Please read below for details on the Python Console and interpreting Python commands.
Interesting places to look for Python documentation are:

• http://www.python.org: this is the Python homepage. You will find documentation, tutorial and links to more Python-related websites.
• http://www.hetland.org/python/instant-python.php: if you are familiar with scripting or programming, this page will get you up and running with Python within minutes.

Because Vue Infinite features its own Python interpreter, you do not need to install any additional software in order to create and run Python scripts in Vue Infinite.

Python Scripts

Python scripts are text files that contain a list of Python statements and function calls. These files usually carry the extension .PY. You can find sample Python scripts in the Python/Scripts folder of your Application CD.
Basically, there are 3 types of Python functions in Vue Infinite:

• Functions that create or modify objects,
• Functions that define specific processing and that are called back by Vue Infinite at various points during execution; these are know as callback functions,
• Functions that setup the callback functions so that they are actually called back by Vue Infinite at the desired point of execution.

The first type of function is typically used in "helper" scripts that could be written to automate certain tasks, such as e.g. generating a patch of grass. The callback functions are used to really "customize" the behavior of Vue Infinite and create entirely new rendering geometries and effects.

Running Python Scripts

To run an existing Python script, simply select the menu command Python | Run Python Script in Vue Infinite. This will open a standard file browser letting you browse to the Python script that you would like to run. By default, the file browser is opened on the Python/Scripts sub-folder of your Vue Infinite folder.
The first time you run a script, it will be compiled on the fly by the Python interpreter and a compiled Python script will be generated and executed. This is to make sure that the script can be executed with maximum performance. Compiled Python scripts carry the extension .PYC. Please note that although the script is compiled and Python performance is very good considering that it is an interpreted script, performance is in no way comparable to hard-coded effects.
The most recently used scripts are listed at the bottom of the Python menu. To re-run a recently used script, simply select it from this list.

Startup Scripts

Startup scripts are script files that are loaded and executed whenever a given scene is loaded. These startup scripts usually setup callback functions, but they could be used for any purpose. For instance, you could easily write a script that creates a new sphere each time a scene is loaded!
Setting up callbacks using a startup script is very useful as it avoids having to set them up manually each time the scene is loaded. For instance, if you look at the scripts in the Python/Scripts/Filters folder of your Application CD, you will notice that these scripts setup callback functions to post-process the pictures as they are rendered. But if you save the scene and open it later, you'll have to run the script again, so that it restores the callbacks. This is where setting a startup script becomes useful:
If you call the VUEScene::SetPythonStartupScriptPath() function with the name of the script as parameter, the script will automatically be loaded and run next time you load the scene.
Now take a look at the scripts in the Python/Scripts/Quartic folder of your Application CD. There are two scripts in this folder, one called Quartic_Builder.py, the other Quartic_Startup.py. If you examine the code in the Builder, you will see that it creates a Python object, and then runs the Startup script. The Startup script sets up several call backs, and then sets itself as the startup script by calling the function. That way, the next time you load this scene, the Python object won't be created again, but the call backs will be properly setup.

Running Python from Command Line

You can run Python scripts from the command line using the -p command. Vue Infinite will immediately load and run the indicated Python script after starting up. For instance, you could write a Python script that loads a scene and then renders it before closing. To run a Python script at startup, run Vue 6 Infinite from the command line with the option -p<Name of Python script> (note: there should be no space between '-p' and the file name; you should add quotes (") around the file name if it contains spaces)
For example, to run myscript.py at startup, browse to the Vue 6 Infinite application folder and enter on Windows systems:

 Vue 6 Infinite.exe -p "C:\\Program Files\\e-on software\\Vue 6 Infinite\\python\\scripts\\myscript.py" 

On Mac OS X system, open a terminal window, go to the Vue 6 Infinite application folder and enter:

 .Vue 6 Infinite.app/Contents/MacOS/Vue 6 Infinite -p "/Applications/Vue 6 Infinite/python/scripts/myscript.py" 

Creating Python Scripts

To create or modify a Python script, all you need is a text editor. Open the text editor and start entering a list of Python commands.
Don't forget to save your script with the .PY extension, or it won't be listed in the file browser when you try to run it in Vue Infinite. You can check that the script performs as expected by running it on regular occasions.

Python Console

The Python Console can be accessed by selecting the menu command Python | Display Console. This console provides feedback on the success of running Python commands or scripts. It is a Python interpreter that can also be used by advanced users to enter commands directly, rather than creating stand-alone Python script files.
You can enter Python statements and function calls at the ">>>" prompt. For instance, entering VUEInterface::AddSphere() at the prompt and pressing enter will add a sphere to the current scene.

Python Documentation

This document contains a detailed list of all the Python structures and functions used in Vue Infinite.
The inline documentation will be updated when any changes are made to the Python interface, so it supersedes the printed version in the Reference Manual.
Python scripts create, modify and customize Vue Infinite through the use of classes. There are basically two types of classes in Vue Python:

• global classes such as VUEApplication, VUEInterface and VUEScene, and
  
• instantiated classes that mirror elements in the Vue scene.
  

For a list of all Python classes in Vue Infinite, check the Compound List section.
For a complete list of all Python functions and enumerations, check the Compound Members section.

Global Classes

The VUEApplication class represent hooks to Vue's global functions. The VUEInterface and VUEScene respectively represent hooks to Vue's interface and to the current scene. Because there is no ambiguity when using a function of these classes, you don't need to name the instance when you want to use one of these functions. For instance, the VUEInterface::AddSphere() function is a member of the VUEInterface class, but you can call it directly by typing VUEInterface::AddSphere(). This function is accessible globally, which would not be the case for e.g. a function that is a member of the VUEBasicObject class (see below).
Documentation for these classes can be found on the following links:

VUEApplication VUEInterface VUEScene

Instantiated Classes

The second type of Python classes in Vue requires instantiation, because otherwise, Python would not know which object you are talking about! This is the case of all classes representing primitives, lights, etc. as well as materials and Vue functions. Because you can have several objects in a scene, you do need to name the object before modifying it so that Python knows which one to modify.
A Python class is associated to each Vue Infinite element. For instance, when you create a sphere, an instance of a Python class will also be created and mapped to the sphere in Vue. Subsequent modifications of this Python "sphere equivalent" will immediately be reflected on the actual Vue sphere.
For instance, the VUEInterface::AddSphere() function in the VUEInterface class creates a sphere in the 3D Views, and returns a Python equivalent of that sphere, in the form of a VUEBasicObject. If, using the Python Console, you type:

 S = AddSphere() [Return] 

A sphere will appear in the 3D Views, and S will be mapped to that sphere. You can now use S to call any of the functions of a VUEBasicObject, e.g.:

 S.Move(0, 0, 50) [Return] 

will move the sphere 50 units upward. Click in a 3D View or type:

 Refresh() [Return] 

to refresh the views and see the sphere at its new position.

Object Classes

The following classes are used to handle the different types of objects in Vue Infinite. All these classes derive from the VUEBasicObject class, which means that VUEBasicObject functions can also be called e.g. for a VUEAggregate object:

VUEBasicObject VUEAggregate VUECamera VUELight VUEPointLight VUESpotLight VUEMeshObject VUETerrain VUETorus VUEPlant VUEEcosystem VUEPythonObject

Material and Function Classes

Documentation for handling materials and functions can be found on the following links:

VUEMaterial VUEFunction

---

Return to Vue Index