Ayam: Miscellaneous

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 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.4 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". 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.5 Wavefront OBJ Export

Since Ayam1.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)
- NPatch (with trim curves) and objects that may be converted to NPatch objects (BPatch, PatchMesh, Revolve, Sweep, Extrude, Skin, Cap, Gordon)
- 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 Wavefront OBJ 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 and possibly present primitive variable tags. Only the pure geometry information is written to the OBJ file.

## 7.6 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.7 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.8 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.9 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.10 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.11 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.12 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:

- The RenderMan Repository: `http://www.renderman.org/`

## 7.13 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:

- 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, 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