Next Previous Contents

## 2. The Ayam GUI

This section describes the user interface of Ayam.

The user interface is split into three types of toplevel windows: a main window, a toolbox and an arbitrary number of view windows. The main window displays the object hierarchy and lets you edit object properties, the toolbox window allows for easy creation of objects and starting of modelling actions. The modelling actions are then carried out in view windows, where the scene is displayed.

The whole application with all windows may be iconified (zapped) using the shortcut `<Ctrl+Z>`. If any of the windows iconified by zap is de-iconified, all other windows iconified by zap will be de-iconified as well.

## 2.1 Anatomy of the Main Window

The main window is split into three large areas:

1. an area named `"Objects:"`
2. an area labeled `"Properties:"`
3. and a text widget (the so called "Console")

The Main Window

The relative sizes of the three areas are managed by a so called paned window management. To change the relative size of the console, you may move your mouse pointer to the upper border of the console until the pointer changes and then drag the border. The same goes for the right border of the objects section.

### Objects

The label `"Objects"` may be used to switch between two representations of the object hierarchy (using a double click). It is also possible to switch between both representations using the context menu. The default representation is a tree view. The second available representation is a simple listbox (as known from The Mops). The two representations have very different properties regarding speed, use of resources, and versatility. The tree is, due to the Drag-and-Drop operations, much more versatile but also slower.

Both representations manage a so called `"current level"`. This level is the level that is displayed in the object listbox. In the tree view the current level is drawn in black while all other levels are grayed out. Selection of objects may only take place in the current level!

You will notice, that there is a first object called "Root" in the top level, even though the scene seems to be empty. See section Root Object for more information regarding this special object, and what it is good for. Note that you cannot delete or copy this object.

Tree View:

Tree View

The tree view is very complex and may be slow on slow machines (Pentium 90 class), especially when dealing with large (deep nested) scenes.

Objects may be selected using the left mouse button. Multiple selection of objects is possible using Shift and Control keys while clicking on objects.

Double clicking on objects with child objects toggles display of the child level. The same may be accomplished using single clicks on the well known plus/minus symbols in front of the name of those objects.

Drag-and-Drop operation is also possible to move objects in the hierarchy and to initiate special actions like connecting materials to objects. However, this last feature is documented in section Ayam Objects and Properties as it is object type specific.

The rightmost mouse button opens a context menu with basic tree and clipboard operations:

- `"Tree/Rebuild"` completely removes the tree nodes, rebuilds the hierarchy, and selects the root object
- `"Tree/Open"` opens all nodes with child nodes
- `"Tree/Close"` closes all nodes with child nodes
- `"Switch to Listbox"` removes the tree and replaces it with the object listbox (see below).
- `"Deselect Object"` deselects the currently selected object(s).
- `"Copy Object", "Cut Object", "Paste Object", "Delete Object"` are standard clipboard operations as documented in section main menu.

Since Ayam 1.6 the scene may be navigated and objects may be selected using the keyboard alone:

- `<Up>` and `<Down>` move the selection to the previous or next object, since Ayam 1.7 holding down the `<Shift>` key while pressing `<Up>` or `<Down>` will not move the selection, but rather extend it in the respective direction,
- `<Home>` and `<End>` select the first or last object in the current level,
- `<Right>` enters the (first) selected object,
- `<Left>` enters the parent level,
- `<Ctrl+a>` and `<Ctrl+n>` select or de-select all object in the current level. If the current level is the root level, the Root object will not be selected by `<Ctrl+a>`.
- `<Space>` toggles display of the child objects of the selected object(s).

Listbox:

Listbox

The hierarchy listbox, displays the object hierarchy of the current scene. Using this listbox you may browse through the hierarchy of the scene with your mouse and you may select one or more objects.

Browsing and selecting should be very intuitively: Use a double click to enter a level (or an object with child objects), and a single click to select objects, multiple objects may be selected using click and drag, or holding down the Shift or Control key while clicking. Keyboard operation is also possible if the listbox has the input focus.

A `".."` is displayed as the first element of the current level if you are "inside" a level or another object. A double click on the `".."` takes you to the parent level. The buttons below the listbox may be used to change the selection or to quickly jump through the hierarchy. They should be self explanatory.

The rightmost mouse button opens a small context menu:

- `"Switch to Tree"` removes the listbox and replaces it with the tree view (see above).
- `"Copy Object", "Cut Object", "Paste Object", "Delete Object"` are standard clipboard operations as documented in section main menu.

Since Ayam 1.6 the scene may be navigated and objects may be selected using the keyboard alone:

- `<Up>` and `<Down>` move the selection to the previous or next object, since Ayam 1.7 holding down the `<Shift>` key while pressing `<Up>` or `<Down>` will not move the selection, but rather extend it in the respective direction,
- `<Home>` and `<End>` select the first or last object in the current level,
- `<Right>` enters the (first) selected object,
- `<Left>` enters the parent level,
- `<Ctrl+a>` and `<Ctrl+n>` select or de-select all object in the current level. If the current level is the root level, the Root object will not be selected by `<Ctrl+a>`.

### Properties

Properties

The listbox right next to the object hierarchy displays the properties of the currently selected object.

If there are multiple selected objects, the properties listbox will display no properties at all.

Unlike the objects tree/listbox, where you can select multiple entries, only one property may be selected. If a property is selected, the associated GUI will be shown in the appropriate area (on the right hand side).

Since Ayam 1.8 the keyboard may be used to select properties, just use one of 0-9. 0 always selects the last and often object type specific property, whereas 1 selects the first property, which is often the standard transformations.

All property GUIs use more or less standardized GUI elements that are organized in list form. The lists may be scrolled if they get too long to fit into the window.

If the elements of the property GUI do not fit into the screen space defined by the current window size, Ayam will automatically resize the window when you select a property. You can toggle this behaviour using the preference setting `"AutoResize"` (see section Preferences).

If an object and a property are selected and a different object is selected, the property GUI that has the same index as the previously selected property in the properties listbox will be selected and shown. This is not necessarily a property of the same type. To avoid that or to clear the property GUI for fast browsing through the scene you may either double click on the "Properties" label or use the context menu of the properties listbox to de-select the current property.

What properties exactly will be shown, and how the GUIs look alike depends on the selected object and the selected property. This is documented in section Ayam Objects and Properties.

Here are some general remarks:

The various things that may be changed using a property GUI will normally not be applied to the object until the "Apply"-button is pressed!

You can undo all changes to the arguments of a property that have been made after the last click on "Apply" with the "Reset" button. This does, however, not use the undo mechanism of Ayam!

Note that property GUIs of custom objects may also offer interactive elements that do an instant "Apply". Most GUIs of the core objects of Ayam and the Scene object do not change anything until the "Apply" button is used, however.

If a property GUI element has the keyboard input focus (it is then usually displayed with a black rim around it), all the keyboard shortcuts for the main menu and scene navigation will have no effect until the keyboard input focus is moved away from the property GUI. You may accomplish this easily using the `<Esc>` key.

A property may be copied and pasted to another object, see the `"Edit"` menu. You can also paste properties to different types of properties (e.g. pasting parameters from a surface shader to the displacement shader) using `"Paste to selected"` in the `"Special/Clipboard"` sub-menu.

Pasting a property to multiple selected objects does work too. This is a great way to apply e.g. a surface shader to a big number of material objects, without going the long way of setting a new shader and entering parameters for it for every object.

Since you may not want to copy and paste whole properties all the time, you may mark single parameters with a double click on the labels of the parameters. The marked parameters will then be preceded by an exclamation mark.

If you now copy this property all marked parameters will be omitted.

It is also possible to copy just the parameters you marked using `"Copy Marked Prop"`.

A simple example:

Our task is to give a big number of material objects the same color, but they already have different opacity settings. Copying the complete attribute property would destroy the opacity values. We can accomplish this by copying just the color attribute, but leave all other attributes as they are:

1. Change the color of a first material object using the `"Attributes"` property GUI. (Do not forget the `"Apply"` button!)
2. Mark the color parameter as to be copied using a double click on the text `"Color"`; it should read `"!Color"` now.
3. Copy just the color parameter to the property clipboard, using `"Copy Marked Prop"` in the `"Edit"` menu or the hot key `<Ctrl+I>`.
4. Select all other material objects.
5. Paste the property using `"Paste Property"` or `<Ctrl+V>`.
6. All done!

Care must be taken when pasting incomplete properties to objects which do not have complete properties already. Do not paste an incomplete shader property to an object which does not already have the same shader!

### The Console

The third part of the main window is the console. The console is mainly for text output (informative, warning and error messages). For this, the console captures the stderr and stdout channels of the Tcl-interpreter Ayam is running in. You can also redirect all Tcl error messages that would normally cause a Tcl error requester to appear to the console using the preference setting `"Misc/RedirectTcl"` (see section Miscellaneous Preferences).

But you can also enter commands, new Tcl procedures and so on in the console. However, this is a feature for the advanced user that studied section The Tcl Scripting Interface. You need to explicitly click into the console to give it the input focus and thus enable input.

An important thing to know is that the keyboard shortcuts for the various main menu entries do not work if the console has the input focus! Instead, other keyboard shortcuts (related to the console) are in effect! How do you get out of this? Simply press `<Shift+TAB>` or click into an entry in a property GUI to move the focus away from the console and enable the main menu shortcuts again.

Note that the `<TAB>` key alone does not move the focus away from the console. `<TAB>` instead completes names of files, commands (procedures), variables and widgets. You may try this out by typing `tip` in the console, then press `<TAB>`. The console automagically completes `tip` to `tipoftheDay` (the procedure that prints out the tip of the day, just try it).

Another simple demonstration of the consoles capabilities:

- Create ten boxes by clicking on the box icon ten times.
- Select all ten boxes.
- Go to the console by clicking into it.
- Enter the following: `forAll 0 {movOb $i 0 0; rotOb [expr $i*10] 0 0}`

This example uses three procedures:

- `forAll`: allows to execute a command for each of the selected objects, or for each object in the current level if no objects are selected.
- `movOb`: moves the selected object(s).
- `rotOb`: rotates the selected object(s).

See section The Tcl Scripting Interface for a listing of all the available commands.

Note that the example uses a side effect (the variable `i` that holds the index of the currently processed object) to calculate the amount of the movement and rotation.

For more information regarding the console, please refer to the appropriate documentation by the original author Jeffrey Hobbs (see the console context menu, that you may open with your right mouse button).

## 2.2 The Main Menu

Another important part of the main window has not been discussed so far. This is the main menu bar. Note that many menu entries have keyboard shortcuts that are displayed in each entry. You can adapt the shortcuts using the file `"ayamrc"` (See section Ayamrc File).

The `File` menu deals with standard file operations:

- `New`, clears the current scene (deletes all objects) and reloads the working environment (if the preference setting `"Main/NewLoadsEnv"` is enabled).
- `Replace`, clears the current scene and closes all views, then loads a new scene from disk. All objects from the file will be read.
- `Insert`, inserts the objects and views of a ayam file into the current scene. All objects from the file will be read.
- `Save as`, saves the current scene asking for a new file name.
- `Save`, saves the scene. If the scene has not been saved before (read, you have not given it a file name) you will be asked for a file name.
- `Import Mops`, import a scene from The Mops, see section Import of Mops Scenes for more information.
- `Export RIB`, exports the current scene to a RIB, asking which camera (which view) to use.
- `Load Custom`, loads a file containing a custom object or a plugin. Depending on the OS Ayam is running on, these are files with the file name extension so or dll. See section Custom Objects for more information about custom objects.
- `Save Prefs`, save the current preference settings to the ayamrc file after making a backup copy of this file (see section Ayamrc File for more information about this file).
- `1.`,`2.`,`3.`,`4.`, immediately replace the current scene with the one in the menu entry. The menu entries are updated and rotated upon successful loading and saving of a scene.
- `Exit!`, remove all temporary files, save preferences (if the preference setting `"Main/AutoSavePrefs"` is turned on) and quit the application.

The `Edit` menu contains object and property clipboard operations, undo actions, and lets you open the preferences editor:

- `Copy`, copies the currently selected object(s) into the clipboard.
- `Cut`, moves the currently selected object(s) into the clipboard.
- `Paste`, copies the object(s) from the clipboard to the current level of the scene. Note that the content of the clipboard remains intact after this operation, this means that you can paste multiple times! You can move objects out of the clipboard using the menu entry `"Special/Clipboard/Paste (Move)"`.
- `Delete`, removes the selected object(s) from the scene.
- `Copy Property`, copies the currently selected property of the currently selected object to the property clipboard (the property clipboard is completely independent from the normal object clipboard!). Marked parameters will be omitted!
- `Copy Marked Prop`, copies the currently marked parameters of the currently selected property of the currently selected object to the property clipboard (the property clipboard is completely independent from the normal object clipboard!).
- `Paste Property`, copies a property from the property clipboard to the currently selected object(s).
- `Undo`, perform undo operation (see section The Undo System for more information)
- `Redo`, perform redo operation (see section The Undo System for more information)
- `Material`, searches for the material object currently associated with the selected object and selects it for editing. If the selected object has no material yet, a new material will be created first.
- `Master`, searches for the master object of the currently selected instance object and selects it for editing, see also section Instance Object.
- `Preferences`, opens the preferences dialog (see section Preferences for more information).

The `Create` menu entries let you create objects. In contrast to the object creation via the toolbox some menu entries present you with small requesters, where you may adjust parameters for the object to be created. Here are the entries of the `Create` menu:

- `NURBCurve`, create a new NURBS curve. A small dialog box will pop up, where you may specify the length of the new curve. See also section NCurve Object.
- `ICurve`, create a new interpolating curve. A small dialog box will pop up, where you may specify the length of the new curve. See also section ICurve Object.
- `NURBPatch`, create a new NURBS patch. A small dialog box will pop up, where you may specify the width and height of the new patch. See also section NPatch Object.
- `BPatch`, create a new bilinear patch. See also section BPatch Object.
- `PatchMesh`, create a new patch mesh. See also section PatchMesh Object.
- `Solid`, create a new solid primitive object, for use in CSG. `Box,` `Sphere`, `Disk`, `Cone`, `Cylinder`, `Torus`, `Hyperboloid` or `Paraboloid` may be selected. See also section Quadric Primitives.
- `Level`, creates a new hierarchy object. `Level` just groups objects, `Union`, `Intersection`, `Difference`, and `Primitive` are CSG operations. See also section Level Object.
- `Light`, create a new light source. See also section Light Object.
- `Custom Object`, create a new custom object. If this sub-menu is empty no custom object has been loaded yet. See also section Custom Object.
- `Instance`, create an instance of the currently selected object, see section Instance Object for more information regarding instances.
- `Clone`, create a clone object, see section Clone Object
- `View`, a new View window will be opened. See also section View Object.
- `Material`, create a new material. A small dialog box will pop up, where you have to specify the name of the new material. See also section Material Object.
- `Camera`, create a new camera. Camera objects may be used to temporarily save view camera settings, see section Camera Object.
- `RiInc`, create a new RIB-include object. Those objects may be used to include objects into your scenes that just exist as a piece of RIB, see also section RInc Object.

The `Tools` menu:

- `Create`, `NURBCurve`, and `NURBPatch`, are sub-menus with various NURBS based modeling tools, that are explained in depth in section NURBS Modeling Tools.
- `PolyMesh`: sub-menu for polygonal mesh related tools:
  - `Merge`: merges all currently selected PolyMesh objects into a single PolyMesh object, without checking for doubly used points, loops, or faces. Normally, the currently selected PolyMesh objects will not be changed by this tool. But you may let the merge-tool delete them immediately, if you enable the `RemoveMerged`-option. If the `OptimizeNew`-option is enabled, the `Optimize`-tool (see below) will be started after the merge operation with the newly created merged object as argument.
  - `Optimize`: optimizes the selected PolyMesh object(s) by removing all multiply used control points (if the option `OptimizeCoords` is enabled) or multiply used faces (not implemented yet). If the option `IgnoreNormals` is enabled, the optimize-tool will consider points with equal coordinates but differing normals to be equal (and optimize them). Removing multiply used control points using the `Optimize`-tool may decrease the memory consumption of the control points by a factor of about six, depending on the connectivity of the original mesh.
- `Show`, `Hide` set and unset the `Hide` attribute of the selected object(s) thus making them invisible. Note that hidden objects may be excluded from RIB-Export, when the preference setting `"RIB-Export/ExcludeHidden"` is activated.
- `Show All` and `Hide All` set and unset the `Hide` attribute of all objects in the scene (including the root object and all views!) regardles of the currently selected objects (and without changing the current selection). These operations are not undoable.
- `Convert`, starts the convert action that has been registered for the type of the selected object(s). The exact behaviour depends on the type of the selected object(s): a Revolve object will e.g. be converted to a level containing NURBS patches that make up the surface of revolution and the caps. This operation is not undoable, i.e. the newly created objects will not be removed by using the undo system.
- `Convert (In Place)`, starts the convert action as outlined above, but replaces the original objects with the new converted ones. This operation, in contrast to the simple conversion, is undoable.
- `Force Notification`, force the notification callbacks of all selected objects (or all objects in the scene if no objects are selected) to be called. The notification callbacks are used by objects like e.g. Revolve to be informed about changes of their child objects to properly adapt to those changes.
- `Highlight Material`, colours all objects of the same material in red color in the tree view. This tool expects a selected material object or a normal object that has a material attached. It will not work for material objects that are not registered or have no normal objects that refer to them. It will also not work for objects that have no material assigned. If the reference counter of a material object is not zero, but `"Highlight Material"` reports 0 objects found, the referring objects probably reside in the object clipboard. You can clear the tree view again by pressing `<Ctrl+l>`.

The `Custom` menu is initially empty. Custom objects and plugins, may create entries here.

The `Special` menu:

- `Save Selected as`, saves just the currently selected objects to disk. Note that Ayam will not check, whether the objects are saved with their materials. It is also possible to save instance objects without their master objects. This will lead to errors while loading such a scene later on.
- `Save Environment`, saves the root object and all views to a so called environment scene file, which is read on program startup and `"File/New"`. Initially, the file requester that asks for the name of the new environment uses the value of the preference setting `"Main/EnvFile"`. Note that there will be no check whether loading of that environment on next start up is enabled in the preferences. Note also, that using `Save Environment` you can just save environment files that contain the root object and all views. If you want to include geometric objects in your environment or if you want to exclude the root object and just save views you have to use `"File/Save"` or `"Special/Save Selected as"` respectively.
- `Clipboard/Paste (move)`, moves objects from the clipboard back to the scene (clearing the clipboard). This is the only way to get referenced objects out of the clipboard.
- `Clipboard/Paste Property to selected` paste the property from the property clipboard to the currently selected property of the currently selected object. No type check of the properties will take place! You may e.g. copy the settings from a displacement shader to a surface shader (as long as the copied arguments of both shaders have the same names and types).
- `Points/Select All Points`, selects all points of the currently selected object(s).
- `Points/Invert Selection`, selects all points of the currently selected object(s) that are not selected, and de-select all points that are currently selected.
- `Points/Apply To All`, applies the transformations encoded in the transformations property of the selected objects to all points of those objects. This will have the effect of resetting the transformations property to the default values without transforming the points.
- `Points/Apply To Selected`, applies the transformations encoded in the transformations property of the selected objects to the selected points. This will reset the transformations property without transforming the selected points. The points currently not selected will be transformed, however!
- `Instances/Resolve all Instances`, converts all instances of the current level (and its child objects) to normal objects.
- `Instances/Automatic Instancing`, pops up a small dialog box, where you may parameterize and start the automatic instantiation algorithm (that automatically creates instances from equal objects). See section Automatic Instancing for more information regarding automatic instancing.
- `Tags/Add RiOption`, pops up a small dialog box, where you may select and parameterize a RiOption tag to add as tag to the Root object (see RiOption Tag). The Root object does not have to be selected, and the current selection will not be changed by this action.
- `Tags/Add RiAttribute`, pops up a small dialog box, where you may select and parameterize a RiAttribute tag to add as tag to the currently selected object(s) (see RiAttribute Tag).
- `Tags/Edit TexCoords`, opens the texture coordinates editor. (see also section TC (TextureCoordinates) Tag).
- `Select Renderer` opens a dialog where the renderer for direct rendering from a view may be choosen. The changes will have effect on all options that control direct rendering from a view, except whether RenderGUIs should be used. If the `"ScanShaders"` checkmark is activated, Ayam will additionally try to load the corresponding shader parsing plugin (see also section Shader Parsing Plugins)) and rescan for compiled shaders. Note that in order for the `"ScanShaders"` feature to work properly you also have to set the `"Main/Shaders"` and `"Main/Plugins"` preference setting correctly (see also section The Main Preferences).
- `RIB-Export/From Camera`, writes a complete RIB of the current scene with the camera transformations taken from the currently selected camera object. The size of the rendered image will be taken from the RiOptions of the root object. If they are zero, default values of 400 pixels width and 300 pixels height will be used. The type of the projection written will be perspective. Otherwise the RIB looks exactly the same as if exported via main menu `File/Export RIB`.
- `RIB-Export/Selected Objects`, exports only the selected objects to a RIB. Note that instances will always be resolved, hidden objects and objects with `"NoExport"` tags are treated as on normal export operations, and light objects are simply ignored. Note also that this RIB, since it e.g. lacks camera transformation and WorldBegin/End directives, may not be rendered directly by a RenderMan compliant renderer (unless the renderer is really forgiving about mis-structured RIBs). The main use of this feature is to let you create RIBs that may be easily included in other RIBs using e.g. ReadArchive.
- `RIB-Export/Create ShadowMaps`, creates the shadow maps for the current scene. See also section Using ShadowMaps.
- `Toggle ToolBox` closes or opens the toolbox window (see The Tool Box Window). From version 1.3 on, Ayam remembers the state of the toolbox in the saved preferences.
- `Toggle TreeView` toggles object tree view and object listbox. From version 1.3 on, Ayam remembers whether the tree view or the object listbox is open in the saved preferences (see also section Objects for more information about both representations).
- `Zap Ayam` iconifies all currently open windows of Ayam. If one of the iconified windows is de-iconified later, all other zapped windows will be de-iconified as well.

The `Help` menu:

- `Help`, opens a web browser and displays the documentation, the URL to display is taken from the `Docs` preference setting.
- `Help on object`, opens a web browser and displays documentation about the currently selected type of object, the URL to display is derived from the `Docs` preference setting, this feature will not work with frame redirects e.g. `http://www.ayam3d.org/`; use `http://ayam.sourceforge.net/docs/` or a `file:`-URL as base URL in the `Docs` preference setting instead!
- `Show Shortcuts`, displays some important shortcuts for modeling actions, you may leave this window open when doing your first steps in modeling with Ayam.
- `About`, displays some version, copyright, and trademark information.
- `Show Tooltips`, enables tool tips (balloon help) for various user interface elements (including the tool box buttons).

## 2.3 Anatomy of a View

A View Window

The view window is split into a menu bar and a OpenGL-widget, where interaction and drawing takes place. The title of the view window gives information about name, current type, and action of the view.

## 2.4 The View Menu

Here are all meny entries of the `"View"` menu:

- `Quick Render`: the scene is exported to a RIB using the camera settings of the current view; then the `"QRender"` command (see the preferences) will be called. Note that the RIB export will override the RiOption settings for image size and use the current window size instead. Also note that the environment variable `SHADERS` will be adapted to the preference setting `Shaders` for rendering.
- `Render`: the scene is exported to a RIB using the camera settings of the current view; then the `"Render"` command (see the preferences) will be called. Note that the RIB export will override the RiOption settings for image size and use the current window size instead. Also note that the environment variable `SHADERS` will be adapted to the preference setting `Shaders` for rendering.
- `Redraw`: forces the OpenGL-widget to be drawn, this is particularly useful if automatic redrawing of the view has been disabled.
- `Export RIB` exports the scene to a RIB. This does exactly the same as the main menu entry `Export RIB`, except that the current view is already selected in the dialog box.
- `Open PPrev`, `Close PPrev`: those menu entries are just available, if the compile time option `AYENABLEPPREV` has been set. This option is not set for the official Ayam binaries. Permanent preview (PPrev) continuously writes a RIB stream to a (fast) RenderMan renderer, a frame for each redraw operation of the view window that was used to open the the preview. This way, the RenderMan renderer immediately displays all changes in the scene. This is a great way to test many different camera or light settings without the need to manually start a rendering process and close the preview window for each different setting. As the RIB client library usually is not able to handle more than one open RIB stream, RIB-Export and direct rendering from view windows is not available until the permanent view window is closed.
- `Create ShadowMaps`: creates the shadow maps for the current scene. See also section Using ShadowMaps.
- `Close`: the View window will be removed.

The `"Type"` menu entries:

- `Front`
- `Side`
- `Top`
- `Perspective`
- `Trim`

may be used to change the type of the view, which restrains the scope of certain modeling actions. See sections View Object and View Window Shortcuts and Actions for more information.

The `"Configure"` menu may be used to change preferences of the view. Some preferences are outlined in greater detail in section ViewAttrib.

- `Automatic Redraw`, toggles whether the view should be redrawn, whenever the scene changes. If this is disabled, you can force a redraw using `View/Redraw`.
- `Drawing Mode` determines whether the view should draw a wireframe representation (`Drawing Mode/Draw`) or a shaded one (`Drawing Mode/Shade`) or, new in Ayam 1.6, a representation where the curves of the draw mode are drawn over the shaded representation (`Drawing Mode/ShadeAndDraw`).
- `Draw Selection only`, if this is enabled, just the currently selected objects (and their children) will be drawn.
- `Draw Level only`, if this is enabled, just the objects of the current level (and their children) will be drawn.
- `Draw BGImage`, if this is enabled, a background image will be drawn.
- `Set BGImage`, may be used to set the current background image of the view, which should be a TIFF file. You can also set this image using the view attribute `BGImage`.
- `Draw Grid`, if this is enabled the grid will be drawn.
- `Use Grid`, if this is enabled the grid will be used to constrain modeling actions to grid coordinates.
- `Set Gridsize`, may be used to change the size of the grid associated with this view. Another way to change the grid size is to use the grid menu on the rightmost side, see below.
- `Half Size`, change width and height to the half of the current values.
- `Double Size`, change width and height to the double of the current values.
- `From Camera`, copy camera settings from the currently selected camera object to the view.
- `To Camera`, copy camera settings to the currently selected camera object from the view.
- `Set FOV`, lets you specify a field of view value for the view, and adapts the zoom accordingly. This is just working for perspective views, of course.
- `Zoom to Object`, adapt the camera settings, so that the currently selected objects are centered in the view.
- `Align to Object`, align the view to the coordinate system of the currently selected object or to the parent object of the current level if no object is currently selected.
- `Edit Local`, if this is enabled modelling will take place in local object space and not in world space. The grid will be changed accordingly (interpreted as if defined in the local coordinate space). See also section Editing in Local Space.

The `"Grid"` menu may be used to change the current grid size:

On the right hand side in the menu bar there is a little icon that displays the current grid size. You may click on the icon to display a menu with predefined grid size values. Choosing one of the values 0.1, 0.25, 0.5, or 1.0 will set the grid size of the view to the value and additionally switch on drawing of the grid and snapping to the grid. The last entry, however, will set the grid size to 0.0 and switch off drawing and snapping to the grid. If a gridsize other than 0.1, 0.25, 0.5, or 1.0 is in effect for the view, a different icon with a small x will be displayed in the menu instead.

### View Window Shortcuts and Actions

Important keyboard commands of a `View`:

- `<Left>`, `<Up>`, `<Right>`, `<Down>` rotate viewer around origin.
- `<Add>`, `<Sub>` (on the numeric keypad) zoom view.

Interactive actions modifying a view:

- Using `<v>` you may move the view with your mouse.
- Using `<V>` you move the camera in the direction it is looking. Note that this affects both, from and to setting of the virtual camera. Furthermore, this movement will have no visible effect in parallel views.
- `<R>` (note the case!) starts rotating the virtual camera around the point it is looking to.
- Rotating the view is also possible in any modeling mode, when holding down the `<Alt>`-key.
- `<o>` starts zooming the view. Moving the mouse up zooms in and moving the mouse down zooms out.
- Since Ayam 1.7 zooming the view into a rectangular region defined through a mouse drag is also possible in any modeling mode, when holding down the `<Shift>`-key.

You may also move the view by dragging with the rightmost mouse button and zoom the view with the middle mouse button.

If you have a wheel mouse and it is configured to send Mouse4 and Mouse5 button events, Ayam will zoom the view when you turn the wheel.

Using the menu entry `"Zoom to Object"` or the shortcut `<Ctrl+o>` you can change the views from to and zoom settings so that the selected objects will be displayed centered in the view window. This is handy, if you are e.g. searching for objects or simply lost in space.

Using the menu entry `"Align to Parent"` or the shortcut `<Ctrl+a>` you can change the views camera settings so that it is aligned to the coordinate system of the currently selected object. This is handy for modeling in local coordinate systems (e.g. editing the points of a 2D curve defined in the XY-plane that has been rotated around the Y-axis). See also section Editing in Local Space.

## 2.5 Selecting Objects within a View

When the views action is `"Pick"` you can pick objects that appear within a view. You can invoke this action by pressing `<Shift+p>` or make this action the default action using the preference setting `"Modeling/DefaultAction"`. This section describes techniques that you can use for selecting one or more objects within a view.

### Selecting Individual Objects

Selecting objects within a view is a straightforward operation that uses standard methods. You will use the following two selection operations most frequently:

- To select a single object within a view, move the cursor to the object and click mouse button 1 (the leftmost one). Once you select an object, any objects previously selected are unselected automatically.
- To select an additional object, move the cursor to the object and `<Control>`+Click (again with the leftmost mouse button). Previously selected objects remain selected, and the newly picked object is added to the selection. Notice that the picked item must belong to the same level as the previously selected objects. An alternative method for selecting multiple objects is to drag a rectangle around them. For more information see Drag-selecting Multiple Objects

### Drag-selecting Multiple Objects

You can select multiple objects using the `<Control>`+Click method described in section Selecting Individual Objects. An additional method for selecting multiple objects is to drag a rectangle around those objects. However only objects that belong to the current level can be picked within a drag-selection. If you want to select multiple objects that belong to another level you must change the current level by either selecting it in the tree/listbox or by picking one object from that level on a view.

The procedure for drag-selecting multiple objects also uses a standard method:

1. Imagine a rectangle that encloses only the objects you want to select.
2. Click at one corner of the rectangle and, while continuing to press the mouse button, drag until you have enclosed all the objects.
3. Release the mouse button. All the valid objects inside or crossing the rectangle are selected and any objects previously selected are unselected automatically.

Note that if you press `<Control>` during the drag-selection, objects that are enclosed by the rectangle will be added to the current selection instead of replacing it.

### Ambiguous Picking

In some cases Ayam is unable to differentiate between the objects you have selected and other nearby or related objects. This ambiguity can arise as follows:

- Imagine a small square surrounding the cursor. When you click an object, any other valid objects that fall inside this square are also considered to be possible selections. For example, if you select an item that is positioned very close to another one, Ayam may consider both items to be possible selections.
- If your model is three-dimensional (which is likely to happen), imagine a line that is perpendicular to the screen and that passes through the cursor and into the model. When you pick an object, any objects that intersect this line are considered to be possible candidates for selection.

List of Ambiguous Candidates

If your selection is ambiguous Ayam displays a window that contains a list of the possible candidates for selection. When you click a name in the list, the corresponding object is highlighted. Click `"OK"` when you have determined which object to select or `"Cancel"` to close the list and keep the previous selection unchanged.

Notes:

- While the list of ambiguous candidates is opened you can not pick other objects within the views.
- It is possible to use the `"Zoom to Object"` action (shortcut `<Ctrl+o>`) while the ambiguous select listbox is open to get a better view of the temporarily selected object.
- The tolerance used to determine whether an object should be picked or not can be adjusted (see `"PickTolerance"` in Hidden Preference Settings).

## 2.6 The Tool Box Window

The Tool Box

The tool window displays some buttons that start interactive modeling actions or other modeling tools, or create objects.

Note that in contrast to the keyboard shortcuts of the view windows the buttons switch to the modeling actions for all available views. For more information about the actions see section Interactive Actions.

The tool window may be configured by the user using the preference setting toolBoxList in the ayamrc file. You may select from the groups and change the order in which they appear in the tool window. See section Hidden Preference Settings for more information.

You may also resize the window to change from the vertical standard layout to a horizontal one, optimizing the use of precious screen space. After resizing, the tool box will re-layout the buttons, warning you if the space is to small for all buttons to display, and if the window is too big for the desired layout shrink wrap the window to match the size occupied by the buttons. Furthermore, using the preference setting `Misc/ToolBoxTrans` the tool box can be made transient. It will then (depending on the window manager or its configuration) get a different or no decoration, no icon, and will always be iconified when the main window gets iconified.

## 2.7 Preferences

Preferences Dialog

The preferences dialog may be opened using the main menu entry `"Edit/Preferences"` or the shortcut `<Ctrl+p>`.

Use

- `"Ok"` to close the preference editor and apply all changes,
- `"Apply"` to apply the changes, but leave the editor open,
- `"Revert"` to reset to the settings that have been loaded on program startup (these are not the factory defaults, to get back to the factory defaults, restart Ayam with the command line option `"-failsafe"`!),
- `"Cancel"` to close the dialog without applying changes (done after the last press of `"Apply"`).

The preferences are divided into five sections.

### The Main Preferences

The `"Main"` section contains the most used preference settings:

- `"Shaders"` contains a number of paths (separated by `":"` on Unix and `";"` on Win32) where Ayam looks for compiled shaders (e.g. files with the extension `".slc"` that have been compiled with slc from BMRT). Using the `"Add"` button, you may add another path, simply press it and select a file inside the directory you want to add. Note that currently the filename of a compiled shader may contain just two `"."` at maximum. The environment variable SHADERS will be adapted to match the contents of this preference setting, so that renderers started by Ayam see exactly the same shaders as Ayam.
- `"Scan for Shaders!"` initiates a rebuild of the internal shaders database. All shaders in the directories specified by the `"Shaders"` entry will be scanned and entered in that database. Watch the console for error messages that may appear while scanning. See also section Shader Parsing for more information on scanning shaders.

The next sub-section contains GUI (user interface) related settings.

- `"Locale"`, sets a language for the balloon help texts, the default value menu shows all currently available locales. The value will have no effect until Ayam is restarted!
- `"AutoResize"` toggles, whether the main window should be resized horizontally according to the property GUI whenever a new GUI is displayed.
- `"AutoFocus"` controls whether Ayam should automatically move the focus to a view or the main window, when the mouse pointer enters it. Note that this may only work correctly, when a window of Ayam already has the focus. Notice also, that moving the focus to a window might also raise it (depending on your operating system or window manager).
- `"TwmCompat"` changes, how Ayam tells the window manager new geometries of windows. Might be useful, if you suffer from jumping windows.
- `"ListTypes"` determines, whether the type of an object should be displayed in brackets in the tree view or listbox.
- `"MarkHidden"` determines, whether hidden objects should be marked (using a preceding exclamation mark) in the tree view or object listbox.
- `"AutoSavePrefs"`, if this is switched on, Ayam will write the preferences settings to the file ayamrc when the program quits.
- `"BakOnReplace"`, if this is switched on, Ayam will make a backup copy of each scene file it loads via main menu `"File/Replace"` or via the most recently used list.
- `"LoadEnv"`, if this is switched on, Ayam will load the scene file specified by `"EnvFile"` on startup.
- `"NewLoadsEnv"`, if this is switched on, Ayam will load the scene file specified by `"EnvFile"` also when the scene is cleared using the main menu entry `"File/New"`.
- `"EnvFile"`; This file typically contains some view objects to create a standard 2-, 3-, or 4-view working environment and is automatically loaded upon startup of Ayam (if the preference option `"LoadEnv"`, see above, is switched on) and upon clearing the scene using `"File/New"` (if the preference option `"NewLoadsEnv"`, see above, is switched on).
- `"Scripts"` is a list of Tcl scripts that will be executed on startup. The scripts have to be specified with full path and filename. If non absolute paths are used they are relative to the current directory of Ayam on application startup (which is typically the directory where the Ayam executable resides). Multiple entries have to be separated by a colon (:) on Unix and by a semicolon (;) on Win32.
- `"Plugins"` is a list of directories that contain custom objects or plugins. Those directories will e.g. be searched for custom objects when unknown object types are encountered while reading Ayam scene files. If a matching custom object is found, it will be automatically loaded into Ayam, so that scene loading may proceed without an error. Multiple entries have to be separated by a colon (:) on Unix and by a semicolon (;) on Win32.
- `"Docs"` is an URL that points to the documentation in HTML format.
- `"TmpDir"` is the directory, where temporary RIBs are created, e.g. when rendering directly from view windows.

### Modeling Preferences

The next section of the preferences, `"Modeling"`, contains modeling related settings:

- `"PickEpsilon"` is used by the single point editing actions to determine which point (vertice) of an object has been selected. A smaller `"PickEpsilon"` means more exact picking. The value of `"PickEpsilon"` should be positive. In older versions of Ayam (prior to 1.8), a value of 0.0 was allowed. This is no longer the case.
- `"LazyNotify"` determines whether notification shall occur on all mouse movements or just on release of the mouse button, for the interactive modeling actions. Notification is the mechanism used to inform objects that rely on certain child objects (e.g. the Revolve custom object) about changes of their child objects, so that the parent can adapt to the child objects automagically.
- `"EditSnaps"` determines, whether points should be snapped to the grid when a grid is defined and in use for the single point modeling actions.
- `"Snap3D"` controls, whether points that are snapped to grid coordinates (in single point editing actions, when grids are active) should be influenced in all three dimensions, or just the two dimensions determined by the type of the view
- `"FlashPoints"` controls flashing of editable points in the single point modeling actions when they would be modified by a click and drag action. Note that a change of this preference option takes effect after the current modeling action has been switched off and the single point editing has been activated (again).
- `"DefaultAction"` determines the modelling action that should be active after a press of the `<Esc>` key.
- `"UndoLevels"` determines the number of modeling steps that should be saved in the undo buffer. Useful values range from 2 to 50 (depending on how much memory you like to spend). If you set `"UndoLevels"` to -1, the undo system will be disabled completely. For more information, see also the section The Undo System.

### Drawing Preferences

The preferences in the `"Drawing"` section let you specify how objects are being drawn:

- `"Tolerance"` is in fact GLU sampling tolerance, used to control the quality of the sampling when rendering a NURBS curve or NURBS patch using GLU. Smaller tolerance settings lead to higher quality. Useful values range from 1 to 100. This setting has no effect for objects that override it using a local tolerance setting different from 0.
- `"DisplayMode"` sets the display mode for NURBS patches. Either the control hull (or control polygon) is drawn (ControlHull), or just the outlines of the polygons created by the tesselation (OutlinePoly), or just the outlines of the patch (OutlinePatch). Note that this setting just affects the drawing of patches if the view is not in shaded mode. Note also, that this setting has no effect for objects that override it using a local DisplayMode setting different from "Global".
- `"NCDisplayMode"` sets the display mode for NURBS curves, The control hull (control polygon) or the curve or a combination of both may be displayed. Note that this setting has no effect for objects that override it using a local DisplayMode setting different from "Global".
- `"UseMatColor"` determines, whether the shaded representation uses the color defined by the material of an object for rendering.
- `"Background"`, `"Object"`, `"Selection"`, `"Grid"`, `"Tag"`, `"Shade"`, and `"Light"` let you set colors that will be used when drawing or shading.

### The RIB-Export Preferences

The `"RIB-Export"` section of the preferences contains settings that affect how RIBs are created.

- `"RIBFile"` allows to set the file Ayam is exporting RenderMan Interface Bytestreams (RIBs) to. Note that some filenames have special meaning:

  If you set `"RIBFile"` to `"Scene"` (this is the default) the RIB file name will be derived from the name of the currently loaded scene with the last extension replaced by `".rib"`. If you set `"RIBFile"` to `"Scenefile"`, the leading path will be stripped from the scene name additionally. Use `"Scenefile"`, if you render with shadow maps. This way the scene will use relative paths to load the shadow maps and you may move the RIBs around more easily.

  `"Ask"` is another special setting, that allows to select a different filename each time you export a RIB file. A file selection dialog will pop up, after the selection of the view to export. The same effect may be achieved by leaving `"RIBFile"` totally empty!

  If you set `"RIBFile"` to `"rendrib"`, libribout.a does not create a RIB file at all, but immediately pipes the resulting byte stream into rendrib (the BMRT renderer) for rendering. The same goes for `"rgl"`. Moreover, filenames that start with a pipe symbol `"|"` will cause the program behind the symbol to be started by libribout and the written RIB to be piped into. This works e.g. with Photorealistic RenderMan, try it out with `"|render"`. In the latter cases of direct rendering, you will probably want to set up the RIB to render to the display (read leave the `"Image"` preference setting empty. However, when you use these options of direct rendering, be warned, that for the time of the rendering Ayam will be frozen (it will neither respond to mouseclicks nor will it update any windows), until the rendering is finished and the display window of the renderer is closed.

- `"Image"` specifies the image file that will be created, when you render the exported RIB file. You may set it to `"RIB"`, this will create image files that are named as the exported RIB file (with the last file extension replaced by `".tif"`). Again, setting it to `"Ask"` will cause a dialog box to appear, each time you export to a RIB file. Note that in contrast to the `"RIBFile"` option leaving the field totally empty is not equal to entering `"Ask"` but generates RIB files that will be set up to render to the display.
- `"ResInstances"`, if this is enabled all instance objects are resolved (temporarily) before being written to the RIB file.
- `"CheckLights"`, if this is enabled Ayam will check the current scene for lights before RIB export. If no lights or no lights that are actually switched on are to be found in the scene, a distant headlight will be added to the scene automatically for RIB export.
- `"DefaultMat"` determines a default material setting that should be written in the top level of the RIB, so that it is in effect for all objects, that are not connected to a material object. Many RenderMan compliant renderers will not render the objects at all, if no material is defined. The default `"matte"`, writes just a simple `RiSurface "matte"` (without parameters) to the RIB. The setting `"default"` looks for a material object named `"default"` and writes it's complete shaders and attributes, if it does not find such a material it falls back to `"matte"`. The setting `"none"` does not write any default material setting.
- `"RIStandard"` determines whether Ayam should omit all non standard RenderMan interface options and attributes on RIB export.
- `"WriteIdent"` determines, whether Ayam should write special RiAttributes (`RiAttribute "identifier" ["name"]`) with the names of the objects to the RIB to aid in RIB file debugging.
- `"ShadowMaps"` determines, whether shadow maps should be used, when writing light sources. It is not sufficient to switch this on to render using shadow maps, light sources that shall use shadow maps have to be parameterized as well, see section Using ShadowMaps. If `"ShadowMaps"` is set to `"Automatic"`, the exported RIBs will automatically render and use all shadow maps; if it is set to `"Manual"`, the shadow maps will be rendered on user request only (using the view menu entry: `"View/Create ShadowMaps"`). `"Manual"` should be used, when rendering directly from view windows with shadow maps.
- `"ExcludeHidden"` causes hidden objects not to be exported to RIB files.
- `"RenderMode"` allows to switch between two different methods of forcing a renderer to render to the screen (via a RiDisplay statement in the exported RIB, necessary for e.g. PRMan and RDC; or via a command line argument, e.g. `-d` for rendrib from BMRT).
- `"QRender"` determines the command that should be executed, upon quick rendering a view, `%s` denotes the name of the RIB file.
- `"QRenderUI"`, enables the Rendering GUI for quick rendering, see discussion of `"RenderUI"` below.
- `"QRenderPT"`, progress template for quick rendering, see discussion of `"RenderPT"` below.
- `"Render"` determines the command that should be executed, upon normal rendering of a view, `%s` denotes the name of the RIB file.
- `"RenderUI"` enables the renderer user interface (Rendering GUI), which consists of a simple progress bar, a label that displays the estimated or elapsed rendering time, a checkbutton to control ringing the bell when the rendering is finished, and a cancel button. This GUI is displayed when a renderer is invoked directly from a view window using the `"Render"` view menu entry (or the equivalent keyboard shortcut). Proper work of this GUI depends on the existence of two external programs: `"cat"` and `"kill"` (those programs should be available on every Unix platform). If you do not have those programs in your path, do not enable the RenderUI option. On the Win32 platform you may also use an internal kill command `"w32kill"` that has been introduced in Ayam 1.4. See also section Hidden Preference Settings.
- `"RenderPT"` is a string that contains a progress output template used by Ayam to determine the current percentage of completion of the rendering for display in the Rendering GUI. The special symbol `"%d"` denotes the position of the percentage number in the output of the renderer. For rendrib from BMRT2.6 this should be set to `"R90000 %d"` and the special command line option `"-Progress"` should be used. For rendrib from BMRT2.5 it should be set to `"Done computing %d"` and no special option has to be given to the renderer. If the output of the renderer contains variable strings before the progress number, a second variant of parsing the output using regular expressions is available since Ayam 1.6. In this case, the progress template should be a complete regexp command for Tcl that parses the string contained in the variable named `"string"` and puts the parsed progress number into a variable named `"progress"`. Here is an example that works with Pixie-1.2.1, which outputs strings like `"fish.rib (222): - 10.00 percent"`:

      regexp -- {^.* - (\[0-9\]+)} string dummy percent

- `"SMRender"`, renderer to use for the rendering of shadow maps using the view menu entry `"View/Create ShadowMaps"`, `%s` denotes the name of the RIB file.
- `"SMRenderUI"`, enables the Rendering GUI for the rendering of shadow maps, see discussion of `"RenderUI"` above.
- `"SMRenderPT"`, progress template for the rendering of shadow maps, see discussion of `"RenderPT"` above.
- `"PPRender"` is the name of the renderer to use for the permanent preview feature (see also section View Menu). This setting is just available, if the compile time option `AYENABLEPPREV` has been set. This option is not set for the official Ayam binaries.

### Miscellaneous Preferences

The (`"Misc"`) section of the preferences contains the dreaded miscellaneous settings.

The first sub-section deals with error message handling:

- `"RedirectTcl"` controls, whether error messages stemming from Tcl/Tk should be redirected to the console, rather than be handled by Tcls sometimes annoying error handling dialog box. However, this dialog box with the built in stack trace can also become very handy, if you write and debug Tcl scripts.
- `"Logging"` determines, whether error messages should be written to the file specified by `"LogFile"`. If this is enabled, you should clear the log manually from time to time, as Ayam will always append to `"LogFile"`.
- `"LogFile"`; see above.

The last sub-section contains miscellaneous user interface related preferences:

- `"SaveAddsMRU"`; if this is switched on, saving to a file will add that file to the most recently used list in the main menu for quick access.
- `"ToolBoxTrans"`; controls whether the tool box window should be declared as a transient window of the main window. It will then, depending on the window manager or its configuration, get a different or no decoration, no icon (or no entry in the task bar on Windows), and will always be iconified when the main window gets iconified.
- `"ToolBoxShrink"`; controls whether the tool box window should automatically shrink-wrap around the calculated layout of the buttons after a resize operation.
- `"RGTrans"`; controls whether the RenderUI-windows should be declared as a transient window of the main window. See the discussion of `"ToolBoxTrans"` above for more information about transient windows.
- `"HideTmpTags"` may be used to hide tags that are marked temporary (internal tag types do so) from the tag property GUI.
- `"TclPrecision"`; this is the precision Tcl handles floating point numbers with. You may want to decrease this number to about 5 if any numbers in the entry fields are represented in an exact, but also too lengthy and hard to read fashion, like 0.4999999 instead of 0.5. Note that you may loose information in doing so. The default value used by Tcl is 12 and results in no loss of information. The default value used by Ayam is 6 and should result in a good balance between precision and readability.
- `"SavePrefsGeom"` controls when the geometry of the preferences editor should be remembered by Ayam, `"Never"`: the window is always opened in standard size, centered on the screen; `"WhileRunning"`: the window width and position will be remembered as long as Ayam is running; `"Always"`: the window width and position will be remembered in the saved preferences, thus, also surviving a restart of Ayam. Note that the height of the preferences window will always be adapted to the currently open preferences section, no matter how `"SavePrefsGeom"` is set.
- `"SMethod"`; is the sampling method used by the NURBS to PolyMesh (tesselation) facility (based on GLU V1.3+). Three methods are available: `"DomainDistance"` (the default) simply tesselates the NURBS into equally sized pieces with regard to parametric space; `"SParam"` controls the number of sampling points in u and v direction; `"PathLength"` ensures that no edge of a polygon generated by the tesselation is longer than the value specified by `"SParam"`; `"ParametricError"` ensures that the distance between the tesselated surface and the original surface is no point bigger than the value specified by `"SParam"`. Note that `"SParam"` is expressed in object space units for the last two sampling methods.
- `"SParam"`; is a parameter for the sampling method above. The default value for the sampling method `"DomainDistance"` is 10. Higher values lead to better quality and more tesselated polygons. The default value for the sampling method `"PathLength"` is 30. Smaller values lead to better quality and more tesselated polygons. The default value for the sampling method `"ParametricError"` is 0.5. Smaller values lead to better quality and more tesselated polygons.

Next Previous Contents