Bella GUI
Jump to:

Bella GUI is a standalone application primarily intended for rendering Bella scenes written with a plugin, in order to allow work to continue in the 3D host application, while rendering is done. However, it does have a good deal of editing functionality, so it can be a comfortable alternative for various parts of a workflow.

Scope of this Document

This document intends to explain specifically about the Bella GUI, not about general Bella concepts, for which you should refer to the core Bella and node definition documentation.


To install Bella GUI, download the package appropriate for you operating system (.zip for Windows, .dmg for MacOS) and follow these steps:


  1. Unzip the downloaded .zip file on your desktop.
  2. Double-click on the installer .exe file and follow the directions.


  1. Double-click the downloaded .dmg to mount it.
  2. Drag to the Applications folder.

Bella's licensing model is deliberately simple, to ensure that you never lose valuable time due to the licensing failures that are so common with typical draconian licensing systems.


Bella's license is implemented as a simple text file, stored in your home directory:

Windows c:\users\<user>\bella\bella.lic
MacOS /Users/<user>/bella/bella.lic

The license file contains nothing related to your machine, and you may therefore easily move it from one machine to another just by copying & pasting the file. This ease of use, however, does not mean the license authorizes simultaneous use on any more machines than the license specifies, it just ensures that you will not be forced to waste time diagnosing the invevitable failure of a more complicated licensing system.

We hope that our honest customers appreciate our approach, and repay our trust by helping us to protect our software against unauthorized use.


Your license text can be retrieved at any time, from the orders page of your account (here). Each order will have its associated license text shown directly in the page for the order:

You can use the "Copy" button to copy the text to your clipboard, then open Bella GUI and go to Help > License Info, and click the "Paste from Clipboard" button to quickly enter the text:

After entering the license text, you can click the "Save" button to save it to the bella.lic file (at the location described above). If this would cause a pre-existing license to be overwritten, you will be asked whether you would like to overwrite it.

Getting Started

The Bella GUI has a central image area, which may be surrounded by various dockable and stackable panels:

Hierarchy Shows the world node and all its children, allowing to quickly assign materials, and toggle visibility.
Settings & Camera These are node editors dedicated to the current settings & camera nodes.
Image Area Shows images from render passes, with a drop-down button for each.
Console & Help Console shows status messages, and Help shows context-sensitive node help.
Node Lists These panels show lists of different types of nodes, currently in the scene.
Material Editor This is an editor that has been specialized for editing materials.


File Menu:
New Clear and reset the scene.
Open Open a BSA or BSX file.
Reload Reload the current BSA or BSX file.
Import Import an OBJ, FBX, DAE, 3DS, or STL file.
Save Save the scene to the current file, if it was opened from, or saved as one.
Save As Save the scene as BSA, BSX, or BSZ.
Recent files Open a recent file.
Quit Close Bella GUI.
Edit Menu:
Undo Undo the previous action.
Redo Redo the previously-undone action.
Remove Unreferenced Remove from the scene, all nodes not referenced by the current state.
Create Menu:
Environment Create environment domes and related nodes.
Camera Create cameras, sensors, lenses, and other camera-related nodes.
Light Create procedural light nodes.
Geometry Create procedural geometry nodes.
Material Create material and related nodes.
Texture Create texture and related nodes.
Math Create maths-related nodes.
Path Create nodes for directories and input/output paths.
Pass Create render pass nodes.
Misc. Create miscellaneous (e.g. settings) nodes.
Layout Menu:
Toolbars Show or hide the various toolbars.
Load/Save Layout Save the current layout to a file, or load a previously-saved layout file.
Toggle All Panels Show or hide all GUI panels.
Toggle Full-screen Switch to full-screen mode.
Panels Toggle visibility of the various GUI panels.
Help Menu:
GUI Docs View this documentation.
Core Docs View documentation on the Bella system.
Node Definitions View documentation for all nodes and attributes.
License Info Show the License Info dialog.
About Bella Show Bella GUI version info, and license status.


File Toolbar:
New Clear and reset the scene.
Open Open a BSA or BSX file.
Reload Reload the current BSA or BSX file.
Save Save the scene to the current file, if it was opened from, or saved as one.
Save As Save the scene as BSA, BSX, or BSZ.
Layout Toolbar:
Console Show/hide the Console, where status & errors are reported.
Nodes Show/hide the Nodes list, which shows all nodes currently in the scene.
Materials Show/hide the Materials list, which shows all materials in the scene.
Cameras Show/hide the Cameras list, which shows all cameras in the scene.
Hierarchy Show/hide the Hierarchy panel, which shows the world node and its children.
Editor Show/hide the Node editor, which shows attributes for the selected node.
Camera Show/hide the Camera panel, which shows the current camera.
Material Show/hide the Material editor, which shows the selected material.
Settings Show/hide the Settings panel, which shows the current settings node.
Help Show/hide the Help panel, which shows help for the selected node.
Render Toolbar:
RENDER Start or stop production rendering.
IPR Start or stop IPR (interactive) rendering.


There are three node-list panels provided:

Nodes This lists all nodes, of any type, in the scene.
Cameras This lists all cameras, sensors, and lenses in the scene.
Materials This lists all materials in the scene.

You can delete a node from the scene by selecting it in one of these lists, and hitting the Delete key.


There are also three editor panels provided:

Settings This editor shows the current settings object.
Camera This editor shows the current camera (i.e. settings:camera).
Material This editor shows the currently-selected material.

These are described in more detail in the following section.


The editors here are based on a common "node editor" panel, which is able to display the attributes for any type of node in the system. All but one are customized to work specifically with their particular node type.

Each editor panel keeps track of its selection history, and you may move backward and forward though that history, by clicking the next and previous keys at the top-left corner of the editor:

Inputs may be connected to outputs by clicking the small box to the right of the control. Node references may be selected by clicking the "select node" hyperlink, or by clicking the small box to the right:

The context-menu that is shown allows to choose from compatible outputs/nodes, or to create a new node.

By default only outputs whose type strictly matches the input are shown, but if you hold CTRL before opening the menu, then it will also show outputs whose type can be coerced to the input type (for example, a Real must be coerced to an Int, since it loses data).

When an input is connected to an output, then rather than the input's immediate value being shown, there will be displayed a hyperlink leading to the connected output's node. Likewise with node-reference inputs, when they are connected to a node, a hyperlink leading to the referenced node will be shown:

When an input is connected, the connection may be broken by clicking the small red 'X' button to its right.


This editor shows the hierarchy of the current world node:

Along the right edge of the window are buttons for cycling the Visibility attribute of xforms between the Visible, Hidden, and Inherit states. Setting an xform to Hidden will hide all its children, unless they override this by using the Visible state.

Next to an xform's Visiblity button, is an icon indicating its assigned material:

To change the xform's assigned material, right-click the button and either choose to assign an existing material, or to create a new one.


This editor shows the current settings node. To make things more convenient, it maintains a row of buttons at the top, which provide shortcuts to important nodes linked to the settings: camera, environment, and beautyPass:


This editor shows the current camera node. Similar to the settings editor, it also has a row of buttons at the top, which in this case provide shortcuts to the camera's sensor and lens nodes:

These buttons are not actually specific to the Camera editor, and are rather specific to camera nodes (and environment nodes, as well). So in fact, these buttons will be shown in any editor, along with a button for selecting the current settings node, when the camera (or environment) being edited is currently linked in the settings.


This editor shows the currently-selected material node, and allows interactive rendering of it:

Additionally, this editor provides buttons for all nodes referenced by the current material, and remembers the currently-selected node, for each material.

Note that it is possible to zoom/pan/orbit the material preview while it is rendering, by holding ALT and the mouse buttons. Each material will remember the camera view last used to render it.



Through the File > Import menu item, it is possible to import several 3D formats. Here is a free 3D model from CG Trader, rendered exactly as it was imported (via the 3DS format):

Each import will be organized under an xform named for the imported file, and where possible, structure from the imported file will be preserved. If available, materials will be generated and assigned to parts in the imported model, though it should be noted that the quality of the translation depends entirely upon the data contained in the imported file.

Imported files may use any combination of scale and axis convention; the way of dealing with this is the same as always in Bella: select the top-level xform for the import, and rotate or scale it -- this will transform all its children, instantly and non-destructively.

Lastly, note that it is possible to select more than one model in the import dialog; this can be useful in cases where a model has been exported to a set of several individual files.


The currently-supported import formats are these:

Format Notes
OBJ No special notes at this time, appears to work well.
FBX Appears to work well. Apparently supports FBX 2011-2013 formats.
DAE Not yet well-tested. SketchUp Make can be used to write DAE files.
3DS Appears to work well, and to be quite a bit quicker than OBJ.
STL STL files have no normals, but the generated normals appear to be okay.

Bella uses Open Asset Import Library for this functionality, so if you find any issues, please report them, so that we can debug, and possibly report errors, or possible improvements, to the project.


IPR stands for Interactive Preview Render, and Bella implements it in order to allow working with a scene while rendering it. IPR uses a specialized beautyPass solver, which is highly-optmized for stopping & starting quickly, in order to respond to changes in the scene, as they are made.


To begin rendering in IPR, just click the "IPR" button at the top-right of the main window area (or in the Rendering toolbar):

The IPR solver requires there to be a beautyPass linked in settings, and it makes use of a few IPR-specific parameters in the current settings:

Threads Set the number of threads to use for IPR. Set 0 to use all, negative for all - N.
Scale Apply a scale factor to the output resolution, to improve interactivity..
Time Set how long the IPR engine will render before going idle, waiting for changes to be made.
Denoise Enable denoising of the IPR render, after a given level has been reached.

While rendering, the IPR solver should correctly respond to any change it is possible to make in the GUI. If you find some type of change that does not work properly, that would be considered a bug, and we would like to hear about it.

At any time after an image has appeared, you may save it to a file, or copy it to the clipboard, using the beautyPass drop-down menu in the image area:


Once an image has appeared, it is possible to zoom in on its pixels by using the scroll-wheel, and to pan the image by moving the mouse with the left mouse-button pressed. At bottom/center of the image area, you will see a semi-transparent heads-up-display, which shows the current zoom level, mouse position, and RGB values currently under the mouse pointer:

In addition to zooming & panning the image pixels, t is also possible to zoom, pan, and orbit the camera in 3D space, using the following key + mouse-button combinations:

ALT + right button Orbit the camera about its focus point.
ALT + left button Zoom the camera along its view vector.
ALT + middle button Pan the camera laterally.

While zooming the camera, its focus distance will be compensated, to keep the focus point at the same point in the scene.


Generally, the way Bella GUI is used, is that it is launched from your 3D host application, when you click a "Render in Bella GUI" button. Once it is running, you are able to monitor render progress, and change various attributes as the image is rendered, or after it has finished.

Render Passes

Bella may produce multiple output images, each of which is rendered by a render pass node (see here for the available passes). Each pass rendered will be assigned a drop-down button in the image area toolbar:

The drop-down menu allows saving the pass buffer to file, copying it to the clipboard, and depending on the pass type, the option to either re-render the image (for example, to re-render an object ID pass with more samples), or for beauty passes, to resume rendering of it (when the BSI file is valid for resuming):

Since pass buffers potentially represent substantial investment of time & CPU, you will be asked whether it is okay to discard them, if you re-start rendering, or enable IPR.


Several attributes may be changed while rendering, or after rendering has finished:

Attribute Notes
Settings : Color Space May be edited, since it only affects the display.
Sensor : ISO May be edited, affecting exposure.
Sensor : Sharpness May be edited.
Sensor : Tonemapping A tonemapping may be assigned (or unassigned), and its parameters edited.
Sensor : Bloom Bloom may be enabled/disabled, and bloom parameters edited.
Lens : Vignetting May be edited.
Lens : Diffraction May be enabled/disabled.
Lens : Filters Filters may be added/removed, and their parameters adjusted.
Beauty Pass : Denoise May be enabled or disabled, but will only be executed when rendering has finished.

While rendering, changes to these parameters will be applied at the next update. After rendering has finished, they will be computed on-demand.

Note that some of the post-processes can take some time to execute. In particular, the denoiser, which must compute internal albedo and normal passes, the first time it is applied to a newly-rendered output. If it is known beforehand that you will denoise, it is preferable to enable the denoiser prior to rendering, in which case the internal albedo & normal passes will be computed during rendering.