Ayam: Objects and Properties

Next Previous Contents

## 4. Objects and Properties

This section informs you about the different object types of Ayam and about the property GUIs that appear in the properties section of the main window if a single object and a property have been selected.

## 4.1 Standard Properties

Most Ayam objects have standard properties. They are used to control transformations and common attributes of objects. The following sections describe the standard properties `"Transformations"`, `"Attributes"`, `"Material"`, `"Shaders"`, and `"Tags"`.

## 4.2 Transformations Property

Use this property to edit the location, orientation, and size of an object.

- `"Reset All!"` immediately resets all transformation attributes to the default values.
- `"Translation_X (_Y, _Z)"` is the displacement of the object from the world origin in X (Y, Z) direction.
- `"Rotation_X (_Y, _Z)"` is the angle (in degrees) of the rotation of the object around the X (Y, Z) axis. Read the next section for more information on how to use these entries. Read it!
- `"Scale_X (_Y, _Z)"` determines a scale factor that will be applied to the object in the direction of the local X (Y, Z) axis.
- `"Quat0 (1, 2, 3)"` the quaternion that is used to determine the orientation of the object in space. This quaternion is not here to be edited directly! The sole purpose of its appearance here is to allow copying and pasting of rotations.

The transformations are applied to the object in the following order: Scale, Rotation, Translation.

### Using the Rotation Attributes

The orientation of an object in space may be expressed using so called Euler angles. This notation (simply three angles determining a rotation about the axes of the coordinate system) suffers from a phenomenon called gimbal lock.

To avoid gimbal locks, Ayam internally holds the orientation of an object in a quaternion. This quaternion not only holds information about the angles but also about the order in which partial rotations occured.

It is important to know, that the values of the angles of the rotation property must not be read in a way that the object will first be rotated around X by x-angle degrees then around Y y-angle degrees then around Z z-angle degrees. In fact, no information about the order in which partial rotations occured may be derived from that three values. This implies, that e.g. the values 0 0 45 may denote a different orientation than the very same values 0 0 45 (no joke)!

But how do you get the three entries to do what you want? You either want to rotate the object around an axis by a given amount or you want to undo a rotation or undo all rotations.

Rotating an object is easy, simply add the amount about which you want to rotate the object to the value currently displayed in the appropriate entry. If you want to rotate about 45 degrees about X and the x-angle entry displays a 30, enter 75. Then press the apply button. If you change multiple entries the rotations made will be in the order X (if changed) then Y (if changed) then Z (if changed). Do not change more than one entry at once until you exactly know what you are doing.

Undoing a single rotation works in the same way, just use a subtraction instead of an addition.

Undoing all rotations (resetting the object to its original state) is simple too: enter 0 for all three entries at once, then press apply.

If you want to copy the orientation of an object to other objects using the property clipboard, make sure that you select all Rotation and Quat property elements.

## 4.3 Attributes Property

The attributes of an object contain currently:

- `"Objectname"`, the name of the object. It is also displayed in the object listbox or tree and may be written to RIB streams.
- `"Hide"`, if this attribute is set this object is not drawn. It may also be excluded from RIB export.
- `"Refcount"`, just displays how many objects point to this object. Objects with a reference count different from zero may not be deleted.

## 4.4 Material Property

The material property allows you to connect geometric objects to material objects (see also section Material Object). The material property GUI consist of the following elements:

- `"Clear Material!"` immediately clears any connection of the current object to its material.
- `"Add/Edit Material!"` adds a material to the current object (if it has none) and immediately selects the new material object for editing. If the current object already has a material, this material object is searched for and selected for editing.
- `"Materialname"` is the name of the material of this object. If you change the name, the object will be disconnected from the old material and connected to the new material. An easier way to connect geometric objects to material objects is to simply drop the geometric objects onto the material object using Drag-and-Drop in the tree view.

## 4.5 Shaders Properties

Shader properties are used to attach shaders of a certain type to objects. The name of the property contains the type of the shader, e.g. light shaders may be attached using a property named `"LightShader"` only. Other types of shaders or shader properties are: `"Surface"`, `"Displacement"`, `"Interior"`, `"Exterior"`, `"Atmosphere"`, and `"Imager"`.

Each shader property GUI, even if no shader is attached to an object, starts with the `"Set new shader."`-button. This button allows to select a new shader of the appropriate type. If you press the `"Set new shader."`-button, a dialog with a list of shaders pops up. If this list is empty, Ayam is probably not set up properly (or you simply do not have shaders of the appropriate type). Check the preference setting `"Main/Shaders"`. After a new shader has been set, the arguments of the shader will be parsed and a GUI will be generated to allow the arguments of the shader to be filled with values.

The `"Delete shader."`-button may be used to delete the current shader from the selected object.

The `"Default Values."`-button resets all arguments of the shader to the default values. See also section Working with Shaders below.

All other elements of the shader property GUI depend on the currently attached shader.

### Shader Parsing

If no plugin is loaded, the official Ayam binaries use libslcargs (from BMRT) to parse shaders that have been compiled with slc (the shader compiler from BMRT). Parsing incorporates detecting the type of the shader and detecting the names, types, and default values of all shader arguments.

Note that currently, Ayam only works properly with shaders that have at most two dots in their file name and that Ayam will simply skip all array arguments (and emit a warning message) while parsing a shader. Those array arguments consequently never appear in the shader property GUIs and RIBs exported by Ayam. Also note that default values for shader arguments of type color will be silently clamped to the range 0-255.

Many shaders use array arguments to define transformation matrices. If this is the case and you have access to the shader source code you may want to modify those shaders to enable working with the transformation matrix carrying shader arguments. To do this, just change all definitions of transformation matrix carrying floating point arrays to real matrices. If the shader contains a

`"float a_matrix_parameter[16]"`

change this to

`"matrix a_matrix_parameter"`.

Note that these changes of the shader argument definitions probably also require changes of the code that uses those arguments. Ayam is able to deal with matrices because of their fixed size of 16 float values, and because libslcargs is able to deliver the default values for a matrix (but not for an array!).

If Ayam has been compiled without a shader parsing library (e.g. without libslcargs), Ayam will parse XML files created by `"sl2xml"` from the K-3D project (see `"http://www.k-3d.com/"`) instead of compiled shaders. The `"Set new shader."`-button will in this case always open a file requester, allowing you to select a XML file, that has been created by sl2xml. Furthermore, the `"Default Values."`-button will not be available; you have to use `"Set new shader."` instead.

From version 1.3 on, Ayam also supports shader parsing plugins to allow parsing of shaders compiled with different shader compilers, see also section Shader Parsing Plugins.

### Working with Shaders

The `"Default Values."`-button resets all arguments of the shader to the default values. For that, the compiled shader will be parsed again. Therefore, this button is quite handy if you have to deal with changing shaders: just edit the shader, recompile it, then back in Ayam just hit the `"Default Values."`-button. Note that this destroys your possibly carefully adjusted shader argument values.

If you want to keep the old shader argument values when a shader changes, simply copy the shader property using the property clipboard (main menu: `"Edit/Copy Property"`) before you load the new default values and paste the property back using `"Edit/Paste Property"` after loading of the new default values. Note that this works only properly, if you do not change the type of existing shader arguments and if no shader arguments are removed in the new version of the shader!

You can also just copy certain parameter values by selecting them using double-clicks on the parameter names in the shader property GUI and then use e.g. `"Edit/Copy Marked Prop"` (see also the description of the property clipboard in section Properties).

## 4.6 Tags Property

Use this property to edit the tags of an object.

Tags provide an easy way to attach arbitrary information (e.g. additional RenderMan interface attributes, special attributes for plugins or even scripts) to objects. A tag consists of two strings, one defining the type and one defining the value of the tag.

The Tags property GUI consists of the following standard elements:

- `"Remove all Tags!"` immediately removes all tags from the object.
- `"Remove Tag!"` is a menu, that allows you to remove a single tag from the object.
- `"Add Tag!"` opens a small dialog box, where you may enter a new tag type and value. Once you press the `"Ok"` button, a new entry will be added to the tags property, displaying the new tag. Just click on the entry to get back to the dialog, to remove the tag using `"Clear"` then `"Ok"`, or to change the type or value of the tag.

The next sub-sections describe the currently available tag types. Note that extensions and plugins may define their own types.

### RiAttribute Tag

The tag type `"RiAttribute"` can be used to attach arbitrary RenderMan interface attributes to objects. This is handy if you use a renderer with lots of RiAttributes that differ from the standard RiAttributes.

`"RiAttribute"` tags attached to a geometric object override `"RiAttribute"` tags possibly attached to the material object of this geometric object.

In order to create a tag of type RiAttribute, the type string must be `"RiAttribute"`. The syntax of the value string is as following:

`<attrname>,<paramname>,<paramtype>,<param>`

where attrname is the name of the attribute (e.g. "render") paramname is the name of the parameter (e.g. "displacementbound") paramtype is a single character defining the type of the parameter (it may be one of `f` - float, `g` - float pair, `i` - integer, `j` - integer pair, `s` - string, `c` - color, `p` - point) and finally param is the value of the parameter itself (e.g. a float: "1.2", an integer value: "3", a string: "on", a color: "1,1,1" or a point: "0.4,0.5,1.0").

Some examples for valid RiAttribute tags:

    RiAttribute render,truedisplacement,i,1
    RiAttribute dice,numprobes,j,3,3
    RiAttribute radiosity,specularcolor,c,0.5,0.5,0.5

Note that the `"RiAttribute"` tag handles just a single parameter at once. Also note that `"RiAttribute"` tags may be created much more easily using the menu entry `"Special/Tags/Add RiAttribute"`. The database of RiAttributes for this GUI may be extended by editing the ayamrc file, see section Ayamrc File.

### RiOption Tag

The tag type `"RiOption"` can be used to attach arbitrary RenderMan interface options to objects. This is handy if you use a renderer with lots of RiOptions that differ from the standard RiOptions. However, they will be only used by the RIB exporter if they are attached to the `"Root"` object! The syntax is similar to the `"RiAttribute"` tag type, see above. Note that RiOption tags may be created easily using the menu entry `"Special/Tags/Add RiOption"`. Tags created with this GUI will always be added to the `"Root"` object. It does not have to be selected! Furthermore, the database of RiOptions for this GUI may be extended by editing the ayamrc file, see section Ayamrc File.

### TC (TextureCoordinates) Tag

The tag type `"TC"` can be used to attach texture coordinates to objects or materials.

`"TC"` tags attached to a geometric object override `"TC"` tags possibly attached to the material object of this geometric object.

The `"TC"` tag always contains a list of eight comma separated float values, that specify a mapping for four 2D points (a quadrilateral) in texture space from the default values (0,0), (1,0), (0,1), and (1,1) to the new specified values.

Examples:

    TC 0,0,10,0,0,10,10,10

Changes the texture coordinate space so that more and smaller tiles of a texture would be displayed on a primitive.

    TC 0,0,0,1,1,0,1,1

Flips the texture coordinate space over two corners. A shader normally generating vertical stripes will create horizontal stripes now.

    TC 0,1,0,0,1,1,1,0

Turns the texture coordinate space by 90 degrees. A shader normally generating vertical stripes will create horizontal stripes now.

Note that the exact behaviour of an object equipped with a TC tag depends heavily on the shader and its use of the texture coordinates!

Note also that using TC tags you change the texture coordinates of entire primitives only, if you want to change the texture coordinates of sub-primitives (e.g. of single control points of a NURBS patch) you would need to use a PV (Primitive Variable) tag instead.

### Texture Coordinate Editor

The texture coordinate editor may be opened using the main menu entry `"Special/Tags/Edit TexCoords"` and lets you edit texture coordinate tags in an intuitive way.

For that, the current texture coordinates are displayed as a black polygon in a canvas with regard to the original (default) values, that are displayed in gray. Small arrows point to positive s and t direction respectively.

Texture Coordinate Editor

The `"RotateR"` and `"RotateL"` buttons shift the coordinate values between the four points. This results in a 90 degree rotation of the texture.

The `"FlipS"` and `"FlipT"` buttons flip the texture coordinate values in s and t direction respectively. This is useful, if you, for example, want to correct a texture mapping for an image that appears upside down.

The next buttons allow to move (using `"MoveS"` and `"MoveT"`) and scale (using `"ScaleS"` and `"ScaleT"`) the texture coordinates by a specific amount that is given in the first entry field.

The `"Load"` and `"Save"` menu buttons allow you to:

- load the default texture coordinate values ((0,0), (1,0), (0,1), (1,1))
- load texture coordinates from a selected BPatch object: The xy coordinates of the four points of the selected BPatch will be interpreted as st coordinates. This allows for more complex transformations of the texture coordinates e.g. rotations about an angle of 45 degrees.
- load TC tags from the selected object
- save the texture coordinates to a BPatch object
- save TC tags to a selected object; Note that it is not possible to save the TC tag to multiple selected objects. Use the property clipboard to achieve this.

Note that the tag numbers in the menu entries count TC tags only.

The texture coordinate dialog is modeless, it may stay open while you model. The `"Dismiss"` button closes the dialog.

### PV (Primitive Variable) Tag

The tag type `"PV"` can be used to attach arbitrary data to geometric primitives and even sub-primitives. With the help of primitive variables you can e.g. attach your own texture coordinates to a NURBS patch primitive or attach distinct colors to the faces or even to single vertices of a polygonal mesh. In the latter case, the data is properly interpolated by the renderer before it is handed over to the shader.

When rendering, all data defined in a `"PV"` tag is handed over to the surface shader that is attached to the respective geometric primitive using additional shader parameters.

Note that Ayam does not check, whether your shader actually uses this data!

The syntax of the value string of a PV tag is as following:

`<name>,<detail>,<type>,<ndata>,<data>`

where `"<name>"` is the name of the primitive variable; `"<detail>"` or storage class should be `"uniform"`, `"varying"`, `"vertex"`, or `"constant"`; `"<type>"` is a single character describing the type of the data (see also the documentation of the `"RiAttribute"` tag above); `"<ndata>"` is an integer number describing how many data elements will follow; and `"<data>"` is a comma separated list consisting of a certain number of elements of type `"<type>"`.

Examples:

    PV mycolor,constant,c,1,0,1,0

adds a single color value (0,1,0), which is the same all over the primitive;

    PV mys,varying,f,4,0.1,0.2,0.3,0.4

could be used to add a distinct float value to each corner point of a standard NURBS patch (order, width, and height 4).

Note that not all geometric objects currently honour PV tags on RIB export. The geometric objects currently supporting PV tags are: SDMesh, PolyMesh, PatchMesh, NURBPatch, and BPatch.

Furthermore, the number of data elements, which depends on the detail or storage class, the type of geometric primitive, and the configuration of the geometric primitive is not checked by Ayam. Some RIB writing libraries, however, check the number and silently omit the primitive variable if there are mismatches. Check your RIB for the presence of the primitive variable after export, especially, if you are adding or editing PV tags manually!

### RiHider Tag

The tag type `"RiHider"` can be used to choose and parameterize different algorithms for hidden surface removal. RiHider tags have to be attached to the root object in order to be used. The syntax of a RiHider tag is quite similar to a RiAttribute tag: `"<type>,<parameterlist>"` where `"<parameterlist>"` is a comma separated list of triplets consisting of name, type, and value of a parameter.

Example

A RiHider tag could look like this:

    RiHider hidden,depthfilter,s,midpoint

### RiDisplay Tag

The tag type `"RiDisplay"` can be used to add more output files of different type (e.g. containing depth-buffer information) to the scene. RiDisplay tags have to be attached to the root object in order to be used. The syntax of a RiDisplay tag is as follows: `"<name>,<type>,<mode>,<parameterlist>"`, where name is e.g. a file or device name, type specifies the destination of the image data (e.g. screen or file), mode specifies which information should be stored or displayed (e.g. color values: rgb, or depth values: z), and `"<parameterlist>"` is a comma separated list of triplets consisting of name, type, and value of a parameter. The name will be automatically changed to `"+name"` on RIB export if it does not already start with a plus.

Example

A RiDisplay tag could look like this:

    RiDisplay imagez.tif,file,z

### NoExport Tag

The tag type `"NoExport"` can be used to exclude certain objects from exported RIBs. The value string of this tag is ignored. All that counts is the presence of the tag. Child objects of objects with the `"NoExport"` tag will also be excluded from the RIB. Since Ayam 1.6, light objects also honour the `"NoExport"` tag. Note that regardless of potentially present `"NoExport"` tags, RIB archives will be created for all referenced objects all the time (even if `"NoExport"` tags are added to all instances).

### SaveMainGeom Tag

The tag type `"SaveMainGeom"` can be used to save the geometry of the main window and the toolbox window (if open) with a scene file. For that the scene saving code checks for the presence of a `"SaveMainGeom"` tag for the root object and fills it with the current geometry information. The scene reading code checks for the presence of a `"SaveMainGeom"` tag for the root object after replacing a scene and re-establishes the geometries of main and toolbox window.

### TP Tag

The tag type `"TP"` can be used to save tesselation parameters to objects of type `"NPatch"`. Those tesselation parameters will be used when the NPatch object is tesselated for e.g. a conversion to a PolyMesh object. The syntax of the TP tag is: `"<tmethod>,<tparamu><tparamv>"` where `"<tmethod>"` is an integer value between 1 and 3, describing which tesselation method to use (1 - ParametricError, 2 - PathLength, and 3 - DomainDistance) and `"<tparamu>"` and `"<tparamv>"` are float values describing the respective parameter value for the chosen tesselation method. The second parameter value is ignored for the tesselation methods 1 and 2.

Note that the syntax of the `"TP"` tag changed in Ayam 1.9, the old syntax only allowed one parameter.

TP tags may be easily created using the tesselation GUI, that can be started with the main menu entry `"Tools/NPatch/Tesselate"` (see also section The Tesselation Tool).

Example

A TP tag could look like this:

    TP 1,0.5,0.6

### DC Tag

The tag type `"DC"` is only used by the AyCSG CSG preview plugin to store the depth complexity of CSG primitives. The syntax of the DC tag is: `"<dcval>"` where `"<dcval>"` is a positive integer value describing the depth complexity of the CSG primitive. See also section CSG preview using the AyCSG plugin for more information regarding the depth complexity value.

Example

A DC tag (valid for e.g. a torus) could look like this:

    DC 2

### NP Tag

The tag type `"NP"` (new property) may be used to add new property GUIs to single objects. The value of the tag is the name of a new property. The necessary code to manage the property data and the windows that make up the property GUI itself have to be present in the Tcl context of Ayam before the user clicks on the new property in the property list box.

### NS Tag

The tag type `"NS"` (notify script) may be used to add scripts to an object, that will be run after the notification callback of that object fired (because e.g. one of the children of the object changed).

Example

A simple NS tag could look like this:

    NS puts "notify callback fired"

For security reasons, Ayam offers to disable all script tags when they are found upon reading of scene files. To disable a tag, Ayam simply changes its type from `"NS"` to `"DNS"` (disabled notify script). It will not be executed then. Disabled notify scripts may be enabled after careful inspection using the main menu entry `"Special/Enable Scripts"`.

### UMM/VMM Tag

The tag types `"UMM"` (u min max) and `"VMM"` (v min max) may be used to store additional parametric domain trimming values to NURBS curve and NURBS patch objects. Note that the GLU NURBS display modes do not honor those tags, but the RIB export does.

Example

An UMM tag could look like this:

    UMM 0.4,0.6

### BP Tag

The tag type `"BP"` (bevel parameters) is used by all bevel supporting tool objects to store their bevel information. The syntax of the BP tag is: `"<side,type,radius,revert>"` where `"<side>"` is an integer value from 0 - 3 defining the side of the surface, where the bevel should be applied to, `"<type>"` is an integer value from 0 - 4 defining the type of the bevel, `"<radius>"` is a floating point value defining the radius of the bevel, and `"<revert>"` is either 0 or 1 and may be used to revert the bevel.

Example

A BP tag could look like this:

    BP 0,0,0.1,0

### Internal Tags

The following tags are of no general use. They are used by Ayam internally only.

### OI - Object ID Tag

This tag is used by the RIB exporter and the scene storage facility to establish links between instance objects and the original objects they are pointing to.

The tag type `OI` is not meant to be used by the end user. Furthermore, changing the IDs manually avails to nothing as the tags are rebuilt before every export/save operation.

### MI - Material ID Tag

This tag is used by the RIB exporter and the scene storage facility to establish links between material objects and the objects they are assigned to.

The tag type `MI` is not meant to be used by the end user. Furthermore, changing the IDs manually avails to nothing as the tags are rebuilt before every export/save operation.

### List of Known Tags

This section contains a comprehensive list of tag names, that are known in Ayam 1.10 and in the accompanying extensions (plugins).

`"RiAttribute", "RiOption", "RiHider", "RiDisplay", "NoExport", "TC", "PV", "SaveMainGeom", "TP", "MI", "OI", "DC", "TM", "NP", "NS", "DNS", "UMM", "VMM", "BP", "IDR", "IIDR", "RIDR", "R3IDR", "CIDR", "CCIDR"`

Documentation on those tags can be found in the sections above.

## 4.7 Root Object

There is always exactly one Root object in the scene. This object is something special in that it cannot be deleted or copied. The Root object holds options global to the scene like RiOptions, atmosphere and imager shaders. Furthermore, all currently open view windows are child objects of the Root object.

If you hide the Root object, the little red/green/blue coordinate system will not be drawn in any view.

The global scene options are documented in the following sections.

### RiOptions Property

The RiOptions property carries RenderMan Interface options. Both, standard and BMRT specific options may be set using this property. For the sake of brevity only a short description of the available options will be given here. Please refer to the documentation of the RenderMan Interface and the documentation of BMRT for more detailed information about the options. The RiOptions property consists of the following elements:

- `"Width"`, `"Height"`, if greater than zero this value will be used for the image size instead of the corresponding dimension of the view window, but only for real RIB export operations, not for the QuickRender and not for the Render actions in view windows. QuickRender and Render actions will always use the dimensions of the view window instead.
- `"StdDisplay"`, if this is enabled, a standard display statement will be written to the RIB, which looks like this:

      Display "unnamed.tif" "file" "rgba"

  If you disable this option, be sure to add atleast one RiDisplay tag to the root object (see also section RiDisplay Tag), otherwise your RIB will not contain a Display statement. This option has no effect on RIBs created by the QuickRender and Render actions in view windows.
- `"Variance"`, maximum allowed variance of two pixel values. The default 0.0 causes no setting in the RIB. If the variance is > 0.0 no pixel samples setting will be written to the RIB. Various sources discourage the use of variance based sampling, because e.g. the number of samples actually taken (and therefore the rendering time) might not easily be predicted anymore.
- `"Samples_X"`, `"Samples_Y"` number of samples taken per pixel.
- `"FilterFunc"`, function used to filter final pixel values.
- `"FilterWidth"`, `"FilterWidth"` size of the filter.
- `"ExpGain"`, Exposure
- `"ExpGamma"`, Exposure Gamma
- `"RGBA_ONE"`, `"RGBA_MIN"`, `"RGBA_MAX"`, `"RGBA_Dither"`, specify quantisation and dithering
- `"MinSamples"`, `"MaxSamples"`, minimum and maximum number of samples per pixels.
- `"MaxRayLevel"`, maximum number of recursive rays.
- `"ShadowBias"`, minimum distance that one object has to be in order to shadow another object.
- `"PRManSpec"`, toggles behaviour of BMRT's specular() function between PRMan compatible (default) and RiStandard compatible.
- `"RadSteps"`, number of radiosity steps, the default 0 leads to no radiosity calculations to be performed.
- `"PatchSamples"`, minimum number of samples per patch to calculate the radiosity form factors for this patch.
- `"Textures"`, `"Shaders"`, `"Archives"` and `"Procedurals"` are search paths for the renderer.
- `"TextureMem"` and `"GeomMem"` determine how much memory rendrib (from BMRT) should use at maximum to cache textures and tesselated geometry.

### Imager, Atmosphere Property

The Imager and Atmosphere properties let you define shaders for the Root object, please refer to section Shaders Properties for information on how to deal with shader property GUIs.

Imager shaders are executed once for every rendered pixel, they may e.g. be used to set a specific background color.

Atmosphere shaders are volume shaders that may be used to implement global atmospheric optical effects like fog.

## 4.8 View Object

Every view window (see also section Anatomy of a View) has a corresponding view object as a child object of the root object. You can change camera settings, the type of the view, and other things related to the view using the properties of the view object. Note that deleting the object that represents a view, will not close the view window. You will just lose a way to configure it. Please, do not mess with the objects in other ways (e.g. copy them), you are asking for trouble otherwise!

Each view is associated with a virtual camera. The type of the view determines the Up-vector of that camera. If the type is "Top" the Up-vector corresponds to the world Z-axis, else the world Y-axis. The type of the view, additionally, determines the so called input plane of the view. Interactive modeling actions in a view are limited to that input plane (unless the view is switched to local modeling; available since Ayam 1.4; see also section Editing in Local Space). The standard input planes are as following: Front - XY-plane, Side - ZY-plane, Top - XZ-plane, Trim - XY-plane.

In perspective views no interactive modeling actions are possible, but you may position the camera and pick objects.

Views of type `"Trim"` are very special. They are used to edit trimcurves of NURBPatch objects only. They display that trimcurves as normal NURBCurves when the current level is inside a NURBPatch. The extensions of the patch in parameter-space are drawn as a rectangle. The trimcurves should completely lie inside this rectangle. Note that picking of objects currently does not work in views of type `"Trim"`.

View objects act in special ways, when certain objects are dropped onto them in the tree view:

When a camera object is dropped onto a view object using Drag-and-Drop in the tree view the camera settings of the camera object will be copied to the views camera.

When a light object of type `"Spot"` is dropped onto a view object using Drag-and-Drop in the tree view the views camera will be changed, so that the user looks along the light to see what objects of the scene are lighted by the light object (this works best with perspective views that have equal width and height).

Since Ayam 1.8 it is possible, to directly drag objects from the tree view to a view window, for geometric objects, the view then performs a zoom to object operation, for cameras and light sources the views camera will be changed accordingly (see the description of Drag-and-Drop with view objects above).

### Camera Property

This section describes all elements of the `"Camera"` property:

- `"From"` is the point where the camera (that is attached to the view) is situated.
- `"To"` is the point the camera is looking to.
- `"Up"` is the up vector of the camera.
- `"Near"` defines the near clipping plane. A value of 0.0 means a default value (that depends on the type of the view) should be used. Near should always be positive for perspective views, and smaller than far.
- `"Far"` defines the far clipping plane. A value of 0.0 means a default value (that depends on the type of the view) should be used. Far should always be bigger than near.
- `"Roll"` defines an angle by which the camera is rotated around the axis that is defined by the points from and to.
- `"Zoom"` is a zoom factor.

Note that the up vector is not checked for erroneous values (e.g. pointing in the direction of from-to) when applying the changes of the `"Camera"` property.

### ViewAttrib Property

This section describes the elements of the `"ViewAttrib"` property:

- `"Type"` specifies the type of the view. Front, Side, Top (all parallel), Perspective and Trim (again parallel) may be selected.
- `"Width"` and `"Height"` control the size of the view window.
- `"Redraw"` toggles automatic redrawing of the view. If this is disabled, no drawing takes place in the view until an explicit redraw is requested (using the view menu, or the shortcut `<Ctrl+d>`).
- `"Shade"` toggles shading of surfaces. Note that the lighting is in no way an exact (or even similar) representation of the light information you specified with Light objects! Instead, a single light source, located at the camera origin (a headlight), will be used!
- `"DrawSel"` toggles drawing of selected objects. If this is enabled, only the current selected objects will be drawn.
- `"DrawLevel"` toggles drawing of the objects of the current level only. If this is enabled, only the objects of the current level will be drawn.
- `"Grid"` is the grid size, 0.0 means no grid.
- `"DrawGrid"` toggles drawing of the current grid.
- `"UseGrid"` toggles, whether the current grid should be used by the interactive modeling actions.
- `"Local"` enables editing in local object space. See also section Editing in Local Space.
- `"DrawBG"` controls whether the background image should be drawn.
- `"BGImage"` is the name of a TIFF file, that will be used as texture for the background image. Ayam will read this image once when you apply the changes to the `"ViewAttrib"` property but reread the image file if the notification callback of the view object is invoked (e.g. using the main menu entry `"Tools/Force Notification"`).

## 4.9 Camera Object

Camera objects are used to temporarily save camera settings of views. Therefore, they has just have two properties explained above, see sections Camera and Attributes Property.

When a view object is dropped onto a camera object using Drag-and-Drop in the tree view, the camera settings from the view will be copied to the camera object.

## 4.10 Box Object

A solid box, centered at the origin of the object coordinate system. This object will always be exported as solid primitive in RIBs; consisting of six bilinear patches.

Since Ayam 1.8.2, a box object may be converted to three NURBS patches using the main menu entry `"Tools/Convert"`.

The following parameters further control the shape of a box:

### BoxAttrib Property

- `"Width"` is the width of the box (size of the box in direction of the X axis of the objects coordinate system).
- `"Length"` is the length of the box (size of the box in direction of the Z axis of the objects coordinate system).
- `"Height"` is the height of the box (size of the box in direction of the Y axis of the objects coordinate system).

## 4.11 Quadric Primitives

Box, and Quadric Primitives

### Sphere Object

A sphere, centered at the origin of the object coordinate system. This object will be exported as solid primitive or as simple sphere (depending on the `"Closed"` parameter of the SphereAttrib property) in RIBs.

Since Ayam 1.8.2, a sphere object may be converted to NURBS patches using the main menu entry `"Tools/Convert"`. This conversion obeys all parameters of the sphere.

The following parameters further control the shape of a sphere:

### RiSphereAttr Property

- `"Closed"` toggles whether the object should be automatically sealed (closed) when exported to RIB. Note that if this option is in use and `"ZMin"`, `"ZMax"` or `"ThetaMax"` have other than the default values, a single sphere will be written (in the worst case) as a CSG hierarchy of two spheres, two cylinders and eight disks! But it may be used in CSG operations, safely.
- `"Radius"` is the radius of the sphere, default is 1.
- `"ZMin"` may be used to chop the sphere off at a certain place at Z.
- `"ZMax"` may be used to chop the off at a certain place at Z.
- `"ThetaMax"` is the sweeping angle of the sphere default is 360.

### Disk Object

A disk, centered at the origin of the object coordinate system. This object will always be exported as simple disk in RIBs.

Since Ayam 1.8.2, a disk object may be converted to a NURBS patch using the main menu entry `"Tools/Convert"`. This conversion obeys all parameters of the disk.

The following parameters further control the shape of a disk:

### RiDiskAttr Property

- `"Radius"` is the radius of the disk, default is 1.
- `"ZMin"` displaces the disk along the Z axis, default is 0.
- `"ThetaMax"` is the sweeping angle of the disk, default is 360.

### Cone Object

A cone, centered at the origin of the object coordinate system, with the base at the XY plane. This object will be exported as solid primitive or as simple cone (depending on the `"Closed"` parameter of the ConeAttrib property) in RIBs.

Since Ayam 1.8.2, a cone object may be converted to NURBS patches using the main menu entry `"Tools/Convert"`. This conversion obeys all parameters of the cone.

The following parameters further control the shape of a cone:

### RiConeAttr Property

- `"Closed"` toggles whether the object should be automatically sealed (closed) when exported to RIB. Note that if this option is in use and `"ThetaMax"` has a different than the default value, a single cone will be written (in the worst case) as a CSG hierarchy of a cone, a disk and two polygons! But it may be used in CSG operations, safely.
- `"Radius"` is the radius of the cone at the base, default is 1.
- `"Height"` is the height of the cone, default is 1.
- `"ThetaMax"` is the sweeping angle of the cone, default is 360.

### Cylinder Object

A cylinder, centered at the origin of the object coordinate system. This object will be exported as solid primitive or as simple cylinder (depending on the `"Closed"` parameter of the RiCylinderAttr property) in RIBs. Note that the OpenGL representation of this object does not reflect the settings of the following parameters of the CylinderAttrib property: `"Closed"` and `"ThetaMax"`.

Since Ayam 1.8.2, a cylinder object may be converted to NURBS patches using the main menu entry `"Tools/Convert"`. This conversion obeys all parameters of the cylinder.

The following parameters further control the shape of a cylinder:

### RiCylinderAttr Property

- `"Closed"` toggles whether the object should be automatically sealed (closed) when exported to RIB. Note that if this option is in use and `"ThetaMax"` has a different than the default value, a single cylinder will be written (in the worst case) as a CSG hierarchy of a cylinder, two disks and two polygons! But it may be used in CSG operations, safely.
- `"Radius"` is the radius of the cylinder, default is 1.
- `"ZMin"` determines the Z location of the base, default is -1.
- `"ZMax"` determines the Z location of the top, default is 1.
- `"ThetaMax"` is the sweeping angle of the cylinder, default is 360.

### Torus Object

A torus, centered at the origin of the object coordinate system. A torus is a donut like shape, that results from sweeping a small circle ( that has been displaced along X sufficiently ) around the Z axis. This object will be exported as solid primitive or as simple torus (depending on the `"Closed"` parameter of the RiTorusAttr property) in RIBs.

Since Ayam 1.8.2, a torus object may be converted to NURBS patches using the main menu entry `"Tools/Convert"`. This conversion obeys all parameters of the torus.

The following parameters further control the shape of a torus:

### RiTorusAttr Property

- `"Closed"` toggles whether the object should be automatically sealed (closed) when exported to RIB. Note that if this option is in use and `"PhiMin"`, `"PhiMax"` or `"ThetaMax"` have different than the default values, a single torus will be written (in the worst case) as a CSG hierarchy of a torus, two disks and two hyperboloids! But it may be used in CSG operations, safely.
- `"MajorRad"` is the radius of the torus, measured from the Z axis to the center of the swept smaller circle, default is 0.75.
- `"MinorRad"` is the radius of the swept circle, default is 0.25.
- `"PhiMin"` determines an angle to limit the swept circle, default is -180.
- `"PhiMax"` determines an angle to limit the swept circle, default is 180.
- `"ThetaMax"` is the sweeping angle of the torus, default is 360.

### Paraboloid Object

A paraboloid, centered at the origin of the object coordinate system. This object will be exported as solid primitive or as simple paraboloid (depending on the `"Closed"` parameter of the RiParaboloidAttr property) in RIBs.

Since Ayam 1.8.2, a paraboloid object may be converted to NURBS patches using the main menu entry `"Tools/Convert"`. This conversion obeys all parameters of the paraboloid.

The following parameters further control the shape of a paraboloid:

### RiParabAttr Property

- `"Closed"` toggles whether the object should be automatically sealed (closed) when exported to RIB. Note that if this option is in use and `"ZMin"`, `"ZMax"` or `"ThetaMax"` have different than the default values, a single paraboloid will be written (in the worst case) as a CSG hierarchy of a paraboloid, two disks and two bicubic patches! But it may be used in CSG operations, safely.
- `"RMax"` is the radius of the paraboloid at a Z of `"ZMax"`, default is 1.
- `"ZMin"` determines the Z location of the base, default is -1.
- `"ZMax"` determines the Z location of the top, default is 1.
- `"ThetaMax"` is the sweeping angle of the paraboloid, default is 360.

### Hyperboloid Object

A hyperboloid, centered at the origin of the object coordinate system. This shape will be created by sweeping a line specified by two points in space around the Z axis. This object will be exported as solid primitive or as simple hyperboloid (depending on the `"Closed"` parameter of the RiHyperbAttr property) in RIBs.

Since Ayam 1.8.2, a hyperboloid object may be converted to NURBS patches using the main menu entry `"Tools/Convert"`. This conversion obeys all parameters of the hyperboloid.

The following parameters further control the shape of a hyperboloid:

### RiHyperbAttr Property

- `"Closed"` toggles whether the object should be automatically sealed (closed) when exported to RIB. Note that due to a bug in BMRT that is still present in V2.3.6 this option does not work properly when `"ThetaMax"` has a different than the default value and the hyperboloid has no displacement shader. In fact, using a displacement shader with a km (amount of displacement) of 0.0 is a work-around for this bug (found by T. E. Burge). Also note that if this option is in use and `"ThetaMax"` has a different than the default value, a single hyperboloid will be written (in the worst case) as a CSG hierarchy of a hyperboloid, two disks and two bilinear patches!
- `"P1_X"`, `"P1_Y"` and `"P1_Z"`, define point one, default is (0, 1, -0.5).
- `"P2_X"`, `"P2_Y"` and `"P2_Z"`, define point two, default is (1, 0, 0.5).
- `"ThetaMax"` is the sweeping angle of the hyperboloid, default is 360.

## 4.12 Level Object

Level objects may be used to build object hierarchies and perform CSG operations. Note that child objects of a level inherit the levels transformations attributes and shaders. Inheritance of e.g. transformations means: If you have a NURBS patch in a level that is translated to 10,0,0, the origin of the local coordinate system of the NURBS patch will be situated at 10,0,0. If you decide to move the patch by a value of 5 in X direction, you will finally arrive at 15,0,0.

### LevelAttr Property

Levels do not have many object type specific properties, you may just modify the type of the level using the attribute `"Type"`.

Levels of type `"Level"` just group objects and inherit attributes.

Levels of type `"Union"`, `"Intersection"`, and `"Difference"` are used to build CSG hierarchies. Additionally, they inherit attributes. Note that Ayam is currently not able to correctly display the results of CSG operations, all objects are always drawn completely, even though a CSG operation cut parts away. Since Ayam 1.8 there is a plugin available, that is able to preview the CSG operations, see also section CSG preview using the AyCSG plugin.

New solid primitives may be created with levels of type `"Primitive"`. Note that Ayam is not able to check, whether your new primitive obeys the rule of total closeness.

## 4.13 Material Object

Material objects are used to attach RiAttributes and shaders to geometric objects.

When geometric objects are dropped onto a material object using Drag-and-Drop in the tree view they will be connected to this object.

When geometric objects are connected to a material object this material object may not be deleted.

### RiAttributes Property

Using this property standard and BMRT specific attributes may be set. Please refer to the documentation of the RenderMan interface and the documentation of BMRT for more detailed information about the RenderMan specific attributes.

- `"Color"`, the color of the object. If you set one of the entries to a negative value (e.g. -1), the color will not be set at all for this object.
- `"Opacity"`, the opacity of the object, the default 255 255 255 means the object is totally opaque. If you set one of the entries to a negative value (e.g. -1), the opacity will not be set at all for this object.
- `"ShadingRate"`, determines how often shaders are evaluated for a sample.
- `"Interpolation"`, determines how return values computed by the shaders are interpolated across a geometric primitive.
- `"Sides"`, determines how many sides of the surface of a geometric primitive should be shaded.
- `"BoundCoord"`, sets the coordinate system in which the displacement bound is expressed.
- `"BoundVal"`, displacement bound value.
- `"TrueDisp"`, toggles true displacements on or off. Default off.
- `"CastShadows"`, determines how the object casts shadows: the default `"Os"` means the object casts shadows according to it's opacity; `"None"` object does not cast any shadows; `"Opaque"` the object is completely opaque and casts shadows; `"Shade"` the object has a complex opacity pattern determined by it's surface shader, that is used in shadow calculations.
- `"Camera"`, `"Reflection"`, and `"Shadow"` toggle visibility attributes.

### Surface, Displacement, Interior, Exterior Property

These properties let you define shaders for the material object, please refer to section Shaders Properties for information on how to deal with shader property GUIs.

Surface shaders may be used to procedurally encode lighting models and textures. Displacement shaders may procedurally deform the object while rendering. Interior and Exterior shaders are so called volume shaders that may be used to capture special optical effects, encoding how light is affected while passing through an object.

### MaterialAttr Property

The MaterialAttr property contains attributes related to the management of material objects:

- `"Materialname"` denotes the name of the material. Note that material names have to be unique in a scene. If two materials with the same name exist, only the first material created with this name is "registered" and thus may be connected to geometric objects.
- `"Refcount"` shows how many geometric objects are connected to (are of) this material. Note that connected or referring geometric objects not necessarily have to live in the scene, they may as well temporarily reside in the object clipboard.
- `"Registered"` displays whether this material may be connected to geometric objects, see the discussion about material names above.

## 4.14 Light Object

In contrast to the light sources as defined in the RenderMan interface, Ayam light sources are always global. This means, regardless of the place of a light source in the scene hierarchy, it will always light all other objects.

The behaviour of a light source object depends heavily on the type of the light source. There are four different types available: `"custom"`, `"point"`, `"distant"` and `"spot"`.

Custom Lights:

Light sources of type custom use the attached light shader.

Note that Ayam is trying to guess from the names of the light shader arguments to draw the light. The names `"from"` and `"to"` denote location and destination of the lightsource. You should not use these names for other things in your light shaders!

Point-, Distant-, and Spotlights:

These (standard) light sources have well defined parameters that will be displayed in the `"LightAttr"` property. Please refer to the RenderMan documentation for more information about the standard light sources (see section references).

### LightAttr Property

Depending on the type of the light source, the light attribute property contains different parameters. Parameters that are not displayed will not be used on RIB export, consequently.

Using `"Type"` you can change the type of the light source. When you change the type of a light source, the property GUI will be adapted but only after you use the `"Apply"`-button.

`"IsOn"` allows you to switch the light off or on. The default value is on.

`"IsLocal"` controls whether the light source should light just local objects (objects, that are defined in the same level in the scene hierarchy as the light source object or below) or all objects in the scene. The default is off, all objects in the scene are lighted! The `"IsLocal"` attribute is ignored for lights that are defined in the root level of the scene. Note that shadow maps will always contain shadows from all objects in the scene, regardless of local lights.

Using the light attribute `"Shadows"` you may determine whether the lightsource should cast shadows. The default is off, no shadows!

The attribute `"Samples"` determines the number of times to sample an area light source, independent of pixel samples, the default value is 1. This attribute is available for custom lights only!

`"UseSM"` determines, whether shadow maps should be created and used for this light source. The resolution of the shadow map may be determined by `"SMRes"`. If `"SMRes"` is 0, a default of 256 by 256 pixels will be used. These options are for renderers that do not support raytraced shadows like PRMan or Aqsis only.

For lights of type `"Distant"` the `"Scale"` attributes of the `"Transformations"` property of the light object may be used to scale the camera transformation used for the creation of the corresponding shadow map. Values of 1 for `"Scale_X"` and `"Scale_Y"` create a shadow map that is sized 1 by 1 units in world space.

All other parameters that may appear in the `"LightAttr"` property are the standard parameters for the standard RenderMan light sources: distant, point, and spot:

- `"From"` and `"To"` denote position and target of the light source as point in space. You may edit both points using standard point editing actions (see also section interactive actions).
- `"Color"` is the color of the light, emitted by the light source.
- `"Intensity"` is the intensity of the light, emitted by the light source. Note that the standard point and spot lights have a quadratic falloff (with distance), that requires the intensity to be set to quite high values in order to achieve some illumination effect (e.g. around 30 for the standard distance of `"From"` and `"To"` of a spot light).
- `"ConeAngle"` is the angle of the beam of a spot light.
- `"ConeDAngle"` (cone delta angle) is the angle that determines a falloff area at the edge of the beam of a spot light.
- `"BeamDistrib"` (beam distribution) determines, how the light falls off in the beam of the spot light. Larger values result in narrower light sources.

In order to ease the parameterisation of spot lights, you may drop the light source object on to a view object (preferably one with a perspective viewing transformation and with equal width and height) to see what objects of the scene are actually lighted by the light object.

### Using ShadowMaps

Using shadow maps requires the global preference setting `"RIB-Export/ShadowMaps"` to be switched on. Furthermore, for each light source for which a shadow map should be created, the attributes `"IsOn"` and `"UseSM"` have to be switched on.

If the preference setting `"RIB-Export/ShadowMaps"` is set to `"Automatic"`, Ayam will create a special version of the RIB on export, that creates all shadow maps automatically. This is done, by rendering depth images from the position of every light source that casts shadows. Special light source shaders later pick up these depth images and calculate shadows. This approach implies, that the scene is rendered multiple times. To reduce the size of the RIB, the objects to be rendered are written to a second RIB file named `"<scene>.obj.rib"`. This file is read from the main RIB several times via `"ReadArchive"`. The RIB contains multiple frames which may be rendered separately. To help you picking the right frame number for the image (e.g. to re-render just the image), a comment with the frame number of the last frame (the image) will be written as last statement to the RIB.

Because multiple files (RIBs and shadow maps) are used, it is suggested to change the preference setting `"RIB-Export/RIBFile"` to `"Scenefile"`. This will strip the leading absolute path component from the filenames so that you may move the scene from one system to another more easily.

If the preference setting `"RIB-Export/ShadowMaps"` is set to `"Manual"`, the exported scene will not render the shadow maps but rather expects them to be present already. You can create them manually (hence the name `"Manual"`) using the view menu entry `"View/Create ShadowMaps"` or the main menu entry `"Special/RIB-Export/Create ShadowMaps"`. The manual approach has the advantage, that the shadow maps will not be re-created each time you render the scene.

Ayam supports three different methods for the creation of shadow maps for certain types of light sources: point, distant, and spot:

The point method is used with lights of type `"Point"` and custom lights that have a light shader argument named "from". Six shadow maps pointing in all possible axis aligned directions and named `"<rib>.point<num>_<dir>.shd"` (where `"<rib>"` is the name of the RIB, `"<num>"` is the number of the light source that makes use of shadow maps and `"<dir>"` is one of `"x+"`, `"x-"`, `"y+"`, `"y-"`, `"z+"`, or `"z-"`) will be created.

The distant method is used with lights of type `"Distant"` and custom lights that have a light shader argument named "from" and a light shader argument named "to". One shadow map is created and named `"<rib>.dist<num>.shd"`. By default, the size of the shadow map is 1 by 1 units in world space, but this may be adapted using the scale transformation attributes of the light object.

The spot method is used with lights of type `"Spot"` and custom lights that have a light shader argument named "from", a light shader argument named "to", and a light shader argument named "coneangle". One shadow map is created and named `"<rib>.spot<num>.shd"`. The spot method uses the cone angle (and additionally the delta cone angle, if present) argument to determine the size of the shadow map in world space.

If a light object of type `"Spot"`, `"Distant"` or `"Point"` is used, Ayam automatically changes the name of the exported light shader to `"shadowspot"`, `"shadowdistant"`, and `"shadowpoint"` respectively. Additionally, the shader will be parameterized to use the created shadow maps. If the light source is of type `"Custom"`, no automatic renaming and adjusting of the shader takes place. This means, you have to make sure that the shader really uses the shadow maps, by selecting the right shader and parameterizing it accordingly. See the discussion above for the names of the shadow map files. Those file names, probably, will have to be entered as parameter to the light shader.

For example, you will not get any shadows if you use a light source of type `"Custom"` with a `"distantlight"` shader attached, even though Ayam is able to create the necessary shadow maps. The `"distantlight"` shader just makes no use of them. You have to manually switch to a shader that makes use of the shadow maps (`"shadowdistant"` in this case) to get shadows.

Here is a short example for a scene using a shadow map:

1. Go to the preferences (section `"RIB-Export"`) and set `"ShadowMaps"` to `"Automatic"`.
2. Create two boxes.
3. Open the `"Transformations"` property of the second box.
4. Translate it by X: 0.0, Y: -1.0, Z: 0.0.
5. Scale it by X: 4.0, Y:1.0, Z:4.0.
6. Create a light source.
7. Open the `"LightAttr"` property.
8. Change the type to `"Spot"`. Press `"Apply"`.
9. Now change the parameters of the spot light to `"IsOn"`: Yes, `"Intensity"`: 18.0, `"UseSM"`: Yes, `"ConeAngle"`: 45.0, `"BeamDistrib"`: 3.0, `"From"`: -2, 2, 2, `"To"`: 1, 0, -1; leave all other parameters at their default values.
10. Create a new view and make it perspective (Menu: `"Type/Perspective"`).
11. Export a RIB from that perspective view (Menu: `"View/Export RIB"`).
12. Render the RIB with a RenderMan compliant renderer, that uses shadow maps, e.g. Photorealistic RenderMan (prman) or Aqsis.

This scene is distributed with Ayam as an example scene named `"shadowmaps.ay"`.

Note that for Aqsis you should add a RiHider hidden,depthfilter,s,midpoint tag to your root object if shadow maps are in use. Other renderers might require additional tweaking using shadow bias RiOption tags.

Do not render directly from a view window if your renderer does not write image files when the command line option to render directly to the display (-d for rendrib, or -fb for Aqsis) is in use. This command line option may inhibit writing of the shadow maps, so that the resulting image will look wrong.

### Using AreaLights

The common idealized standard light sources `"Point"`, `"Distant"` and `"Spot"` have no own geometric extension in space. This means, shadows resulting from such light sources will have sharp borders which does not look too naturally. Good looking soft shadows may be generated using area lights.

Area lights may be created by simply placing a single object as child object of a `"Custom"` light object that has the `"arealight"` shader attached:

    +-AreaLight(Light)
     \--AreaLightGeometry(Sphere)

This child object determines the geometry of the lightsource. According to L. Gritz, Spheres and Cylinders work best as area light geometry for BMRT, because of special sampling code.

An example:

- Create a custom light object.
- Assign the arealight light shader to it.
- Create a Sphere.
- Drag-and-Drop the Sphere onto the Light object so that it becomes a child of the light object.
- Transform the object to your hearts content; the position and size of the object determines the position and size of the lightsource!

There is an example scene named `"arealight.ay"` distributed with Ayam.

## 4.15 NURBCurve Object

NURBS curves are used to build more complex smoothly shaped objects using operations like extrude, revolve, sweep or skin. They can be closed and used to emulate Bezier and B-Spline curves easily.

### Multiple Points

A NURBS Curve with Multiple Points (big handles)

The NURBS curves of Ayam support so called multiple points. A multiple point is made of a number of different control points that have the same coordinates. Modeling actions will always modify all the control points that make up a multiple point. Multiple points will be drawn with a bigger handle than normal points (see image above). They may e.g. be used to create closed curves. Note that the control points that make up a multiple point do not have to be consecutive (in the control point vector of the NURBS curve). Multiple points may be created using the collapse tool, and split up again using the explode tool (see sections The Collapse Tool and The Explode Tool for more information regarding those tools). Note that even though you might have exploded some multiple points Ayam will re-create them on several occasions like reading of a scene, inserting/deleting points, and applying the NURBCurveAttrib property if they still have identical coordinate values. In other words, you should immediately edit the control points after exploding! You may also totally inhibit creation of multiple points for a NURBS curve using the attribute `"CreateMP"`.

### NCurveAttrib Property

The first section of the NCurveAttrib property contains curve specific settings:

- `"Type"`: This attribute replaces the `"Closed"` attribute since Ayam 1.9.

  The type `"Open"` is for the standard open NURBS curve.

  If the type is `"Closed"`, the first and last control point of the curve will be made identical. This will close the curve but without any guaranteed continuity. Such a closed curve will e.g. be created by the NURBS circle tool. It is important to know, that identical start/end control points alone can not guarantee that the curve is closed if the knot vector is not clamped. If in doubt, use the clamp tool or a knot vector of type NURB.

  If the type is `"Periodic"`, the last p control points of the curve will be made identical to the first p where p is the degree of the curve (read order-1). This will close the curve with guaranteed continuity. Note that for a cubic spline (order 4) you will need atleast 6 control points to close it. It is important to know, that the multiple control points alone can not guarantee that the curve is closed if the knot type of the curve is Custom; if you really want a closed curve switch to type B-Spline.

  You may want to enable the creation of multiple points using the `"CreateMP"` attribute (see below) for closed curves so that single point editing actions modify all multiple control points.

- `"Length"` is the number of control points of the curve.
- `"Order"` is the order of the curve.
- `"Knot-Type"`: Using `"Knot-Type"` you may select from NURB, Bezier, B-Spline and Custom knot sequences. If the knot type is not Custom, the next setting `"Knots"` will be ignored. Instead, knots of type NURB, Bezier or B-Spline will be generated.

  How do the different knot types affect the curve?

  The knot type NURB will generate knot values ranging from 0.0 to 1.0, where the multiplicity of the knots at the ends will be of order of the curve. This guarantees that the curve will touch the control points at the ends of the curve. The curve is clamped.

  The knot type Bezier will generate just 0.0 and 1.0 values. Note that the order of the curve has to be equal to the length of the curve, if Bezier knots are generated. Otherwise, the generated knot sequence is illegal. The resulting curve looks and behaves exactly like a real Bezier curve, interpolating it's ends and so on.

  The knot type B-Spline will generate equidistant knot values (without any multiple knots). The resulting curve looks and behaves like a B-Spline curve.

- `"Knots"` lets you enter your own custom knot sequences. Note that `"Knots"` are not in use if `"Knot-Type"` is of type NURB, B-Spline or Bezier!
- `"CreateMP"` toggles, whether multiple points should be created for this curve. See also the discussion in section Multiple Points.
- `"IsRat"` informs you since Ayam 1.9, whether the curve is rational (uses weight values different from 1.0).

The GLU-parameters control the appearance of the curve when curve/surface display is enabled.

- `"Tolerance"` is in fact GLU sampling tolerance, used to control the quality of the sampling when rendering a curve. Smaller tolerance settings lead to higher quality but also slower display. A setting of 0.0 means, that the global preference setting `"Drawing/Tolerance"` should be used.
- `"DisplayMode"` determines how the curve should be drawn. The control hull (control polygon) or the curve or a combination of both may be displayed. The setting `"Global"` means, that the global preference setting `"Drawing/NCDisplayMode"` should be used.

When changing more than one of the above values the changes will be applied in the order of the values in the property. The sum of the changed values should describe a valid NURBS curve. It is perfectly legal to change the length of the curve, it's order, and switch to a custom knot vector (be sure to actually enter a valid new knot vector) at once. Ayam will check your changes and fall back to certain default values if e.g. your knot sequence is wrong. Check the console for any messages!

## 4.16 NURBPatch Object

This object allows to model NURBS surfaces in a direct way, e.g. by modifying control points. Note that using NURBPatch objects should be seen as last resort, only to be used when the flexibility of all the NURBS surface creating tool objects is not high enough to achieve a certain shape.

Since Ayam 1.10, NURBPatch objects also support the concept of multiple points, see section Multiple Points for more information regarding this.

### NPatchAttrib Property

The first section of the NPatchAttrib property contains patch specific settings:

- `"Width"` and `"Height"` control the dimensions of the patch.
- `"Order_U"` and `"Order_V"` set the orders of the patch.
- `"Knot-Type"` and `"Knots"`: For a discussion of the `"Knot-Type"` and `"Knots"` parameters, please see section NCurveAttrib.
- `"CreateMP"` toggles, whether multiple points should be created for this surface. See also the discussion in section Multiple Points. This option is available since Ayam 1.10.
- `"IsRat"` informs you since Ayam 1.9, whether the patch is rational (uses weight values different from 1.0).

The next parameters control the appearance of the patch for display in Ayam:

- `"Tolerance"` is in fact the GLU sampling tolerance used to control the quality of the sampling when rendering the patch. Smaller tolerance settings lead to higher quality but also slower display. A setting of 0.0 means, that the global preference setting `"Drawing/Tolerance"` should be used.
- `"DisplayMode"` sets the display mode, either the control hull is drawn (`"ControlHull"`), or just the outlines of the polygons created by the tesselation (`"OutlinePolygon"`), or just the outlines of the patch (`"OutlinePatch"`). The default setting (`"Global"`) means, that the value of the global preference setting `"Drawing/NPDisplayMode"` should be used instead.

## 4.17 Trim Curves

Trim curves may be used to cut out certain parts of a NURBS patch. They are simple 2D NURBS curves defined in the parametric space of the associated NURBS patch. Trim curves have to be defined as child objects of the NURBS patch object they belong to. In contrast to other child objects, however, they do not inherit the transformation attributes of the parent object. Trim curve editing should take place in views of type `Trim`, that draw the boundaries of the parametric space of the corresponding NURBS patch as rectangle, but otherwise act as normal `Front` views.

Note that the direction of the trim curve determines which part of the NURBS patch should be cut out. You can use the `Revert` tool (`Tools/NURBCurve` menu) to easily change the direction of a trim curve.

Some special restrictions apply to trim curves:

- All trim curves should entirely lie in the (u,v) parameter space of the NURBS patch (remember the rectangle in the `Trim` view). Note that this restriction does not apply to the control points, but the curves! It is ok to have control points outside the rectangle if the defined curve is inside the rectangle.
- The last point of a trim curve must be identical to the first point.
- Trim loops (multiple trim curves that form loops) are possible too; the last point of each curve in the loop must be identical to the first point of the next curve in the loop and the first point of the first curve of a loop must be identical to the last point of the last curve of that loop.
- To mark a set of curves to be a loop, they must be placed in a level object. The order of the curves in this level is the order of the loop. The transformation attributes of this level object are fully ignored for trimming.
- Drawing trimmed NURBS patches with certain implementations of OpenGL may require a special trim curve (a rectangular piecewise linear curve that encloses the whole NURBS patch) to be present. Such a curve may be generated with the `TrimRect` tool. You can find this tool in the `Tools/Create` menu. This curve is needed if you want to cut out a hole with a single trim curve. This curve is generally not needed if you want to render the patch with BMRT but it should not hurt if it is present.
- If there are nested trim curves, their direction must alternate.
- Trim curves may not intersect each other or themself.

Note that Ayam is not checking whether your trim curves follow these rules!

Warning: Certain OpenGL implementations may be easily crashed drawing trimmed NURBS patches with trims that do not follow the aforementioned rules! When in doubt or while heavy modeling, switch to wireframe drawing and switch off shading temporarily and you will be on the safe side.

Since Ayam 1.5 also NURBS curve providing objects are supported as trim curves.

## 4.18 BPatch Object

A BPatch is a simple bilinear patch defined by four control points. BPatch objects are e.g. used to build box objects, see Box Object).

### BPatchAttrib Property

The BPatchAttrib property allows you to set the four points defining the geometry of the patch:

- `"P1_X"`, `"P1_Y"`, `"P1_Z"`, first point.
- `"P2_X"`, `"P2_Y"`, `"P2_Z"`, second point.
- `"P3_X"`, `"P3_Y"`, `"P3_Z"`, third point.
- `"P4_X"`, `"P4_Y"`, `"P4_Z"`, fourth point.

## 4.19 PatchMesh Object

The PatchMesh object may be used to model with bilinear and bicubic patch meshes. The PatchMesh object may be converted to a NURBS patch representation. However, this does not work for all possible types of patch meshes (e.g. patch meshes with the basis types Catmull-Rom, Hermite, or Custom). The NURBS patch representation is also in use when drawing the patch mesh (if the `"DisplayMode"` is not `"ControlHull"`) and when shading the patch mesh. Consequently, there is currently no shaded representation of patch meshes of basis type Catmull-Rom, Hermite or Custom.

### PatchMeshAttr Property

The first section of the PatchMeshAttr property contains patch specific settings:

- `"Type"` may be set to `"Bilinear"` or `"Bicubic"`.
- `"Width"` and `"Height"` control the dimensions of the patch.
- `"Close_U"` and `"Close_V"` determine, whether the patch mesh should be closed in u- and v-direction respectively.
- `"BType_U"` and `"BType_V"` control the basis type for bicubic patches. You may choose between the basis types: `"Bezier"`, `"B-Spline"`, `"Catmull-Rom"`, `"Hermite"`, and `"Custom"`. In the latter case (`"Custom"`), additional parameters may be set. Those are `"Step_U"`/`"Step_V"` (the stepsize of the basis) and `"Basis_U"`/`"Basis_V"` the basis itself (please see the RenderMan Companion for a discussion of basis types).

The parameters `"BType_U"` and `"BType_V"` and consequently `"Step_U"`/`"Step_V"` and `"Basis_U"`/`"Basis_V"` are only available to bicubic patch meshes.

The next parameters control the appearance of the patch for display in Ayam:

- `"Tolerance"` is in fact GLU sampling tolerance, used to control the quality of the sampling when rendering the patch. A setting of 0.0 means, that the global preference setting `"Drawing/Tolerance"` should be used.
- `"DisplayMode"` sets the display mode, either the control hull is drawn, or just the outlines of the polygons created by the tesselation (OutlinePolygon), or just the outlines of the patch (OutlinePatch). The default setting (Global) means, that the global preference setting `"Drawing/DisplayMode"` should be used.

## 4.20 PolyMesh Object

The PolyMesh object may be used to include objects that have been modeled using the polygonal modeling paradigm in Ayam scenes.

There are no special modeling actions for this type of object, but you may select and modify single points as you can do it with other object types, e.g. curves.

The PolyMesh object is equivalent to the general points polygons primitive of the RenderMan interface. This means, each PolyMesh object may contain multiple general (convex or concave) polygons, which in turn may consist of an outer loop and an arbitrary number of inner loops that describe holes in the polygon. The loops use a point indexing scheme to efficiently reuse coordinate values. This general approach requires a so called tesselation to be carried out, in order for the PolyMesh object to be shaded. For that, Ayam uses the tesselation routines of the GLU library.

Ayam is able to automatically create face normals for PolyMeshes. They will be calculated while tesselating the PolyMesh and be perpendicular to the plane determined by the first three vertices of the outer loop of a polygon. Furthermore, Ayam supports vertex normals (normals stored for every control point).

Note that storing a bunch of triangles each in its own PolyMesh object will lead to a real waste of memory. You may use the merge tool (main menu `"Tools/PolyMesh/Merge"`) to merge many PolyMesh objects into a single PolyMesh object.

### PolyMeshAttr Property

The PolyMeshAttr GUI just displays some information about the PolyMesh object:

- `"NPolys"` the number of polygons.
- `"NControls"` the total number of control points defined.
- `"HasNormals"` is 1 if the object uses vertex normals, else it is 0.

## 4.21 SDMesh Object

The SDMesh object may be used to include objects that have been modeled using the subdivision modeling paradigm in Ayam scenes.

There are no special modeling actions for this type of object, but you may select and modify single points as you can do it with other object types, e.g. curves.

The SDMesh object is equivalent to the Subdivision Mesh primitive of the RenderMan interface. This means, each SDMesh object may contain multiple faces with arbitrary number of vertices that form a polygonal mesh. This polygonal mesh is then successively refined using a subdivision scheme and, depending on the number of refinement (or subdivision) steps, results in a more or less smooth surface. There are several different subdivision schemes, but the scheme currently supported by most RenderMan compliant renderers is named "Catmull-Clark".

Tags may be specified for faces, edges, or vertices to control the subdivision process (e.g. to create sharp corners or edges in the resulting surface). All tags known from the RenderMan interface (hole, crease, corner, and interpolateboundary) are supported by Ayam, but they may currently not be changed by the user.

Furthermore, Ayam is currently not able to do the subdivision and show the resulting smooth surface. All that is shown in wireframe and shaded views is the original polygonal mesh.

### SDMeshAttr Property

The SDMeshAttr GUI just displays some information about the SDMesh object:

- `"Scheme"`, subdivision scheme, currently only 0 (Catmull-Clark).
- `"NFaces"`, the number of faces.
- `"NControls"`, the total number of control points defined.

## 4.22 Instance Object

The term instance is unfortunately misleading (and can be very confusing if you are accustomed to the terminology of object oriented programming), but it is the term that seems to be used and understood by most computer graphic artists. A better term would be link, as an instance object has the same basic properties as a link in a Unix file system. A link is just a pointer to an original file, the same goes for an instance object: it is just a pointer to an original object (master). A link can be placed anywhere on the file system, an instance object can be placed anywhere in the hierarchy, and additionally, it can be transformed (otherwise it would be pretty useless).

The sole purpose of instance objects is to save storage. The amount of saved diskspace can be very high, but this depends heavily on the scene. If there are no similar objects in the scene you can hardly use instancing. Similar means "the same except for the transformation property" in this context.

Some simple rules for instancing:

- No instances may be created of objects of the following types: Root, View, Instance, Material, Light. Do not try to fool Ayam and create instances of levels that contain aforementioned types of objects, things will go awry! You may, however, put some instances into a level object and create instances of this level (this is sometimes called hierarchical instancing). But you may not put instances of a level into the very same level (this would be recursive instancing, which is not supported by Ayam).
- The original object may not be deleted from the scene as long as there are instances of that object in the scene or in the object clipboard.

If you cannot delete an object, and the error message tells you something about a reference counter, then you were about to violate the second rule. Clean the clipboard using the menu `"Special/Clipboard/Paste (Move)"` and delete or resolve all references.

Note that it is not possible to copy a master object and some instances of it, so that the new instances point to the newly created master. All copies of instance objects always point to the same master object. However, it is possible to move instances using Drag-and-Drop in the tree view or using the clipboard with `"Edit/Cut"` and then `"Special/Clipboard/Paste (Move)"`.

You can resolve an instance object at any time using the converter registered for objects of type `Instance` (simply select the instance object and use the menu entry `"Tools/Convert"`). To resolve all instance objects in a scene to normal objects, you may use the main menu entry: `"Special/Instances/Resolve all Instances"`.

The RIB export of instances does not use the RiInstance facility of the RenderMan interface, but the ReadArchive mechanism. This means, every original object in the scene will be written in a separate archive (RIB file) on disk, and every instance will cause that archive file to be read. You can change that behaviour using the preference setting `"ResInstances"`. If `"ResInstances"` is enabled, all instances will be resolved (temporarily) before being exported to RIB.

Ayam can also create instances automatically (see section Automatic Instancing).

To easily find the master object of an instance, just select the instance, then use the main menu entry: `"Edit/Master"`.

## 4.23 Clone Object

Clone Object with Trajectory Curve (white)

The Clone object allows you to easily create and control a number of instances of a single object. The instances will be created internally and transformed, each by a certain amount. The original object is the first child object of the Clone object. If a second object is present as child of the Clone object it is treated as trajectory (or path) curve, similar to the Sweep object (see section Sweep Object).

Thus, the object hierarchy of a Clone object may look like this:

    +-Clone
     | Cloned-Object
     \ [Trajectory(NCurve)]

If you use a trajectory curve to place the clones, you may want to hide the parameter object and add a `"NoExport"` tag to it. Otherwise the original object will appear twice, on the trajectory and on its normal position. Note that the transformation attributes of the parameter object will be completely overwritten when placing the clones on the trajectory curve. If the parameter object has distinct scale or rotation attributes it should be placed inside a level object like this:

    +-Clone
     +-Level
     |\-Cloned-Object with non-standard Scale/Rotation
     \ Trajectory(NCurve)

It is not possible to create clones from objects that may not be master objects of instance objects (e.g. light objects, or material objects). However, (since Ayam 1.7) it is possible to use instances as parameter objects.

If an instance object is used as parameter object it should be placed in a level (see above) and the `"NoExport"` tag should added to the level object (as you can not add tags to instance objects).

The following attributes further control the clone process:

### CloneAttr Property

- `"NumClones"` the number of clones to create.
- `"Rotate"` is only used, if a trajectory curve is present. If it is enabled all clones will be aligned according to the normal of the trajectory curve.
- `"Mirror"` allows to choose between three different mirror modes. If mirroring is enabled, for each child of the Clone object, a mirrored counterpart will be created and all other parameters of the Clone object will be ignored. Since Ayam 1.9, the original object(s) and their mirrored counterparts will be provided by the Clone object, and, additionally, the order of the mirrored objects will be reversed so that it is possible to use a single Clone object in mirror mode (with one or multiple NURBS curves as children) as parameter object of e.g. a Skin object:

      +-Skin
       +-Mirror(Clone)
        \-NCurve

- `"Translate_X"`, `"Translate_Y"`, `"Translate_Z"`, `"Rotate_X"`, `"Rotate_Y"`, `"Rotate_Z"`, `"Scale_X"`, `"Scale_Y"`, `"Scale_Z"`, those attributes control the transformation of the instances. They are not used, if a trajectory curve is present.

## 4.24 Revolve Object

Revolve Object (left: Curve, right: Surface of Revolution)

The Revolve object forms a surface of revolution from a NURBS curve.

The Revolve object has the generating NURBS curve as child object and watches its changes and adapts to it automagically.

The axis of revolution is always the Y axis of the coordinate system that is defined by the next higher level in the object hierarchy (the Y axis of the revolve object itself). The generating curve should lie in the XY plane of this coordinate system. If not, it will be squashed down to this plane!

The following simple experiment should make the last statements more clear, during all steps watch the movements of the revolution:

- Create a NURBCurve. Select it.
- Create a Revolve custom object using the menu entry (`Tools/NURBCurve/Revolve`).
- Select the Revolve object, and rotate it around Z. (The axis of the revolution changes. The generating NURBS curve, as child object, will also be rotated.)
- Now enter the Revolve object, select the child curve and edit the control points (Note how the Revolution changes).
- Rotate the curve around Z (Note how the Revolution changes).
- Switch to a Side view, edit the generating curve here in Z direction only (Revolution does not change!).

You may convert the current surface of revolution and the caps, if there are any, to ordinary NURBS patches using the main menu entry `"Tools/Convert"`.

### RevolveAttr Property

Using the parameter `"ThetaMax"` you can specify the sweeping angle of the revolution just like with an ordinary RenderMan quadric.

Since Ayam 1.8 the Revolve object supports a B-Spline mode, that may be enabled by setting the new parameter `"Sections"` to a value higher than 2. In this mode, a circular B-Spline is used as basis for the surface of revolution, instead of the standard NURBS circle. Depending on the number of sections choosen, the surface of revolution does not exactly interpolate the parameter curve, but the surface may be edited more easily after a possible conversion to an ordinary NURBS patch object, because the control points will not be rational. In addition to the number of sections, in B-Spline mode it is possible to control the order of the surface of revolution using the new parameter `"Order"`. If `"Order"` is 0, a standard value of 3 will be used. Note that the B-Spline mode is currently only available for full revolutions (`"ThetaMax"` should be 360.0).

The revolve object can automatically generate caps, which are trimmed NURBS patches. Using the parameters `"UpperCap"`, `"LowerCap"`, `"StartCap"`, and `"EndCap"`, you determine whether such caps should be generated, default is off (no caps).

If the side caps of a surface of revolution of an open curve are not created correctly, (GLU complains about "intersecting or misoriented trimcurves"), try to revert the revolved curve.

See section NPatchAttrib for a description of the other two attributes `"DisplayMode"` and `"Tolerance"`.

## 4.25 Extrude Object

Extrude Object (left: Curve, middle: normal Extrusion, right: Extrusion with Caps)

The extrude object forms an extrusion from a number of NURBS curves.

The first curve determines the outline, and the other curves determine holes in the extrusion object. Holes may be used by objects that form e.g. letters.

The object has the generating NURBS curves as child objects and watches them and adapts to them automagically.

Consequently, the object hierarchy of an Extrude object may look like this:

    +-Extrude
     | Outline(NCurve)
     | [Hole1(NCurve)]
     \ [Hole2(NCurve)]

The extrude object can generate caps, if the generating curves are closed. Cap generation may fail, if the outer curve has weights and the curve itself leaves the convex hull of the control polygon. Be careful when using curves with weights!

The sharp corners between caps and extrusion may be beveled.

The axis of the extrusion is always the Z axis of the coordinate system that is defined by the next higher level in the object hierarchy (the Z axis of the extrude object itself). The generating curves should lie in the XY plane of this coordinate system. If not, they will be squashed down to this plane!

You may convert the current surface of extrusion and the caps and bevels, if there are any, to ordinary NURBS patches using the main menu entry `"Tools/Convert"`.

### ExtrudeAttr Property

Using the parameter `"Height"` you determine how big in Z direction the extrusion should be. Note that the height of the bevels will not be taken into account here, if you have an extrusion with height 1.0 and you switch on beveling (upper and lower) with radius 0.1 you end up with an object that is 1.2 whatever big in Z direction.

The extrude object can automatically generate caps, that are trimmed NURBS patches. Using `"StartCap"` and `"EndCap"` you determine whether such caps should be generated, default is off (no caps). Note that this feature does only work properly, if the generating NURBS curves are closed and not self intersecting, this is because the generating curves themselves are used as trim curves for the caps. Warning, Ayam will not check whether your curves conform to this criteria. Ayam, however, detects the correct orientation of the curves (and reverts them if necessary).

Since Ayam 1.10 the bevel parameters of the extrude object are saved in bevel parameter tags and the property GUI changed to conform to all other bevel supporting tool objects. The old options `"LowerBevel"`, `"UpperBevel"`, `"BevelType"`, and `"BevelRadius"` are no longer available. They were replaced with new dynamic tag creating bevel property GUI sections that are accessible through the new command entries `"Add Start Bevel!"` and `"Add End Bevel!"` respectively. If one of those entries is used, a bevel parameter tag is created and more options will be made available in the property GUI to adjust the bevel parameters or remove the tag again. A more thorough discussion of those options is available in section BevelAttr Property.

See section NPatchAttrib for a description of the other two attributes `"DisplayMode"` and `"Tolerance"`.

### Using Holes and Bevels

All curves forming holes in the extruded object must be defined inside (geometrically) the first curve (the outline curve). Additionally, they may not intersect each other or themself and you cannot have hole curves inside hole curves. Ayam will not check whether your curves conform to these criteria!

With the direction of the curve you decide the direction of the bevel as well (should it round outwards or inwards?). If the bevels of the holes look wrong try to revert the generating curves of the holes. Note that beveling does not work well with open curves. You should always use closed curves for beveling! Beveling may lead to self intersecting trimcurves in sharp corners of an extrusion. Decrease the bevel radius or round the corners of the extruded curve (using insertion of additional control points) if cap generation fails due to self intersecting bevels.

## 4.26 Sweep Object

Sweep Object (left: Curves, right: Resulting Swept Surface)

The sweep object forms a surface that results from moving a NURBS curve (cross section or profile) along a second NURBS curve (trajectory or path). The cross section may be scaled while sweeping using a third curve, the scaling function.

The sweep object has the generating NURBS curves as child objects and watches their movements and adapts to them automagically. The first curve is the cross section, the second is the trajectory, and the third curve represents the scaling function.

The object hierarchy of a Sweep object, thus, may look like this:

    +-Sweep
     | Cross_Section(NCurve)
     | Path(NCurve)
     \ [Scaling_Function(NCurve)]

Note that the `"Translate"` attributes of the cross section curve will be fully ignored. All other transformation attributes (of cross section and trajectory!) will be used to determine place, orientation and size of the sweep object!

The cross section curve has to be defined in the YZ-plane of the Sweep objects coordinate system but it also has to be defined in the XY-plane of its own coordinate system. This means, that a simple circular curve as e.g. created with the toolbox has to be rotated by 90 degrees around the Y-axis using its transformation attributes to follow these rules. Later editing of this curve has to be done in a Side view (or in an aligned local Front view, if the Sweep object itself is transformed somehow).

The scaling function is sampled for each section and the Y-component of the coordinates of the current curve point will be used as scale factor, that is applied to the cross section in Y- and Z-direction. This implies, that a scaling function that does nothing should e.g. be linear from (0,1,0) to (1,1,0).

Sweep Object with Scaling Function (white)

Here is a short example for the creation of a sweep:

- Create a circular BSpline using the toolbox. (This will be our cross section.)
- Rotate it by 90 degrees around the Y-axis. (Use the `"Transformations"` property for that.)
- Create a simple NURBS curve using the toolbox. (This will be our trajectory.)
- Select both curves. (Select the first curve, hold down the `"Shift"` key and select the other curve.)
- Create the Sweep object using the toolbox.
- Now you may enter the Sweep object and modify e.g. the second curve, the trajectory. (Press `"e"`, then drag some control points around.)
- To modify the cross section you would need to switch to a view of type `"Side"`. (Use the `<Ctrl+s>` shortcut while the view has the input focus.)

Section Easy Sweep has an example script that automates creation and parameterisation of a suitable cross section curve.

You may convert the current sweep and the caps, if there are any, to ordinary NURBS patches using the main menu entry `"Tools/Convert"`.

### SweepAttr Property

If `"Interpolation"` is enabled, all section curves will be interpolated by the swept surface.

The second parameter `"Sections"` determines how many sections (in u direction) should be used, when generating the sweep NURBS patch. The NURBS patch always has sections+1 control points in u direction.

If `"Rotate"` is enabled, the cross sections will be rotated so that they are always perpendicular to the trajectory, this is the default.

The attributes `"StartCap"` and `"EndCap"` may be used to automatically create cap surfaces, that close the Sweep on both ends. Note that this works properly only if the cross section curve is closed and planar (defined in the XY plane).

Since Ayam 1.10 bevels are available for sweeps. They are accessible through the new command entries `"Add Start Bevel!"` and `"Add End Bevel!"` respectively. If one of those entries is used, a bevel parameter tag is created and more options will be made available in the property GUI to adjust the bevel parameters or remove the tag again. A more thorough discussion of those options is available in section BevelAttr Property.

See section NPatchAttrib for a description of the other two attributes `"DisplayMode"` and `"Tolerance"`.

## 4.27 Birail1 Object

Birail1 Object (left: Curves, right: Resulting Swept Surface)

The Birail1 object forms a surface by sweeping a cross section (or profile) curve along two so called rail curves. The object hierarchy of a Birail1 object, thus, looks like this:

    +-Birail1
     | Cross_Section(NCurve)
     | Rail1(NCurve)
     \ Rail2(NCurve)

When the cross section touches the rail curves in their respective starting points, the resulting surface will interpolate the rail curves. The direction of the cross section curve will be parallel to the v parametric dimension (height) and the direction of the rail curves will be parallel to the u parametric dimension (width) of the resulting surface. Height and width of the surface will be derived from the length of the cross section curve and the number of sections, respectively.

Valid Configuration of Parameter Curves (white) for Birail1 (blue)

The image above shows a valid configuration of parameter curves for the Birail1 object. Mind the direction of the rail curves (R1 and R1) with regard to the cross section curve (CS) and the fact that the cross section curve touches the starting points of the rail curves.

Note that the cross section curve does not have to be two dimensional, and, in contrast to the normal Sweep object, it also does not have to be defined in a special plane. Also note that the precision with which the resulting surface will interpolate the rail curves depends on the number of sections choosen.

The Birail1 object watches the child objects and adapts to them automatically via the notification mechanism.

You may convert the current birailed surface and the caps, if there are any, to ordinary NURBS patches using the main menu entry `"Tools/Convert"`.

The following parameters further control the birailing process:

### Birail1Attr Property

The parameter `"Sections"` determines how many sections (in u direction) should be used, when generating the birailed NURBS patch. The birailed NURBS patch always has sections+1 control points in u direction.

The attributes `"StartCap"` and `"EndCap"` may be used to automatically create cap surfaces, that close the birailed surface on the respective end. Note that this only works properly if the cross section curve is closed and planar (e.g. defined in the XY plane).

Since Ayam 1.10 bevels are available for birails. They are accessible through the new command entries `"Add Start Bevel!"` and `"Add End Bevel!"` respectively. If one of those entries is used, a bevel parameter tag is created and more options will be made available in the property GUI to adjust the bevel parameters or remove the tag again. A more thorough discussion of those options is available in section BevelAttr Property.

See section NPatchAttrib for a description of the other two attributes `"DisplayMode"` and `"Tolerance"`.

## 4.28 Birail2 Object

Birail2 Object (left: Curves, right: Resulting Swept Surface)

The Birail2 object forms a surface by sweeping a cross section (or profile) curve along two so called rail curves, while morphing it into a second cross section (or profile) curve. The morphing process may be controlled by a fifth parameter curve. The object hierarchy of a Birail2 object, thus, looks like this:

    +-Birail2
     | Cross_Section1(NCurve)
     | Rail1(NCurve)
     | Rail2(NCurve)
     | Cross_Section2(NCurve)
     \ [Interpolation_Control(NCurve)]

When the cross sections touch the rail curves in their respective starting points, the resulting surface will interpolate the rail curves. The direction of the cross section curves will be parallel to the v parametric dimension (height) and the direction of the rail curves will be parallel to the u parametric dimension (width) of the resulting surface. Height and width of the surface will be derived from the length of the cross section curves and the number of sections, respectively.

Valid Configuration of Parameter Curves (white) for Birail2 (blue)

The image above shows a valid configuration of parameter curves for the Birail2 object. Mind the direction of the rail curves (R1 and R1) with regard to the two cross section curves (CS1 and CS2) and the fact, that all curves touch at their respective end points.

Note that the cross section curves do not have to be two dimensional, and, in contrast to the normal Sweep object, they also do not have to be defined in a special plane. Furthermore, they do not have to be compatible in terms of length, order, and knots. Incompatible curves will be made compatible before birailing automatically; the height of the resulting surface, however, is not easily predictable anymore in this case. Also note that the precision with which the resulting surface will interpolate the rail curves depends on the number of sections choosen.

If a fifth curve is present as parameter object, this curve will control the morphing (interpolation) process. The y coordinate of this curve at a specific point, which should have a value between 0 and 1, determines the ratio of control of the first cross section (0) and the second cross section (1) over the interpolated curve. Thus, a straight line running from point (0,0) to (1,1) will mimic the standard linear interpolation that would be carried out if no interpolation control curve were present. Note, however, that the interpolation control curve has no influence on the first and last copy of the respective cross section curve, unless the `"InterpolCtrl"` option is used (which is available since Ayam 1.10). If `"InterpolCtrl"` is not enabled, the first and last border of the resulting surface will always exactly match the parameter curves (CS1 and CS2 respectively).

The Birail2 object watches the child objects and adapts to them automatically via the notification mechanism.

You may convert the current birailed surface and the caps, if there are any, to ordinary NURBS patches using the main menu entry `"Tools/Convert"`.

The following parameters control the birailing process:

### Birail2Attr Property

The parameter `"Sections"` determines how many sections (in u direction) should be used, when generating the birailed NURBS patch. The birailed NURBS patch always has sections+1 control points in u direction.

The attributes `"StartCap"` and `"EndCap"` may be used to automatically create cap surfaces, that close the birailed surface on the respective end. Note that this only works properly if the cross section curve is closed and planar (e.g. defined in the XY plane).

Since Ayam 1.10 bevels are available for birails. They are accessible through the new command entries `"Add Start Bevel!"` and `"Add End Bevel!"` respectively. If one of those entries is used, a bevel parameter tag is created and more options will be made available in the property GUI to adjust the bevel parameters or remove the tag again. A more thorough discussion of those options is available in section BevelAttr Property.

See section NPatchAttrib for a description of the other two attributes `"DisplayMode"` and `"Tolerance"`.

## 4.29 Skin Object

Skin Object (left: Curves, right: Resulting Skinned Surface)

The skin object forms a surface defined by a set of cross section curves, where the first and last curve will always be interpolated by the surface (this process is sometimes also called lofting). When only two parameter curves are used the skin forms a so called ruled surface.

The complete template for the Skin object hierarchy, consequently, looks like this:

    +-Skin
     | C1(NCurve)
     | C2(NCurve)
     | [...
     \ Cn(NCurve)]

Note that in contrast to the build from curves tool, the curves may be of arbitrary length and order. You may e.g. easily skin a curve of order 2 and length 6 with a second curve of order 4 and length 4 and a third curve with order 3 and 5 control points. If the curves are of different length or order, they will all be converted internally until they are compatible. Be warned, that this process may consume a considerable amount of time because all unclamped curves have to be converted to clamped ones; then, for every curve with low order degree elevation has to be done; then a uniform knot vector has to be found; then all curves have to be refined using this new knot vector; interpolation adds another dimension of complexity... If you experience lags when editing the child curves of a skin object try to switch to lazy notification. Since Ayam 1.9, a skin object will also use all the curves of a tool object, that provides multiple curves, e.g. a clone object in mirror mode.

The direction of the parameter curves will be parallel to the v dimension (height) of the skinned surface. The number of the parameter curves will define the u dimension (width) of the skinned surface.

Also note that the resulting patch may be quite complex, even though the curves are not, if the orders or knot vectors of the curves do not match. A skinned patch from two curves of length 4 but one with order 4 and the other with order 2 will result in a patch with a width of 2 and a height of 10!

The skin object has the generating NURBS curves as child objects and watches their changes and adapts to them automagically.

You may convert the current skin and the caps, if there are any, to ordinary NURBS patches using the main menu entry `"Tools/Convert"`.

The following parameters control the skinning process:

### SkinAttr Property

The first parameter `"Interpolation"` controls, whether the inner curves should also be interpolated by the skinning surface.

The second parameter `"Order_U"` determines the order of the resulting surface in u direction (the order in v direction is determined by the curves). The order may not be higher than the number of curves used. If the specified value is higher than the number of curves, the order of the generated surface will be silently set to the number of curves. If `"Order_U"` is 0, a default value of 4 will be used.

Using the next parameter `"Knot-Type_U"`, you can adapt the type of the knot vector that should be used in the u direction of the skinned surface. Note that this setting will have no effect if interpolation is switched on because then a chord length parameterisation will be used. If the knot type is Bezier and the specified order (see above) does not exactly match the number of skinned curves, then the order will be silently adapted to the number of skinned curves. New in Ayam 1.7 is support for the knot type Custom, which creates a chord length parameterisation, even if interpolation is not enabled.

The attributes `"StartCap"` and `"EndCap"` may be used to automatically create cap surfaces to close the skinned surface on both ends. Note that this works only if the respective curves are closed and planar (e.g. defined in the XY plane). Furthermore, if the skin is not interpolating the respective parameter curves (this may be the case if the `"Knot-Type_U"` parameter is set to `"B-Spline"`) the cap(s) will not be created in the right place. The cap(s) will always be created in the position of the first (last) parameter curve.

Since Ayam 1.10 bevels are available for birails. They are accessible through the new command entries `"Add Start Bevel!"` and `"Add End Bevel!"` respectively. If one of those entries is used, a bevel parameter tag is created and more options will be made available in the property GUI to adjust the bevel parameters or remove the tag again. A more thorough discussion of those options is available in section BevelAttr Property.

See section NPatchAttrib for a description of the other two attributes `"DisplayMode"` and `"Tolerance"`.

## 4.30 Gordon Object

Gordon Object (left: Curves, right: Resulting Gordon Surface)

The Gordon object forms a surface defined by two sets of intersecting curves (a network of curves), where all curves will always be interpolated by the surface (see image above). The image below shows the simplest configuration of such a network, consisting of four parameter curves. Note the order and the direction of the curves.

Gordon Surface with Parameter Curves (white)

The curves may be of arbitrary length and order. You may e.g. use a curve of order 2 and length 6 with a second curve of order 4 and length 4 and a third curve with order 3 and 5 control points for the u parametric dimension. Note, however, that only non-rational curves can be used as parameter curves for a Gordon surface. If the parameter curves are rational, the weight information of the curves will simply be ignored.

The Gordon object has the generating NURBS curves as child objects and watches their changes and adapts to them automagically. Separation of the two sets of curves has to be done using an empty level object. The first set of curves determines the u direction and the second set of curves the v direction of the Gordon surface. For the example surface in the image above, the child objects of the Gordon object would have to look like this in the Ayam object tree view:

    +-Gordon
     | U1(NCurve)
     | U2(NCurve)
     | Level
     | V1(NCurve)
     \ V2(NCurve)

The creation of a Gordon surface is computationally expensive. It involves (interpolated) skinning of the two sets of parameter curves, finding the intersection points of the two sets of parameter curves, interpolating the matrix of intersection points, making the three resulting surfaces compatible, and finally combining the three surfaces into the resulting Gordon surface. If you experience lags while editing the parameter curves of a Gordon surface, consider switching to lazy notification.

In order to ease the computationally intensive intersection detection for Ayam you may specify a third argument (separated from the two sets of parameter curves by a second empty level object). This third argument should be a NURBS patch object that describes all intersection points (by its control points). If present, this intersection patch always takes precedence over the intersection points calculated internally. You may want to add a `"NoExport"` tag to this patch. The object hierarchy of a Gordon object using such a patch, consequently looks like this:

    +-Gordon
     | U1(NCurve)
     | U2(NCurve)
     | Level
     | V1(NCurve)
     | V2(NCurve)
     | Level
     \ Intersections(NPatch)

The complete template for the Gordon object hierarchy, consequently, looks like this:

    +-Gordon
     | U1(NCurve)
     | U2(NCurve)
     | [...
     | Un(NCurve)]
     | Level
     | V1(NCurve)
     | V2(NCurve)
     | [...
     | Vn(NCurve)]
     | [Level
     \ Intersections(NPatch)]

The Gordon object watches the child objects and adapts to them automatically via the notification mechanism.

You may convert the current Gordon surface to an ordinary NURBS patch using the main menu entry `"Tools/Convert"`.

The following parameters of the Gordon object further control the creation of the Gordon surface:

### GordonAttr Property

If the parameter `"WatchCurves"` is switched on, Ayam will check for all four outer parameter curves, whether they touch in their endpoints. If not, the endpoints will be corrected. Note that this works only properly with clamped curves and objects that directly contain editable control points (i.e. it works with NCurve and ICurve objects, but not with Instance or ConcatNC objects). If Ayam can determine which curve was modified last, the other curve that should meet at the endpoint in question will be modified by `"WatchCurves"`. If Ayam finds no information on modifications, the U curves take precedence (i.e. the V curves will be modified).

The parameters `"Order_U"` and `"Order_V"` determine the desired order of the resulting surface in u and v direction. However, depending on the number and configuration of curves used in the u or v direction, it may not be possible to create a Gordon surface of the desired order. If `"Order_U"` or `"Order_V"` are 0, a default value of 4 will be used.

See section NPatchAttrib for a description of the other two attributes `"DisplayMode"` and `"Tolerance"`.

## 4.31 Bevel Object

Bevel Object (Curve, Resulting Bevelled Surface)

The bevel object forms a bevelled surface from a single parameter curve. Consequently, the template for the object hierarchy of a Bevel object looks like this:

    +-Bevel
     \-NCurve

Bevels are also available as properties of different tool objects (e.g. Extrude or Sweep). In fact, Bevel objects use the same creation algorithm as bevel properties but increase flexibility in terms of material settings. Surfaces created from bevel properties always share the material settings of the tool object. In contrast, Bevel objects may have their own material settings. Bevel objects are available in Ayam since version 1.10.

Note that the parameter curve should be closed and planar to achieve best results. If the curve is closed or periodic, the appropriate curve type should be set, otherwise the bevelled surface may expose defects.

The Bevel object watches the child object and adapts to it automatically via the notification mechanism.

You may convert the current bevelled surface to an ordinary NURBS patch object using the main menu entry `"Tools/Convert"`.

The following parameters of the Bevel object further control the creation of the bevelled surface:

### BevelAttr Property

- `"BevelType"` lets you choose between different shapes of bevels:
  - `"Round"` a quarter circle,
  - `"Linear"` a straight bevel,
  - `"Ridge"` a more complex ridged surface,
  - `"RoundCapped"` a quarter circle followed by a cap made by placing a single point in the center of the last bevel profile and extending the beveled surface to this point,
  - `"LinearCapped"` a straight bevel followed by a cap made by placing a single point in the center of the last bevel profile and extending the beveled surface to this point.
- `"BevelRadius"` controls the size of the bevelled surface when seen from the top of the parameter curve.
- `"BevelRevert"` allows to revert the sense of the bevelled surface, should it round inwards or outwards? The sense may also be controlled using the direction of the parameter curve and, additionally, the sense in a different dimension may also be affected by using negative values for the bevel radius.

See section NPatchAttrib for a description of the two attributes `"DisplayMode"` and `"Tolerance"` of the `"BevelAttr"` property.

Note that the bevel types `"RoundCapped"` and `"LinearCapped"` lead to degenerated NURBS surfaces. If applied shaders or textures look wrong, consider creation of real cap surfaces instead.

## 4.32 Cap Object

Cap Object (Curve, Resulting Cap Surface)

The cap object forms a surface that fills a closed planar NURBS curve. If multiple curves are present as child objects, the curves following the first curve define holes in the cap surface similar to the parameter curves of an extruded surface (see also section Using Holes and Bevels).

Consequently, the template for the object hierarchy of a Cap object looks like this:

    +-Cap
     | Outline(NCurve)
     | [Hole1(NCurve)]
     +-[Hole2(Level)
      | Part1(NCurve)
      \ Part2(NCurve)]

Note that the curves have to be planar and defined in the XY plane. Furthermore, cap generation may fail, if the control points of the first curve have weights and the curve leaves the convex hull of the control polygon. Be careful when using weights!

The Cap object watches the child objects and adapts to them automatically via the notification mechanism.

You may convert the current cap surface to an ordinary NURBS patch object using the main menu entry `"Tools/Convert"`.

### CapAttr Property

See section NPatchAttrib for a description of the two attributes `"DisplayMode"` and `"Tolerance"` of the `"CapAttr"` property.

## 4.33 ICurve Object

The ICurve object creates an interpolating spline curve from n points in space. The created curve is either a C2 cubic curve with n+2 control points or a global interpolating rational (Global4D) curve with n control points and with arbitrary order.

The global interpolation generates a bit smoother curves which look best with an order of 3, your mileage may vary however.

Different ICurves

The image above shows some interpolating curves, the left ones are C2 cubic, the right ones Global4D, the upper open, and the lower closed ones. The interpolation fidelity for the closed curves could be increased considerably by adjusting the `"IParam"` parameter, see below.

In both interpolation modes chord length parameterisation will be used to determine the knot vector of the interpolating curve.

This object makes use of the provide mechanism. It marks itself as providing a NURBCurve (it creates and uses NURBS curves internally anyway) and all other objects that work with the provide mechanism (e.g. revolve, sweep, extrude, and skin) are able to work with an ICurve object instead of an object of type NURBCurve.

You may convert the current ICurve to an ordinary NURBS curve using the main menu entry `"Tools/Convert"`.

The following parameters control the interpolation process:

### ICurveAttr Property

- Using `"Length"` you determine the number of points to interpolate.
- The curve can be closed with the parameter `"Closed"`.
- The parameter `"Mode"` determines whether the curve should be a C2 cubic curve (with n+2 control points (n+3 if the curve is closed)) or a so called global interpolating curve (with n control points (n+3 if the curve is closed) and arbitrary order).
- The next parameter `"Order"` is used only if the mode is Global4D. It determines the order of the interpolating curve. If the specified order is bigger than the number of control points used by the interpolating curve, then the order is silently changed to match the number of control points.
- The parameter `"IParam"` is used to control the position of the second and last-1 control point of the interpolating curve. It scales the vectors used to position the aforementioned points. You can try to change (decrease) this value, if you are not satisfied with the shape of the curve near the first or last interpolated point. This parameter has no effect on open curves when the mode is Global4D.
- See section NCurveAttrib for a description of the last attribute: `"Tolerance"`.

## 4.34 ConcatNC Object

ConcatNC Object from a Linear Curve and 3 Instances (white)

The ConcatNC object concatenates all child objects (which should be NURBS curves or provide NURBS curves) to a single NURBS curve. Since the ConcatNC object also provides a NURBS curve, it is possible to use it as child object for another ConcatNC object (with possibly different parameters) or as a parameter object for a tool object that works with NURBS curves such as Revolve or Extrude.

How does the concatenation process work? First, the orders of all child curves will be elevated to the maximum order of all the child curves (see section elevate tool for more information on elevation) and all curves will be clamped (see section clamp tool for more information on clamping). If `"FillGaps"` is enabled (see below), fillet curves will be created for every gap between the child curves of the ConcatNC object. If `"Closed"` and `"FillGaps"` are enabled an additional fillet is created to close the curve. Then, the control points of all child curves and fillets are simply copied into a new big control point vector, without checking for double points. Attributes like display mode and tolerance for the new concatenated curve are simply taken from the first child object. The knot sequence of the new concatenated curve will be of type `"NURBS"` or a custom knot vector will be computed (depending on the setting of `"Knot-Type"`). If `"Knot-Type"` is `"NURBS"`, the shape of the concatenated curve will differ from the child curves if any of the child curves has a custom knot vector with non equidistant knots. If `"Knot-Type"` is `"Custom"`, the shape of the child curves will be preserved.

You may convert the current ConcatNC object to an ordinary NURBS curve object using the main menu entry `"Tools/Convert"`.

The following parameters further control the concatenation process:

### ConcatNCAttr Property

- Using `"Closed"` you may create a closed concatenated curve. If `"FillGaps"` (below) is enabled, an additional fillet will be created for the last and the first child curve to close the concatenated curve. If `"FillGaps"` (below) is not enabled, the concatenated curve will be closed with the same algorithm that is also used by the close curve tool (possibly changing the shape again!).
- `"FillGaps"`, creates fillet curves for all gaps between the child curves of the ConcatNC object. The fillet curves will be cubic Bezier curves. The direction of the tangents in the endpoints of the fillets and the gap enclosing curves will match, so that the transition should be G1 continuous.
- `"Revert"` the orientation of the concatenated curve will be reversed.
- `"FTLength"` determines a scale factor for the tangent vectors of the fillets. A value of 1.0 leads to vectors that are as long as the matching vectors in the control point arrays of the original curves. A value of 0.3 is the default value. You may need to tweak this, if you experience discontinuities in the transitions between original curves and fillets, especially, if `"Knot-Type"` (see below) is set to `"Custom"`.
- `"Knot-Type"` in fact toggles between two different modes of concatenation. If `"Knot-Type"` is `"NURB"` a simple knot vector with equidistant knots is generated, which leads to a concatenated curve, that does not exactly preserve the shape of the original curves. If `"Knot-Type"` is `"Custom"`, the knot vector is composed from the knot vectors of the original curves, and thus, their shape may be preserved completely.

## 4.35 ExtrNC Object

The ExtrNC object extracts a NURBS curve from a NURBS patch object, for use as parameter object for other tool objects, like e.g. Revolve. It also works with NURBS patch providing objects, so that the following example hierarchy is valid:

    --NPatch
    +-Skin
     +-ExtrNC
     |\-Instance_of_NPatch(Instance)
     \-NCurve

Depending on the parameters of the ExtrNC object, the skin will have one boundary in common with a boundary or an iso-curve of the NPatch object.

The extraction process is controlled by the following attributes:

### ExtrNCAttr Property

- `"Side"` controls, which curve should be extracted. Available values are `"U0"`, `"Un"`: extract boundary curve along width; `"V0"`, `"Vn"`: extract boundary curve along height; `"U"`, `"V"` extract curve along width and height respectively at specified parametric value (see below). The options `"U"`, `"V"` are implemented since Ayam 1.8.1!
- `"Parameter"` controls the parametric value in u or v direction in the parameter space of the NURBS patch object where the curve should be extracted.
- `"PatchNum"` allows to select a patch from a list of patches delivered e.g. by a beveled extrude object as child of the ExtrNC object. This way it is possible to extract a curve from a bevel or cap surface.

See section NPatchAttrib for a description of the other two attributes `"DisplayMode"` and `"Tolerance"`.

## 4.36 Text Object

Text Object set in Verdana

Text objects may be used to easily create objects that form letters or even whole words in very high quality. For that, they parse TrueType font description files, extract the Bezier curves from the font description, sort the curves, connect them properly and finally extrude them. As with the Extrude objects, caps and bevels may be created automatically.

Parsing of TrueType font descriptions is quite tricky. For the sake of brevity and ease of the implementation, Ayam does not support elaborate TrueType features like kerning tables, that e.g. control distances between certain letters (You are not going to typeset a book with Ayam anyway, aren't you?). Therefore you might experience wrong letter distances from time to time. If this happens, just create a Text object for each letter, and arrange the objects as you like.

The following attributes control the creation of the text objects.

### TextAttr Property

- Using `"FontName"` you specify a TrueType font description file. Those files usually have the file name extension `".ttf"`. Only real TrueType font files, containing Bezier curve font descriptions, are supported. There are also rastered, bitmap containing TrueType font description files, those will not work.
- Using `"String"` you specify the letters to be created. This entry (and the corresponding data structures) are Unicode clean. This means you can put any Unicode letters into this entry. You should of course make sure, that the specified letters are included in the selected font file.
- `"Height"` controls the height of the extruded object.
- `"Revert"` reverts the sense of inside-outside detection mechanism for the cap generation. Depending on the actual font description file (or even letter) you may need to toggle this to get caps.
- `"UpperCap"`, `"LowerCap"`, work like for the Extrude object (see section ExtrudeAttr Property for a more exhaustive description of those parameters).
- `"Add Start Bevel!"`, `"Add End Bevel!"`: Since Ayam 1.10 the bevel parameters of the text object are saved in bevel parameter tags and the property GUI changed to conform to all other bevel supporting tool objects. The old options `"LowerBevel"`, `"UpperBevel"`, `"BevelType"`, `"BevelRadius"`, and `"RevertBevels"` are no longer available. They were replaced with new dynamic tag creating bevel property GUI sections that are accessible through the new command entries `"Add Start Bevel!"` and `"Add End Bevel!"` respectively. If one of those entries is used, a bevel parameter tag is created and more options will be made available in the property GUI to adjust the bevel parameters or remove the tag again. A more thorough discussion of those options is available in section BevelAttr Property.

  Just one note: for some fonts, the bevel radius has to be set to really small values (about 0.0008) to get proper bevels and caps. This is because of sharp corners in some letters that lead to self overlapping borders of the bevel surfaces with high values for the bevel radius.

See section NPatchAttrib for a description of the other two attributes `"DisplayMode"` and `"Tolerance"`.

## 4.37 RiInc Object

RiInc objects may be used to include objects or whole scene parts into your scenes that, for some reason, are just available as a piece of RIB.

The following attributes control the inclusion:

### RiIncAttr Property

- Using `"File"` you specify the filename of the RIB to be included.
- `"Width"`, `"Height"`, and `"Length"` specify the size of a box, that will be drawn as a geometric representation of the RIB.

## 4.38 RiProc Object

RiProc objects may be used to include procedural objects or external archives into your scenes.

The following attributes control the RiProc object:

### RiProcAttr Property

- `"Type"` defines the type of the procedural object which is one of `"DelayedReadArchive"`, `"RunProgram"`, or `"DynamicLoad"`.
- Using `"File"` you specify the filename of the RIB archive, program, or dynamic shared object (depending on the type of the procedural object).
- Using `"Data"` additional arguments may be supplied to procedural objects of type `"RunProgram"` and `"DynamicLoad"`.
- `"MinX"`, `"MaxX"`, `"MinY"`, `"MaxY"`, `"MinZ"`, and `"MaxZ"` specify the size of the bounding box of the objects that the procedural will create or the archive contains.

## 4.39 Script Object

Script objects are the most flexible object type of Ayam. They may be used to create new objects, modify existing objects, or realise mechanisms like constraints.

Theoretically, the scripts can use any functionality from Tcl and the Tcl scripting interface of Ayam (see also section The Tcl Scripting Interface). However, certain script object types may impose special constraints.

For security reasons, if scene files containing script objects are loaded, Ayam will raise a warning offering to temporarily disable all script objects that will be read.

The script of a script object will be run each time it is modified and each time the notification callback of the object is called (e.g. because one of the children of the script object changed). As long as the script of a script object is executed, Ayam will not process any events except for checking whether the script emergency hotkey `<Ctrl+Shift+c>`, that may also be used to escape from infinite loops in the Ayam console, is pressed. Calling commands and procedures that lead to the processing of events or that are slow because they manipulate or update the GUI of Ayam should be avoided. In particular, the following procedures and commands should not be used: uS, uCR, uCL, sL, selOb, plb_update, cutOb, copOb, delOb, undo.

Since Ayam 1.8.2 script objects may also create their own property GUIs for e.g. script parameters. This may be accomplished by adding tags of type `"NP"` with the name of the new property as value to the script object. The script itself is responsible for data management and property GUI creation. Since Ayam 1.9 the parameters set via the property GUI may be comfortably saved with scene files by just adding the following comment as first line to the script:

    # Ayam, save array: <arrayname>

where arrayname designates the name of the global Tcl array the property GUI elements operate with.

The binary and source distributions of Ayam contain several example scripts for script objects in the `"ayam/bin/scripts"` and `"ayam/src/scripts"` directories, respectively.

The next section discusses the available script object types and additional controlling parameters.

### ScriptAttr Property

- If `"Active"` is disabled, the script will not be run.
- `"Type"` is the type of the script object. Three types of script objects are currently available:
  - `"Run"`, the script will be run and no special action will take place.
  - `"Create"`, the script will be run and will create and parameterise a single new object. After running the script, the new created object will automatically be copied into the internal data structure of the script object. The script object will look like and act as an object of the type that the script created. If the script creates e.g. a NURBCurve object, the script object may be used as parameter object of a tool object that needs a NURBCurve, e.g. a Sweep:

        +-Sweep
         | Cross_Section(Script)
         \ Path(NCurve)

    The newly created object has to be selected by the script code for parameterisation and copying. The selection should be done using the new scripting interface command `"hSL"` (hidden select last). Consequently, the most simple example script for a script object of type `"Create"` looks like this:

        crtOb NCurve
        hSL

  - `"Modify"`, if the script object has child objects, these child objects will be copied into the internal data structure of the script object. A selection of the copied objects will be established, then the script will be run. Usually, the script modifies one of the selected objects (moves control points, adds tags, or does something similar). Note that the original child objects will not be modified. If certain actions in the script shall be restricted to one of the child objects of the script object, the `"withOb"` command may be used to accomplish this easily. The script object will look like and act as an object of the type of the first child object of the script object. If the script object has e.g. a NURBCurve object as first child, the script object may be used as parameter object of a tool object that needs a NURBCurve, e.g. a Sweep:

        +-Sweep
         +-Cross_Section(Script)
         | \ NCurve
         \ Path(NCurve)

  A simple example script for a script object of type `"Modify"` that needs a single NURBS curve as child object may look like this:

      revertNC

- `"Script"` is the script code. The widget is a standard Tcl text widget that allows to directly edit the code. It is also possible to edit the code in an external editor and copy it to the script object using the clipboard and the context menu entry `"Paste (Replace)"`.

## 4.40 Custom Objects

What is a custom object?

Custom objects are plugins that extend the Ayam capabilities by defining totally new types of e.g. geometric objects. This may be done easily, because the Ayam core is written in a modelling paradigm independent way.

A simple example of a custom object is the CSphere, which implements a simple sphere and has a new property named `"CSphereAttr"`. This property contains all parameters of a simple RenderMan Interface quadric sphere. A more complex example would be the MetaObj custom object. It is possible, but not planned for now, to integrate the T-Spline modelling paradigm into Ayam this way.

Since a custom object has total control over properties and representations, you should refer to the documentation of the custom object for more information regarding its properties.

## 4.41 Metaball Object

A Metaball Object from Six Meta Components

A metaball object is a custom object (see also section Custom Object). It allows you to model with implicit surfaces in realtime.

To start modelling you should first create a `"MetaObj"` object using the menu entry `"Create/Custom Object/MetaObj"` (if this menu entry is not available, you have to load the `"metaobj"` plugin using the menu entry `"File/Load Plugin"` first). `"Create/Custom Object/MetaObj"` creates a so called meta world with a single meta component (a sphere) in it. The meta world is represented by a `"MetaObj"` object and the component by a `"MetaComp"` object which is a child of the `"MetaObj"` object.

The complete template for the MetaObj object hierarchy, consequently, looks like this:

    +-MetaWorld(MetaObj)
     | C1(MetaComp)
     | [...
     \ Cn(MetaComp)]

Meta components live only in a meta world, therefore it makes no sense to create `"MetaComp"` objects in other places except as a child of a `"MetaObj"` object. Type, parameters, and transformation attributes of the meta components define the function of an implicit surface. The `"MetaObj"` object, that represents the meta world, evaluates this function on a regular three-dimensional grid and creates a polygonal representation for a specific function value (the so called threshold value).

This process may be further parameterized using the `"MetaObjAttr"` property:

### MetaObjAttr Property

- With the parameter `"NumSamples"` you specify the resolution of the three-dimensional regular grid, on which the implicit function is evaluated, in each dimension. A higher number of samples results in better quality but more polygons are created and more CPU power and memory are needed. For modelling you should set this to a lower value of about 40. For final rendering you may increase this to about 160.
- `"IsoLevel"`, defines the threshold value for that a polygonal representation of the implicit function should be created. Normally, you should not need to change this value.
- To show the actual bounds of the meta world, you may enable the `"ShowWorld"` parameter.

New in Ayam 1.5 is an adaptive calculation mode of the implicit surface. It may be switched on using the new attribute `"Adaptive"`. In the adaptive calculation mode, Ayam tries to vary the resolution of the resulting polygonal mesh according to the features of the implicit surface in order to capture fine details, even though a coarse grid is used. This is not done using a successively refined grid but by a refinement of the triangles created by the original algorithm (see also XXXX). You may control the adaptation process using three parameters: `"Flatness"`, `"Epsilon"`, and `"StepSize"`. If `"Adaptive"` is set to `"automatic"`, Ayam will not use the adaptive calculation while a modelling action is in progress. This mode has been introduced, because the adaptive mode may consume a considerable amount of CPU ressources.

While modelling with meta balls you may add other `"MetaComp"` objects to the `"MetaObj"` object and parameterize them. A `"MetaComp"` object has the following properties.

### MetaCompAttr Property

- `"Formula"` specifies the type of the meta component. The following types are available: Metaball, Torus, Cube, Heart, and Custom. The latter gives you the possibility to use your own formulas.
- With the parameter `"Negative"` you define a component with a negative effect on the implicit function value. Negative components are not visible on their own but they are useful for modelling holes. Just try it.

The other parameter are specific to the type of the component:

### Metaball

- `"Radius"` sets the radius of the metaball
- `"EnergyCoeffA"`, `"EnergyCoeffB"`, and `"EnergyCoeffC"` are some parameters for the metaball formula. Usually you can leave those parameters at their default values. If you change them, be careful.

### Torus

- `"Ri"` the inner radius of the torus
- `"Ro"` the outer radius if the torus
- `"Rotate"` rotates the torus about 90 degree

### Cube

- `"EdgeX"`, `"EdgeY"`, and `"EdgeZ"`, let you define the sharpness of the edges of the cube

### Custom

- `"Expression"` is a piece of Tcl script, that represents your own custom formula for a meta component. The expression may call any Tcl commands to calculate a field value from the current grid position, which is given in the global variables `"x"`, `"y"`, and `"z"`. The expression has to return the field value in the global variable `"f"`. Here is an example for a custom expression:

      set f [expr {pow($x,4)+pow($y,4)+pow($z,4)}]

  Note that those expressions are called many times and since they are programmed in Tcl, this can be quite slow. You should use any tricks (like the curly braces in the expr-statement above) to speed up the expression.

Next Previous Contents