Next Previous Contents

4. Objects, Properties, and Tags

This section informs 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.

Note that the "Help on object" and "Help on property" main menu entries in Ayam can be used to directly jump to the appropriate sub-section of this part of the documentation.

Documentation on the standard properties (Transformations, Attributes, Material, Shader, and Tags) can be found in section Standard Properties.

Furthermore, this section contains information about all tag types, see section Tags.

In the next sections general object capabilities will be briefly documented in tables like this:

TypeParent ofMaterialConverts to / ProvidesPoint Edit
Object TypeNo / Object Type+/∗Yes/NoN/A / Children / Object Type+/∗Yes/No*

Object Capabilities Template

The capabilities are:

Example:

TypeParent ofMaterialConverts to / ProvidesPoint Edit
RevolveNCurveYesNPatch+No*

Object Capabilities Example

Explanation:

4.1 Object Types Overview

This section provides an overview on the object types available in Ayam (since there are so many). The object types are grouped by application in the following sections.

 

Scene Organization

These objects help to organize/structure the scene; view, camera, light, and material objects are also listed here (even though deserving an own section each):

TypeParent ofMaterialConverts to / ProvidesPoint Edit
RootView+NoN/ANo
LevelAny+YesN/A / Children+No
CloneAny+NoChildren+No*
MirrorAny+NoChildren+No*
InstanceNoNoMasterNo*
SelectAny+NoN/A / Children+No
RiIncNoNoN/ANo
RiProcNoNoN/ANo
ViewNPatchNoN/AYes
CameraNoNoN/AYes
LightNoNoN/AYes
MaterialNoN/AN/ANo

Scene Organization

 

CSG / Solid Primitives

These objects serve as geometric primitives in CSG hierarchies:

TypeParent ofMaterialConverts to / ProvidesPoint Edit
BoxNoYesNPatchNo*
SphereNoYesNPatch+No*
DiskNoYesNPatchNo*
ConeNoYesNPatch+No*
CylinderNoYesNPatch+No*
TorusNoYesNPatch+No*
ParaboloidNoYesNPatch+No*
HyperboloidNoYesNPatch+No*

CSG / Solid Primitives

 

Freeform Curves

These objects are mainly used as child objects for the surface generating tool objects:

TypeParent ofMaterialConverts to / ProvidesPoint Edit
NCurveNoNoN/AYes
ICurveNoNoNCurveYes
ACurveNoNoNCurveYes
NCircleNoNoNCurveNo*

Freeform Curves

 

Freeform Surfaces

These objects enable direct manipulation of freeform surfaces:

TypeParent ofMaterialConverts to / ProvidesPoint Edit
NPatchNCurve+/ Level+YesPolyMeshYes
IPatchNoYesNPatchYes
BPatchNoYesNPatchYes
PatchMeshNoYesNPatchYes

Freeform Surfaces

 

Curve Tool Objects

These objects modify existing curves or create new curves:

TypeParent ofMaterialConverts to / ProvidesPoint Edit
ConcatNCNCurve+NoNCurveNo*
ExtrNCNPatchNoNCurveNo*
OffsetNCNCurveNoNCurveNo*

Curve Tool Objects

 

Surface Tool Objects

These objects create freeform surfaces from curves or other surfaces:

TypeParent ofMaterialConverts to / ProvidesPoint Edit
RevolveNCurveYesNPatch+No*
ExtrudeNCurve+YesNPatch+No*
SwingNCurveYesNPatch+No*
SweepNCurveYesNPatch+No*
Birail1NCurveYesNPatch+No*
Birail2NCurveYesNPatch+No*
SkinNCurveYesNPatch+No*
GordonNCurve/ Level / NPatchYesNPatch+No*
BevelNCurve+YesNPatchNo*
CapNCurve+YesNPatchNo*
TextNoYesNPatch+No*
TrimNPatch / NCurve+/ Level+YesNPatchNo*
ConcatNPNPatch/ NCurveYesNPatchNo*
ExtrNPNPatchYesNPatchNo*
OffsetNPNPatchYesNPatchNo*

Surface Tool Objects

 

Polygonal and Subdivision Objects

These objects complement the Ayam feature set and allow objects modelled in the polygonal or subdivision modelling paradigms to be included in Ayam scenes:

TypeParent ofMaterialConverts to / ProvidesPoint Edit
PolyMeshNoYesSDMeshYes
SDMeshNoYesPolyMeshYes

Polygonal and Subdivision Objects

 

Scripts and Plugins

These objects create/modify arbitrary other objects from scripts or define entirely new object types via the custom object plugin mechanism.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
ScriptAny+NoAnyNo*
MetaObjMetaComp+YesPolyMeshNo
MetaCompNoNoN/ANo
SDNPatchNoYesPolyMeshYes
SfCurveNoNoNCurveNo*

Scripts and Plugins

4.2 Scene Organization Objects

These objects help to organize/structure the scene; view, camera, light, and material objects are also listed here (even though deserving an own section each).

 

Root Object

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

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

The Root object also aids in per-scene window geometry management using SaveMainGeom and SavePaneLayout tags (see also sections SaveMainGeom and SavePaneLayout).

The following table briefly lists some capabilities of the Root object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
RootView+NoN/ANo

Root Object Capabilities

The global scene rendering options are documented in the following sections.

RiOptions Property

This 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:

Renderer specific options may also be set with RiOption tags (see section RiOption Tag), most comfortably added via the main menu "Special/Tags/Add RiOption" (see section Tags Special Menu).

Imager, Atmosphere Property

The Imager and Atmosphere properties let you define shaders for the Root object, please refer to section Shader 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.

RIB Export

The Root object appears in RIB output in different places as collection of RenderMan Interface options and imager as well as atmosphere shaders.

The exact RIB statements used depend on the configuration of the object and the preference setting "RIB-Export/RIStandard".

The Root object is the only object to support RiOptions, RiHider, and RiDisplay tags (see also section Tags.

 

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 modelling actions in a view are limited to that input plane (unless the view is switched to local modelling; see also section Editing in Local Spaces).[*]

The standard input planes are as following: Front – XY-plane, Side – ZY-plane, Top – XZ-plane, Trim – XY-plane.

In perspective views no interactive modelling actions are possible, but the camera may be modified, objects can be picked, and points selected.

Views of type "Trim" are used to edit trim curves of NPatch objects only. They display those trim curves as normal NURBS curves when the current level is inside a NPatch. The extensions of the patch in parameter-space are also drawn as a dashed rectangle. The trim curves should completely lie inside this rectangle. Note that picking of objects currently does not work in views of type "Trim".

The following table briefly lists some capabilities of the View object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
ViewNPatchNoN/AYes

View Object Capabilities

The next sections detail the properties of the view object.

Camera Property

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

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:

Drag and Drop Support

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, 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, the views camera will be changed, so that the user looks along the light to see what objects of the scene are lit by the light object (this works best with perspective views that have equal width and height).

It is also possible, to directly drag arbitrary 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 as if the object was dropped onto a View object in the tree view (see the above description).[*]

 

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.

The following table briefly lists some capabilities of the Camera object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
CameraNoNoN/AYes

Camera Object Capabilities

Drag and Drop Support

When a View object is dropped onto a Camera object the camera settings from the view will be copied to the Camera object.

RIB Export

Camera objects never appear in RIB output.

 

Light Object

Lightsource Examples (l: Distant, m: Point, r: Spot)

Light objects represent light sources.

There are currently four different light types available in Ayam: "Point", "Distant", "Spot", and "Custom" (see also the image above).

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 these standard light sources (see section References).

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 light source. Those names should not be used for other things in the light shaders.

In contrast to the light sources as defined in the RenderMan interface, Ayam light sources are always global by default. This means, regardless of the place of a light source in the scene hierarchy, it will always light all other objects (unless the "IsLocal" attribute is used).

Note that the effect of a light source can not be previewed in shaded Ayam views, currently. However it is possible to estimate the effect of a spot light source by simply dropping it into a perspective view window; the view will then adapt the camera attributes (from, to, and zoom) of the view to show the objects lit by the spot.

The following table briefly lists some capabilities of the Light object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
LightYesNoN/AYes

Light Object Capabilities

LightAttr Property

The parameter "Type" determines the type of the light source.
Depending on the type of the light source, the light attribute property contains different sets of parameters. Parameters that are not displayed will not be used on RIB export, consequently. When the type of a light source is changed, the property GUI will be adapted to show only the options available for the new light source type. Note that this adaptation happens when the "Apply"-button is used.

"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 it) or all objects in the scene. The default is off, all objects in the scene are lit. The "IsLocal" attribute is ignored for lights that are defined in the root level of the scene. Mind also that shadow maps will always contain shadows from all objects in the scene, regardless of the "IsLocal" attribute of the light source.

Using the light attribute "Shadows" you may determine whether the light source should cast shadows. The default is off, no shadows. Note that this option will not magically enable shadows on renderers that create shadows by shadow maps. It will merely be interpreted by raytracing renderers like BMRT.

The parameter "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 the attribute "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:

In order to ease the parameterisation of spot lights, the light source object may be dropped onto a view object or into a view window (preferably one with a perspective viewing transformation and with equal width and height) to see what objects of the scene are actually lit 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.

Automatic Creation of ShadowMaps

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 upon rendering. 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 also be rendered separately if the frame number is known. To help picking the right frame number for the image (e.g. to re-render just the final image, when only a material setting was changed, and no shadow casting lights were moved and no shadow casting geometry was changed), 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 the exported scene may be moved from one system to another more easily.

Do not render directly from a view window to the display when the "ShadowMaps" "RIB-Export" preference option is set to "Automatic". Your renderer may 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. Consequently, this may also inhibit writing of the shadow maps, so that the resulting image will look wrong, or the renderer will render the shadow map to the display and simply stop.

Manual Creation of ShadowMaps

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. They can be created manually (hence the name "Manual") using the view menu entries "View/Create ShadowMap", "View/Create All ShadowMaps" or the main menu entries "Special/RIB-Export/Create ShadowMap", "Special/RIB-Export/Create All ShadowMaps". The manual approach has the advantage, that the shadow maps will not be re-created each time the scene is rendered.

ShadowMap Types

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 parameterised 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 parameterising it accordingly. See the discussion above for the names of the shadow map files. Those file names, most 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 the normal "distantlight" shader attached, even though Ayam is able to create the necessary shadow maps. The normal "distantlight" shader just makes no use of the shadow maps. You have to manually switch to a shader that makes use of the shadow maps ("shadowdistant" in this case) to actually get shadows.

ShadowMap Mini Tutorial

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", see also the following image from that scene that was created with an additional point light and Aqsis as renderer:

Shadowmaps Example

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. Please consult the documentation of your renderer on how to achieve the best results using shadow maps.

Using Area Lights

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 natural. Good looking soft shadows may be generated using area lights. See also the image below.

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, i.e. the scene hierarchy looks like this:

+-AreaLight(Light)
 \ AreaLightGeometry(Sphere)
This child object determines the geometry (place and extension) of the light source. According to L. Gritz, Spheres and Cylinders work best as area light geometry for BMRT, because of special sampling code.

An example:

There is an example scene named "arealight.ay" distributed with Ayam, see also the following images from that scene that were created with BMRT 2.6 as renderer:

Area Light (l) and Point Light (r)

 

Material Object

Material objects are used to attach RenderMan attributes and shaders to geometric objects.

As long as geometric objects are connected to a material object, this material object may not be deleted.

The following table briefly lists some capabilities of the Material object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
MaterialNoN/AN/ANo

Material Object Capabilities

RiAttributes Property

Using this property standard and BMRT specific RenderMan 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.

Surface, Displacement, Interior, Exterior Property

These properties let you define shaders for the material object, please refer to section Shader 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:

Drag and Drop Support

When geometric objects are dropped onto a material object they will be connected to this material object.

RIB Export

Material objects only appear in RIB output if connected to a geometric object (e.g. a Box).

The exact RIB statements used depend on the configuration of the material and the preference setting "RIB-Export/RIStandard".

If all elements of the MaterialAttr property are left on their default values, only color and opacity will be written to the RIB:

RiColor(...);
RiOpacity(...);
After the elements of the MaterialAttr property, the surface, displacement, interior, and exterior shaders (if attached to the material) will be exported, all shader parameters will be properly declared:
RiDeclare("Ka", "float");
...
RiSurface("Ka", 0.9, ...);
...
After the material description custom RiAttributes and texture coordinates from tags will be exported.

No attempt is being made to re-order or sort objects in a level according to their attached materials, they will rather be exported in the order of their appearance in the level and thus each object with a material will also be prepended by a full material specification as described above.

 

Level Object

Level objects may be used to build object hierarchies and perform CSG operations.

Ayam does not offer a layer concept, but by grouping objects using levels and the hide/show tools, layer functionality may be emulated to a certain extent.

Organizing the scene and working in levels also increases the speed of object tree updates, as only the current level and its sub-levels are subject to a tree update if something in the object hierarchy changes.

Note that child objects of a level inherit the levels transformations, material, 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 by setting a corresponding value in the Transformations property of the patch object, the local coordinate system of the patch will be placed at (15,0,0) in world coordinates, i.e. the control point (1,0,0) will be at (16,0,0).

Note also that since Ayam 1.12, Level objects provide their child objects to their parent objects as a list. This means the following hierarchy is now valid:

+-Skin
 +-Level
  | NCurve
  | NCurve
  | ICurve
  \ NCurve
All NURBS curves and objects that may be converted to NURBS curves (in this example: the ICurve) will be provided to the Skin by the Level object. Transformation attributes of the Level will be added to the provided objects. Objects that do not provide the wanted type will be silently ignored.

The following table briefly lists some capabilities of the Level object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
LevelAny+YesN/A / Children+No

Level Object Capabilities

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 would cut parts away.

However, since Ayam 1.8 there is a plugin available that is able to preview the results of CSG operations, see also section CSG preview using the AyCSG plugin.

The object hierarchy to cut away a part of a box using a sphere looks like this:

+-Level_of_Type_Difference(Level)
 | Box
 \ Sphere
More than two objects may be arguments of a CSG operation:
+-Level_of_Type_Difference(Level)
 | Box
 | Sphere
 \ Sphere
In this example, the two spheres would cut away parts of the box.

New solid primitives may be created with levels of type "Primitive".

+-Level_of_Type_Difference(Level)
 +-Level_of_Type_Primitive(Level)
 | | Sphere_blue
 | \ Disk_red
 \ Box_grey
In this example an open sphere with "ThetaMax" 180.0 (a hemisphere) is manually capped by a disk object. The two objects need to be placed into a level of type "Primitive" because each object alone is an open surface and therefore not a valid CSG primitive. Both objects that form the new primitive use a different material. In addition, a grey box cuts away a part from the multi colored hemisphere. The above CSG hierarchy is available as example scene file "multicolcsg.ay".

See also this image:

Multicolor CSG Example

Note that Ayam is not able to check, whether your new primitive obeys the rule of total closeness. For instance, if the disk in the above example would not totally cap the sphere (this happens if the disk "ThetaMax" is not 360.0 or if it is not placed exactly at the sphere) Ayam would not complain upon RIB export. The rendered image would expose serious errors, however.

Furthermore, it is not necessary to enclose normal child objects (e.g. quadrics with the "Closed" attribute set to on) of CSG levels in primitive levels for RIB export. This is done by Ayam automatically where needed.

RIB Export

The exact representation of a Level in RIB output depends on its type.

Normal Level objects appear in RIB output as Transformation hierarchies:

RiTransformBegin();
RiTranslate(...);
RiRotate(...);
RiScale(...);

«Children RIB output»

RiTransformEnd();

Level objects of type Union, Difference, or Intersection will additionally emit a call to SolidBegin, and each child will be properly declared as primitive, e.g.:

RiTransformBegin();
«Level Transformations»
RiSolidBegin(RI_DIFFERENCE);

RiSolidBegin(RI_PRIMITIVE);
«Child #1 RIB output»
RiSolidEnd();

RiSolidBegin(RI_PRIMITIVE);
«Child #2 RIB output»
RiSolidEnd();

RiSolidEnd();
RiTransformEnd();

 

Clone Object

Clone Object (blue) with Trajectory Curve (white)

The Clone object allows to easily create and control an arbitrary number of instances of a single object, hereafter called the cloned object. The instances can be transformed (each by a certain amount expressed as difference between two instances) or placed on a trajectory curve (see also the image above).

If a second object is present as child of the Clone object it is treated as trajectory (or path) curve automatically. The process of placing the clones on the trajectory is very similar to the sweeping operation (see also section Sweep Object).

Thus, the default object hierarchy of a Clone object looks like this:

+-Clone
 | Cloned-Object
 \ [Trajectory(NCurve)]
If you use a trajectory curve to place the clones, you may want to hide the cloned object and also add a "NoExport" tag to it. Otherwise the original object will appear twice, on the trajectory and on its normal, untransformed, position. Note that the transformation attributes of the cloned object will be completely overwritten when placing the clones on the trajectory curve. If the cloned object has distinct scale or rotation attributes it should be put 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. it is not possible to clone 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 cloned object on a trajectory it can be placed in a level and the "NoExport" tag can be added to the level object (as adding tags to Instance objects is more involved), see the following hierarchy for an example:

+-Clone
 +-Level with NoExport tag
 |\ Instance
 \ Trajectory(NCurve)

Since Ayam 1.20 the mirror facility of the Clone object is realized through the new Mirror object (see also section Mirror Object). The mirror facility was integrated into the Clone object before.

The following table briefly lists some capabilities of the Clone object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
CloneAny+NoChildren+No*

Clone Object Capabilities

CloneAttr Property

The following attributes control the cloning process:

The following table summarizes which transformation attributes are used in the respective clone modes.

ModeUse Child TransformUse CloneAttrib TransformUse Clone Transform
CloneNoYesYes
TrajectoryYesYesYes
MirrorYesN/AYes

Clone Parameterisation Examples

Conversion Support

The Clone object may be converted to ordinary objects using the main menu entry "Tools/Convert".

Upon conversion a Level object will be created, that contains the original object and the clones.

RIB Export

Clone objects appear in RIB output as a number of real objects, each with different transformation attributes.

As the original objects will also appear in the RIB output, it is suggested to add a "NoExport" tag to the original if the Clone is in trajectory mode.

 

Mirror Object

Mirrored Object (blue) From Curve (white)

The Mirror object allows to easily create and control an arbitrary number of mirrored instances of a number of objects.[*]

The original object(s) and their mirrored counterparts will be provided by the Mirror object to the respective parent object (normally, tool objects do not provide their unmodified children). Additionally, the order of the mirrored objects will be reversed so that it is possible to use a single Mirror object (with one or multiple NURBS curves as children) as parameter object of e.g. a Skin object:

+-Skin
 +-Mirror
  \ NCurve
+-Skin
 +-Mirror
  | NCurve_1(NCurve)
  | NCurve_2(NCurve)
  \ NCurve_3(NCurve)
The first Skin object in the above example can only work, because also the unmodified NCurve is provided by the Mirror object. The second Skin object can only work properly, because the order of the provided objects is reversed, so that it gets to see the curves in the following sequence: "NCurve_1", "NCurve_2", "NCurve_3", "Mirrored_NCurve_3", "Mirrored_NCurve_2", "Mirrored_NCurve_1".

The following table briefly lists some capabilities of the Mirror object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
MirrorAny+NoChildren+No*

Mirror Object Capabilities

MirrorAttr Property

The following attributes control the mirror process:

Conversion Support

The Mirror object may be converted to ordinary objects using the main menu entry "Tools/Convert".

Upon conversion a Level object will be created, that contains the original objects and the mirrored counterparts (the latter in reverse order).

RIB Export

Mirror objects appear in RIB output as a number of real objects, each with different transformation attributes.

 

Instance Object

Instance objects help to save memory consumption in scenes with many similar or repeating objects or transport geometric data across the scene hierarchy.

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 (here also called master object). A link can be placed anywhere on the file system, an instance object can be placed anywhere in the scene hierarchy, and additionally, it can be transformed.

Normally, the sole purpose of instance objects is to save space, in memory and on the disk. But in the tool object context, instances also serve as a means to transport geometric data across the scene hierarchy to make tool objects depend on each other (see also section The Modelling Concept Tool-Objects). Note that in the tool object context, instance objects are the only objects, that are subject to a second round of provision.

The amount of saved space can be very high, depending heavily on the actual scene and at what levels in the hierarchy instances are used. If there are no similar objects in the scene, however, instancing can hardly be utilised. Similar means "the same except for the transformation property" in this context.

Some simple rules for instancing:

If deleting of an object fails, and the error message complains about the reference counter not being zero, then the last rule was about to be violated. Clean the clipboard using the menu "Special/Clipboard/Paste (Move)" and delete or resolve all references first.

Ayam can also create instances for complete scenes 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".

The following table briefly lists some capabilities of the Instance object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
InstanceNoNoMasterNo*

Instance Object Capabilities

Instances without Transformations (References)

Instance objects support the "RP" tag type in a special way: if the "Transformations" property is removed using a "RP" tag, the instance does not provide objects with an own set of transformation attributes (to ease hierarchy building with e.g. "ExtrNC"/"ExtrNP" objects, where only pointers to already existing objects are required and where it is expected, that the instance reflects the master exactly, including its transformation attributes).[*]

The extract curve/surface tools automatically add such a tag to the instances they create.

To create such a tag manually, select the Instance object and enter into the Ayam console:

» addTag RP Transformations

This special case of an instance is sometimes also called reference.

Instances and the Object Clipboard

This section contains additional information on instances and what happens to them when copied and pasted using the object clipboard.

All copies of instance objects, that are created by the object clipboard, always point to the same original master object. Therefore, 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.

For example, when the following two objects are copied and pasted back to the scene

--NCurve   <-----.
                 |
--Instance  -----'
the following scene hierarchy results:
--NCurve   <-----+-.
                 | |
--Instance  -----' |
                   | !
--NCurve           |
                   |
--Instance  -------'
The new instance still points to the original master and not to the copy of the master.

It is possible to move masters and instances through the scene hierarchy using drag and drop in the tree view or using the object clipboard with "Edit/Cut" and then "Special/Clipboard/Paste (Move)" however.

Conversion Support

An Instance object may be converted to an ordinary object using the main menu entry "Tools/Convert". This process is also called resolving the instance.

To resolve all instance objects in a scene to normal objects, also the main menu entry: "Special/Instances/Resolve all Instances" can be used.

RIB Export

The RIB export of instances does not use the RiInstance facility of the RenderMan interface, but rather the more flexible ReadArchive mechanism.

This means, every master 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 when rendering the RIB file. The resulting RIB file is not self contained: multiple files need to be transferred to other systems when rendering shall occur there.

This behaviour can be changed using the RIB export preference setting "ResInstances": If "ResInstances" is enabled, all instances will be resolved temporarily to normal objects before being exported to RIB. The resulting RIB file will then be self contained but probably also much larger.

 

Select Object

The Select object may be used in hierarchies of tool objects to select one object from a list of provided objects.[*]
Also multiple objects and ranges (even decreasing ranges that lead to reversed orders) may be selected.[*]

In the following example hierarchy, a single patch from multiple provided patches of the Sweep object (the swept surface, a bevel, or a cap) could be selected by the Select object and delivered upstream to the ExtrNC object.

+-Sweep
+-Revolve
 +-ExtrNC
  +-Select
   \ Instance_of_Sweep(Instance)
Note that this example just serves illustrative purpose; the hierarchy presented is not exactly useful, as the ExtrNC object has a selector facility built in. Consequently, the Select object should be used in scenarios, where a selector facility does not exist or is hard to implement, as e.g. in Script object scripts.

The following table briefly lists some capabilities of the Select object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
SelectAny+NoN/A / Children+No

Select Object Capabilities

SelectAttrib Property

The following attribute controls the selection process:

RIB Export

Select objects never appear in RIB output.

 

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 table briefly lists some capabilities of the RiInc object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
RiIncNoNoN/ANo

RiInc Object Capabilities

RiIncAttr Property

The following attributes control the inclusion process:

RIB Export

RiInc objects export as single

ReadArchive

 

RiProc Object

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

The following table briefly lists some capabilities of the RiProc object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
RiProcNoNoN/ANo

RiProc Object Capabilities

RiProcAttr Property

The following attributes control the RiProc object:

RIB Export

RiProc objects export as single

RiProcedural(...);

4.3 CSG / Solid Primitives

These objects serve as geometric primitives in CSG hierarchies.

 

Box Object

A solid box, centered at the origin of the object coordinate system.

The following table briefly lists some capabilities of the Box object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
BoxNoYesNPatchNo*

Box Object Capabilities

BoxAttrib Property

The following parameters control the shape of the box:

Conversion Support

A box object may be converted to three NURBS patches using the main menu entry "Tools/Convert".[*]

See section Cylindrical Box for a Script object that converts to a single NURBS patch.

RIB Export

The box object will always be exported as six bilinear patches.

 

Sphere Object

A sphere, centered at the origin of the object coordinate system.

The following table briefly lists some capabilities of the Sphere object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
SphereNoYesNPatch+No*

Sphere Object Capabilities

SphereAttr Property

The following parameters control the shape of the sphere:

Conversion Support

A Sphere object may be converted to NURBS patches using the main menu entry "Tools/Convert". This conversion obeys all parameters of the sphere.[*]

If the sphere is closed, an enclosing Level object will be created and the caps follow the sphere in the following order: disk-shaped cap at zmin, disk-shaped cap at zmax, cap at theta 0, cap at thetamax.

RIB Export

The Sphere object appears in RIB output as simple

RiSphere(...);
or, if "Closed" is enabled and "ZMin", "ZMax", or "ThetaMax" have other than the default values, as complex CSG hierarchy of at most two spheres, two cylinders, and eight disks.

 

Disk Object

A disk in the XY-plane, centered at the origin of the object coordinate system.

The following table briefly lists some capabilities of the Disk object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
DiskNoYesNPatchNo*

Disk Object Capabilities

DiskAttr Property

The following parameters control the shape of the disk:

Conversion Support

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.[*]

RIB Export

The Disk object will always be exported as simple disk:

RiDisk(...);

 

Cone Object

A cone, centered at the origin of the object coordinate system, with the base in the XY-plane.

The standard cone is always pointed. See section Truncated Cone for a Script object that implements a truncated cone.

The following table briefly lists some capabilities of the Cone object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
ConeNoYesNPatch+No*

Cone Object Capabilities

ConeAttr Property

The following parameters control the shape of the cone:

Conversion Support

A Cone object may be converted to NURBS patches using the main menu entry "Tools/Convert". This conversion obeys all parameters of the cone.[*]

If the cone is closed, an enclosing Level object will be created and the caps follow the cone in the following order: disk-shaped cap at the base, cap at theta 0, cap at thetamax.

RIB Export

The Cone object appears in RIB output as simple

RiCone(...);
or, if "Closed" is enabled and "ThetaMax" has a different than the default value, as complex CSG hierarchy of at most one cone, one disk, and two polygons.

 

Cylinder Object

A cylinder, centered at the origin of the object coordinate system.

The following table briefly lists some capabilities of the Cylinder object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
CylinderNoYesNPatch+No*

Cylinder Object Capabilities

CylinderAttr Property

The following parameters control the shape of the cylinder:

Conversion Support

A cylinder object may be converted to NURBS patches using the main menu entry "Tools/Convert". This conversion obeys all parameters of the cylinder.[*]

If the cylinder is closed, an enclosing Level object will be created and the caps follow the cylinder in the following order: disk-shaped cap at zmin, disk-shaped cap at zmax, cap at theta 0, cap at thetamax.

RIB Export

The cylinder object appears in RIB output as simple

RiCylinder(...);
or, if "Closed" is enabled and "ThetaMax" has a different than the default value, as complex CSG hierarchy of at most one cylinder, two disks, and two polygons.

 

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.

The following table briefly lists some capabilities of the Torus object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
TorusNoYesNPatch+No*

Torus Object Capabilities

TorusAttr Property

The following parameters control the shape of the torus:

Conversion Support

A torus object may be converted to NURBS patches using the main menu entry "Tools/Convert". This conversion obeys all parameters of the torus.[*]

If the torus is closed, an enclosing Level object will be created and the caps follow the torus in the following order: disk-shaped cap at theta 0, disk-shaped cap at thetamax, ring-shaped cap at phimin 0, ring-shaped cap at phimax.

RIB Export

The torus object appears in RIB output as simple

RiTorus(...);
or, if "Closed" is enabled and "PhiMin", "PhiMax", or "ThetaMax" have different than the default values, as complex CSG hierarchy of at most one one torus, two disks, and two hyperboloids.

 

Paraboloid Object

A paraboloid, centered at the origin of the object coordinate system.

The following table briefly lists some capabilities of the Paraboloid object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
ParaboloidNoYesNPatch+No*

Paraboloid Object Capabilities

ParaboloidAttr Property

The following parameters control the shape of the paraboloid:

Conversion Support

A paraboloid object may be converted to NURBS patches using the main menu entry "Tools/Convert". This conversion obeys all parameters of the paraboloid.[*]

If the paraboloid is closed, an enclosing Level object will be created and the caps follow the paraboloid in the following order: disk-shaped cap at zmin, disk-shaped cap at zmax, cap at theta 0, cap at thetamax.

RIB Export

The paraboloid object appears in RIB output as simple

RiParaboloid(...);
or, if "Closed" is enabled and "ZMin", "ZMax", or "ThetaMax" have different than the default values, as complex CSG hierarchy of at most one paraboloid, two disks, and two bicubic patches.

 

Hyperboloid Object

A hyperboloid, centered at the origin of the object coordinate system. The shape of the hyperboloid will be created by sweeping a line specified by two points in space around the Z-axis. Thus, disk, cylinder, and cone are special cases of the hyperboloid.

The following table briefly lists some capabilities of the Hyperboloid object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
HyperboloidNoYesNPatch+No*

Hyperboloid Object Capabilities

HyperboloidAttr Property

The following parameters control the shape of the hyperboloid:

Conversion Support

A hyperboloid object may be converted to NURBS patches using the main menu entry "Tools/Convert". This conversion obeys all parameters of the hyperboloid.[*]

If the hyperboloid is closed, an enclosing Level object will be created and the caps follow the hyperboloid in the following order: disk-shaped cap at P1, disk-shaped cap at P2, non-planar cap at theta 0, non-planar cap at thetamax.

RIB Export

The hyperboloid object appears in RIB output as simple

RiHyperboloid(...);
or, if "Closed" is enabled and "ThetaMax" has a different than the default value, as complex CSG hierarchy of at most one hyperboloid, two disks, and two bilinear patches.

Note that due to a bug in BMRT that is still present in V2.3.6 the "Closed" 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).

4.4 Freeform Curve Objects

These objects are mainly used as child objects for the surface generating tool objects.

 

NCurve (NURBS Curve) Object

A simple NURBS Curve

The NCurve object is the most used basic object for NURBS modelling in Ayam because NURBS curves are used to build more complex smoothly shaped surfaces using operations like extrude, revolve, sweep or skin. NURBS curves can be open or closed and used to emulate Bezier and B-Spline curves easily. In addition, for easier modelling, they support multiple points, as explained in section Multiple Points.

The following table briefly lists some capabilities of the NCurve object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
NCurveNoNoN/AYes

NCurve Object Capabilities

NCurve objects may be created via the toolbox, the main menu, several tools as documented in section Curve Creation Tools, or the scripting interface, see also section Creating Objects.

Tools that process NCurve objects are documented in Curve Modification Tools.

The next section details the NCurve object property.

NCurveAttr Property

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

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

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 after pressing the "Apply" button!

When the curve type is changed using the NCurveAttr property Ayam may also have to change the position of some control points as follows:

When changing the order of a periodic curve (and not touching the length) Ayam will automatically add or remove control points to/from the curve so that the shape of the curve remains largely intact and the periodic extensions plausible.[*]

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. Modelling actions will always modify all the control points that make up a multiple point even if just one of the control points is selected. 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 Collapse Tool and Explode Tool for more information regarding those tools). Note that even though you might have exploded some multiple points Ayam will re-create them automatically on several occasions like reading of a scene, inserting/deleting points, and applying the NCurveAttr property if they still have identical coordinate values. In other words, you should immediately edit the control points (move them apart) after exploding to avoid that they automatically collapse to a multiple point again! You may also totally inhibit creation of multiple points for a NURBS curve using the attribute "CreateMP".

RIB Export

NCurve objects never directly appear in RIB output (only indirectly as trim curve).

 

ICurve (Interpolating Curve) Object

The ICurve object creates a global interpolating NURBS curve from n 3D non-rational ordered data points. The curve may be open or closed, the order of the curve may be configured, the parameterisation may be adapted, and end derivatives may be specified. The open versions create n+2 NURBS control points, and the closed ones n+3.

Different ICurves resulting from identical data point configurations (Upper Left: Open, Order 3; Upper Right: Open, Order 4; Lower Left: Closed, Order 3; Lower Right: Closed, Order 4)

The image above shows some interpolating curves, the left ones are of order 3 (quadratic curves), the right ones are of order 4 (cubic curves), the upper open, and the lower closed ones. The interpolation fidelity for the closed curves was tuned by adjusting the "SDLen" and "EDLen" parameters (all set to 0.2), see also the discussion of the parameters below.

In all parameterisation modes, knot averaging will be used to determine the knot vector of the interpolating curve.

Note that the axis of symmetry for closed interpolating curves crosses the first data point (in contrast to open interpolating or closed approximating curves, where it crosses between the last and first data point). For example, the closed interpolating curves in the above example image are indeed both symmetric, but the axis of symmetry is crossing the first and third data point and is, thus, rotated by 45 degrees.

This object makes use of the provide mechanism. It marks itself as providing a NCurve object (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 NCurve.

The following table briefly lists some capabilities of the ICurve object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
ICurveNoNoNCurveYes

ICurve Object Capabilities

ICurve objects may be created via the toolbox, the main menu, or the scripting interface, see also Creating Objects.

ICurveAttr Property

The following parameters control the interpolation process:

The parameters "Mode", "Closed", and "IParam" are gone since Ayam 1.16. "Closed" was replaced by "Type", "IParam" by "SDLen" and "EDLen", and the "Mode" is now determined automatically from the desired order.

Conversion Support

The interpolating curve may be converted to an ordinary NURBS curve using the main menu entry "Tools/Convert".

RIB Export

ICurve objects never directly appear in RIB output (only indirectly as trim curve).

 

ACurve (Approximating Curve) Object

Different ACurves (Upper Left: ALength 3, Order 3; Upper Right: ALength 4, Order 4; Lower Left: ALength 4, Order 4; Lower Right: ALength 6, Order 3)

The ACurve object creates an approximating NURBS curve with m control points from n 3D non-rational ordered data points (see image above).[*]

The number of desired output control points must be smaller than or equal to the number of data points to approximate (m≤n). The approximation algorithm used is of the least squares variety. If the number of control points approaches the number of data points, undesired wiggles in the output curve may occur.

This object makes use of the provide mechanism. It marks itself as providing a NCurve object (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 ACurve object instead of an object of type NCurve.

The following table briefly lists some capabilities of the ACurve object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
ACurveNoNoNCurveYes

ACurve Object Capabilities

ACurve objects may be created via the main menu or the scripting interface, see also Creating Objects.

ACurveAttr Property

The following parameters control the approximation process:

Conversion Support

The approximating curve may be converted to an ordinary NURBS curve using the main menu entry "Tools/Convert".

RIB Export

ACurve objects never directly appear in RIB output (only indirectly as trim curve).

 

NCircle (NURBS Circle) Object

Different NCircle Objects (l: default, m: TMax 180, r: Radius 0.5, TMax -200)

The NCircle object creates a circular NURBS curve or a circular arc in the XY-plane centered at the origin with designated radius and start/end angles (see image above).[*]

A full circle is created using nine rational control points in a rectangular configuration, circular arcs are created with fewer control points. See section NURBS Circle with Triangular Base for a Script object that implements a circle with less control points.

In order to revert the created NURBS curve the start/end angles may be used, e.g. "TMin" 0.0, "TMax" -360.0 for a reverse full circle.[*]

The following table briefly lists some capabilities of the NCircle object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
NCircleNoNoNCurveNo*

NCircle Object Capabilities

NCircleAttr Property

The following parameters control the shape of the circle or arc.

Conversion Support

The circular curve/arc may be converted to an ordinary NURBS curve using the main menu entry "Tools/Convert".

RIB Export

NCircle objects never directly appear in RIB output (only indirectly as trim curve).

4.5 Curve Tool Objects

These objects modify existing curves or create new curves.

 

ConcatNC (Concatenate NURBS Curves) Object

ConcatNC Object (blue) 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.

The concatenation process works as follows:

  1. The orders of all parameter curves will be elevated to the maximum order of all the parameter curves (see also section elevate tool for more information on elevation) and all curves will be clamped (see also section clamp tool for more information on clamping).
  2. If the parameter "FillGaps" is enabled, fillet curves will be created for every gap between the parameter curves of the ConcatNC object. If "Closed" and "FillGaps" are enabled, an additional fillet is created to close the curve.
  3. Now the control points of all parameter curves and fillets are simply copied into a new big control point vector, without checking for double points. This means that for parameter curves that touch at their respective ends, at least double control points in the new concatenated curve will result.
  4. If "Closed" is enabled, the curve will be closed.

The knot sequence of the new concatenated curve will be of type "NURB" or a custom knot vector will be computed (depending on the setting of "Knot-Type").
If "Knot-Type" is "NURB", the shape of the concatenated curve will differ from the parameter curves if any of the parameter curves has a custom knot vector with non equidistant knots.
If "Knot-Type" is "Custom", the shape of the parameter curves will be preserved completely, but the knot vector of the concatenated curve will then contain internal multiple knots.

Attributes like display mode and tolerance for the new concatenated curve are simply taken from the first parameter curve.

For best results, only clamped curves should be used as parameter objects.

The following table briefly lists some capabilities of the ConcatNC object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
ConcatNCNCurve+NoNCurveNo*

ConcatNC Object Capabilities

ConcatNCAttr Property

The following parameters control the concatenation process:

Conversion Support

The concatenated curve may be converted to an ordinary NURBS curve using the main menu entry "Tools/Convert".

RIB Export

ConcatNC objects never directly appear in RIB output (only indirectly as trim curve).

 

ExtrNC (Extract NURBS Curve) Object

Extracted Curves (white) from Arbitrarily Shaped Surface (blue)

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 (see image above). 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 object above will have one boundary in common with a boundary or an iso-curve of the NPatch object. Note that using an instance object of some other surface object (as shown in the above example) is in fact the recommended way of using the ExtrNC object. Therefore, the main menu entry "Tools/Create/ExtrNC" will automatically create an instance of the currently selected object and move it to the newly created ExtrNC object.

As the geometry of the extracted curve is completely defined by the master surface, ExtrNC objects do not support own transformation attributes.[*]

Note that the extraction of any curves currently completely ignores potentially present trimming information of the NPatch object, i.e. the extracted curves will not be trimmed.
However, complete trim boundaries may be extracted .[*]

The following table briefly lists some capabilities of the ExtrNC object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
ExtrNCNPatchNoNCurveNo*

ExtrNC Object Capabilities

ExtrNCAttr Property

The extraction process is controlled by the following attributes:

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

Conversion Support

The extracted curve may be converted to an ordinary NURBS curve using the main menu entry "Tools/Convert".

RIB Export

ExtrNC objects never directly appear in RIB output (only indirectly as trim curve).

 

OffsetNC (Offset NURBS Curves) Object

Offset Curves (white) from NURBS Curves (blue) with Offset 0.2, -0.2, and 0.3

The OffsetNC object creates offset curves from planar NURBS curves using four different algorithms.[*]
See also the image above.

The offset curve will always match the original curve in type, length, order, and knots. No attempt is made to prevent collisions or self intersections. Rational curves are not supported well.

The available offset algorithms are:

Point
offsets each control point along the normal derived from the surrounding control points; the offset curve created by this algorithm may come too near the original curve at sharp convex features whose exact forms are not preserved well either,

Section
this algorithm offsets all control polygon sections in the direction of their normal and places new control points at intersection points of the lines defined by the offset sections; this algorithm is better in avoiding self intersections of the offset curve but the offset curve may be too far away from the original curve at sharp convex or concave features (regions of high curvature),

Hybrid
this algorithm offsets the curve two times using the Point and Section algorithms and then mixes the results so that the bad features of the two algorithms cancel out each other,[*]

3DPVN
Since Ayam 1.18 there is a fourth offsetting algorithm available, that creates true three dimensional offsets from non planar curves using a primitive variable tag that contains normal information for the curve (vertex normals). Such tags can be created manually or automatically e.g. when extracting curves from surfaces using the "ExtrNC" object.

As the geometry of the offset curve is completely defined by the master curve and the offset parameter, OffsetNC objects do not support own transformation attributes.[*]

The "Bevel3D" offset algorithm has been removed since Ayam 1.19.

The following table briefly lists some capabilities of the OffsetNC object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
OffsetNCNCurveNoNCurveNo*

OffsetNC Object Capabilities

OffsetNCAttr Property

The following parameters control the offsetting process:

Conversion Support

The offset curve may be converted to an ordinary NURBS curve using the main menu entry "Tools/Convert".

RIB Export

OffsetNC objects never directly appear in RIB output (only indirectly as trim curve).

4.6 Freeform Surface Objects

These objects enable direct manipulation of freeform surfaces.

 

NPatch (NURBS Patch) Object

NURBS Patch: Surface (blue) from Control Polygon (white)

The NPatch object allows to model NURBS surfaces in a direct way, e.g. by modifying control points (see also the image above). Note that using NPatch 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.

Like NCurve objects, NPatch objects mark their last control point with a small arrow. Note that the arrow points in the V direction (height).

NPatch objects also support the concept of multiple points, see section Multiple Points for more information regarding this.[*]

The following table briefly lists some capabilities of the NPatch object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
NPatchNCurve+/ Level+YesPolyMeshYes

NPatch Object Capabilities

NPatch objects may be created via the toolbox, the main menu, some tools as documented in section Surface Creation Tools, or the scripting interface, see also Creating Objects.

Tools that process NPatch objects are documented in section Surface Modification Tools.

NPatchAttr Property

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

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

Trim Curves

A Trimmed NURBS Patch

Trim curves may be used to cut out certain parts of a NURBS patch (see also the image above). 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 can 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. The Revert tool ("Tools/Curve" menu) can be used to easily change the direction of a trim curve.

Some special restrictions apply to trim curves:

Note that Ayam is not checking whether the 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 modelling, switch to wire-frame drawing and switch off shading temporarily and you will be on the safe side.

NURBS curve providing objects are also supported as trim curves.[*] When objects provide multiple NURBS curves, those do not form a single loop, but are seen as individual loops.

Caps and Bevels

The NPatch object supports the standard caps as lined out in section Caps Property and the standard bevels as lined out in section Bevels Property.
The boundary names are U0, U1, V0, and V1.

Integration is not supported; the corresponding option is silently ignored.

Conversion Support

A NPatch object may be converted to a PolyMesh object using the main menu entry "Tools/Convert".

This process is also called tesselation and thus, the tesselation parameters from TP tags will be used in the conversion process (if present) (see also section TP Tag).

If bevels or caps are present, an enclosing Level object will be created and the tesselated bevels or caps follow the tesselated NPatch in the following order: U0, U1, V0, V1.

RIB Export

NPatch objects will be exported as NURBS patch primitives:

RiNuPatch(...);
PV tags are supported and also trim curves may appear.

Multiple TC tags are also supported.[*]

 

IPatch (Interpolating Patch) Object

Interpolating surface (blue) from data points (white)

An IPatch forms a surface defined by interpolating a regular grid of three dimensional and non rational data points (see also the image above).

The following table briefly lists some capabilities of the IPatch object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
IPatchNoYesNPatchYes

IPatch Object Capabilities

IPatch objects may be created via the main menu or the scripting interface, see also Creating Objects.

IPatchAttr Property

The IPatchAttr property contains the following elements:

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

Caps and Bevels

The IPatch object supports the standard caps as lined out in section Caps Property and the standard bevels as lined out in section Bevels Property.
The boundary names are U0, U1, V0, and V1.

Conversion Support

The interpolated surface may be converted to an ordinary NURBS patch using the main menu entry "Tools/Convert".

RIB Export

IPatch objects will be exported as NURBS patch primitives:

RiNuPatch(...);
PV tags are currently not supported.

Multiple TC tags are also supported.[*]

 

BPatch (Bilinear Patch) Object

Bilinear Patch

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

The following table briefly lists some capabilities of the BPatch object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
BPatchNoYesNPatchYes

BPatch Object Capabilities

BPatchAttr Property

The BPatchAttr property allows to directly control the four points defining the geometry of the patch:

Conversion Support

The bilinear patch may be converted to an ordinary NURBS patch using the main menu entry "Tools/Convert".

RIB Export

BPatch objects will be exported as bilinear patch primitives:

RiPatch(RI_BILINEAR, ...);
PV tags are supported.

 

PatchMesh Object

Bicubic (left) and Bilinear (right) PatchMesh Surfaces (blue) from their Respective Control Polygons (white)

The PatchMesh object may be used to model with bicubic and bilinear patch meshes, see the image above for two examples.

Like NCurve objects, PatchMesh objects mark their last control point with a small arrow. Note that the arrow points in the V direction (height).

The following table briefly lists some capabilities of the PatchMesh object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
PatchMeshNoYesNPatchYes

PatchMesh Object Capabilities

PatchMeshAttr Property

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

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

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

Caps and Bevels

The PatchMesh object supports the standard caps as lined out in section Caps Property and the standard bevels as lined out in section Bevels Property .[*]
The boundary names are U0, U1, V0, and V1.

Conversion Support

The patch mesh may be converted to an ordinary NURBS patch using the main menu entry "Tools/Convert". In Ayam versions prior to 1.21, conversion (and shaded display) did not work for patch meshes with the basis types Catmull-Rom, Hermite, or Custom. This is no longer the case.

RIB Export

PatchMesh objects will be exported as patch mesh primitives:

RiPatchMesh(...);
PV tags are supported.

Multiple TC tags are also supported.[*]

4.7 Surface Tool Objects

These objects create freeform surfaces from curves or other surfaces.

 

Revolve Object

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

The Revolve object forms a surface of revolution from a NURBS curve, see the image above for an example.

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. The parameter curve should be defined in the XY-plane. If not, the curve will be projected to this plane before revolving.

The following table briefly lists some capabilities of the Revolve object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
RevolveNCurveYesNPatch+No*

Revolve Object Capabilities

RevolveAttr Property

The parameter "ThetaMax" specifies the sweeping angle of the revolution just like for an ordinary RenderMan quadric primitive.

The Revolve object also supports a B-Spline mode that may be enabled by setting the parameter "Sections" to a value higher than 0.[*]

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 chosen, 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 if the revolved curve is also not rational.
Note that also the B-Spline mode can realize arbitrary "ThetaMax" values.[*]

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 parameter "Order". If "Order" is 0, a standard value of 3 will be used.

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

Caps and Bevels

The Revolve object supports the standard caps as lined out in section Caps Property and the standard bevels as lined out in section Bevels Property.

The boundary names are:
Upper – curve formed by revolving the start point of the cross section,
Lower – curve formed by revolving the end point of the cross section,
Start – cross section, and
End – cross section at end of revolution.

Conversion Support

The surface of revolution and the bevels and caps may be converted to ordinary NURBS patches using the main menu entry "Tools/Convert".

If bevels or caps are present, an enclosing Level object will be created and the bevels or caps follow the surface of revolution in the following order: upper, lower, start, end.

Integrated bevels or caps do not appear as extra objects.

The Revolve object provides a list of NURBS patch objects in the same order as created upon conversion.

RIB Export

Revolve objects will be exported as NURBS patch primitives:

RiNuPatch(...);
If bevels or caps are present, those follow as potentially trimmed NURBS patch primitives in the following order: upper, lower, start, end.

PV tags are supported.[*]

Multiple TC tags are also supported.[*]

 

Extrude Object

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

The Extrude object forms a linear extrusion from a number of planar NURBS curves, see the image above for an example.

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, watches them and adapts to them automagically.

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

+-Extrude
 | Outline(NCurve)
 | [Hole_1(NCurve)
 | ...
 \ Hole_n(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. The parameter curves should be defined in the XY-plane. If not, they will be squashed down to this plane. See section To XY Tool for information on how to easily achieve curves in the XY-plane.

The dimensions and orders of the extruded surface(s) will be taken from the respective parameter curves as follows: width and order in U direction will be 2, height and order in V direction are taken from the parameter curve.

The following table briefly lists some capabilities of the Extrude object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
ExtrudeNCurve+YesNPatch+No*

Extrude Object Capabilities

ExtrudeAttr Property

The parameter "Height" determines how big in Z direction the extrusion should be. Note that the height of the bevels will not be taken into account here, if the extrusion height is 1.0 and beveling (upper and lower) is switched on with radius 0.1 the resulting object extends 1.2 units 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 the parameter curves conform to these criteria. Ayam, however, automatically 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 corresponding 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 NPatchAttr 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 them self and there can not be hole curves inside hole curves. If there are bevels and caps, allow some extra spacing between the curves (for the bevels). Ayam will not check whether the parameter curves conform to these criteria.

With the direction of the curve, the direction of the bevel is determined 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. It is suggested to always use closed curves for beveling. Beveling may lead to self intersecting trim curves 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.

Another special issue shall be noted: If there are holes, the corresponding bevels will be scaled with the hole curve object transformation values. Thus, to achieve equally sized bevels for outline and holes, possible scale transformations should be carried out on the hole curve control points, rather than on the hole curve object transformation attributes.

Conversion Support

The extruded surface, the bevels, and the caps may be converted to ordinary NURBS patches using the main menu entry "Tools/Convert".

If bevels or caps are present, an enclosing Level object will be created and the bevels and caps follow the extruded surface in the following order: end bevel, end cap, start bevel, start cap.

The Extrude object provides a list of NURBS patch objects in the same order as created upon conversion.

RIB Export

Extrude objects will be exported as NURBS patch primitives:

RiNuPatch(...);
If caps or bevels are present, those follow as potentially trimmed NURBS patch primitives in the following order: end bevel, end cap, start bevel, start cap.

PV tags are supported but all NURBS patch primitives will get the same set of tags.[*]

 

Swing Object

Swing Object (left: Curves, right: Resulting Swung Surface)

The Swing object forms a surface that results from rotating a NURBS curve (called cross section or profile) around an axis while scaling it according to a second NURBS curve (called trajectory or path).[*]
This process is sometimes also called rotational sweep. See the image above for an example.

The Swing 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.

The object hierarchy of a Swing object, thus, looks like this:

+-Swing
 | Cross_Section(NCurve)
 \ Trajectory(NCurve)

The swing operation will occur around the Y-axis, i.e. the trajectory should be defined in the XZ-plane.

The cross section curve should be defined in the YZ-plane and the trajectory should start here. See also the image below.

Swing Cross Section (l), Trajectory (r), Surface (blue)

Note that the swing create tool will automatically modify the control points of NCurve, ICurve, and ACurve objects so that they are defined in the proper plane. For all other object types, the transformation attributes will be set (Rotate_Y is set to 90 if currently set to 0).[*]

The dimensions and orders of the swung surface will be taken from the respective parameter curves as follows: width and order in U direction from the trajectory, height and order in V direction from the cross section.

The following table briefly lists some capabilities of the Swing object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
SwingNCurveYesNPatch+No*

Swing Object Capabilities

SwingAttr Property

The swung surface is completely controlled by the parameter curves.

See section NPatchAttr for a description of the attributes "DisplayMode" and "Tolerance".

To help in the exact configuration of the swung surface, the "NPInfo" field always displays the parameters of the created NURBS patch.

Caps and Bevels

The Swing object supports the standard caps as lined out in section Caps Property and the standard bevels as lined out in section Bevels Property.

The boundary names are:
Start – cross section,
End – cross section at end of sweep,
Upper – curve formed by sweeping the start point of the cross section, and
Lower – curve formed by sweeping the end point of the cross section.

Conversion Support

The swung surface and the caps may be converted to ordinary NURBS patches using the main menu entry "Tools/Convert".

If bevels or caps are present, an enclosing Level object will be created and the bevels or caps follow the swung surface in the following order: upper, lower, start, end.

Integrated bevels or caps do not appear as extra objects.

The Swing object provides a list of NURBS patch objects in the same order as created upon conversion.

RIB Export

Swing objects will be exported as NURBS patch primitives:

RiNuPatch(...);
If bevels or caps are present, those follow as potentially trimmed NURBS patch primitives in the following order: upper, lower, start, end.

PV tags are supported.[*]

Multiple TC tags are also supported.[*]

 

Sweep Object

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

The Sweep object forms a surface that results from moving a NURBS curve (called cross section or profile) along a second NURBS curve (called trajectory or path). See the image above for an example.

The cross section may be scaled while sweeping using a third curve, the scaling function. Swept surfaces may be closed in the direction of the trajectory and they may also be periodic.[*]

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, looks like this:

+-Sweep
 | Cross_Section(NCurve)
 | Trajectory(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. See also the image below.

Sweep Cross Section (l), Trajectory (r), Surface (blue)

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. This can be done either by modifying the control points, or by setting the transformation attributes accordingly. Later editing of this curve has to be done in a Side view. Note that the sweep create tool will automatically modify the control points of NCurve, ICurve, and ACurve objects so that they are defined in the proper plane. For all other object types, the transformation attributes will be set (Rotate_Y is set to 90 if currently set to 0).[*]

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-direction.

If any sample point of the scaling function has a Z-component different from zero, the Z-component will be used to independently scale the cross section in X-direction, otherwise the Y-component will be used to also scale the cross section in X-direction.[*]

This implies, that e.g. a scaling function that does nothing should be a linear curve from (0,1,1) to (1,1,1). Scale components that are less than or equal to zero will be silently ignored.

Sweep Object (blue) with Scaling Function (white)

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

  1. Create a circular B-Spline curve using the toolbox. (This will be our cross section.)
  2. Create a simple NURBS curve using the toolbox. (This will be our trajectory.)
  3. Select both curves. (Select the first curve, hold down the "Shift" key and select the other curve.)
  4. Create the Sweep object using the toolbox.
  5. Observe that the cross section curve was rotated automatically to the YZ-plane.
  6. Now you may enter the Sweep object and modify e.g. the second curve, the trajectory. (Press <e>, then drag some control points around.)
  7. To modify the cross section you would need to switch to a view of type "Side". (Use the views "Type" menu or the <PgDwn> keyboard 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.

The following table briefly lists some capabilities of the Sweep object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
SweepNCurveYesNPatch+No*

Sweep Object Capabilities

SweepAttr Property

The "Type" attribute controls whether the swept surface should be open, closed, or periodic in the direction of the trajectory curve.[*]

If "Interpolation" is enabled, an additional interpolation will be run on the swept surface in U direction so that all section curves will be interpolated by the swept surface. Instead of a NURBS knot vector, the swept surface will then get a Chordal knot vector (calculated by knot averaging) and the swept surface will follow the trajectory more closely. See the image below for an example.

Sweep Along a Quarter Circle without (left) and with (right) Interpolation Enabled

The third parameter, "Sections", determines how many control points (in U direction) should be used, when generating the sweep NURBS patch. The sweep NURBS patch has sections+1 control points in U direction for open and closed sweeps, whereas sections+order control points will be created for periodic sweeps.
Zero is a valid setting for the "Sections" parameter and used as default value.[*] In this case the number of sections is directly derived from the length of the trajectory curve plus one (except for trajectory curves of length 2, where the number of sections is 1).
For example, if "Sections" is zero, for a standard NURBS curve of length 4, the number of sections used is 5 and the width of the created NURBS patch is 6, for a curve with just 2 control points, the number of sections used is 1 and the width of the resulting patch is 2. See the table below for more examples.
Moreover, if "Sections" is zero, the order of the sweep in U direction is taken from the trajectory curve. Otherwise, the order of the created patch depends on the number of sections as follows: for 1 and 2 sections the order will be 2 and 3 respectively, in all other cases it will be 4.

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

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

To help in the exact configuration of the swept surface, the "NPInfo" field always displays the parameters of the created NURBS patch.

The following table shows some example parameter configurations for the Sweep object.

SectionsTrajectory LengthTrajectory OrderSweep LengthSweep Order
02222
05464
06575
46554
1065114

Sweep Parameterisation Examples

Caps and Bevels

The Sweep object supports the standard caps as lined out in section Caps Property and the standard bevels as lined out in section Bevels Property.

The boundary names are:
Start – cross section,
End – cross section at end of sweep,
Left – curve formed by sweeping the start point of the cross section, and
Right – curve formed by sweeping the end point of the cross section.

Conversion Support

The swept surface, the bevels and the caps may be converted to ordinary NURBS patches using the main menu entry "Tools/Convert".

If bevels or caps are present, an enclosing Level object will be created and the bevels and caps follow the swept surface in the following order: start bevel, start cap, end bevel, end cap, left bevel, left cap, right bevel, right cap.

Integrated bevels or caps do not appear as extra objects.

The Sweep object provides a list of NURBS patch objects in the same order as created upon conversion.

RIB Export

Sweep objects will be exported as NURBS patch primitives:

RiNuPatch(...);
If caps or bevels are present, those follow as potentially trimmed NURBS patch primitives in the following order: start bevel, start cap, end bevel, end cap, left bevel, left cap, right bevel, right cap.

PV tags are supported.[*]

Multiple TC tags are also supported.[*]

 

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. See the image above for an example.

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 R2) 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 chosen.

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

The following table briefly lists some capabilities of the Birail1 object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
Birail1NCurveYesNPatch+No*

Birail1 Object Capabilities

Birail1Attr Property

The following parameters control the birailing process.

Similar to the Sweep object, the "Type" attribute controls whether the birailed surface should be open, closed, or periodic in the direction of the rail curves.

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.
Also zero is a valid setting for the "Sections" parameter and used as default value.[*]
If "Sections" is zero the number of sections is directly derived from the length of the first rail curve plus one (except for curves of length 2, where it is 1). See the table below for examples.
Moreover, if "Sections" is zero, the order of the birail in U direction is taken from the first rail curve. Otherwise, the order of the created patch depends on the number of sections as follows: for 1 and 2 sections the order will be 2 and 3 respectively, in all other cases it will be 4.

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

To help in the exact configuration of the birailed surface, the "NPInfo" field always displays the parameters of the created NURBS patch.

The following table shows some example parameter configurations for the Birail1 object.

SectionsRail1 LengthRail1 OrderBirail1 LengthBirail1 Order
02222
05464
06575
46554
1065114

Birail1 Parameterisation Examples

Caps and Bevels

The Birail1 object supports the standard caps as lined out in section Caps Property and the standard bevels as lined out in section Bevels Property.

The boundary names are:
Start – cross section,
End – cross section at end of sweep,
Left – curve formed by sweeping the start point of the cross section, and
Right – curve formed by sweeping the end point of the cross section.

Conversion Support

The birailed surface, the bevels, and the caps may be converted to ordinary NURBS patches using the main menu entry "Tools/Convert".

If bevels or caps are present, an enclosing Level object will be created and the bevels and caps follow the birailed surface in the following order: end bevel, end cap, start bevel, start cap, left bevel, left cap, right bevel, right cap.

Integrated bevels or caps do not appear as extra objects.

The Birail1 object provides a list of NURBS patch objects in the same order as created upon conversion.

RIB Export

Birail1 objects will be exported as NURBS patch primitives:

RiNuPatch(...);
If caps or bevels are present, those follow as potentially trimmed NURBS patch primitives in the following order: end bevel, end cap, start bevel, start cap, left bevel, left cap, right bevel, right cap.

PV tags are supported.[*]

Multiple TC tags are also supported.[*]

 

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. See also the image above for an example.

The morphing process may be controlled by a fifth parameter curve, the interpolation control 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 R2) 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 chosen.

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 be equivalent to 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.[*]

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

The following table briefly lists some capabilities of the Birail2 object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
Birail2NCurveYesNPatch+No*

Birail2 Object Capabilities

Birail2Attr Property

The following parameters control the birailing process.

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.
Also zero is a valid setting for the "Sections" parameter and used as default value.[*]
If "Sections" is zero the number of sections is directly derived from the length of the first rail curve plus one (except for curves of length 2, where it is 1). See the table below for examples.
Moreover, if "Sections" is zero, the order of the birail in U direction is taken from the first rail curve. Otherwise, the order of the created patch depends on the number of sections as follows: for 1 and 2 sections the order will be 2 and 3 respectively, in all other cases it will be 4.

The parameter "InterpolCtrl" allows the interpolation controlling curve full influence on the birailed surface. If "InterpolCtrl" is disabled, the first and last border of the resulting surface will always exactly match the parameter curves (CS1 and CS2 respectively), regardless of the interpolation control curve.

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

To help in the exact configuration of the birailed surface, the "NPInfo" field always displays the parameters of the created NURBS patch.

The following table shows some example parameter configurations for the Birail2 object.

SectionsRail1 LengthRail1 OrderBirail2 LengthBirail2 Order
02222
05464
06575
46554
1065114

Birail2 Parameterisation Examples

Caps and Bevels

The Birail2 object supports the standard caps as lined out in section Caps Property and the standard bevels as lined out in section Bevels Property.

The boundary names are:
Start – first cross section,
End – second cross section,
Left – curve formed by sweeping the start point of the first cross section, and
Right – curve formed by sweeping the end point of the first cross section.

Conversion Support

The birailed surface, the bevels, and the caps may be converted to ordinary NURBS patches using the main menu entry "Tools/Convert".

If bevels or caps are present, an enclosing Level object will be created and the bevels and caps follow the birailed surface in the following order: end bevel, end cap, start bevel, start cap, left bevel, left cap, right bevel, right cap.

Integrated bevels or caps do not appear as extra objects.

The Birail2 object provides a list of NURBS patch objects in the same order as created upon conversion.

RIB Export

Birail2 objects will be exported as NURBS patch primitives:

RiNuPatch(...);
If caps or bevels are present, those follow as potentially trimmed NURBS patch primitives in the following order: end bevel, end cap, start bevel, start cap, left bevel, left cap, right bevel, right cap.

PV tags are supported.[*]

Multiple TC tags are also supported.[*]

 

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). See also the image above.

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
 | C_1(NCurve)
 | C_2(NCurve)
 | [...
 \ C_n(NCurve)]

Note that in contrast to the build from curves tool, the curves may be of arbitrary length and order. It is e.g. possible to use a parameter 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.

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. For example, 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.

The following table briefly lists some capabilities of the Skin object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
SkinNCurveYesNPatch+No*

Skin Object Capabilities

SkinAttr Property

The following parameters control the skinning process.

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", the type of the knot vector that should be used in the U direction of the skinned surface can be adapted. 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. The knot type "Custom" creates a chord length parameterisation, even if interpolation is not enabled.[*]

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

To help in the exact configuration of the skinned surface, the "NPInfo" field always displays the parameters of the created NURBS patch.

Caps and Bevels

The Skin object supports the standard caps as lined out in section Caps Property and the standard bevels as lined out in section Bevels Property.

The boundary names are:
Start – first parameter curve,
End – last parameter curve,
Left – curve through start points of parameter curves, and
Right – curve through end points of parameter curves.

Conversion Support

The skinned surface, the bevels, and the caps may be converted to ordinary NURBS patches using the main menu entry "Tools/Convert".

If bevels or caps are present, an enclosing Level object will be created and the bevels and caps follow the skinned surface in the following order: start bevel, start cap, end bevel, end cap, left bevel, left cap, right bevel, right cap.

Integrated bevels or caps do not appear as extra objects.

The Skin object provides a list of NURBS patch objects in the same order as created upon conversion.

RIB Export

Skin objects will be exported as NURBS patch primitives:

RiNuPatch(...);
If caps or bevels are present, those follow as potentially trimmed NURBS patch primitives in the following order: start bevel, start cap, end bevel, end cap, left bevel, left cap, right bevel, right cap.

PV tags are supported.[*]

Multiple TC tags are also supported.[*]

 

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 arrangement and the direction of the curves. Also note that this configuration is in fact equivalent to a Coons patch.

Gordon Surface with Parameter Curves (white)

The curves may be of arbitrary length and order. It is e.g. possible to 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 in the general case 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. However, since Ayam 1.13 there is a special case allowed: if exactly four parameter curves are present, their weight information will be used properly. Mind that for a correct surface interpolation the curves weights have to match in the respective end points.

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 there are 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 a third parameter object may be specified (separated from the two sets of parameter curves by a second empty level object). This third parameter object 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. A "NoExport" tag should be added to this patch, to prevent it from appearing in RIB output.

The object hierarchy of a Gordon object using such a patch may look like this:

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

The complete template for the Gordon object hierarchy, consequently, is as follows:

+-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.

The following table briefly lists some capabilities of the Gordon object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
GordonNCurve/ Level / NPatchYesNPatch+No*

Gordon Object Capabilities

GordonAttr Property

The following parameters of the Gordon object control the creation of the Gordon surface.

If the parameter "WatchCorners" 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. If Ayam can determine which curve was modified last, the other curve that should meet at the endpoint in question will be modified. If Ayam finds no information on modifications, the U curves take precedence (i.e. the V curves will be modified). Note that this works only properly with clamped curves. Furthermore, only NCurve, ICurve, or ACurve objects will be modified, but end point data will be derived from any objects providing a NCurve (e.g. ExtrNC).[*]

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 NPatchAttr for a description of the other two attributes "DisplayMode" and "Tolerance".

To help in the exact configuration of the Gordon surface, the "NPInfo" field always displays the parameters of the created NURBS patch.

Caps and Bevels

The Gordon object supports the standard caps as lined out in section Caps Property and the standard bevels as lined out in section Bevels Property.

The boundary names are:
U0 – first curve of first set,
U1 – last curve of first set,
V0 – first curve of second set, and
V1 – last curve of second set.

Conversion Support

The Gordon surface, the bevels, and the caps may be converted to ordinary NURBS patches using the main menu entry "Tools/Convert".

If bevels or caps are present, an enclosing Level object will be created and the bevels and caps follow the Gordon surface in the following order: u0 bevel, u0 cap, u1 bevel, u1 cap, v0 bevel, v0 cap, v1 bevel, v1 cap.

Integrated bevels or caps do not appear as extra objects.

The Gordon object provides a list of NURBS patch objects in the same order as created upon conversion.

RIB Export

Gordon objects will be exported as NURBS patch primitives:

RiNuPatch(...);
If caps or bevels are present, those follow as potentially trimmed NURBS patch primitives in the following order: u0 bevel, u0 cap, u1 bevel, u1 cap, v0 bevel, v0 cap, v1 bevel, v1 cap.[*]

PV tags are supported.[*]

Multiple TC tags are also supported.[*]

 

Bevel Object

Bevel Object (left: Curve, right: Resulting Bevelled Surface)

The Bevel object forms a bevelled surface from a single parameter curve. See also the image above. The bevel cross section shape may be defined by a second curve. Consequently, the template for the object hierarchy of a Bevel object looks like this:

+-Bevel
 | NCurve
 \ [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 offer increased flexibility in terms of e.g. material settings. Surfaces created from bevel properties always share the material settings of the progenitor 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 of a Bevel object should be closed and planar to achieve best results; see section To XY Tool for information on how to easily achieve this. If the curve is closed or periodic, the appropriate curve type should be set in the curve object, otherwise the bevelled surface may expose defects.

Since Ayam 1.19 the Bevel object supports a second parameter curve that defines the bevels cross section shape. It should be defined in the XY-plane and run from (0, 0) to (1, 1). If this curve is present, the Bevel type parameter is ignored as the shape of the bevel is already completely defined. Note that even though the curve should end at (1, 1), this is not mandatory and therefore allows for bevels of differing width and height to be created.

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

The following table briefly lists some capabilities of the Bevel object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
BevelNCurve+YesNPatchNo*

Bevel Object Capabilities

BevelAttr Property

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

To create the tag with the normal and tangent information, the "Extract" option of the ExtrNC object can be used. Otherwise PV tags of appropriate name, storage class, and data type must be created manually or with the help of the scripting interface. Consider the following example script:

crtOb NCurve -length 4 -order 2 -cv {0 0 0 1  1 0 0 1  0 1 0 1  0 0 0 1}
uS;sL
addTag PV "N,varying,n,4, -1,0,0, 1,0,0, 0,1,0, -1,0,0"
addTag PV "T,varying,n,4, 0,0,1, 0,0,1, 0,0,1, 0,0,1"

Also note that the planarity and exact shape defined by rational coordinate values (e.g. circular arcs) will not be preserved by the bevel types that support non-planar curves with one exception: RoundToCap bevels on fully planar curves/boundaries do preserve the boundary shape fully (unless overridden by "Force3D").[*]

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

To help in the exact configuration of the bevel surface, the "NPInfo" field always displays the parameters of the created NURBS patch.

Caps

The Bevel object supports the standard caps as lined out in section Caps Property.

The boundary names are:
Start – start of bevel cross section,
End – end of bevel cross section.

Conversion Support

The bevelled surface may be converted to an ordinary NURBS patch using the main menu entry "Tools/Convert".

If caps are present, an enclosing Level object will be created and the caps follow the bevel surface in the following order: start cap, end cap.

RIB Export

Bevel objects will be exported as NURBS patch primitives:

RiNuPatch(...);

If caps are present, those follow as potentially trimmed NURBS patch primitives in the following order: start cap, end cap.

PV tags are supported.[*]

Multiple TC tags are also supported.[*]

 

Cap Object

Cap Object (left: Curve, right: Resulting Cap Surface)

The Cap object forms a surface that fills a closed NURBS curve. See also the image above.

Four different types of cap surfaces with different characteristics and parameter curve requirements are supported: Trim, Gordon, Simple, and Simple3D.[*]

The Trim cap type requires planar parameter curves but they may be concave. Furthermore, 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 in Trim mode looks like this:

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

Note that the 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.

The Gordon cap type supports only a single parameter curve but this curve may be non planar. Internally the Cap object will split the parameter curve into four sections and build a Gordon surface from the four sections (see the following image for an example).

Cap from Non-Planar Curve (left: Curve, right: Resulting Cap Surface)

The Simple cap type just extends the parameter curve linearly to a middle point, not supporting non planar curves well and not supporting concave curves at all but ensuring compatibility with the progenitor curve/surface (which may be important for tesselation or further surface processing).

The Simple3D cap type extends the parameter curve to a middle point via an additional planar and circular ring of control points, therefore rounding more smoothly to the middle (especially useful for non planar parameter curves or parameter curves with discontinuities), and retains all other characteristics of the Simple type.

A MP tag can be set to the Cap object to control the middle point in both simple modes (see section MP (Mean Point) Tag).

See also the following table for an overview on the available cap types:

TypePlanarConcaveHolesCompatibility / Integration
TrimYesYesYesNo
GordonNoNoNoNo
SimpleYesNoNoYes
Simple3DNoNoNoYes

Cap Types Overview

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

The following table briefly lists some capabilities of the Cap object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
CapNCurve+YesNPatchNo*

Cap Object Capabilities

CapAttr Property

The following parameters control the cap creation process.

The attribute "Type" allows to select one of the following cap creation methods:

See also the general discussion about the Cap object above.

The "Fraction" parameter allows to adjust the placement of the additional control point ring in Simple3D mode.

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

To help in the exact configuration of the cap surface, the "NPInfo" field always displays the parameters of the created NURBS patch.

Conversion Support

The cap surface may be converted to an ordinary NURBS patch using the main menu entry "Tools/Convert".

RIB Export

Cap objects will be exported as NURBS patch primitives:

RiNuPatch(...);

PV tags are supported.[*]

 

ConcatNP (Concatenate NURBS Patches) Object

ConcatNP Object (white) From Two NURBS Patches (blue)

The ConcatNP object concatenates all child objects, which should be NURBS patches or provide NURBS patches to a single NURBS patch (see also the image above).[*]

The concatenation simply breaks all surfaces into curves, makes the curves compatible, and joins them to the concatenated surface.

Also NURBS curves or objects that provide NURBS curves can be used as parameter objects.[*]

Eventually present trim curves will be copied and transformed to the appropriate place and orientation in the concatenated surface, according to the new knot domain.[*]

Attributes like display mode and tolerance for the new concatenated patch are simply taken from the first parameter patch.

Since the ConcatNP object also provides a NURBS patch, it is possible to use it as child object for another ConcatNP object (with possibly different parameters). This way, a hierarchy of ConcatNP objects can be used to emulate patch based modelling to certain extents.

For best results, only clamped surfaces should be used as parameter objects.

The following table briefly lists some capabilities of the ConcatNP object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
ConcatNPNPatch/ NCurveYesNPatchNo*

ConcatNP Object Capabilities

ConcatNPAttr Property

The following parameters control the concatenation process.

Caps and Bevels

The ConcatNP object supports the standard caps as lined out in section Caps Property and the standard bevels as lined out in section Bevels Property.
The boundary names are U0, U1, V0, and V1.

Conversion Support

The concatenated surface may be converted to an ordinary NURBS patch using the main menu entry "Tools/Convert".

If bevels or caps are present, an enclosing Level object will be created and the bevels and caps follow the concatenated surface in the following order: U0 bevel, U0 cap, U1 bevel, U1 cap, V0 bevel, V0 cap, V1 bevel, V1 cap.

Integrated bevels or caps do not appear as extra objects.

The ConcatNP object provides a list of NURBS patch objects in the same order as created upon conversion.

RIB Export

ConcatNP objects will be exported as NURBS patch primitives:

RiNuPatch(...);
If caps or bevels are present, those follow as potentially trimmed NURBS patch primitives in the following order: U0 bevel, U0 cap, U1 bevel, U1 cap, V0 bevel, V0 cap, V1 bevel, V1 cap.[*]

PV tags are supported but all NURBS patch primitives will get the same set of tags.[*]

Multiple TC tags are also supported.[*]

 

ExtrNP (Extract NURBS Patch) Object

Extracted Surface (white) from Arbitrarily Shaped Surface (blue)

The ExtrNP object extracts a NURBS patch from another NURBS patch object, for use as parameter object for other tool objects (see image above).[*]

It also works with NURBS patch providing objects, so that the following example hierarchy is valid:

--NPatch
+-ExtrNP
 \ Instance_of_NPatch(Instance)
Note that using an instance object of some other surface object (as shown in the above example) is in fact the recommended way of using the ExtrNP object. Therefore, the main menu entry "Tools/Create/ExtrNP" will automatically create an instance of the currently selected object and move it to the newly created ExtrNP object.

As the geometry of the extracted surface is completely defined by the master surface, ExtrNP objects do not support own transformation attributes.[*] However, if a NP tag makes the Transformation property available again, the transformation attributes will be employed as usual.[*]

Also note that eventually present trim curves will not be honored properly.

The following table briefly lists some capabilities of the ExtrNP object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
ExtrNPNPatchYesNPatchNo*

ExtrNP Object Capabilities

ExtrNPAttr Property

The extraction process is controlled by the following attributes:

Caps and Bevels

The ExtrNP object supports the standard caps as lined out in section Caps Property and the standard bevels as lined out in section Bevels Property.
The boundary names are U0, U1, V0, and V1.

Conversion Support

The extracted surface may be converted to an ordinary NURBS patch using the main menu entry "Tools/Convert".

If bevels or caps are present, an enclosing Level object will be created and the bevels or caps follow the extracted surface in the following order: U0, U1, V0, V1.

Integrated bevels or caps do not appear as extra objects.

The ExtrNP object provides a list of NURBS patch objects in the same order as created upon conversion.

RIB Export

ExtrNP objects will be exported as NURBS patch primitives:

RiNuPatch(...);
If bevels or caps are present, those follow as potentially trimmed NURBS patch primitives in the following order: U0, U1, V0, V1.

PV tags are supported but all NURBS patch primitives will get the same set of tags.[*]

Multiple TC tags are also supported.[*]

 

OffsetNP (Offset NURBS Surfaces) Object

Offset Surface (white) from NURBS Surface (blue) with Offset 0.2

The OffsetNP object creates offset surfaces from NURBS surfaces using a simple algorithm: each control point is moved along a normal vector obtained by all direct neighboring control points.[*] See also the image above.

The offset surface will always match the original surface in width, height, orders, and knots.

The offsetting also works for closed and periodic surfaces in any possible combinations in the two dimensions.[*] Degenerate surfaces are supported.[*] However note that rational surfaces are still not supported. No attempt is made to prevent collisions or self intersections.

Trim curves are copied verbatim from the parameter surface to the offset surface.

As the geometry of the offset surface is completely defined by the master surface and the offset parameter, OffsetNP objects do not support own transformation attributes.[*]

The following table briefly lists some capabilities of the OffsetNP object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
OffsetNPNPatchYesNPatchNo*

OffsetNP Object Capabilities

OffsetNPAttr Property

The following parameters control the offsetting process:

Caps and Bevels

The OffsetNP object supports the standard caps as lined out in section Caps Property and the standard bevels as lined out in section Bevels Property.
The boundary names are U0, U1, V0, and V1.

Conversion Support

The offset surface may be converted to an ordinary NURBS patch using the main menu entry "Tools/Convert".

If bevels or caps are present, an enclosing Level object will be created and the bevels or caps follow the offset surface in the following order: U0, U1, V0, V1.

Integrated bevels or caps do not appear as extra objects.

The OffsetNP object provides a list of NURBS patch objects in the same order as created upon conversion.

RIB Export

OffsetNP objects will be exported as NURBS patch primitives:

RiNuPatch(...);
If bevels or caps are present, those follow as potentially trimmed NURBS patch primitives in the following order: U0, U1, V0, V1.

PV tags are supported but all NURBS patch primitives will get the same set of tags.[*]

Multiple TC tags are also supported.[*]

 

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 Text object can be converted to ordinary NURBS patches using the main menu entry "Tools/Convert".

The following table briefly lists some capabilities of the Text object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
TextNoYesNPatch+No*

Text Object Capabilities

TextAttr Property

The following attributes control the creation of the text objects.

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

Conversion Support

The extruded surfaces, the bevels, and the caps, may be converted to ordinary NURBS patches using the main menu entry "Tools/Convert".

If bevels or caps are present, an enclosing Level object will be created and the caps follow the extruded surfaced in the following order: end bevel, end cap, start bevel, start cap.

The Text object provides a list of NURBS patch objects in the same order as created upon conversion.

RIB Export

Text objects will be exported as NURBS patch primitives:

RiNuPatch(...);
If caps or bevels are present, those follow as potentially trimmed NURBS patch primitives in the following order: end bevel, end cap, start bevel, start cap.

PV tags are supported but all NURBS patch primitives will get the same set of tags.[*]

 

Trim Object

Trimmed Swing Object Example

The Trim object may be used in hierarchies of tool objects to trim NURBS patch providing objects otherwise unavailable to trimming like e.g. a Revolve object.[*]

See also the image above which depicts the swung surface example object further trimmed by a Trim object.

The first child of the Trim object is the NURBS patch providing object and the second object is the trim curve (defined in the parametric space of the NURBS surface). More curves and loops may follow. All parameter curves must obey the rules for trimming as outlined in section Trim Curves. The surface may already be trimmed and there may be multiple provided patches, however, only one of them will be trimmed by the Trim object.

The object hierarchy of a Trim object, thus, looks like this:

+-Trim
 | Surface(Revolve)
 | Trim_1(NCurve)
 +-[Trim_2(Level)
 | | NCurve
 | \ NCurve
 | ...
 \ Trim_n(ICurve)]

The following table briefly lists some capabilities of the Trim object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
TrimNPatch / NCurve+/ Level+YesNPatchNo

Trim Object Capabilities

TrimAttrib Property

The following parameters control the trimming process:

Conversion Support

The trimmed surface may be converted to an ordinary NURBS patch using the main menu entry "Tools/Convert".

RIB Export

Trim objects will be exported as NURBS patch primitives:

RiNuPatch(...);
PV tags are currently not supported.

4.8 Polygonal and Subdivision Objects

These objects complement the Ayam feature set and allow objects modelled in the polygonal or subdivision modelling paradigms to be included in Ayam scenes.

 

PolyMesh Object

PolyMesh Example

The PolyMesh object may be used to include objects that have been modeled using the polygonal modelling paradigm in Ayam scenes. See the image above for a simple example.

There are just a few special modelling actions for this type of object (see section PolyMesh tools), but its control points can be selected and modified as it can be done 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 (see also the image above, showing a polygonal mesh with one pentagonal face and a triangular hole). 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 the tesselation, Ayam uses 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 single triangles in PolyMesh objects will lead to a real waste of memory. The merge tool (main menu "Tools/PolyMesh/Merge") can be used to combine many PolyMesh objects into a single PolyMesh object.

The following table briefly lists some capabilities of the PolyMesh object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
PolyMeshNoYesSDMeshYes

PolyMesh Object Capabilities

PolyMeshAttr Property

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

Conversion Support

PolyMesh objects may be converted to SDMesh objects using the main menu entry "Tools/Convert".[*]

Note that no verification of the usability of the mesh as base mesh for a subdivision surface is carried out. Usually, such meshes have to be manifold and may not contain T-junctions.

RIB Export

PolyMesh objects will be exported as RiPointsGeneralPolygons primitives (regardless of whether the actual configuration would fit into a simpler polygonal primitive of the RenderMan interface, e.g. a RiGeneralPolygon).

PV tags are supported.

 

SDMesh Object

SDMesh object with original polygonal mesh (blue)

The SDMesh object may be used to include objects that have been modeled using the subdivision modelling paradigm in Ayam scenes (see also the image above).

There are no special modelling actions for this type of object, but its control points can be selected and modified as it can be done 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.

Unless the "subdiv" plugin (available since Ayam 1.19) is loaded, Ayam is not able to do the subdivision and show the resulting smooth surface. All that is shown in wire-frame and shaded views is the original polygonal mesh.

The following table briefly lists some capabilities of the SDMesh object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
SDMeshNoYesPolyMeshYes

SDMesh Object Capabilities

SDMeshAttr Property

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

Conversion Support

SDMesh objects may be converted to PolyMesh objects.[*]

Note however that only the original, unrefined, control polygon (i.e. the base mesh) will be converted unless the "Level" attribute is not zero and the "subdiv" plugin is loaded.

RIB Export

SDMesh objects will be exported as subdivision mesh primitives:

RiSubdivisionMesh(...);
PV tags are supported.

4.9 Script and Custom Objects

These objects create/modify arbitrary other objects from scripts or define entirely new object types via the custom object plugin mechanism.

 

Script Object

Script Object Example

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 using small scripts that are embedded in the Script objects themselves.

Those small embedded scripts may employ functionality from Tcl and the Tcl scripting interface of Ayam (see also section Scripting Interface). See also the image above, depicting a simple example script object that creates a NURBS curve and puts the control points of the curve in a circle in the XY-plane while continuously offsetting in Z so that a spiral forms. This example is also distributed with Ayam.

Script objects may also use arbitrary, plugin provided, scripting languages, like JavaScript, provided by the "jsinterp" plugin (see also: JavaScript Scripting Interface).[*]

Script Object Usage

The script of a Script object will be run each time the script is modified and each time the notification callback of the Script 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+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, selOb, plb_update, undo!

If a script fails, the Script object will be disabled by means of the "Active" attribute.[*] Furthermore, the script line where the error occurred will be highlighted.

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 (menu entry "Special/Tags/Add Property"). The script itself is responsible for data management and property GUI creation (see section ScriptAttr Property below).

There is also a tag type to remove properties ("RP").[*] Using this tag, the actual script code can be hidden and thus users are blocked from unintentionally changing it.

Starting with Ayam 1.16, the environment for running Script objects scripts has been refined to allow more complex scripts (that traverse the scene or use the clipboard) to be written:
When a script is running, the current level is the child level of the respective Script object. Furthermore, the object clipboard is saved for running the script and re-established after the script finished, and the "CreateAtMark" option is disabled.

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. In addition, there are example scene files using Script objects in the "ayam/scn/scripts" directory.

The following table briefly lists some capabilities of the Script object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
ScriptAny+NoAny+No*

Script Object Capabilities

ScriptAttr Property

This section discusses the available Script object types and additional controlling parameters.

Safe Interpreter

In Ayam versions prior to 1.16 Script object scripts could use any functionality of Tcl, Tk, and the Tcl scripting interface of Ayam which posed a huge security risk. This is no longer the case. Script objects scripts now run in a safe interpreter with reduced instruction set. They can no longer write to the file system, get onto the network, or confuse the application state. Direct access to Tk is also completely blocked, but Script objects still can have their own property GUIs (refer to the examples below).

In particular, the following Tcl commands are not available in the safe interpreter: cd, encoding, exec, exit, fconfigure, file, glob, load, open, pwd, socket, source, unload; auto_exec_ok, auto_import, auto_load, auto_load_index, auto_qualify, unknown (the missing unknown and autoloading facilities lead to further unavailability of commands normally available via autoloading, like e.g. parray, history).
The puts command is available in a limited fashion: only access to the stdout and stderr channels is allowed.

Ayam scripting interface commands that directly manipulate the user interface are also not available (uS, rV etc.). Please refer to the documentation of the scripting interface commands about their availability in the safe interpreter (see section Procedures and Commands).

In addition, access to global variables deserving protection like env, ay, ayprefs is not allowed. In fact, the safe interpreter has a completely separate set of variables. Transfer of data between both interpreters must be arranged manually from the Ayam interpreter (i.e. with scripts that run in the Ayam console).

With the help of scripts, that run in the Ayam interpreter, more commands may be transferred to or made available in the safe interpreter. But this may, of course, open security holes again.

Full access from Script objects to the complete scripting interface may be re-enabled by recompiling Ayam. If this is enabled and scene files containing Script objects are loaded, Ayam will raise a warning dialog, offering to temporarily disable all Script objects that will be read. The Script objects will be disabled using their "Active" Script object property and may be enabled again after careful inspection of the script code manually or using the main menu entry "Special/Enable Scripts".

Transformation Support

Even though, initially, Script objects do not show and use the Transformations property, they can support transformations under certain circumstances. To enable this support, a NP tag with the value "Transformations" must be added to the Script object (i.e. the Transformations property must be visible in order to be effective).
Now, the result(s) of the script can, additionally, be manipulated by the standard interactive modelling actions, like move or scale.

Note, that upon provide or conversion the transformations from the Script object will be added to the transformations of the objects created by the script in the same way as by the delegate transformations tool, which fails for complex setups. However, this problem can be avoided by using the "applyTrafo" command on the created objects in the script.

Conversion Support

Script objects convert to the objects they create/modify using the main menu entry "Tools/Convert".

When converting in place, some special rules are in effect:
if there is just one created/modified object, its tags are appended to the tags of the Script object and its material setting only takes precedence if there is actually a material set.
If there are multiple created/modified objects, the Script object is transformed into a Level object, keeping its tags and material settings. The created/modified objects will become children of the new Level object (with tags and material properties unchanged).
The current children of the Script object will be removed prior to conversion. If this fails (e.g. due to references), they may end up in the object clipboard.

When the script created a master object and instances of this master, normal conversion will not be able to duplicate this relationship (due to the copy semantics of instance objects, see also section Instances and the Object Clipboard). To get around this, just copy the Script object and then use in place conversion on the copy.

RIB Export

Script objects will be exported to RIB files as the objects they create/modify.

Script Object Examples

This section illustrates the development of a Script object for parametric lines, otherwise unavailable in Ayam.

We start with a simple version, that first creates a NURBS curve object with two control points and then places the control points each at +/- half the desired line length on the X-axis. Just copy the following code to the Script property of a Script object of type "Create", and activate it.


set length 1
crtOb NCurve -length 2
sL
setPnt 0 [expr {-$length/2.0}] 0.0 0.0 1.0
setPnt 1 [expr {$length/2.0}] 0.0 0.0 1.0

Simple Script for Parametric Line Primitive

This code works, but if lines of a different length than 1 are needed, the user must edit the script which is not very convenient and error prone.
A complete, easy to use, and safe GUI for the length parameter can be added by changing the script code to:


# Ayam, save array: LineAttrData
if { ![info exists ::LineAttrData] } {
    array set ::LineAttrData {
        Length 1
        SP {Length}
    }
}
if { ![info exists ::LineAttrGUI] } {
    set w [addPropertyGUI LineAttr]
    addParam $w LineAttrData Length
}
set length $::LineAttrData(Length)
crtOb NCurve -length 2
sL
setPnt 0 [expr {-$length/2.0}] 0.0 0.0 1.0
setPnt 1 [expr {$length/2.0}] 0.0 0.0 1.0

and by adding a "NP" (new property) tag to the Script object with the value "LineAttr", resulting in a new clickable graphical user interface as can be seen in the following image:

Parametric Line Primitive with Parameter GUI

The GUI setup code creates a Tcl array essential to manage the data of an Ayam object property (LineAttrData). Then, the LineAttr property GUI is created and a GUI element is added to the GUI using "addParam". Note that the "addPropertyGUI" command expects for a property named "SomePropertyName" a corresponding property data array named "SomePropertyNameData" to exist. The GUI setup code should just run once, therefore it checks for the presence of the variable LineAttrGUI (which is set on the first run of "addPropertyGUI") first. See also sections Property GUI Management and Global Property Management and Data Arrays for more information about property GUIs and the Ayam scripting interface.

Finally, to enable saving of the parameter value in the new property "LineAttr" to scene files, a comment must be prepended to the script ("Ayam, save array: LineAttrData"), and to enable multiple and individually parameterised copies of this Script object, a "SP" entry needs to be added to the "LineAttrData" array as well.

The complete script is also available as example script file "scripts/crtlinegui.tcl" in the Ayam distribution.

In addition, a second example demonstrates the scene traversal and hierarchy building capabilities available to Script objects since Ayam 1.16.

Create a Script object, and add two children to it, a box and a NURBS curve (order 2, knot type: chordal works best). Then add the following script to the Script object:


# this script needs object type "Modify" and two children:
# a box/sphere and a curve
withOb 1 {estlenNC len}
cutOb
crtOb Clone
goDown -1
pasOb -move
goUp
sL
getProp
set CloneAttrData(NumClones) [expr round($len)]
setProp

This little script first determines the length of the curve, then it creates a Clone object and moves the children of the Script object to it (via the object clipboard). Finally, the Clone object is parameterised, so that the trajectory is completely filled (assuming that each copy of the first child needs one length unit on the trajectory) with objects. The curve can now be modified using interactive modelling actions, or its length can be changed, and the trajectory will always be completely filled with an appropriate number of box objects. See example image below (compare the Clone configurations from the two different trajectory curves):

Hierarchy Building Script Object Example

 

Custom Objects Management

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

Custom objects may also define own modelling tools. Those can usually be found in the "Custom" main menu.

Unlike other modelling helper plugins, custom object plugins will be loaded automatically with the scene files that contain such objects. Note, that this only works properly if the preference option "Main/Plugins" is correctly set.

Several custom object plugins are already distributed with Ayam. Those are documented in the next sections.

 

SfCurve (Superformula Curve) Object

The SfCurve object creates a superformula curve from four parameters named m, n1, n2, and n3 (see also the image below). The superformula is a generalization of the superellipse; in polar coordinates it is defined as:

r(t) = (cos((m·t)/4)n2 + sin((m·t)/4)n3)-(1/n1)

where r is the radius and t the angle. The SfCurve object allows to specify start and end values for t as well as the number of sample points in between.
The generated NURBS curve is always closed, but the order may be configured freely.

Superformula Curve from Parameters 10, 22, -11, 3

The following table briefly lists some capabilities of the SfCurve object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
SfCurveNoNoNCurveNo*

SfCurve Object Capabilities

SfCurveAttr Property

The SfCurve object provides the following parameters:

Conversion Support

The superformula curve may be converted to an ordinary NURBS curve using the main menu entry "Tools/Convert".

RIB Export

SfCurve objects never directly appear in RIB output (only indirectly as trim curve).

 

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)]

The following table briefly lists some capabilities of the MetaObj and MetaComp objects.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
MetaObjMetaComp+YesPolyMeshNo
MetaCompNoNoN/ANo

MetaObj/MetaComp Object Capabilities

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).

MetaObjAttr Property

The following attributes control the creation of the implicit surface:

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 resources.

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

MetaCompAttr Property

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

Metaball

Torus

Cube

Custom

Conversion Support

Metaball objects may be converted to PolyMesh objects using the main menu entry "Tools/Convert".

RIB Export

Metaball objects will be exported as RiPointsGeneralPolygons primitives (regardless of whether the actual configuration would fit into a simpler polygonal primitive of the RenderMan interface, e.g. a RiGeneralPolygon).

PV tags are currently not supported.

 

SDNPatch Object

SDNPatches, l: control mesh, m: subdivided mesh with knot, r: subdivided mesh without knot

The SDNPatch custom object is available since Ayam 1.16 and allows to model with Subdivision NURBS, which extend the traditional subdivision schemes with knot values (see also the image above, where in the middle mesh a knot value has been set in the left hand side of the mesh). The SDNPatch plugin is based on libsnurbs by Tom Cashman.

There are some special modelling actions for Subdivision NURBS defined (see below) and there are PLY import/export facilities. Furthermore, there are two conversion operations that convert NURBS patch and PolyMesh objects to SDNPatch objects. Thus, SDMesh objects may be converted in two steps to SDNPatch objects, first to a PolyMesh then to the SDNPatch.

Please note that the plugin is still in experimental state, there is limited error checking and crashes may occur, if the special modelling actions are used.

The following table briefly lists some capabilities of the SDNPatch object.

TypeParent ofMaterialConverts to / ProvidesPoint Edit
SDNPatchNoYesPolyMeshYes

SDNPatch Object Capabilities

SDNPatchAttr Property

The SDNPatchAttr property allows to set the following SDNPatch specific attributes:

SDNPatch Modelling Actions

This section, briefly, explains the special modelling actions defined for the SDNPatch custom object. In order to select a face or edge for such an operation, just select all the control points defining the face or edge. All modelling actions can be started via the "Custom/SDNPatch" main menu.

In addition, there are two conversion operations that convert NURBS patch objects (or NURBS patch providing objects) and PolyMesh objects (or PolyMesh providing objects) to SDNPatch objects.

Note that the PolyMesh to SDNPatch conversion only accepts closed quadrilateral polygon meshes (triangles are omitted) and expects an optimized mesh (i.e. adjacent faces should share the same vertices).

Conversion Support

SDNPatch objects may be converted to PolyMesh objects using the main menu entry "Tools/Convert".

RIB Export

SDNPatch objects will be exported as RiPointsGeneralPolygons primitives (regardless of whether the actual configuration would fit into a simpler polygonal primitive of the RenderMan interface, e.g. a RiGeneralPolygon).

PV tags are currently not supported.

4.10 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".

 

Transformations Property

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

The corresponding property GUI contains the following elements:

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

How to use 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 principal 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 occurred.

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 by y-angle degrees then around Z by z-angle degrees. In fact, no information about the order in which partial rotations occurred may be derived from that three values. This implies, that e.g. the values 0 0 45 may actually denote a different orientation than the very same values 0 0 45.

Rotating an object is easy, simply add the amount about which the object shall be rotated to the value currently displayed in the appropriate entry.

For example, if an object is to be rotated 45 degrees about X and the x-angle entry displays a 30, enter 75. Then press the apply button.
If multiple entries are changed 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 unless 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 orientation) is simple too: enter 0 for all three entries at once, then press apply.

To copy just the orientation of an object to other objects using the property clipboard, all Translate and Scale property elements should be marked/selected via double clicks, then "Edit/Copy Property" can be used. Just marking the Rotate elements and then using "Edit/Copy Marked Prop" will not work, because then the quaternion will not be copied properly.

 

Attributes Property

The "Attributes" property of an object contains currently:

 

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:

 

Shader 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 available 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, i.e. they represent the arguments of the shader function.

Shader Parsing

Parsing a shader incorporates detecting the type of the shader and reading the names, types, and default values of all shader arguments.

Shaders will be parsed on the following occasions:

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.

Some 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. For instance, 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 shader source 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.org/") 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. Additionally, the compiled shader will be parsed again and the property GUI will be adapted (new shader arguments will appear, removed shader arguments will disappear). 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. Beware! This works properly only, if the type of existing shader arguments does not change and if no shader arguments are removed in the new version of the shader.

It is also possible to just copy certain parameter values (shader arguments whose types do not change) 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).

 

Caps Property

Many tool object have a "Caps" property to easily close the created surface.

Cap Property of NPatch Object

The exact names of the attributes available in this property are object type specific as each object types boundary names are different: the boundary names of a Skin object are e.g. "Left", "Right", "Start", and "End", whereas the boundary names of a NPatch object are "U0", "U1", "V0", and "V1" (see also the image above).

To reduce GUI clutter, initially, the Caps property only contains buttons that allow to enable/disable the associated cap and control appearance of further options.

For each enabled cap a menu button will appear that allows to set the corresponding cap type (see section CapAttr Property for more information on the available cap types).

In addition, the Caps property allows to create caps that integrate with the progenitor surface of the corresponding tool object (after the potential integration of bevels) via the additional parameter "Integrate". However, integration is only supported for the cap types "Simple" and "Simple3D". If integration is enabled and there is a bevel that is not integrating with the progenitor surface, the cap will integrate into the bevel instead. Integration will change the number of provided objects and the parameters of the progenitor surface.

 

Bevels Property

Many tool object have a "Bevels" property to easily round the otherwise sharp borders of the created surface.

Bevel Property of NPatch Object

The exact names of the attributes available in this property are object type specific as each object types boundary names are different: the boundary names of a Skin object are e.g. "Left", "Right", "Start", and "End", whereas the boundary names of a NPatch object are "U0", "U1", "V0", and "V1" (see also the image above).

To reduce GUI clutter, initially, the Bevels property only contains buttons that allow to enable/disable the associated bevel and control appearance of further options.

Many attributes of the Bevels property are also available for the Bevel object (see also BevelAttr Property). In addition to those attributes, the Bevels property allows to integrate the created bevel surface with the progenitor surface of the corresponding tool object via the additional parameter "Integrate". Integration will change the number of provided objects and the parameters of the progenitor surface.

 

Tags Property

Use the "Tags" property to edit the tags of an object. See also the image below.

Tags Property GUI with Context Menu

All tag entries have a context menu, where the corresponding tag can be copied/added to the property clipboard.[*]

Long and multiline tag values will be displayed in abbreviated fashion (with an ellipsis – ...).

The tags property GUI also consists of the following standard elements (see also above image):

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

4.11 Tags

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.

Tags may be manipulated via the tags property GUI (see section Tags Property) or the scripting interface.

The following two tables contains a compact list of tag names and short explanations, for all tag types that are known in Ayam and in all accompanying extensions (plugins); tag types marked with an asterisk (*) are for internal use only.

NameDescription
ANSAfter Notify Script
AsWireX3D export control
BNSBefore Notify Script
BPBevel Parameter
CPCap Parameter
CIDRImportance Driven Rendering
CCIDRImportance Driven Rendering
DANSDisabled After Notify Script
DBNSDisabled Before Notify Script
DCDepth Complexity
HCHas Children*
IDRImportance Driven Rendering
IIDRImportance Driven Rendering
MIMaterial ID*
MNMean Normal
mnmaster name*
MPMean Point
NMNotify Master*
NONotify Object*
NoExportExport Control
NPNew Property
NTNormals Tangents

Tags Overview (1/2), * – internal

NameDescription
OIObject ID*
PVPrimitive Variable
RiAttributeRenderMan Export
RiDisplayRenderMan Export
R3IDRImportance Driven Rendering
RIDRImportance Driven Rendering
RiHiderRenderMan Export
RiOptionRenderMan Export
RPRemove Property
SaveMainGeomGeometry Management
SavePaneLayoutGeometry Management
SPSelected Points
TCTexture Coordinates
TMTransformation Matrix*
TPTesselation Parameters
UMMU Min Max
VMMV Min Max
XMLXML Data

Tags Overview (2/2), * – internal

 

RiAttribute Tag

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

"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").

Example

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

Notes

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 the scene. This is handy if a renderer with lots of RiOptions that differ from the standard RiOptions is in use. 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.

Example

RiOption
radiosity,steps,i,16

RiOption
shadow,bias0,f,0.01

Notes

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 when the GUI is used. Furthermore, the database of RiOptions for this GUI may be extended by editing the ayamrc file, see section Ayamrc File.

 

TC (Texture Coordinates) Tag

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

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.

Example

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.

Notes

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

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, the texture coordinates of entire primitives are changed. To change the texture coordinates of sub-primitives (e.g. of single control points of a NURBS patch) "PV" (Primitive Variable) tags must be used instead.

To ease setting of "TC" tag values Ayam provides a special graphical editor as outlined below.

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 space.

The "FlipS" and "FlipT" buttons flip the texture coordinate values in s and t direction respectively. This is useful, if, for example, a texture mapping shall be corrected 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 to:

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

The texture coordinate dialog is mode-less, it may stay open while modeling.

 

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 texture coordinates can be attached 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 RenderMan renderer before it is handed over to the surface 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. For RIB export, proper "RiDeclare" statements will be created automatically by Ayam.

However, Ayam does not check, whether the shaders actually use the data from the "PV" tag.

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 one of "uniform", "varying", "vertex", or "constant";
<type> is a single character describing the type of the data (one of "c" (color), "f" (float), "g" (float[2]), "n" (normal), "p" (point), "s" (string), or "v" (vector), 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 <ndata> 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, the respective surface shader should have a parameter "color mycolor";
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 four point NURBS patch (of order, width, and height 2), the respective surface shader should have a parameter "varying float mys".

Notes

The following data types are not supported: "i", "j". Support for the data types "n" (normal), and "v" (vector) was added in Ayam 1.17.

Not all geometric objects currently honour PV tags on RIB export. The geometric objects currently supporting PV tags are: SDMesh, PolyMesh, PatchMesh, NPatch, and BPatch. Most tool objects that internally create NPatch objects also support PV tags.[*] Mind that the same set of tags will be used for all surfaces that make up the tool object, e.g. the swept surface, its bevels, and its caps.

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, do verify the numbers and silently omit the primitive variable if there are mismatches. The RIB should be examined for the presence of the primitive variable after export, especially, if PV tags were added or edited manually.

 

RiHider Tag

The tag type "RiHider" can be used to choose and parameterise different algorithms for hidden surface removal when rendering the exported scene with a RenderMan compliant renderer. 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 output files of different type (e.g. containing depth-buffer information) to the scene or to directly control the output format when rendering the exported scene with a RenderMan compliant renderer. 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.

Example

A RiDisplay tag to add output of the depth-buffer information to the file "imagez.tif" could look like this:

RiDisplay
imagez.tif,file,z

Notes

The name will be automatically changed to "+name" on RIB export if it does not already start with a plus.

 

AsWire Tag

The tag type "AsWire" switches export of certain objects from surface to wire-frame mode. The value string of this tag is ignored. All that counts is the presence of the tag. Note that only X3D export honours this tag.

 

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) to 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.

 

SavePaneLayout Tag

The tag type "SavePaneLayout" can be used to save the relative sizes of the internal windows of the main window when Ayam runs in the single window GUI mode to a scene file. For that the scene saving code checks for the presence of a "SavePaneLayout" tag for the Root object and fills it with the current geometry information. The scene reading code checks for the presence of a "SavePaneLayout" tag for the Root object after replacing a scene and re-establishes the geometries of the internal windows.

 

TP (Tesselation Parameter) Tag

The tag type "TP" can be used to save tesselation parameters to objects of type "NPatch" (and objects that may be converted to "NPatch" objects). 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: "<smethod>,<sparamu>,<sparamv>[,<refinetrims>]" where
<smethod> is an integer value between 1 and 6, describing which sampling method to use (1 – ParametricError, 2 – PathLength, 3 – DomainDistance, 4 – NormalizedDomainDistance, 5 – AdaptiveDomainDistance, and 6 – AdaptiveKnotDistance) and
<sparamu> and <sparamv> are float values describing the respective parameter value for the chosen sampling method. The second parameter value is ignored for the sampling methods 1 and 2.

The last value, "refinetrims", is an integer between 0 and 5 controlling how many times the trim curves are to be refined before tesselation for improved tesselation fidelity along trim edges. The "refinetrims" value may be omitted and defaults to 0.

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/Surface/Tesselate" (see also section Tesselation Tool).

Example

A TP tag could look like this:

TP
1,0.5,0.6

 

DC (Depth Complexity) 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 (New Property) 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.

Example

NP
Transformations
This tag can e.g. be added to Script objects that create objects.

Any script controlled property GUI of a Script object must also be enabled using a NP tag like this:

NP
MyProperty

Notes

NP tags can be managed more easily using a specialized dialog that is available in the main menu "Special/Tags/Add Property".

 

RP (Remove Property) Tag

The tag type "RP" (remove property) may be used to remove GUI access to a property from single objects. The value of the tag is the name of the property to be removed. The GUI access will be blocked by simply omitting the property from the property listbox. Note well: the property is still present and active in the objects themselves and values may still be set using the scripting interface.

Example

RP
Script
removes direct access to the Script property of a Script object. Ideally, the Script object also has a "NP" tag, to allow direct control of script parameters. This way, the user does not see the script (code), just a clean parameter GUI.

Here is another example: the tag

RP
Transformations
can be added to Instance objects to turn them into references (instances without own transformation attributes).

Notes

RP tags can be managed more easily using a specialized dialog that is available in the main menu "Special/Tags/Remove Property".

 

BNS (Before Notify Script) Tag

The tag type "BNS" (before notify script) may be used to add scripts to an object, that will be run before the notification of that object starts. A notification, in turn, will be executed because e.g. one of the children of the object changed (see also section The Modelling Concept Tool-Objects). When the script runs, the respective object with the BNS tag will already be selected. Current level and selection will be restored when the script finishes, neither need to be done by the script.

Example

A simple BNS tag could look like this:

BNS
puts "notify callback about to fire"

A more useful example (that is also available as example scene "ayam/scn/scripts/bnstag.ay"):

BNS
getProp;set ::RevolveAttrData(Sections) ...
... \[expr int(\$::RevolveAttrData(ThetaMax)/10)\];setProp
This tag computes the number of sections from the ThetaMax value of a Revolve object. Whenever the ThetaMax is changed, the number of sections adapt, so that each section always spans the same angle. The backslash characters are only necessary when entering the script in the add/edit tag dialog. They merely avoid that the dialog evaluates the expr command. The function call int() is needed because the C code for the setProp command of the RevolveAttr property only looks for integer data in the variable Sections and without int() the variable would contain incompatible floating point data.

Here is another shorter example; the BNS tag

BNS
applyTrafo -all
makes sure, that a NCurve or NPatch object always has the default transformations, as any changes to the transformation attributes will immediately be applied to the control points and the transformation attributes will be reset in the progress.

Notes

In Ayam versions prior to 1.16 BNS tag scripts could use any functionality of Tcl, Tk, and the Tcl scripting interface of Ayam which posed a huge security risk. This is no longer the case. BNS tag scripts now run in a safe interpreter with reduced instruction set. They can no longer write to the file system, get onto the network, or confuse the application state, see also section Safe Interpreter. Consequently, the warning dialog that appeared when files with BNS tags were loaded is also gone.

The original functionality can still be re-enabled by recompiling Ayam. If this is enabled and scene files containing BNS tags are loaded, Ayam will again raise a warning dialog, offering to temporarily disable all such tags that will be read for obvious security reasons. To disable a BNS tag, Ayam simply changes its type from "BNS" to "DBNS" (disabled before notify script). It will not be executed then. Disabled notify script tags may be enabled after careful inspection by simply changing their type back to "BNS" or by using the main menu entry "Special/Enable Scripts".

If the script of a BNS tag fails, the tag will be disabled by changing the type to DBNS.[*]

Also note that BNS tag scripts must not change the scene hierarchy, i.e. they must not create or delete objects or use the object clipboard.

 

ANS (After Notify Script) Tag

The tag type "ANS" (after notify script) may be used to add scripts to an object, that will be run after the notification of that object completed. The notification, in turn, will be executed because e.g. one of the children of the object changed (see also section The Modelling Concept Tool-Objects). When the script runs, the respective object with the ANS tag will already be selected. Current level and selection will be restored when the script finishes, neither need to be done by the script.

Example

A simple ANS tag could look like this:

ANS
puts "notify callback completed"

Notes

In Ayam versions prior to 1.16 ANS tag scripts could use any functionality of Tcl, Tk, and the Tcl scripting interface of Ayam which posed a huge security risk. This is no longer the case. ANS tag scripts now run in a safe interpreter with reduced instruction set. They can no longer write to the file system, get onto the network, or confuse the application state, see also section Safe Interpreter. Consequently, the warning dialog that appeared when files with ANS tags were loaded is also gone.

The original functionality can still be re-enabled by recompiling Ayam. If this is enabled and scene files containing ANS tags are loaded, Ayam will again raise a warning dialog, offering to temporarily disable all such tags that will be read for obvious security reasons. To disable a ANS tag, Ayam simply changes its type from "ANS" to "DANS" (disabled before notify script). It will not be executed then. Disabled notify script tags may be enabled after careful inspection by simply changing their type back to "ANS" or by using the main menu entry "Special/Enable Scripts".

If the script of a ANS tag fails, the tag will be disabled by changing the type to DANS.[*]

Also note that ANS tag scripts must not change the scene hierarchy, i.e. they must not create or delete objects or use the object clipboard.

 

UMM/VMM (U/V Min Max) 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 (Bevel Parameters) Tag

The tag type "BP" (bevel parameters) is used by all bevel supporting tool objects to store their bevel information. See also sections Bevels property and BevelAttr Property.
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, to add the bevel to,
<type> is an integer value 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

 

CP (Cap Parameters) Tag

The tag type "CP" (cap parameters) is used by all cap supporting tool objects to store their cap information. See also sections Caps property and Capttr Property.
The syntax of the CP tag is:

"<side>,<type>,<integrate>,<fraction>"
where
<side> is an integer value from 0 - 3 defining the side of the surface, to add the cap to,
<type> is an integer value from 0 - 3 defining the type of the cap,
<integrate> determines whether to integrate the cap into the progenitor surface (0 or 1)
<fraction> a floating point parameter value for the Simple3D cap type.

Example

A CP tag could look like this:

CP
0,0,0,0.5

 

MN (Mean Normal) Tag

The tag type "MN" (mean normal) can be added to the Bevel object to control the mean/target normal of the "RoundToNormal" bevel mode. The tag value is a list of three comma separated floating point numbers, a 3D vector. The vector does not have to be normalized.

Example

A MN tag could look like this:

MN
0.0,1.0,0.1

 

MP (Mean Point) Tag

The tag type "MP" (mean point) can be added to the Cap object or objects with caps to control the middle point of the "Simple" and "Simple3D" caps. This is useful if e.g. the automatically calculated mean point of the parameter curve is off. The tag value is a list of three comma separated floating point numbers, a 3D vector, followed by an integer value between 0 and 3 designating the cap. On Cap objects, the cap number may be omitted.

Example

A MP tag could look like this:

MP
0.5,0.25,0.1,0

 

XML Tag

The tag type "XML" can be used to enrich XML based export formats with arbitrary user defined data (attributes and nodes).[*] It can currently only be added to Material and NURBS surface objects for X3D export (see also section X3D (Web3D) Export). The value string of this tag must be a valid XML node hierarchy where the outer node specifies the target node of the XML data. Attributes of the outer node will be added to the target XML node for export, already existing attributes will be overwritten (i.e. the XML data tag will be processed after the XML export converted the corresponding Ayam object to a XML node hierarchy). Likewise, all child nodes of the outer node will be added to the matching target XML node. CDATA sections are also supported properly (this is important for GLSL shader source code).

Examples

XML tags could look like this:

XML
<Material shininess='0.7'/>

to add the shininess attribute to a Material.

XML
<Appearance>
<ComposedShader language='GLSL'>
...
</ComposedShader>
</Appearance>

to add a GLSL shader to a Material.

 

Internal Tags

The following tags are used by Ayam internally only; they will not appear in the tags property GUI and they can not be deleted or changed using the scripting interface.


Next Previous Contents