Scripts and plugins in 3D Canvas

Chapter 1: Introduction

3D Canvas is a program for 3D modelling and animation. It runs under Windows and you can get it for free at Amabilis. If you buy the Pro version you can write and run scripts and plugins to do many things. The author of 3D Canvas is Richard Borsheim.

This tutorial is by me,George Jenner.

In 3D Canvas scripts and plugins are little computer programs that run within the main program. Each line in a script contains an instruction. When you run a script within 3D Canvas, the lines in that script are executed one at a time: that is to say the instruction on that line of program code is carried out. Typically the instruction will have something to do with transforming the model you are working on within3D Canvas.

I use scripts to create objects and apply textures to them. You can also use them in the context of animation. I don't, so you won't find any help in that area on these pages. So rather than a tutorial it is really a description of my idiosyncratic use of the facility. The possibilities are infinitely more interesting than covered by my few pages.

You are welcome to use and change any program from these pages. For clarity (and my laziness) there is neither crash protection not input checking built into these programs. Please save your work before running them as crashing, freezing, and even rebooting, are possibilities.

To use the scripts

You need 3D Canvas Pro. You can either copy and paste them to the \scripts directory in the 3D Canvas Program directory, or download them all in one bunch from here. Scripts only run from that directory, and are plain text files with a ".cs" ending. You may need to restart 3D Canvas to access them.

If you have never written a computer program

This is not the place to start, but it's not far from it. Most of this work is in VBScript, a version of Microsoft's Visual Basic. The B in Ba is for Beginners, but the extensions for using Basic in 3D Canvas may be confusing. You might like to go away and learn some basic Basic (or Javascript) first.

A good place to start is writing macros in a spreadsheet program, such as MS Excel. I even use Excel to debug my scripts sometimes. The languages are the same (or at least from the same stable and trainer) and Excel has an excellent environment for debugging.

The scripting editor in 3D Canvas is functional but limited, and debugging is limited by the constraints of the language.

What you can and can't do with scripts in 3D Canvas

• You can create and manipulate objects (typically a model with geometry that is easily described mathematically). You do this by creating geometry, creating points in space to represent that geometry, then connecting the points with faces.
• You can apply textures to those objets, face by face. (I tend to use texture and material interchangeably. Pedants forgive)
• You can to animation stuff.
• You cannot (at least as yet) create objects using primitives.
• You cannot apply operations such as crease or smooth to the objects.
• You can have happy accidents. Here are two of today's accidents: a beach ball, and some crumpled cellophane.

If you have written programs but have never heard of object oriented languages

Hey, aren't digital watches a nifty idea?

Everything in your computer is an object these days. For example, if you are creating a model car in 3D Canvas then:
• 3D Canvas is an object of Windows
• The car is an object of 3D Canvas
• A face on that car is an object of the car

You'll have to get used to it.

Choice of language

Most of the scripts here are in VBScript.This is only because I started by modifying the example provided with 3D Canvas - which are in Visual Basic. You can use any language that supports the Microsoft Scripting Host: JScript, for example.

The advantages of VBScript:
• the code can be used nearly unmodified to make plugins. But to do that you need to buy MS Visual Basic Pro, which costs mucho dinero.
• you can rip off the code from the example scripts.

The advantages of JScript:
• There are many algorithms for graphics on the www. They are usually written in C++ or Java. These languages are easier to convert to JavaScript than to Visual Basic.
• It's weirder.

Script or plugin?

A plugin is like a script except that it is precompiled and is accessed by 3D Canvas as a .dll library file in the "plugins" directory.

As plugins are only useful for model creation (and not animation) they appear less useful. Plugins are more usefil than scripts when there is a lot of information required by the script. For example, if the script needed 10 numbers from the user to work, it would have to ask 10 questions. In a plugin written in a language (like Visual Basic and Delphi) that uses "forms", all the numbers can be displayed on one input form. You can also do things like access databases from plugins.

So far I have not noticed much difference in speed of execution between VBScript and plugins written in Visual Basic.

A Note on 3D Canvas Version 5.5

In Version 5.5 or 3D Canvas Frames where renamed as Groups (that is the Frame boxes around objects, not the animation Frames). All methods referring to Frames where also changed to reflect this. I hope I've caught all instances and fixed them, but maybe not. If your own scripts aren't running, this could be a cause.