Next Previous Contents

## 7. Miscellaneous

## 7.1 The Undo System

Using the undo system you may correct mistakes you made while modeling. However, it is currently not possible to undo any changes to the object hierarchy, including clipboard and Drag-and-Drop operations. If you delete an object, it is gone! If you, accidentally, move an object using Drag-and-Drop, undo will not help! Only changes to objects are undoable. This includes changes made by modeling actions, changes made using property GUIs, but also changes to views (type changes or changes to the camera settings associated with a view).

The undo system works by storing copies of the different states of changed objects in an undo buffer. The storage space occupied by the undo buffer may be adjusted using the preferences (Prefs/Modeling/UndoLevels). Note that a value of -1 for UndoLevels completely disables the undo system. You may step backward through the saved states using `<Ctrl+z>` (undo) but also forward using `<Ctrl+y>` (redo).

Several actions will completely clear the undo buffer (no undo is possible after those actions): Delete Object, New Scene, Replace Scene, and Close View.

Note that undo/redo will also modify objects that currently reside in the object clipboard if they have saved states in the undo buffer.

## 7.2 Ayamrc File

To customize Ayam the ayamrc file may be used. This file is either pointed to by the environment variable `AYAMRC` or is determined as following:

- On Unix it is `"~/.ayamrc"`, where `"~"` denotes the home directory of the current user.
- On Win32 platforms (Windows95-2000) it is `"$(HOME)/ayamrc"` if the environment variable `HOME` exists, else `"$(TEMP)/ayamrc"`.

The ayamrc file is read on each start of Ayam and saved again on exit (if the preference setting `"Main/AutoSavePrefs"` is enabled).

The ayamrc file contains:

1. preference settings (including some hidden settings that require just occasional tweaking and are not reachable using the GUI preference editor)
2. position and size of the main window and the tool box window
3. keyboard shortcuts to menu entries and modeling actions
4. RiOption and RiAttribute databases

You may edit the file by hand, but keep in mind, that the file will be parsed by Tcl. Should you, for some reason, destroy your ayamrc so that Ayam does not start correctly anymore you may start Ayam with the command line option `"-failsafe"`. When the application is left the next time, or the main menu entry `"Save Prefs"` is invoked a correct ayamrc will be created again. All preference settings will be reset to factory defaults, however!

### Changing Keyboard Shortcuts

You may adapt the shortcuts used in the GUI to your special needs using the ayamrc file. Note that if you do that the GUI (the menu entries) will adapt to your changes but certainly neither this documentation nor the tutorials! Ayam does not check for clashes! This means, the last set binding for a key will be used. On Unix, the output of the program `xev` and the manual page for the `bind` command of Tk provide helpful information about which strings may be used to describe key presses. For your convenience, the special string `"Ctrl"` will be replaced by `"Control"` before a shortcut is handed to the `bind` command.

Example:

    set aymainshortcuts(Prefs) {Ctrl-p}

sets the keyboard shortcut for opening of the preferences editor to `<Ctrl+p>`. See the ayamrc file itself for a complete listing of available shortcuts.

### Hidden Preference Settings

The ayamrc file currently contains the following adjustable hidden preference settings:

- `"Balloon"`: time in ms until the tooltip window appears (default: 1500 - 1.5s)
- `"EFlush"`: time in ms between two flushes of the error message buffer (default: 2000 - 2s)
- `"toolBoxList"`: a list of sections describing the appearance of the tool box window (default; using all available sections: `{trafo trafo2 solids misco nurbs toolobjs points nctools1 nctools2 camera misc}`)
- `"Kill"`: name of a program that kills other processes and accepts a process id as argument (used by the Rendering GUI) (default: `"kill"`) (a setting of `"kill"` will be automatically replaced by `"kill.exe"` on Win32) On the Win32 platform you may also use an internal kill command `"w32kill"` that has been introduced in Ayam 1.4.
- `"Cat"`: name of a program that can read from and write to a pipe (used by the Rendering GUI) (default: `"cat"`) (a setting of `"cat"` will be automatically replaced by `"cat.exe"` on Win32)
- `"KeepNTmpFiles"`: how many incarnations of the scene in RIB form (which actually may be split in more than one file due to e.g. instances) created by Direct Rendering should be kept on disk (default: 5)
- `"Wpclip_pastetosel"`: should `"Special/Clipboard/Paste Property to Selected"` raise a warning requester? (default: 1 - yes)
- `"DailyTips"`: a list of strings that appear as tips on startup in the console
- `"PickTolerance"`: the tolerance used to determine whether an object should be picked or not (default: 5); this setting determines the size of a rectangular area around the picked point in pixels, all objects that are inside or touch this area are considered picked
- `"MaxTagLen"`: the maximum number of characters to be displayed in the buttons in the Tag Property GUI (default: 30)
- `"Wait"`: set this to `"waitPid"` if you want to enable the work around for zombie processes created by the Rendering GUI. This is e.g. necessary for the Linux platform.
- `"Prompt"`: controls the prompt for the console. If set to an empty string a default of

      \[Undo:$ay(undoo)/Redo:$ay(redoo)\].../[file tail [pwd]]>

  will be used, which displays the name of the operations that you can undo and redo and the last component of the current directory of Ayam. You may e.g. change this to `"[pwd]>"` to see just the full path name of the current directory. If you want to display the value of a variable in the prompt (e.g. designating the current level in the scene hierarchy) you need to bind a write-trace to that variable, that calls the procedure `"update_prompt"`. This write-trace may e.g. be established using a small script: `"trace variable <vname> update_prompt"`.
- `"BackupExt"`: is the file name extension to be used for backup files. Default values are `"~"` for Unix and `".bak"` for Win32.
- `"SelXOR_R"`, `"SelXOR_G"`, `"SelXOR_B"`: determine a color value that is used for drag selection rectangles. Note that the color is not used directly but combined with the color value of already drawn pixels by XOR. The default values are 255 for the red, 128 for the green, and 0 for the blue component.
- `"IconGamma"`: this setting may be used to adapt the contrast of all icons (in view menu and toolbox) to your display gamma. If you are on a SGI it is recommended to set this to about "0.7".

### RiOption and RiAttributes Database

Using your ayamrc file, you may also adapt the database of RiOptions and RiAttributes to your rendering system.

You can then easily add those options and attributes to your scenes using tags and the main menu entries `"Special/Tags/Add RiOption"` and `"Special/Tags/Add RiAttribute"`, see also sections RiAttribute Tag and RiOption Tag.

The syntax for a new RiOption is quite simple as the following example shows:

    set riopt(runtime) { { verbosity s { "silent" "normal" "stats" "debug" } } }

This snippet sets the section `"runtime"` and adds a single option, `"verbosity"`, to it. The option is declared to be of type string using `"s"` and provided with a list of default values: `"{ "silent" "normal" "stats" "debug" }"`.

To add another option to this section, say the option `"op"` which shall be an integer value you have to change the aforementioned snippet to:

    set riopt(runtime) { { verbosity s { "silent" "normal" "stats" "debug"} }
     { op i }
    }

As you can see, it is not mandatory to provide default values. But be careful with the brackets!

Available types of parameters are:

- i: a scalar integer value
- j: a pair of integer values
- f: a scalar float value
- g: a pair of float values
- s: a string value
- p: a point in space (simply three float values), the default values (if provided) are three float values in curly braces, such as `{{0.0 0.0 0.0}{1.0 1.0 1.0}}`
- c: a color, the default values (if provided) are three float values in curly braces, such as `{{0.0 0.0 0.0}{1.0 1.0 1.0}}`

## 7.3 Environment Variables

This section documents the environment variables used by Ayam.

- `"AYAMRC"`: designates the full filename of the ayamrc file.
- `"HOME"`: path to the ayamrc file (used on Win32 if `"AYAMRC"` is not set).
- `"TEMP"`: path to the ayamrc file (used on Win32 if `"AYAMRC"` and `"HOME"` are not set); initial value of the `"TmpDir"` preference setting (used on Win32 if no ayamrc file exists).
- `"BROWSER"`: filename of the preferred WWW browser (used to display the documentation URL)
- `"NETSCAPE"`: (if `"BROWSER"` does not exist) filename of the Netscape WWW browser (used to display the documentation URL)
- `"SHADERS"`: initial value of `"Shaders"` preference setting (used if no ayamrc file exists).

## 7.4 Repair Ayam

Since Ayam1.8.2 an external Tcl script named "repairAyam.tcl" is provided that may be used to repair the application state of Ayam should it be stuck e.g. in an endless loop of Tcl error message.

On Unix systems repairAyam may be started from a shell by typing `"repairAyam.tcl"` (without the quotes); if it detects that it is running on Unix and not in Ayam it will send itself to the Tcl interpreter Ayam is running in using the send command. If this does not work as expected it may still be run as on Win32.

On Win32 you have to start repairAyam.tcl from the Ayam console using the command: `"source scripts/repairAyam.tcl"` or using the consoles context menu: `"Console/Load File"`.

The script repairAyam.tcl should be considered as a last resort, to help you save your modified objects. It will close all views, clean up the application state variables, reset the mouse cursor and the console prompt, and try to update important main window widgets. After running repairAyam.tcl you should save the scene (or just the important objects you were editing, possibly using `"Special/Save Selected"`) to a scratch file and restart Ayam.

## 7.5 Import of Mops Scenes

Mops scenes may be imported using the main menu entry: `"File/Import Mops"`.

Ayam is able to import most elements of a Mops scene except for RiAttributes attached to arbitrary geometric objects, because attributes and shaders are managed by material objects in Ayam. However, if a Mops object has a surface or displacement shader, a material object with the shaders from the Mops object and its RiAttributes will be automatically created and linked with the geometric object while importing. Only Mops objects with surface or displacement shaders are considered because otherwise a material object would have to be created for every imported Mops object. The material objects are named `"mat0"`, `"mat1"` and so on. Make sure, that the current scene in Ayam does not contain material objects with those names, otherwise Mops import will not be able to create material objects for the scene to import.

The import options `"ResetDM"` and `"ResetST"` control, whether GLU display mode and tolerance settings (see sections NCurveAttrib, and NPatchAttrib for more information about tolerance and display mode) of NURBS primitives should be reset to using global preference values (the default in Ayam) instead of using the values from the Mops scene file.

## 7.6 Import of RenderMan Interface Bytestreams (RIB)

Using the RRIB (Read RIB) plugin you may import RenderMan Interface Bytestreams into Ayam. Start importing a RIB using the menu entry `"Custom/RRIB/Import RIB"` (if this menu entry is not available, you have to load the `"rrib"` plugin using the menu entry `"File/Load Custom"` first).

The RRIB plugin supports import of the following geometric primitives:

- Quadrics (Sphere, Disk, Cylinder, Cone, Paraboloid, Hyperboloid, Torus)
- bilinear and bicubic patches and patch meshes
- NURBS patches (with trim curves)
- (general) polygons and (general) polygon meshes
- subdivision meshes (with all tags)

Furthermore, the plugin supports reading of CSG, object-instances, archives, light sources (including area-lights), arbitrary linear transformations (except shear transformations!), arbitrary RiOptions and RiAttributes, shaders (except transformation shaders and without array arguments!), and (since Ayam 1.7) arbitrary primitive variables (e.g. varying or vertex).

The RRIB plugin does not support reading of curves, implicit surfaces (blobby models), procedural objects, delayed read archives, and other calls to the RenderMan Interface not that useful for a RIB import like e.g. RiMakeTexture. Unsupported geometric primitives and other calls to the RenderMan Interface are silently ignored.

The RIB import may be controlled via different options:

- `"ReadFrame"`, specifies the number of the frame in the RIB to read. A value of -1 means, all frames are to be read. If you specify a frame number and this frame does not show up in the RIB as `"FrameBegin <yournumber>"` nothing will be imported!
- `"ReadCamera"`: if this is switched on, a Camera object will be created when the RIB plugin encounters a `"WorldBegin"`. You may drag this camera object onto a perspective View object in Ayam after import to see through the camera of the imported RIB.
- `"ReadOptions"`, controls, whether RiOptions are to be imported from the RIB to the scene. Note that those RiOptions will overwrite the current global settings in the Ayam scene.
- `"ReadLights"`, if this is enabled the lights from the RIB will be imported.
- `"ReadMaterial"`, controls, whether material objects are to be created for the imported objects. All material objects are created in a special level named `"Materials"` in the top level of the scene. The plugin tries to keep the number of generated material objects as low as possible by comparing with already existing materials in this level. This also works with material objects that exist before the RRIB plugin is invoked (as long as they reside in this special level).
- `"ReadPartial"`, this option is useful if you want to import partial RIBs (e.g. archives) that do not contain a `"WorldBegin"`. Be careful with this option (i.e. use it only if reading of a RIB fails), as it switches reading of all types of objects on, regardless of the RIB structure.
- `"ErrorLevel"`, this option controls how many error messages should be printed to the Ayam console while reading the RIB. Available values are: `"Silence"` no output except for severe errors, `"Errors"` all error messages should be printed, `"Warnings"`, all error and warning messages should be printed, and finally `"All"` all messages, even informative, should be printed. Note that in the case of serious syntactic errors of the RIB file more informative error messages are printed to the stderr channel of Ayam (which is not redirected to the Ayam console).

Note that for NURBS patches and bicubic patch meshes, points of type "P" will be promoted to "Pw". Trimming of NURBS patches by clamping the knot ranges is not supported. Furthermore, objects of type (general) polygon and polygon mesh will be promoted to general polygon meshes. Object-instances are resolved to normal objects while importing. Instances may be easily created again using Automatic Instancing (see section Automatic Instancing).

## 7.7 Wavefront OBJ Import

Since Ayam 1.8.3 a Wavefront OBJ (version 3.0) import facility is available. The corresponding main menu entry is `"File/Import/Wavefront OBJ"`.

Wavefront OBJ import supports reading of polygonal faces with vertex normals and texture coordinates (read as primitive variable tags) and freeform curves and surfaces (NURBS) with trim curves and with texture coordinates (read as primitive variable tags).

Freeform curves and surfaces of basis type bmatrix, cardinal and taylor are currently not supported. Also, import of special curves and points (e.g. curve on surface) is currently not supported. Furthermore, trimming of freeform curves and surfaces by clamping their knot ranges is not supported. No material and grouping information will be imported. Unsupported statements will be silently ignored.

The following options further control the import process:

- `"FileName"` is the name of the Wavefront OBJ file (version 3.0)
- `"MergeFaces"` controls, whether consecutive polygonal faces should be merged into a single PolyMesh object for import.
- `"MergePVTags"` controls, whether the PV tags of PolyMesh objects should be merged as well if they are subject to automatic merging (see above).
- `"OmitCurves"` if this is enabled, no freeform curves will be imported. This option does not prevent reading of trim curves!
- `"STagName"` controls the name of the PV tag to be used for the s component of the texture coordinates.
- `"TTagName"` controls the name of the PV tag to be used for the t component of the texture coordinates.

Wavefront OBJ import expects the file to be syntactically correct. It is not very good in detecting and reporting errors. If the import fails, use third party tools first (e.g. a demo version of Okino Graphics PolyTrans(R)), to check whether the Wavefront OBJ file is valid at all.

## 7.8 Wavefront OBJ Export

Since Ayam 1.7, it is possible to export scenes or objects to the Wavefront OBJ format (version 3.0). The corresponding main menu entry is `"File/Export/Wavefront OBJ"`. The Wavefront export currently supports the following primitives:

- NCurve and objects that may be converted to NCurve objects (ICurve, ConcatNC, ExtrNC)
- NPatch (with trim curves) and objects that may be converted to NPatch objects (BPatch, PatchMesh, Revolve, Sweep, Extrude, Skin, Cap, Gordon, Birail1, Birail2, Text); since Ayam 1.8.3 also Quadrics will be automatically converted to NURBS surfaces and exported
- PolyMesh and objects that may be converted to PolyMesh objects (MetaObj), faces with holes are not supported by the Wavefront OBJ format and will be tesselated to triangles for export automatically
- Box
- Instance, Clone; both will be resolved to normal objects for export as Wavefront OBJ does not support referenced geometry
- Level, CSG operations are not supported and will be written as normal Level objects, transformations will be delegated to the child objects

Since the Wavefront OBJ format does not support separate transformation attributes, all transformation attributes will be used to transform the coordinate values (the control points) of the exported objects.

The Wavefront OBJ export, currently, ignores all material information. Only the pure geometry information is written to the OBJ file. Since Ayam 1.8.3, however, texture coordinates from primitive variable tags can be exported.

The following parameters, additionally, control the Wavefront OBJ export:

- `"FileName"` is the filename of the Wavefront OBJ file;
- `"Selected"` exports only the currently selected object(s);
- `"TessPoMesh"` automatically tesselates all PolyMesh objects to triangles for export;
- `"OmitCurves"` omits all NURBS curves and NURBS curve providing objects from the exported file;
- `"STagName"` controls the name of the PV tag to be used for the s component of the texture coordinates, and
- `"TTagName"` controls the name of the PV tag to be used for the t component of the texture coordinates.

## 7.9 3DMF Import Export (MFIO) Plugin

Using the MFIO plugin you may import and export scenes from (to) the 3DMF format (version 1.0 only!) from Apple. Start importing a 3DMF file using the menu entry `"Custom/3DMF/Import"` (if this menu entry is not available, you have to load the `"mfio"` plugin using the menu entry `"File/Load Custom"` first).

Import supports the following primitives:

- Polyline, Triangle, TriGrid, Polygon, general Polygon, Box,
- NURBS curve, NURBS surface (with trim curves),
- Ellipsoid, Cylinder, Cone, Disk, and Torus.

The following transformations are supported:

- Scale,
- Translate,
- Rotate, RotateQuaternion, RotateAxis (if axis is X, Y, or Z).

Furthermore, the import plugin reads the structure of the scene from Container objects. Reference objects will be resolved to normal objects while importing. Instances may be easily created again using Automatic Instancing (see section Automatic Instancing).

The MFIO export supports the following primitives:

- NURBS curve and NURBS surface (with trim curves) including all NURBS curve/surface providing objects, such as ICurve, Skin etc.,
- Sphere, Disk, Cone, Cylinder, Torus,
- Box, and PolyMesh.

All transformations are supported and will be written as Translate, Rotate, and Scale transformations, respectively. All Instance objects will be resolved for export. Level objects (regardless of type) will be written as Container objects. If an object has a material, the color and opacity of the material will be written as DiffuseColor and TransparencyColor, if the red component has a value different from -1.

Support for import or export of lights, camera attributes as well as material attributes other than material color and opacity is currently not available.

## 7.10 The OpenNURBS IO (onio) Plugin

Since version 1.8.2 Ayam contains a plugin that may export to and import from the Rhino 3DM file format using the OpenNURBS toolkit from Robert McNeel & Associates.

Start exporting to a Rhino 3DM file using the menu entry `"Custom/OpenNURBS IO/Export"` (if this menu entry is not available, you have to load the `"onio"` plugin using the menu entry `"File/Load Custom"` first).

The export functionality of the onio plugin currently covers export of all boxes, quadrics, NURBS, instances, clones, script objects (of type `"Create"` or `"Modify"`) and objects that may be converted to NURBS curves or surfaces. Even though export of planar cap surfaces of various tool objects is supported, the export of general trimmed NURBS patches is not supported. This is because of a missing feature (pushing up 2D trim curves to 3D curves for arbitrary NURBS surfaces) in the OpenNURBS toolkit. Since Ayam 1.8.3, also PolyMesh objects may be exported.

The export process is controlled by the following options:

- `"Accuracy"`: The `"Accuracy"` option controls the tolerance of internal OpenNURBS operations (currently those are: pushing up 2D trim curves to 3D curves and checking NURBS surfaces for planarity).
- `"WriteSelected"`: exports only the selected objects.
- `"ObeyNoExport"`: ignores all objects with `"NoExport"` tags.
- `"IgnoreHidden"`: ignores all hidden objects.
- `"WriteCurves"`: If the `"WriteCurves"` option is disabled, no curves will be written to the exported Rhino file.
- `"QuadAsBRep"`: If the `"QuadAsBRep"` option is enabled spheres, cylinders, cones, and torii will not be exported as collection of NURBS surfaces (as converted by Ayam) but as BRep objects (as converted by the OpenNURBS toolkit). However, not all features of the quadric objects will be translated in this case: The BRep sphere does not support ZMin, ZMax, and ThetaMax. The BRep cylinder does not support ThetaMax (base caps will be created if the cylinder is closed). The BRep cone does not support ThetaMax (a base cap will be created, if the cone is closed). The BRep torus does not support PhiMin, PhiMax, and ThetaMax. The option has no effect on the export of disks, hyperboloids, and paraboloids. Those will always be exported as NURBS surfaces.
- `"STagName"` controls the name of the PV tag to be used for the s component of the texture coordinates, and
- `"TTagName"` controls the name of the PV tag to be used for the t component of the texture coordinates.

Since the Rhino 3DM file format does not support hierarchy and transformation attributes per object, the hierarchy of the Ayam scene will be squashed and all transformation attributes will be applied to the control points of the objects for export. CSG operations are fully ignored, all objects will be written as if combined by the union operator. Furthermore, all instance objects will be resolved to normal objects. All objects will be written to the first layer (the default layer). Object names will be written as well. Names of level objects will be prepended to the names of their child objects. The object hierarchy:

    +-Arm(Level)
     |MySphere(Sphere)
     \MyCylinder(Cylinder)

for instance, leads to two objects named `"Arm/MySphere"` and `"Arm/MyCylinder"`.

Start importing from a Rhino 3DM file using the menu entry `"Custom/OpenNURBS IO/Import"` (if this menu entry is not available, you have to load the `"onio"` plugin using the menu entry `"File/Load Custom"` first).

The import functionality of the onio plugin currently covers import of all NURBS and BRep objects and objects that may be converted to NURBS using the OpenNURBS toolkit (those are: PolylineCurve, PolyCurve, LineCurve, ArcCurve, CurveOnSurface, RevSurface, SumSurface, and PlaneSurface). References will be resolved. Names will be imported, but converted to an ASCII representation. Since Ayam 1.8.3 Mesh objects will be imported to PolyMesh objects, texture coordinates will be read and appropriate PV tags will be created.

The import process is controlled by the following options:

- `"Accuracy"`: The `"Accuracy"` import option controls the tolerance of OpenNURBS internal operations, in this case the value is mostly used for conversion operations to the NURBS form.
- `"Accuracy"`: If the `"ReadCurves"` import option is switched off, no curves will be imported.
- `"ReadLayers"`: By default, all objects from all layers will be imported. Using the `"ReadLayers"` import option, a single layer or a range of layers may be selected for import.
- `"IgnoreFirstTrim"`: Another import option is `"IgnoreFirstTrim"`, this is useful if the first bounding trim loop of NURBS surfaces should be ignored. This trim loop is often not needed, because it encloses the whole surface that is not trimmed further in many cases. Importing this trim loop will often just make the Ayam scene more complex than needed.
- `"STagName"` controls the name of the PV tag to be used for the s component of the texture coordinates, and
- `"TTagName"` controls the name of the PV tag to be used for the t component of the texture coordinates.

## 7.11 Shader Parsing Plugins

Since Ayam 1.3, the following plugins are provided to allow parsing of shaders: `"ayslb"` for Air, `"ayslx"` for Aqsis, `"ayso"` for RDC, `"ayslo"` for PRMan, `"ayslo3d"` for 3Delight, and (since Ayam 1.6) `"aysdr"` for Pixie.

After loading of one of the aforementioned plugins, Ayam will be able to parse shaders compiled with the shader compiler of the respective renderer.

A shader parsing plugin may be loaded automatically on startup of Ayam using one of the provided Tcl scripts: `"loadayslb.tcl"`, `"loadayslo.tcl"`, `"loadayslo3d.tcl"`, `"loadayslx.tcl"`, `"loadayso.tcl"`, and `"loadaysdr.tcl"`. To automatically load a plugin simply add the appropriate script to the preference setting `"Main/Scripts"` using the `"Add"` button in the preferences editor.

Additionally, those scripts may be further adapted to set a different `"Shaders"` preference setting or to immediately scan for shaders after loading of the plugin. For that, just remove the leading hash-marks (#) from the corresponding lines in the script. However, the standard behavior while loading of such a plugin requires you to adapt the shaders search path manually and to scan manually for shaders too. Both actions may be carried out using the preferences editor.

This is, however, not necessary if you load the shader parsing plugin automatically on startup of Ayam, as the loading of the scripts will happen before the startup sequence executes the initial shader scanning pass.

## 7.12 Automatic Instancing

Automatic Instancing is available via the main menu entry: `"Special/Instances/Automatic Instancing"`. Automatic Instancing creates instances from all instantiable objects from the current level and below, using a simple algorithm that recursively compares objects. The comparison of materials and tags may be turned off in the small dialog that pops up after selection of the menu entry `"Special/Instances/Automatic Instancing"`.

The algorithm is able to create instances of grouping objects too (objects with child objects, e.g. levels or tool-objects like revolve). However, in order for two grouping objects to be instantiated not only all child objects and the grouping objects have to be instantiable, but the child objects also have to be in the right order. It is not sufficient, that for every child of the potential master, a matching child of the potential instance exists. Instantiation of grouping objects may drastically decrease the total number of objects in a scene.

Note that before the automatic instantiation starts, all currently existing instances will be resolved! After instantiation some statistics will be displayed in the console.

More information about this subject can be found in:

Schultz, R., and Schumann, H.: "Automatic Instancing of Hierarchically Organized Objects", in: Kunii T.L. (ed.): Spring Conference on Computer Graphics (SCCG 2001) Conference Proceedings, Budmerice, Slovakia, 25-28 April 2001, ISBN 80-223-1606-7

## 7.13 Importance Driven Rendering (IDR)

The importance driven rendering plugin may be used to drastically reduce rendering times while developing a scene. It works in three main steps:

1. Importance values are assigned to elements of the scene.
2. Two rendering passes are started according to the assigned importance values. Elements of different importance values are mutually masked out using `"RiMatte"` statements.
3. The resulting partial images are composed to a single resulting image, which is then displayed.

The parameterisation of the two rendering passes ensures, that the total rendering time is lower than the rendering time of a single pass with high quality.

Many options exist to assign importance and parameterize the rendering passes:

Elements of the scenes may be geometric objects, regions in image space, or regions in object space. Importance values are currently just binary values. Assignment may take place manually (using IDR tags) or half-automatic by derivation of importance from currently selected or changed objects. To avoid inconsistency in the resulting images, importance values may be propagated between (geometrically or hierarchically) near objects, or between objects that are related (e.g. from a material to a geometric object).

Parameterisation of the two rendering passes currently includes selection of a different renderer and the possibility to reduce rendering resolution and shading rate. To further reduce rendering times for Raytracing renderers, the size of the region to render may be automatically adapted to the elements of the current importance value (including an optimisation run that balances renderer startup times and times needed to render regions not originally occupied by two regions to merge).

Furthermore, caching of partial images is possible. However, the implementation of this feature is not very sophisticated at the moment, as it uses the Unix text tool `"diff"` to decide whether two RIB streams are identical and hence need no re-rendering.

To start using IDR:

1. load a scene (e.g. the cactus example scene),
2. load the IDR plugin (menu `"File/Load Custom"`),
3. open the IDR control window using the main menu `"Custom/Open IDR"`,
4. set the assign mode to `"Selection"`,
5. select an object in the scene (e.g. the object named `"Pot"`),
6. then press the `"Render!"` button.

Compare the rendering time with a full render from the view window.

IDR requires that atleast the renderer of the second rendering pass honours RiMatte! Since rgl does not honour RiMatte, it is sometimes necessary to simply exclude objects of different importance value. No wrong images are to be expected from this, as rgl does not calculate other than local lighting effects.

More information about this subject can be found in:

Schultz, R., and Schumann, H.: "Importance Driven Rendering - Using Importance Information in the Rendering Process", in: Hamza M., Sarfraz M. (ed.): Computer Graphics and Imaging (CGIM 2001) Conference Proceedings, Honolulu, Hawaii, 13-16 August 2001, ISBN 0-88986-303-2

## 7.14 CSG preview using the AyCSG plugin

CSG preview example (left without, right with CSG)

The AyCSG plugin may be used to resolve and preview CSG operations. For this, the plugin uses image based CSG rendering algorithms provided by the OpenCSG library. The OpenCSG library, currently, supports the Goldfeather and the SCS algorithm. The latter only works properly with convex primitives. Since both, Goldfeather and SCS, are image based rendering algorithms, there is no limit in geometric object types that may be used in CSG hierarchies. You may e.g. use Quadrics, NURBS, and Metaballs in every possible combination. You just have to make sure, that every CSG primitive describes a closed space.

In order for the CSG rendering algorithms to work properly, the depth complexity (convexity) of a primitive must be known. The depth complexity of a primitive determines the maximum number of forward oriented surfaces any ray through this primitive would pass. A regular sphere has a depth complexity of 1, a torus of 2, but do not confuse depth complexity with genus, they are different values! A 3D representation of the letter A e.g. has a genus of 1 but a depth complexity of 3. The depth complexity of a primitive should be stored in a `"DC"` tag. A torus would e.g. get a tag named `"DC"` with the value `"2"`. If no `"DC"` tag is present for a primitive, a default value for the depth complexity of `"1"` will be used. If you fail to correctly specify the depth complexity, rendering errors, like missing parts of surfaces, will occur.

Note that the correct operation of AyCSG not only depends on the depth complexity but also the winding order of the OpenGL primitives (triangles or quads) used for drawing of the CSG primitives. The winding order has to be consistent in a scene, so that the rendering algorithm can decide what is inside and what is outside by looking at a single OpenGL primitive. For all quadric primitives of Ayam the winding order is always consistent. However, for NURBS patches the winding order depends on the orientation of the patch dimensions. If NURBS patches are used in CSG operations you, consequently, may need to revert the patches (e.g. using the `"RevertU"` tool, see Revert U tool). If the winding order of some of the primitives in a CSG hierarchy is not right, the respective primitives will not be effective in the CSG operations to the extent that the rendered image becomes completely empty.

The AyCSG rendering obeys the `"Draw Selection only"` and `"Draw Level only"` view options as well as the hide attribute of objects. If the CSG rendering fails, you might still get a preview of the important CSG using objects by selecting them and enabling the `"Draw Selection only"` view option.

Also note that CSG rendering requires fast graphics hardware (the more fillrate, the better). Furthermore, your OpenGL subsystem has to support the PBuffers extension and, depending on the rendering options chosen, a stencil buffer. Speedups may be achieved using the `"GL_ARB_occlusion_query"` or `"GL_NV_occlusion_query"` extensions (if available to you).

Once the AyCSG plugin is loaded successfully you can render the CSG preview in any view window using the keyboard shortcut `<Ctrl+Shift+c>` or using the new button in the menu bar of every view window. If you hold down `<Shift>` while pressing the button, the view will continually render CSG.

The AyCSG plugin supports the following options, that are available through the main menu entry `"Custom/AyCSG Preferences"`:

- `"Algorithm"` allows to switch between the Goldfeather and SCS algorithm. Note again that the SCS algorithm only works correctly for convex primitives. The `"Automatic"` setting chooses one of the algorithms based on whether concave primitives (depth complexity > 1) are present or not.
- `"DCSampling"` determines a depth complexity sampling strategy. Quoting from the OpenCSG documentation, the following options are available:

  `"NoDCSampling"`: Does not employ the depth complexity. This essentially makes the algorithm O(n^2), but with low constant costs.

  `"OcclusionQuery"`: Uses occlusion queries to profit implicitly from depth complexity without calculating it. This is especially useful for the SCS algorithm where this strategy is applied at shape level, resulting in a O(n*k') algorithm (where k' <= k), without significant constant overhead. This strategy requires hardware occlusion queries, i.E., the OpenGL extension `"GL_ARB_occlusion_query"` or `"GL_NV_occlusion_query"`.

  `"DCSampling"`: Calculates the depth complexity k using the stencil buffer. This makes the algorithm O(n*k), but with high constant costs. In case of the Goldfeather algorithm, the literature denotes this as layered Goldfeather algorithm.

- `"CalcBBS"` determines whether bounding boxes should be calculated and used for speed up (not working at the moment).

## 7.15 Increasing drawing speed

In case of sluggish response of the user interface of Ayam (not accounting for long tree update operations) several things to increase drawing speed can be done:

- Hide objects or complete object hierarchies using `"Hide"` in the `"Tools"` menu.
- Disable drawing of true NURBS curves/surfaces, if you can. Use the ControlHull display modes.
- If you need to see curves/surfaces, try to increase the (GLU) sampling tolerance of the objects (use a value of about 60.0).
- Switch the primary modeling view to draw just the selected object(s) or the current level.
- Iconify views you do not need, they will not be redrawn then.
- Switch off automatic redrawing of slow redrawing (e.g. shaded) views, and control their redraw by pressing `<Ctrl+d>` manually.
- Do not create unnecessary caps, they are trimmed NURBS patches that render very slowly.
- Disable `"UseMatColor"`.

## 7.16 How can you help?

1. Write/translate tutorials.
2. Implement custom objects. This will be discussed a bit more later on.
3. Donate source to improve several critical parts of the modeler, some ideas are: better (more exact) lighting simulation (is this possible to do with OpenGL at all?), CSG-preview with OpenGL, true support for subdivision surfaces. The project page of Ayam on SourceForge lists some more tasks.
4. Debug the MF3D code, which is currently not working well with binary files from different byte-order platforms.
5. Donate money by registering ShellyLib. ShellyLibs source will be converted to a first high level custom object that creates objects of type seashell for Ayam. This object, however, will be Shareware!

You can help by implementing more different high level objects like Trees, Landscape, Sky, Text, whatever you can think of. Note that the license of Ayam does not prevent you from implementing your object as Shareware or even Commercial software. However, Freeware is preferred for obvious reasons.

But please do me a favour and do not implement objects like simple triangles or polygons. This would be something that really is not intended by me, and it would surely show the limits of the current design of all code operating on the scene structure. Ayam objects should be high-level objects!

Reading the last paragraph you might think that I am a bit biased against polygonal models. I am not. Polygonal models are the only way to preview complex geometry using hardware accellerated graphics, for the moment. But even while RenderMan supports rendering of polygonal models their use as a primitive is not recommended for good reasons. In other words, use polygonal models in the modeler as quick representation of your higher level objects, but please, if you are going to actually render something, do not use that polygonal representation. If you want to go a complete polygonal way instead, voila, there are good modelers out there.

## 7.17 References

Suggested reading:

- Advanced RenderMan: Creating CGI for Motion Pictures by Tony Apodaca and Larry Gritz (Morgan-Kaufmann, 1999)
- The RenderMan Companion: A Programmer's Guide to Realistic Computer Graphics by Steve Upstill (Addison-Wesley, 1989)
- Textures and Modeling: A Procedural Approach by Ebert, Musgrave, Peachey, Perlin, and Worley (Academic Press, 1994)

WWW resources:

- Ayam Tutorial #1: `http://www.ayam3d.org/tut1/tutorial1.html`
- The Ayam FAQ: `http://www.ayam3d.org/faq.html`
- The RenderMan Repository: `http://www.renderman.org/`
- The RenderMan Academy: `http://www.rendermanacademy.com/`

## 7.18 Acknowledgements

First of all, I would like to express a big "Thank you!" to Bernd (Pink) Sieker. He is the first real Mops user and beta tester, who urged me during the last years via E-Mail and on IRC to fix this particular bug, add some essential features, move the lights again etc. pp. in countless iterations. Bernd, without your help I surely would not be that far, thanks!

Furthermore, I would like to thank the following people:

- Florian Kirsch: OpenCSG
- Bertrand Coconnier: implementation of object picking
- Hermann Birkholz: initial implementation of the tree widget, shadow map support, AI, and IDR
- Frank (Copper) Pagels: MetaBalls custom object, TTF parser, providing a lot of good music
- Stephen Echavia: Icons
- Larry Gritz: BMRT
- Benjamin Bederson, Brian Paul et. al.: The Togl Widget
- Jeffrey Hobbs: tkMegaWidget set
- Jan Nijtmans: Tcl/Tk PlusPatches, tcl2c, Wrap
- Thomas E. Burge: The Affine Toolkit
- Apple, Duet Development Corp.: 3DMF parser
- Mark J. Kilgard: GLUT
- Les A. Piegl and Wayne Tiller: The NURBS Book
- W. T. Hewitt and D. Yip: The NURBS Procedure Library
- Philippe Lavoie: The NURBS++ Library
- Everyone involved in the development of Tcl/Tk, OpenGL, The RenderMan Interface

OpenGL (R) is a registered trademark of Silicon Graphics, Inc.

The RenderMan (R) Interface Procedures and Protocol are: Copyright 1988, 1989, 2000 Pixar All Rights Reserved

RenderMan (R) is a registered trademark of Pixar

The Affine Libraries and Tools are Copyright (c) 1995, 1996, 1997, 1998 Thomas E. Burge All rights reserved.

Affine (R) is a registered trademark of Thomas E. Burge.

TIFF Software is Copyright (c) 1988-1997 Sam Leffler Copyright (c) 1991-1997 Silicon Graphics, Inc.

Next Previous Contents