Next Previous Contents

## 2. The Ayam GUI

This section describes the user interface of Ayam.

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

The whole application with all open 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.

Single Window GUI Mode

Until Ayam 1.14 all windows, main, toolbox, and views were always single top level windows – a so called floating windows GUI mode. Since version 1.14, a new GUI mode is available where the main window, three view windows and the toolbox are integrated in one top level window. This mode is called single window GUI mode, see also the image above. The new single window GUI mode is enabled by default. All sub windows are in panes, the space occupied by a sub window may be adjusted by dragging the mouse at the borderlines of the panes. The number of views is not limited to three, albeit all extra views will become extra top level windows.

The next sections document the three types of windows, main, toolbox, and views in detail.

## 2.1 Anatomy of the Main Window

The main window is split into three major 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 geometry management. To change the relative size of the console, move the 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 default representation of the object hierarchy is a tree view. The second available representation is a simple listbox (as known from `"The Mops"`). The label `"Objects"` may be used to switch between the two representations of the object hierarchy quickly (using a double click). It is also possible to switch between both representations using the context menu.

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 scene 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 take place in the current level only!

After the start-up of Ayam you will notice, that there is a first object called `"Root"` in the top level of the scene, 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 one can not delete or copy this object.

Object Tree View:

Object Tree View

The object tree view is quite complex and may be slow on slow machines (of the Pentium 90 class), especially when dealing with scenes that contain many objects. This should not be a problem nowadays. Nevertheless, Ayam tries to keep tree update delays as low as possible, but this works only if the scene uses the hierarchy and changes happen in sub levels (not the root level).

In the tree view, objects may be selected using the left mouse button. Multiple selection of objects is possible by holding down the `<Shift>` or `<Ctrl>` key 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 Objects, Properties, and Tags 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, makes the top level current, and clears the object selection,
- `"Tree/Expand All"` opens all nodes with child nodes,
- `"Tree/Collapse All"` closes all nodes with child nodes,
- `"Tree/Toggle Selected"` toggles display of all sub-levels of the selected objects,
- `"Switch to Listbox"` removes the tree view 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.
- `"Help on Object"` displays the help of the selected object.

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.
- `<Shift-Up>` and `<Shift-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,
- `<Shift+Home>` and `<Shift+End>` extend the selection to the first or last object in the current level respectively. * The root object, however, will always be omitted.
- `<Right>` enters the (first) selected object,
- `<Left>` enters the parent level,
- `<Ctrl+a>` and `<Ctrl+n>` select or de-select all objects 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).
- `<Shift+Space>` toggles display of all sub-levels of the selected object(s). *

If those shortcuts do not work you may need to move the keyboard input focus away from (internal) view windows, the property GUI, or the console using `<Tab>` or `<Shift+Tab>` first.

Another way of moving the focus (and cleaning up the application state) is by using the `<Esc>` key: In property GUIs and the console, pressing `<Esc>` moves the focus away to the main window or object selection window.

Pressing `<Esc>` twice in a view window will also reset the focus to the main window/object selection window. * Pressing `<Esc>` twice in the object selection window will additionally clear the selection (this implies removal of the currently displayed property GUI) and change the current level to the root level.

Thus, if you feel lost anywhere in Ayam, just press `<Esc>` twice or thrice.

Object Listbox:

Object Listbox

The object 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 intuitive: Use a double click to enter a level (or an object with child objects), use a single click to select objects, multiple objects may be selected using click and drag, or holding down the `<Shift>` or `<Ctrl>` 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.
- `"Help on Object"` displays the help of the selected object.

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.
- `<Shift-Up>` and `<Shift-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,
- `<Shift+Home>` and `<Shift+End>` extend the selection to the first or last object in the current level respectively. * The root object, however, will always be omitted.
- `<Right>` enters the (first) selected object,
- `<Left>` enters the parent level,
- `<Ctrl+a>` and `<Ctrl+n>` select or de-select all objects in the current level. If the current level is the root level, the Root object will not be selected by `<Ctrl+a>`.

If those shortcuts do not work you may need to move the keyboard input focus away from (internal) view windows, the property GUI, or the console using `<Tab>` or `<Shift+Tab>` first.

Another way of moving the focus (and cleaning up the application state) is by using the `<Esc>` key: In property GUIs and the console, pressing `<Esc>` moves the focus away to the main window or object selection window.

Pressing `<Esc>` twice in a view window will also reset the focus to the main window/object selection window. * Pressing `<Esc>` twice in the object selection window will additionally clear the selection (this implies removal of the currently displayed property GUI) and change the current level to the root level.

Thus, if you feel lost anywhere in Ayam, just press `<Esc>` twice or thrice.

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

Also the keyboard may be used to select properties: just press one of the `<0>-<9>` keys (most comfortably using the numeric keypad). `<0>` always selects the last and often the only object type specific property, whereas `<1>` selects the first property, which often contains 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 Ayam is in floating windows GUI mode and the elements of the current property GUI do not fit into the screen space that is defined by the main window size, Ayam can automatically resize the main window. This behaviour may be controlled 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, hit the `<Esc>` key three times, 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 comprehensively in section Objects, Properties, and Tags.

Here are some general remarks about object properties:

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

Holding down the `"Shift"` button while interacting with the property GUI or pressing `"Return"` when entry widgets have the keyboard input focus will also lead to an instant apply. *

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

Note also that property GUIs of custom objects may offer interactive elements that do an instant "Apply" operation. Most GUIs of the core objects of Ayam 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 property values 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 parameterised surface shader to a bigger number of material objects, without going the long way of setting a new shader and entering parameters for it for every material object.

Since you may not want to copy and paste whole properties all the time, you may even mark single parameters with a double click on the labels of the parameters. The selected parameters will then be preceded by an exclamation mark (!) in the property GUI.

If this property is then copied, all marked parameters will be omitted.

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

A simple example for the property clipboard:

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 individually adjusted opacity values. We can solve 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.

Special 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

Console

The third part of the main window is the console. The console is mainly for unobtrusive text output (informative, warning, and error messages). If something does not work as advertised, the console may be worth a look.

The console captures the stderr and stdout channels of the Tcl-interpreter Ayam is running in. It is also possible to redirect all internal Tcl error messages, that would normally cause a Tcl error dialog window to appear, to the console using the preference setting `"Misc/RedirectTcl"` (see section Miscellaneous Preferences).

One can of course also enter commands or even complete new Tcl procedures into the console. However, this is a feature for an advanced user that studied section 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 `<Esc>` 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).

Remember that many commands of the Ayam scripting interface work in background: without update of object selection widget, property GUI or redrawing of view windows. But one can enforce an immediate update of the GUI and redrawing of all views by using `<Shift-Enter>` instead of `<Enter>` when entering commands.

Another simple demonstration of the consoles capabilities:

- Create ten box objects 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 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 Main Menu

This section discusses the main menu bar. Note that many menu entries have keyboard shortcuts that are displayed in each entry.

Note that the main menu keyboard shortcuts only work if the main window has the keyboard input focus and the input focus is not in the console or in a property GUI element (i.e. a data entry field). Hit `<Esc>` to set the focus to the object selection widget and thus enable the main menu keyboard shortcuts.

One can adapt these shortcuts using the `"ayamrc"` file (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.
  This operation cannot be undone!
- `"Open"`, clears the current scene and closes all views, then loads a new scene from disk.

  All objects from the file will be read. A backup copy of the file will be made before loading (depending on the preference setting `"Main/BakOnReplace"`). See section Opening Scene Files for a more detailed discussion.
  This operation cannot be undone!

  Also files supported by any of the import plugins may be imported using this route. * Note that this only works if the selected file has a file name extension. The appropriate plugin will be loaded automatically (from the list of plugin directories in the preferences) if needed and the import options dialog of the plugin will be opened, with the `"FileName"` option already set. Mind that in this case, no backup copy of the file will be made. See also section Import and Export.

- `"Insert"`, inserts the objects and views of an Ayam scene file into the current scene.

  All objects from the file will be read. If the file to be inserted contains a Root or View objects, the new objects will be created in the top level of the scene. Otherwise, if just geometric objects are in the scene file (i.e. the file was created using `"Special/Save Selected"`), the new objects will be inserted in the current level of the scene. See section Inserting Scene Files for a more detailed discussion.
  This operation cannot be undone!

  Also files supported by any of the import plugins may be imported using this route. See above (`"Open"`). *

- `"Save as"`, saves the current scene asking for a new file name.

  All objects in the scene will be saved to the scene file, but if the current scene was loaded from a file without root object (and thus without view windows), root and views will be omitted from the saved scene file as well. See section Saving Scene Files for a more detailed discussion.

  Also files supported by any of the export plugins may be exported using this route. Just pick a file name with the desired extension (see above, `"Open"`). *

- `"Save"`, saves the scene. If the scene has not been saved before (the scene file name is "unnamed") Ayam will ask for a file name first.

  All objects in the scene will be saved to the scene file, but if the current scene was loaded from a file without root object (and thus without view windows), root and views will be omitted from the saved scene file as well. See section Saving Scene Files for a more detailed discussion.

- `"Import/"`, since Ayam 1.13 this sub menu is initially empty. You need to load a plugin first to gain to the menu entries described here.
- `"Import/Apple 3DMF"`, import a scene from the Apple 3DMF format, see section 3DMF (Apple) Import for more information.
- `"Import/AutoCAD DXF"`, import a scene from the AutoCAD DXF format, see section AutoCAD DXF import for more information.
- `"Import/Mops"`, import a scene from The Mops, see section Import of Mops Scenes for more information.
- `"Import/Rhino 3DM"`, import a scene from the Rhino 3DM format, see section 3DM (Rhino) Import for more information.
- `"Import/Wavefront OBJ"`, import a scene from the Wavefront OBJ format, see section Wavefront OBJ Import for more information.
- `"Import/Web3D X3D"`, import a scene from the XML based X3D format published by the Web3D Consortium, see section X3D (Web3D) Import for more information.
- `"Export/"`, since Ayam 1.13 this sub menu initially only contains the `"RenderMan RIB"` entry. You need to load a plugin first to gain access to the other menu entries described here.
- `"Export/RenderMan RIB"`, exports the current scene to a RIB, asking which camera (which view) to use.
- `"Export/Apple 3DMF"`, export a scene to the Apple 3DMF format, see section 3DMF (Apple) Export for more information.
- `"Export/Rhino 3DM"`, export a scene to the Rhino 3DM format, see section 3DM (Rhino) Export for more information.
- `"Export/Wavefront OBJ"`, exports the current scene to a Wavefront OBJ file, see also section Wavefront OBJ export.
- `"Export/Web3D X3D"`, export a scene to the XML based X3D format published by the Web3D Consortium, see section X3D (Web3D) Export for more information.
- `"Load Plugin"`, loads a file containing a custom object or a plugin. Depending on the platform Ayam is running on, these are files with the file name extension `".so"` or `".dll"`. See section Plugins Overview for more information regarding Ayam plugins.
- `"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 so that the first entry always contains the scene that was loaded (or saved) last.
- `"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.
  This operation cannot be undone!
- `"Cut"`, moves the currently selected object(s) into the clipboard.
  This operation cannot be undone!
- `"Paste"`, copies the object(s) from the clipboard to the current level of the scene.
  This operation cannot be undone! 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 (clearing it) using the menu entry `"Special/Clipboard/Paste (Move)"`. Also note that referenced objects, when moved into the clipboard with `"Cut"`, can not be moved out of it using a simple `"Paste"`, use `"Special/Clipboard/Paste (Move)"` instead! See also section Instances and the Object Clipboard.
- `"Delete"`, removes the selected object(s) from the scene.
  This operation cannot be undone!
- `"Select All"`, selects all objects in the current level (except for the root object).
- `"Select None"`, de-selects all currently selected objects.
- `"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 all property data from the property clipboard to the currently selected object(s). The data will get pasted to the property type saved by the last copy operation. It will not get pasted to the currently selected property; use `"Special/Clipboard/Paste Property to selected"` for that.
- `"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: Ayam will prompt for the name of the new material, the material object will be created, if successful, the material will be linked to all currently selected objects (even if they are already linked to other objects).
- `"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 dialogs, where you may adjust parameters for the object to be created. The entry fields in those dialogs support Tcl expressions as detailed in section Expression Support in Dialog Entries. 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. This dialog also contains a `"AddArgs"` entry field where you may specify additional command line arguments to the `"crtOb NCurve"` command, as outlined in section Creating Objects. *
- `"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. This dialog also contains a `"AddArgs"` entry field where you may specify additional command line arguments to the `"crtOb ICurve"` command, as outlined in section Creating Objects. *
- `"ACurve"`, create a new approximating curve. A small dialog box will pop up, where you may specify the length of the new curve. See also section ACurve Object. This dialog also contains a `"AddArgs"` entry field where you may specify additional command line arguments to the `"crtOb ACurve"` command, as outlined in section Creating Objects. *
- `"NCircle"`, create a new NURBS circle. See also section NCircle 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. This dialog also contains a `"AddArgs"` entry field where you may specify additional command line arguments to the `"crtOb NPatch"` command, as outlined in section Creating Objects. *
- `"IPatch"`, create a new interpolating patch. * A small dialog box will pop up, where you may specify the width and height of the new patch. See also section IPatch Object. This dialog also contains a `"AddArgs"` entry field where you may specify additional command line arguments to the `"crtOb IPatch"` command, as outlined in section Creating Objects.
- `"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.
- `"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.
- `"View"`, a new View window will be opened. See also section View 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
- `"Mirror"`, create a Mirror object, see section Mirror 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 RiInc Object.
- `"RiProc"`, create a new procedural object, see also section RiProc Object.
- `"Script"`, create a new script object, see also section Script Object.
- `"Select"`, create a new select object, see also section Select Object.
- `"Text"`, create a new text object, see also section Text Object.

The `"Tools"` menu hosts modelling tools to create complex objects or modify existing objects. Some tools open dialog windows to request parameters. The entry fields in those dialogs support Tcl expressions as detailed in section Expression Support in Dialog Entries. The entries of the `"Tools"` menu are:

- `"Last (None)"`, this menu entry allows quick access to the last used entry/tool in the `"Tools"` menu hierarchy. * The label of the entry will be changed appropriately when a tool was started, e.g. to `"Last (Revert U)"` after the `"Tools`Surface/Revert U"/-tool was used. The corresponding keyboard shortcut is `<Ctrl+t>`. To repeat the last used tool with the same set of parameters (and without opening the parameter dialog window again) the shortcut `<Ctrl+T>` can be used instead.
- `"Create"`, `"Curve"`, and `"Surface"`, are sub-menus with various NURBS based creation and modelling tools, that are explained in depth in section NURBS Modelling 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. The currently selected PolyMesh objects will not be changed by this tool. But you may let the merge-tool delete them immediately after the merging operation, by enabling 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.
  - `"Split"`: splits the faces from the selected PolyMesh objects off and into a second PolyMesh object. The faces to be split off are selected by selecting all their control points with the select points modelling action (see also section Selecting Points). The original selected PolyMesh objects will be changed, the selected faces will be removed. The changes to the original objects cannot be undone. Since the split operation does not create optimized new objects, the `"Optimize"`-tool (see below) may be started immediately after splitting using the `"OptimizeNew"`-option.
  - `"Optimize"`: optimizes the selected PolyMesh object(s) by removing all multiply used (and unused) 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.
- `"Points"`: sub-menu for tools that work on points:
  - `"Select All Points"`, selects all points of the currently selected object(s).
  - `"Invert Selection"`, selects all points of the currently selected object(s) that are not selected, and de-select all points that are currently selected.
  - `"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 (visibly) changing the points of the selected objects.
  - `"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 (visibly) changing the selected points. The points currently not selected will be transformed, however!
  - `"Center All Points (3D)"`, moves all points of the selected objects so that their common center (the center of gravity) is the center of the respective objects coordinate system. Note that, currently, this works on each of the selected objects separately!
  - `"Center All Points (2D-XY)"`, `"Points/Center All Points (2D-YZ)"`, `"Points/Center All Points (2D-XZ)"`: work like the center 3D tool but just center in the designated plane.
- `"Show"`, `"Hide"` set and unset the `"Hide"` attribute of the selected object(s) thus making them invisible or visible again. 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 can not be undone using the undo system.
- `"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 can not be undone, i.e. the newly created objects will not be removed, 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 above, can be undone.
- `"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 color from the tree view with the keyboard shortcut `<Ctrl+l>`.

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

The `"Special"` menu contains seldom used tools:

- `"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/Replace"`, replaces the currently selected object(s) with the object clipboard content, moving the replaced objects into the clipboard. If multiple objects are selected in non consecutive sequences, only the first consecutive sequence or single object is replaced.
- `"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! One 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).
- `"Instances/Resolve all Instances"`, converts all instances of the current level (and its child objects) to normal objects. If objects are selected, only those selected objects will be processed. *
- `"Instances/Automatic Instancing"`, pops up a small dialog box, where you may parameterise 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 parameterise 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 parameterise 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 (Texture Coordinates) Tag).
- `"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/RenderMan 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 the created 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. the ReadArchive directive.
- `"RIB-Export/Create ShadowMap"`, creates the shadow maps from the currently selected light source. See also section Using ShadowMaps.
- `"RIB-Export/Create All ShadowMaps"`, creates all shadow maps for the current scene (regardless of selection). See also section Using ShadowMaps.
- `"Enable Scripts"` enables all disabled script tags and objects. Objects and tags in the object clipboard are not affected!
- `"Select Renderer"` opens a dialog where the renderer for direct rendering from a view may be chosen. The changes will have effect on all preference settings 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 the `"Main/Shaders"` and `"Main/Plugins"` preference settings have to be set correctly (see also section Main Preferences).
- `"Scan Shaders"` initiates the shader parsing with the built in shader parser or the currently loaded shader parsing plugin (see also section Shader Parsing Plugins).
- `"Reset Preferences"` removes the current ayamrc file, where the preferences are saved; after a restart of Ayam, all preferences will be reset to factory defaults. See also section Ayamrc File for more information about the ayamrc file.
- `"Reset Layout"` resets the pane layout in single window GUI mode so that the upper internal views get an approximately even share of available screen space and the object selection widget and property GUI are completely visible.
- `"Toggle Toolbox"` closes or opens the toolbox window (see The Toolbox Window). From version 1.3 on, Ayam remembers the state of the toolbox in the saved preferences. This option is not available if Ayam is in single window GUI mode.
- `"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 modelling actions, you may leave this window open when doing your first steps in modelling with Ayam.
- `"About"`, displays some version, copyright, and trademark information.
- `"Show Tooltips"`, enables tool tips (balloon help) for various user interface elements (including the toolbox buttons).

## 2.3 Main Window Keyboard Shortcuts

An important group of shortcuts is available on the function keys:
`<F1>` has already been mentioned, it opens a web browser and displays the URL from the `"Docs"` preference setting.
`<F2>` and `<F3>` lower and raise the global GLU sampling tolerance value respectively, allowing fast adjustment of the NURBS drawing/shading quality.
`<F4>` toggles between display of NURBS control cage and true curves / surface outlines.
`<F5>` rebuilds the object tree and issues a complete notification. It is therefore helpful to update the complete GUI after changes made to the scene using the scripting interface in the console.
`<F6>` toggles lazy notification.

`<Ctrl+A>` is bound to the `"Apply"` and `<Ctrl+R>` to the `"Reset"` button of the property GUI.

The object selection can be manipulated by the cursor keys, see also section object tree shortcuts and section object list shortcuts.

Many main menu entries have direct keyboard shortcuts, displayed directly in the menu entries, see also section main menu.

Note that the main window keyboard shortcuts only work if the main window has the keyboard input focus and the input focus is not in the console or in a property GUI element (i.e. a data entry field). Hit `<Esc>` first to set the focus to the object selection widget and thus enable the main window keyboard shortcuts.

One can adapt all these shortcuts using the `"ayamrc"` file (see section Ayamrc File).

## 2.4 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 the currently active modelling action of the view.

The current modelling action, modelling mode, drawing mode and grid size are also displayed as a set of icons on the right hand side of the view menu bar.

## 2.5 View Menu

This section discusses the view menu bar. Note that many menu entries have keyboard shortcuts that are displayed in each entry. Those view menu keyboard shortcuts only work if the view window has the keyboard input focus. The shortcuts are adaptable using the `"ayamrc"` file (see section Ayamrc File).

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

- `"Quick Render"`: the scene is exported to a RIB file using the camera settings of the current view; then the `"QRender"` command (see the preferences) will be called. Note that the RIB export will not use the RiOption settings for image size but 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 file using the camera settings of the current view; then the `"Render"` command (see the preferences) will be called. Note that the RIB export will not use the RiOption settings for image size but 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 `"File/Export/RenderMan RIB"`, except that the current view will already be 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 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 multiple open RIB streams simultaneously, RIB-Export and direct rendering from view windows are not available until the permanent preview window is closed.
- `"Create ShadowMap"`: creates the shadow maps for the currently selected light source. See also section Using ShadowMaps.
- `"Create All ShadowMaps"`: creates all shadow maps for the current scene (regardless of selection). See also section Using ShadowMaps.
- `"Close"`: the View window will be removed. This entry is not available for the internal views of Ayam in single window GUI mode.

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 modelling actions. See sections View Object, View Window Shortcuts and Actions, and Modelling 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 the menu entry `"View/Redraw"` or the corresponding keyboard shortcut `<Ctrl+d>`.
- `"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"`).
- `"Modelling Mode"` allows to switch the modelling coordinate system from world space (`"Global"`) to the space defined by the current parent object (`"Local (Level)"`) or even the space defined by the currently selected object (`"Local (Object)"`) See also section Editing in Local Spaces.
- `"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 Object CS"`, if this is enabled, small coordinate systems (three colored lines) will be drawn at the base of each objects coordinate system.
- `"AntiAlias Lines"`, if this is enabled, all lines will be anti-aliased (smoothed).
- `"Draw BGImage"`, if this is enabled, the 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 modelling 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 icon 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.

Apart from the text based menus documented above, there are also some icon based menus in the view window menu bar:

The `"Modelling mode"` icon menu may be used to quickly change the current modelling mode (global or local, see also section Editing in Local Spaces). Apart from a different icon, the local modes will display a L or O in the lower right corner of the icon. The icon, additionally, conveys whether objects or points will currently modified by a modelling action (for points, a red dot will be present in the upper right corner of the icon). Furthermore, the type of the view will be displayed in the upper left corner of the icon as letter F, S, T, or P for front, side, top, or perspective views, respectively. Views of type trim get no designating letter in the icon. See also the image below:

Modelling Mode Icon Menu

The `"Drawing mode"` icon menu may be used to quickly change the current drawing mode, drawing, shading, or drawing and shading. See also the image below:

Drawing Mode Icon Menu

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

On the right hand side in the view 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 chosen value and will additionally enable drawing of the grid and snapping to the grid. The entry `"X"` allows to set a custom grid value. The last entry will set the grid size to 0.0 and disable drawing of and snapping to the grid. If a grid size other than 0.1, 0.25, 0.5, or 1.0 is in effect for the view, a generic icon (with a X instead of a number) will be displayed in the icon menu. See also the image below:

Grid Icon Menu

## 2.6 View Window Shortcuts and Actions

Important keyboard commands of a view window (aside from the view menu shortcuts) are discussed in this section.

Note that the view keyboard shortcuts only work if the view window has the keyboard input focus.

One can adapt these shortcuts using the `"ayamrc"` file (see section Ayamrc File).

Keyboard shortcuts directly modifying the camera, that is associated with the view window, are:

- `<Left>`, `<Up>`, `<Right>`, `<Down>` rotate viewer around origin.
- `<Shift+Left>`, `<Shift+Up>`, `<Shift+Right>`, `<Shift+Down>` pan the view.
- `<+>`, `<->`, or `<Add>`, `<Sub>` (on the numeric keypad) zoom the view.
- `<Ctrl+5>` (on the numeric keypad!) resets the views camera (From and To) to the view type dependend default values.
- `<.>` pans the view to the mark.

Interactive actions modifying the camera, that is associated with the view window, are:

- 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 modelling mode, by holding down the `<Alt>`-key.
- `<o>` starts zooming the view. Moving the mouse up zooms in and moving the mouse down zooms out.
- Zooming the view into a rectangular region defined through a mouse drag is also possible in any modelling mode, by holding down the `<Shift>`-key. *

See also the table below.

Name | Shortcut | Icon
Pan View | `<v>` |
Zoom View | `<V>` |
Rotate View | `<R>` |

View Actions Overview

You may also pan/move the view by dragging with the rightmost mouse button and zoom the view with the middle mouse button without affecting any other active view or modelling action.

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.

`<PgUp>` and `<PgDown>` allow to cycle through the view types. *

`<Ctrl+PgUp>` and `<Ctrl+PgDown>` cycle through the drawing modes. *

Using the menu entry `"Zoom to Object"` or the corresponding shortcut `<Ctrl+o>` (`<O>` for internal views) one can change the views camera settings so that the selected objects will be displayed centered in the view window. This is handy to search for objects or if the user is simply lost in space.

Using the menu entry `"Align to Object"` or the shortcut `<Ctrl+a>` (`<L>` for internal views) one can change the views camera settings so that it is aligned to the coordinate system of the currently selected object. This is handy for modelling in local coordinate systems (e.g. when editing the control points of some planar curve defined in the XY-plane that has been rotated around the Y-axis). See also section Editing in Local Spaces.

It is also possible to move through the scene hierarchy and change the selection directly in view windows: *

- `<Ctrl+4>`, `<Ctrl+6>` (on the numeric keypad!) move up and down in the hierarchy respectively, also selecting the parent or first child.
- `<Ctrl+2>`, `<Ctrl+8>` (on the numeric keypad!) select the next or previous object.
- `<Ctrl+Shift+2>`, `<Ctrl+Shift+8>` (on the numeric keypad!) extend the current selection to include the next or previous object.

## 2.7 Selecting Objects within a View

This section describes techniques that you can use for selecting one or more objects within a view window with the mouse.

When the view windows action is `"Pick"` you can pick (select) objects that appear within this view with the mouse. You can invoke this action by pressing `<P>` or make this action the default action using the preference setting `"Modelling/DefaultAction"`. If picking is the default action, it will be automatically enabled when any other action is broken using `<Esc>`.

### 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 the 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.
It is also possible to use a double click in the list of selection candidates to select an object and immediately close the dialog. *

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 `<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.8 The Toolbox Window

The Toolbox

The toolbox window displays some buttons that start interactive modelling actions, modelling tools, or create objects. You can open and close it using the main menu entry `"Special/Toggle Toolbox"`.

Note that in contrast to the keyboard shortcuts of the view windows, the buttons in the toolbox may switch to the modelling actions for all open views. This is the case if Ayam is in single window GUI mode and AutoFocus is enabled or if Ayam is in multi window GUI mode. For more information about the actions see section Modelling Actions.

When creating objects, holding down the `<Ctrl>` key while pressing the corresponding toolbox button will keep the objects selected. This is especially useful for objects that would move the currently selected objects to themselves as children (Level, Revolve, Skin etc.).

Several other tool buttons also change their behaviour with modifier keys, check the tooltips.

The toolbox window may be configured by the user using the hidden preference setting `"toolBoxList"` in the ayamrc file. Using this setting you may select from certain groups of buttons and change the order in which they appear in the toolbox window. See section Hidden Preference Settings for more information.

The toolbox is also open for extension by scripts, see section Script Examples (Toolbox Buttons) for examples.

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 toolbox will re-layout the buttons, warning you if the space is too small for all buttons to display. If the window is too big for the desired layout and the hidden preference setting `"ToolBoxShrink"` is switched on, the toolbox will shrink wrap the window to match the space occupied by the buttons. Furthermore, using the hidden preference setting `"ToolBoxTrans"` the toolbox window 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.9 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"` or use the main menu entry `"Special/Reset Preferences"`),
- `"Cancel"` to close the dialog without applying any changes. All changes done after the last press of `"Apply"` will be lost.

Note that while the preference editor is open, AutoFocus is temporarily turned off and changes to the `"AutoFocus"` preference setting will only be realized after the editor is closed.

The preferences are divided into five sections as follows.

### Main Preferences

The `"Main"` section contains the most important application setup related preference settings.

Note that unused settings will not be shown, e.g. on the Win32 platform, the `"TwmCompat"` setting will be hidden. *

- `"Shaders"` contains a number of paths (separated by a colon `":"` on Unix and by a semicolon `";"` 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 easily add another path, simply press the button and select a file from 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 through the `"Shaders"` preference setting.

  Note that this option does of course not affect any renderers that are started outside the Ayam context.

- `"Scan for Shaders!"` initiates a rebuild of the internal shader database. All shaders in the directories specified by the `"Shaders"` preference setting 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!

- `"SingleWindow"` toggles, whether Ayam should create just one main window with internal views and toolbox or use the old floating windows style GUI. The new single window GUI mode is enabled by default.
- `"AutoResize"` toggles, whether the main window should be resized horizontally according to the property GUI whenever a new GUI is displayed.

  This option is not available in the single window GUI mode.

- `"AutoFocus"` controls whether Ayam should automatically move the focus to a view or the main window, when the mouse pointer enters it. However, depending on your operating system, window manager, or their settings, this may only work correctly, when a window of Ayam already has the focus. On some operating systems or window managers AutoFocus might not work at all. Furthermore, note that moving the focus to a window might also raise it.

  In single window GUI mode, AutoFocus additionally manages the input focus of the internal views, tree view, property GUI, and console.

  While the preference editor is open, AutoFocus is temporarily turned off and changes to the `"AutoFocus"` preference setting will only be realized after the preferences editor is closed.

- `"TwmCompat"` changes, how Ayam tells the window manager new geometries of windows. This option has to be toggled if Ayam fails to correctly remember the geometry of the main window between two invocations or if the main window jumps downward when properties are selected.

  This option is not available on the Win32 platform and on MacOSX Aqua.

- `"AutoSavePrefs"`, if this is switched on, Ayam will write the preferences settings to the ayamrc file when the program quits.
- `"BakOnReplace"`, if this is switched on, Ayam will make a backup copy of each scene file it loads via the main menu entry `"File/Open"` or via the most recently used list. The backup file will be placed right next to the loaded file and get an additional file name extension according to the hidden preference setting `"BackupExt"`.
- `"AddExtensions"`, this option may be used to let Ayam automatically add file name extensions to saved files (if they do not have already a proper extension).
- `"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 hidden preference option `"LoadEnv"` is switched on) and upon clearing the scene using `"File/New"` (if the hidden preference option `"NewLoadsEnv"` is switched on). See also section Hidden Preference Settings.
- `"Scripts"` is a list of Tcl script files that will be executed on startup. The scripts do not have to be specified with full path and filename. * Furthermore, the scripts and plugins directories (as specified using the `"Plugins"` option below) are automatically searched, and the tcl file name extension is automatically added, so that a setting of `"colfocus;loadayslx"` would load the colfocus script from the scripts directory and the ayslx shader parsing plugin from the plugins directory. 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. If unsure about the correct syntax, just use the `"Add"` button.
- `"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. If non absolute paths are used they are relative to the directory where the Ayam executable resides. Thus, the default value "plugins" leads to Ayam searching for plugins in the directory "plugins" located in the directory, where the Ayam executable resides:

  > `

  >     .../ayam/bin/Ayam.exe
  >     .../ayam/bin/plugins/
  >     .../ayam/bin/plugins/ayslx.dll

  > `

  Multiple entries have to be separated by a colon (`":"`) on Unix and by a semicolon (`";"`) on Win32. If unsure about the correct syntax, just use the `"Add"` button.
- `"Docs"` is an URL that points to the documentation in HTML format.
- `"TmpDir"` is the directory, where temporary RIB files are created, e.g. when rendering directly from view windows.

The preference settings `"ListTypes"`, `"MarkHidden"`, `"LoadEnv"`, and `"NewLoadsEnv"` are hidden preference settings since Ayam 1.14, see section Hidden Preference Settings.

### Modelling Preferences

The next section of the preferences, `"Modelling"`, contains modelling related settings:

- `"PickEpsilon"` is used by the single point editing actions (see section Editing Points) to determine which point of an object has been selected. A smaller `"PickEpsilon"` means more exact picking. The value of `"PickEpsilon"` should be positive and is expressed in terms of object coordinates, however, also the view zoom factor modifies the effective `"PickEpsilon"` value in a way that for zoomed-in views a smaller value will be used (and vice versa).

  In older versions of Ayam (prior to 1.8), a value of 0.0 was allowed and default. This is no longer the case, the new default value is 0.05.

- `"LazyNotify"` determines whether notification shall occur on all mouse movements or just on release of the mouse button, for the interactive modelling actions. This option may also be toggled easily using the keyboard shortcut `<F6>`.

  Notification is the mechanism used to inform objects that rely on certain child objects (e.g. the Revolve tool object) about changes of their child objects, so that the parent can adapt to the child objects automagically (see also section The Modelling Concept Tool-Objects).

- `"CompleteNotify"` determines when notification of all objects depending on references of changed objects takes place:
  - `"Never"`, for manual control of complete notification (manual complete notification can be carried out using the main menu entry `"Tools/Force Notification"`) or using the keyboard shortcut `<F5>`;
  - `"Always"`, a complete notification is done whenever the normal notification is carried out;
  - `"Lazy"`, the complete notification runs only after a modelling action finished (when the mouse button is released).
  Note that complete notify also updates objects that implicitly depend on updated objects via instances.
- `"EditSnaps"` determines, whether points should be snapped to the grid when a grid is defined and in use for the single point modelling actions.
- `"Snap3D"` controls whether points that are snapped to grid coordinates (in single point editing actions and 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 modelling actions when they would be modified by a click and drag action. Note that a change of this preference option only takes effect for the next invocation of the single point editing modelling action.
- `"GlobalMark"` toggles whether each view should manage its own mark (off, default), or whether there should be just one global mark (on). Note that enabling this preference setting will not immediately lead to a global mark set in all windows, one rather needs to set a new mark that will then become global.
- `"DefaultAction"` determines the modelling action that will be active after a press of the `<Esc>` key in a view window.
- `"UndoLevels"` determines the number of modelling 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.

  Using the keyboard shortcuts `<F2>` and `<F3>` the GLU tolerance may also be set easily.

- `"NPDisplayMode"` 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 does not affect shaded patches.

  Note also, that this setting has no effect for objects that override it using a local DisplayMode setting different from `"Global"`.

  Toggling between drawing of hulls and outlines may also be done easily using the keyboard shortcut `<F4>`.

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

  Toggling between drawing of hulls and curves may also be done easily using the keyboard shortcut `<F4>`.

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

### 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 after the pipe 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 parameterised 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 (e.g. using the view menu entry: `"View/Create All 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 (e.g. view menu entry `"View/Create All ShadowMaps"`), see also section Using 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.
- `"SMFileFormat"`, designates the file format of the shadow maps, use `"zfile"` for RenderMan and `"shadow"` for Gelato.
- `"SMFileType"`, type of shadow maps to be created, currently available types are `"z"` – normal shadow maps (for RenderMan renderers and Gelato), `"avgz"` – Woo shadow maps (for Gelato only!), and `"volz"` – volume shadow maps (for Gelato only!).
- `"SMChangeShaders"`, toggles, whether Ayam should automatically prepend a "shader" to light shader names for lights that use shadow maps upon RIB export. Not changing the shader names is necessary for Gelato.
- `"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.

Note that you can set many renderer related preferences at once using the select renderer tool via the main menu `"Special/Select Renderer"` (see also section Special Menu). In fact, using `"Special/Select Renderer"` first, then fine tuning your renderer setup using the preferences editor is the suggested way to switch Ayam to a certain RenderMan renderer.

### 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, while writing and debugging 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.
- `"ErrorLevel"`, this option controls how many messages should be written to the Ayam console. Available values are: `"Silence"` no output, `"Errors"` only error messages, `"Warnings"`, only error and warning messages, and finally `"All"` (default), all messages, even informative, should be written to the console.

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 files list in the main menu for quick access.
- `"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 lose model precision in doing so. The default value used by Tcl is 12 and results in no loss of precision. 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+). Five methods are available:
  1. `"DomainDistance"` (the default) simply tesselates the NURBS into equally sized pieces with regard to parametric space; `"SParamU"` and `"SParamV"` control the number of sampling points in U and V direction respectively per unit length. This leads to different numbers of samples for knot vectors of different length in parameter space.
  2. The tesselation method `"PathLength"` ensures that no edge of a polygon generated by the tesselation is longer than the value specified by `"SParamU"` and the tesselation method
  3. `"ParametricError"` ensures that the distance between the tesselated surface and the original surface is no point bigger than the value specified by `"SParamU"`.
  4. `"NormalizedDomainDistance"` ensures that the tesselation creates the same number of sample points (as given via `"SParamU"` and `"SParamV"`) for any knot vector and
  5. `"AdaptiveDomainDistance"` additionally adds sample points dependend on the number of control points (width or height of the patch) to provide a better adaptation to complex patches.
  The tesselation methods,`"NormalizedDomainDistance"` and `"AdaptiveDomainDistance"` are available since Ayam 1.9 to overcome the limitations of the `"DomainDistance"` method.

  Note that `"SParamU"` is expressed in object space units for the `"PathLength"` and `"ParametricError"` tesselation methods.

- `"SParamU"`; 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.
- `"SParamV"`; is just available for the tesselation modes `"DomainDistance"`, `"NormalizedDomainDistance"`, and `"AdaptiveDomainDistance"`.

Next Previous Contents