Using 3D Canvas Scripting (Available with 3D Canvas Pro)

3D Canvas Pro provides scripting capabilities through the Microsoft Windows Script Host. Programmers and would-be programmers can use this feature to write small programs to do useful things in 3D Canvas such as create objects, animate lighting, export scene information etc.

For example, a script could be written to animate the brightness of a light to create a strobe effect, or create a pulsating object or most anything that you would want. It also can be used to write export scripts, import scripts or create new primitive objects.

Scripts can be written in VBScript, JScript (JavaScript) or any other scripting language that supports the Windows Script Host. Microsoft provides considerable information on using VBScript and JScript on their Windows Script Technologies web site.

In 3D Canvas there are two types of scripts: General Purpose Scripts and Animation Scripts

General Purpose Scripts

The Tools menu provides the ability to create, edit, delete and run scripts. To create a new script, select Create Script. A script editing window will open that allows you to type in, or paste in, a script. After you save your script you can run it by selecting Run Script. The Tools menu also provides the ability to Edit and Delete scripts.

3D Canvas General Purpose Scripts are saved as simple text files and are located in the Scripts folder within the 3D Canvas program folder. These General Purpose scripts can be distributed to other users of 3D Canvas Pro. You can also edit these files with any editor you wish.

A script can be very simple. The following script is written in VBScript and displays a message box that says "Hello World!":

Language = VBScript

Sub Main (CanvasApplication)

    MsgBox "Hello World!"

End Sub

The first line of a 3D Canvas Script must indicate the language in which the script in written. A general purpose 3D Canvas script must include a Sub named Main that has a single parameter. The Main Sub is run by 3D Canvas when you select Run Script from the Tools menu. 3D Canvas will provide a CanvasApplication object as an argument to this script. This object provides helper functions, information about 3D Canvas' current state and allows you to get the active Scene. See the CanvasApplication object documentation for more information.

Animation Scripts

3D Canvas scripts can also be used to animate Frames, Objects, Lights and the Animation Camera.

A script can be attached to a 3D Canvas scene component by right-clicking on it and selecting Open Component Script or Open Frame Script.

Following is a script for a Frame that animates a Frame along the Y axis:

Language = VBScript

Sub AnimateFrame (Time, CanvasFrame)

    CanvasFrame.SetPosition Nothing, Time, 5, Time, 5  

End Sub

A frame animation script must include a Sub named AnimateFrame that has two parameters. The AnimateFrame Sub is run by 3D Canvas prior to rendering when an animation is running or being recorded. 3D Canvas provides the animation key-frame being rendered (Time) and a CanvasFrame object. Any changes that you make to a frame's position and orientation overrides what 3D Canvas sets.

Note that the position and orientation you set will not be retained for the next time that AnimateFrame is called.

Following is a script for an Object that scales it over time:

Language = VBScript

Sub AnimateObject (Time, CanvasObject)

    Dim PointCount
    Dim PointIndex
    Dim PointX
    Dim PointY
    Dim PointZ

    'get the number of points in the object
    PointCount = CanvasObject.GetPointCount

    'Run through the points scaling them
    For PointIndex = 0 to PointCount - 1

        'get the point
        CanvasObject.GetPoint PointIndex, PointX, PointY, PointZ

        'scale the point
        PointX = PointX * (Time+1)
        PointY = PointY * (Time+1)
        PointZ = PointZ * (Time+1)

        'set the point
        CanvasObject.SetPoint PointIndex, PointX, PointY, PointZ

    Next

End Sub

An object animation script must include a Sub named AnimateObject that has two parameters. The AnimateObject Sub is run by 3D Canvas prior to rendering when in animation mode. 3D Canvas provides the animation key-frame being rendered (Time) and a CanvasObject object. Note that unlike the AnimateFrame sub, AnimateObject is called before each render in Animation Mode regardless of whether you are running an animation or not.

Note that the changes you make to the object will not be retained for the next time that AnimateObject is called. 3D Canvas will reset the object to the state it was in prior to your changes.

Following is a script for a light that makes it brighter over time.

Language = VBScript

Sub AnimateLight (Time, CanvasLight)

    'make sure that we don't set a color intensity > 1
    If Time < 10 Then
        CanvasLight.SetColor Time/10, Time/10, Time/10
    Else
        CanvasLight.SetColor 1, 1, 1
    End If

End Sub

A light animation script must include a Sub named AnimateLight that has two parameters. The AnimateLight Sub is run by 3D Canvas prior to rendering when in animation mode. 3D Canvas provides the animation key-frame being rendered (Time) and a CanvasLight object. Note that unlike the AnimateFrame sub, AnimateLight is called before each render in Animation Mode regardless of whether you are running an animation or not.

Note that the changes you make to the light will not be retained for the next time that AnimateLight is called. 3D Canvas will reset the light to the state it was in prior to your changes.

Following is a script for the Animation Camera that increases the Animation Camera's field of view over time:

Language = VBScript

Sub AnimateCamera (Time, CanvasCamera)

    CanvasCamera.SetFieldOfView (Time+1)*.1 

End Sub

A camera animation script must include a Sub named AnimateCamera that has two parameters. The AnimateCamera Sub is run by 3D Canvas prior to rendering when in animation mode. 3D Canvas provides the animation key-frame being rendered (Time) and a CanvasCamera object. Note that unlike the AnimateFrame sub, AnimateCamera is called before each render in Animation Mode regardless of whether you are running an animation or not.

Note that the changes you make to the light will not be retained for the next time that AnimateCamera is called. 3D Canvas will reset the camera to the state it was in prior to your changes.