Animation Master Python Script Plug-in

© Copyright 2001 - Petr Sorfa
(08/19/2001 - v0.4a Released - Many new commands (see examples), download here and see the Change Log
(08/13/2001 - v0.3b Released - Plug-in recompiled as non debug version, download here and the Change Log )
(08/12/2001 - v0.3a Released (see the Change Log for enhancements and fixes), with two new examples )
(08/05/2001 - Added code examples and screenshots)
(07/27/2001 - v0.2 Released : More commands and fixed transformations)
(07/12/2001 - v0.1 Released : Basic commands)

COMING SOON IN V0.5: Stuff! (Note that 0.5 will be released sometime in September)

Introduction

The Animation Master Python script plug-in allows folks to write their own programming scripts to create and change content in Animation Master v9.0.

Installation and Setup

To use the plug-in you need the following:

Windows - There should be a Mac port available soon though.
Animation Master v9.0 Tutorial 4 and higher - you can download it from here , as long as you have an AM2001 CD.
Python 2.1 - You need to install Python 2.1 on your system. You can download it from here.
The Animation Master Script Plugin - Download it and then copy the plug-in to your "hxt" directory under your Animation Master installation directory.

What can it do?

The plug-in attempts to borrow some of it's core ideas from Pixar's RenderMan interface language. Currently the plug-in is only available in a model window, but in time should be able to work in the action, choreography components as well. Future capabilities include scripting materials and importers/exporters.

The current programming API supports the following:

Transformations: translate, rotate and scale
Primitives: cube and a surface mesh
Attributes: colo(u)r

It might seem not much, which is good. It should be straight forward and simple. The API is deceptively simple and much can be accomplished by combining the Python programming language with these API calls.

Hop over to the tutorial section for step by step guides.

API Documentation

Python Library AM
begin()	Initialize the components of the AM Python API.
end()	Signals the end of the AM Python script to Animation Master.
transform_begin()	Start a new transformation scope.
transform_end()	Ends the current transformation scope.
translate(x, y, z)	Moves everything in the current scope to position (x, y, z)
rotate(angle, x, y, z)	Rotates angle degrees around the axis as defined by (x, y, z)
scale(x, y, z)	Scales along the axis and magnitude defined by (x, y, z)
cube()	Creates a unit cube.
sphere()	Creates a unit sphere.
surface_begin()	Indicates the creation of a mesh.
surface_begin(name)	Indicates the creation of a mesh with a user defined name
surface_add((x,y,z),[(x, y, z)]+)	(NOTE: Defunc t) Adds a row of points to the mesh. IMPORTANT : Each row must have the exact same number of points for a particular mesh. Also, each row must have at lest two points.
surface_add_row((x,y,z),[(x,y,z)]+)	New name for surface_add which is now considered defunct. Adds a row of points to the mesh. IMPORTANT : Each row must have the exact same number of points for a particular mesh. Also, each row must have at lest two points.
surface_end()	Finishes the mesh, and creates it in Animation Master.
surface_attribute_row(row)	Current attributes are assigned to the specified row of the surface. The function must be called between surface_begin() and surface_end(), and the row must exist.
surface_attribute_column(column)	Current attributes are assigned to the specified column of the surface. Function must be called between surface_begin() and surface_end(), and the column must exist.
surface_attribute_cell(row, column)	Current attributes are assigned to the specified cell of the surface. The function must be called between surface_begin() and surface_end(), and the cell must exist.
surface_set_closed()	Indicates that the current surface is closed, by creating a row between the first and last row added to the surface. Creates a seamless surface.
color_diffuse(r, g, b) colour_diffuse(r, g, b)	Specifies the red, green and blue components of the diffuse colour for the current attribute scope.
color_specular(r, g, b) colour_specular(r, g, b)	Specifies the red, green and blue components of the specular colour for the current attribute scope
group(name)	Reference to a group, which then can then be treated like an object. Transformations affect the group.
group_copy(name, new_name)	Creates a copy of the group name, and names it new_name.
group_extrude(name, new_name)	Creates a extrusion of the group name, and names it new_name .
spline_begin()	Start the creation of a spline.
spline_begin(name)	Start the creation of a spline named name.
spline_add_point(x,y,z)	Add a point to the spline.
spline_set_point(pos,x,y,z)	Change the value of the point in the current spline, indicated by the index pos (valid values 0 to number points in the spline - 1.)
spline_attach_points(name0,name1,pos0,pos1)	Attach the point in a spline indicated by the name name1 and pos1 to the point indicated in spline name0 and pos0.
spline_set_point_peaked(pos)	Set the point pos in the current spline to be peaked (i.e. not really a spline point.)
spline_set_point_smooth(pos)	Set the point pos in the current spline to be smooth (i.e. a spline point.)
spline_set_point_in_gamma(pos,value)	Set the current spline point at pos's in gamma value to value .
spline_set_point_in_alpha(pos,value)	Set the current spline point at pos's in alpha value to value .
spline_set_point_in_magnitude(pos,value)	Set the current spline point at pos's in magnitude value to value .
spline_set_point_out_gamma(pos,value)	Set the current spline point at pos's out gamma value to value .
spline_set_point_out_alpha(pos,value)	Set the current spline point at pos's out alpha value to value .
spline_set_point_out_magnitude(pos,value)	Set the current spline point at pos's out magnitude value to value .
spline_set_peaked()	Set all the points in the spline to be peaked (i.e. not spline points.)
spline_set_smooth()	Set all the points in the spline to be smooth (i.e. spline points.)
spline_set_in_gamma(value)	Set all the spline points' in gamma value to value.
spline_set_in_alpha(value)	Set all the spline points' in alpha value to value.
spline_set_in_magnitude(value)	Set all the spline points' in magnitude value to value.
spline_set_out_gamma(value)	Set all the spline points' out gamma value to value.
spline_set_out_alpha(value)	Set all the spline points' out alpha value to value.
spline_set_out_magnitude(value)	Set all the spline points' out magnitude value to value.
colour_ambiance(value)	Set the ambiant property. The amount of surface light shown irrespective of light sources. Valid values are between 0 and 1.
colour_diffuse_fall_off(value)	Set the diffuse fall off property. Valid values are 0 and greater.
colour_specular_size(value)	Set the specular size property. Valid values are 0 and greater.
colour_specular_intensity(value)	Set the specular intensity property. Valid values are 0 and greater.
colour_roughness(value)	Set the roughness property. Valid values are 0 and greater.
colour_roughness_scale(value)	Set the roughness scale property. Valid values are 0 and greater.
colour_transparency(value)	Set the transparency property. Valid values are between 0 and 100.
colour_density(value)	Set the density transparency property. Valid values are between 0 and 100.
colour_refraction(value)	Set the refraction property. Valid values are between 1 and 2.
colour_translucency(value)	Set the translucency property. Valid values are between 0 and 100.
colour_reflectivity(value)	Set the reflectivity property. Valid values are between 0 and 100.
colour_reflectivity_fall_off(value)	Set the reflectivity fall off property. Valid values are between 0 and 100.
colour_radiance(value)	Set the radiance property. Valid values are between 0 and 100.
colour_glow_radius(value)	Set the glow radius/radiance property. Valid values are 0 and greater.

Tutorials

- Absolute Beginners
- 3D Artist Article #45
- Using Attributes
- More Transformations

Downloads

- The Animation Master Python Script Plug-in v0.1 (A:M v9.0 Tut 4 and 5 )

- The Animation Master Python Script Plug-in v0.4a (A:M v9.0 Tut 6+)

Examples

The examples below are based on something that either I made up, made specifically for the 3D Artist A:M script article or based loosely off the excellent 3d paramteric site by Chris Sinclair & Martin Kraus . Also used as reference were examples from Mike's Isosurface Tutorial. More examples will be added as the plug-in expands in capability and contributions.

Cube

Surface

Cube 5x5 Matrix (3D Artist Example) FOR SCRIPT PLUG-IN VERSION 0.1

Cube 5x5 Matrix (adapted 3D Artist Example) FOR SCRIPT PLUG-IN VERSION 0.2+

Log Spiral (3D Artist Example)

Parametric: Cylinder

Parametric: Paraboloid

Parametric: z = x*x

Parametric: z = sin (x*x + y*y)

Parametric: 3 Half Spheres

Parametric: Bipolar Cylinder (sort of)

Parametric: Flower Box (something I made up by fiddling around)

Parametric: Bohemian Dome

Parametric: Conical Spiral

Log Spiral Colour FOR SCRIPT PLUG-IN VERSION 0.3+

Surface in Colour FOR SCRIPT PLUG-IN VERSION 0.3+

Staircase FOR SCRIPT PLUG-IN VERSION 0.4+

Group Copy FOR SCRIPT PLUG-IN VERSION 0.4+

Group Extrude FOR SCRIPT PLUG-IN VERSION 0.4+

Group Transform FOR SCRIPT PLUG-IN VERSION 0.4+

Spline Spin FOR SCRIPT PLUG-IN VERSION 0.4+

Spline Peak FOR SCRIPT PLUG-IN VERSION 0.4+

Spline Attach FOR SCRIPT PLUG-IN VERSION 0.4+

Spline Triangle FOR SCRIPT PLUG-IN VERSION 0.4+

Spline Squares FOR SCRIPT PLUG-IN VERSION 0.4+

Surface Sphere FOR SCRIPT PLUG-IN VERSION 0.4+

Attribute Spheres FOR SCRIPT PLUG-IN VERSION 0.4+

Change Log

Version 0.4a (08192001):
    * New surface commands:
        - surface_add_row(x,y,z,[x,y,z]+)
        - surface_set_closed()
    * Enhanced surface_begin command:
        - surface_begin(name)
    * New group commands:
        - group(name)
        - group_copy(name, new_name)
        - group_extrude(name, new_name)
    * New spline commands:
        - spline_begin()
        - spline_begin(name)
        - spline_add_point(x,y,z)
        - spline_set_point(pos,x,y,z)
        - spline_attach_points(name0,name1,pos0,pos1)
        - spline_set_point_peaked()
        - spline_set_point_smooth()
        - spline_set_point_in_gamma(value)
        - spline_set_point_in_alpha(value)
        - spline_set_point_in_magnitude(value)
        - spline_set_point_out_gamma(value)
        - spline_set_point_out_alpha(value)
        - spline_set_point_out_magnitude(value)
        - spline_set_peaked()
        - spline_set_smooth()
        - spline_set_in_gamma(value)
        - spline_set_in_alpha(value)
        - spline_set_in_magnitude(value)
        - spline_set_out_gamma(value)
        - spline_set_out_alpha(value)
        - spline_set_out_magnitude(value)
    * New colour attribute commands:
        - colour_ambiance(value)
        - colour_diffuse_fall_off(value)
        - colour_specular_size(value)
        - colour_specular_intensity(value)
        - colour_roughness(value)
        - colour_roughness_scale(value)
        - colour_transparency(value)
        - colour_density(value)
        - colour_refraction(value)
        - colour_translucency(value)
        - colour_reflectivity(value)
        - colour_reflectivity_fall_off(value)
        - colour_radiance(value)
        - colour_glow_radius(value)
    - Better error handling and error detection in surface commands.
    - More bug fixes to attribute stack

Version 0.3b (08132001):
- Rebuilt as non debug binary
- Worked around a Python API bug

Version 0.3a (08122001):
* New surface attribute commands:
- surface_attribute_row (row)
- surface_attribute_column (column)
- surface_attribute_cell (row, column)
- Group named surface[num] is created for each surface
- Colour attributes work for a whole surface
- Colour attribute stack now works

Links

Hash Inc.	Creators of Animation Master.
3D Artist Magazine	An excellent source of general and Animation Master specific articles.
Python.org	The Python language home base.
Pixar	The creators of RenderMan.