1. Introduction

This section contains general information about this manual and Ayam.

1.1 About this Manual

As this document is a reference manual, it is probably pointless to read it from the beginning to the end (except maybe for the next section, explaining the basics of the user interface). Instead, just look up the documentation of the things you are interested in via the table of contents or the index. Cross references will then guide you to other important parts of the documentation. Again: this manual has a rather large index, please use it (see section Index)!

This document is organized in the following way:

After this first introductory section, the user interface of Ayam is explained and basic handling instructions for the application are given in the second section.
In the third section all interactive modelling actions are documented.
The fourth section details all object types and object properties, followed by documentation on all NURBS modelling tools in the fifth section.
In the sixth section the Tcl scripting interface is explained and the following seventh section has all information about the import and export plugins.
The eighth section is the dreaded miscellaneous section that contains documentation not fitting elsewhere.

In this manual, the following typographic conventions are used:

• keyboard shortcuts: <Ctrl+c> (press control and c key), for shortcuts like <Ctrl+Shift+t> an abbreviated version: <Ctrl+T> will be used;
• names (of object types, menu entries, properties, or property elements): "A Name";
• Tcl code examples:

  ---

  set riopt(runtime) { a b }
  

  ---

• Object hierarchies:

  +-Parent_Object(Type)
   | First_Child_Object(Type)
   | Second_Child_Object(Type)
   | [Third_Child_Object_may_be_present_or_not(Type)]
   | Empty_Level(Level)
   +-Sub_Level(Level)
   || First_Child_Object_of_Sub_Level(Type)
   |\ Last_Child_Object_of_Sub_Level(Type)
   \ Last_Child_Object(Type)
  +-Next_Parent_Object(Type)
  

• Commands:
  » command arguments
• Historical annotations appear when the mouse pointer hovers over the asterisk: ^[*^]

1.2 About Ayam

Ayam is a free 3D modelling environment for the RenderMan Interface, distributed under the modified BSD licence (no advertisement clause).

History

Ayam is in development since 1997 and was formerly known as "The Mops". Ayam formed the software base of the authors PhD work. New versions of Ayam were released in approximately half year intervals since.

Features Overview

Here is a short summary of the Ayam feature set:

• RIB (RenderMan Interface Bytestream) export and import.
• Support for NURBS curves, interpolating and approximating curves, (trimmed) NURBS surfaces, interpolating surfaces, bilinear and bicubic patches and patch meshes, Boxes, Quadrics (Sphere, Disk, Cylinder, Cone, Hyperboloid, Paraboloid and Torus), MetaBalls, polygonal meshes, subdivision meshes and more.
• All primitives may be combined with the common CSG-operations: Intersection, Difference, and Union.
• NURBS modelling includes extrude, revolve, sweep, birail, skin, and gordon operations (with caps, holes, and bevels) realized as Tool-Objects (see also section The Modelling Concept Tool-Objects).
• Wavefront OBJ export and import, Rhino 3DM export and import, AutoCAD DXF export and import, Web3D X3D export and import, Apple Quicktime 3D Metafile (3DMF) export and import.
• Custom objects that may freely implement their representations (using OpenGL and RIB) and even small GUIs to edit their type specific parameters may be written by the user and dynamically loaded at runtime.
• Scripting interfaces: Tcl, JavaScript, Lua.
• Script objects.
• Miscellaneous: (automatic) instancing, arbitrary number of modelling views, object clipboard, independent property clipboard, console, n-level undo.

Since Ayam 1.12, dynamic loading of custom objects and certain plugins are also available on the Win32 platform (they were not available before).

Ayam is primarily aimed at the Linux, IRIX, and Win32 platforms. On those platforms BMRT (Blue Moon Rendering Tools, a RenderMan compliant renderer by Larry Gritz) is available. Even though the distribution of BMRT is stopped it is still the recommended renderer for Ayam. Despite of this, Ayam may be used on many more platforms with any RenderMan compliant renderer.

For platforms where BMRT is not available (e.g. FreeBSD or NetBSD), Ayam may be compiled with code from the Affine Toolkit with limited functionality (see also the file INSTALL). In this case, no parsing of slc compiled shaders will be possible.

Since Ayam 1.6 it is also possible to completely replace the BMRT shader parsing and RIB writing code with code from the Aqsis project, thus completely eliminating the need for BMRT. Furthermore, shader parsing plugins are available for all major RenderMan compliant renderers allowing a tight integration of Ayam with any of those renderers.

Coordinate Systems and Units

Ayam uses a right-handed coordinate system as used by OpenGL but as opposed to RenderMan (the latter is using a left-handed coordinate system).

In the default modelling view of type "Front", the positive X-axis points to the right, the positive Y-axis points upwards and the Z-axis points outside the screen, to the user. See also the following image.

All coordinate values in Ayam are dimensionless. It is up to the user to define what a value of 1.0 means: e.g. one centimeter or one meter.

Due to the limited precision of floating point arithmetics used in Ayam, coordinate values should be defined in the range between -10.0 and 10.0 for most accurate results.

Rational Style

NURBS curves and surfaces support rational coordinate values by allowing a fourth value (the weight) to be specified for each control point. In Ayam versions prior to 1.19 those weights were always multiplied with the coordinate values (i.e. homogeneous rational coordinates) to allow faster drawing with OpenGL/GLU, which expects rational coordinate values to be delivered this way. But a negative side effect of this approach was that modification of coordinates or weights for modelling purposes was unnecessarily complicated.
Therefore, since Ayam 1.19, rational coordinates are now euclidean rational, the weight is not pre-multiplied with the coordinates anymore (this will be done internally when handing the coordinates over for drawing or export purposes).
Ayam can still display the coordinates in both styles, controlled by the preference option "RationalPoints" (see also section Modelling Preferences), but internally the coordinates are kept in euclidean rational style.

Scene files from older versions of Ayam are converted automatically to the new rational style when read by Ayam 1.19 and above, but loading of scene files written by Ayam 1.19 and above into older versions of Ayam requires manual intervention (e.g. by means of a script).