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:

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:

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:

7.3 Environment Variables

This section documents the environment variables used by Ayam.

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:

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:

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:

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:

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:

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:

The following transformations are supported:

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:

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:

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:

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

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:

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:

WWW resources:

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:

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