**Bella GUI**
[Bella for Rhino](../bella_rhino/index.html) |
[Bella for Maya](../bella_maya/index.html) |
[Bella for SketchUp](../bella_sketchup/index.html) |
[Bella GUI](../bella_gui/index.html) |
[Bella CLI](../bella_cli/index.html) |
[Bella Core](../bella/index.html) |
[Tutorials](../../tutorials) |
[Node Definitions](../nodes/index.html) |
[Main site](https://bellarender.com) |
[Discord](https://discord.gg/AaQtpWt5aT)
Introduction
===================================================================================================
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 also serve as a comfortable alternative
for various parts of a workflow.
## Scope
This document pertains specifically to the Bella GUI, and does not cover general Bella concepts,
for which you should refer to the [core Bella](../bella/index.html) and [node definition](../nodes/index.html)
documentation.
Installation
===================================================================================================
To install Bella GUI, download the package appropriate for you operating system (.zip for Windows, .dmg
for MacOS) and follow these steps:
## Windows
1. Unzip the downloaded .zip file on your desktop.
2. Double-click on the installer .exe file and follow the directions.
## MacOS
1. Double-click the downloaded .dmg to mount it.
2. Drag bella_gui.app to the Applications folder.
Licensing
===================================================================================================
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.
## Overview
Bella's license is contained in a simple text file, stored in your home directory:
OS | Path
------------|-----
Windows | `c:\users\\bella\bella.lic`
MacOS | `/Users//bella/bella.lic`
Linux | `$HOME/bella/bella.lic`
[Bella license file locations.]
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 customers appreciate this approach, and repay our trust by helping us to protect
our software against unauthorized use.
## Installation
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.
Panels
===================================================================================================
The Bella GUI has a central image area, which may be surrounded by various dockable and stackable panels:
Panel | Description
---------------------|------------
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.
[GUI panels.]
## Lists
There are several 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.
Textures | This lists all textures in the scene.
[GUI list panels.]
You can delete a node from the scene by selecting it in one of these lists, and hitting the Delete key.
## Hierarchy
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.
## Editors
There are also several 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.
[GUI editors.]
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.
### Settings
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:
The environment is usually most-conveniently edited from this panel.
### Camera
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.
### Material
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. To reset the
view, just hit the R key.
Rendering
===================================================================================================
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.
## Post-process
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.
[Attributes that don't require restarting render.]
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.
IPR
===================================================================================================
IPR stands for Interactive Preview Render, and Bella implements it in order to allow working with a
scene while rendering it. IPR uses the Saturn solver, with noise target currently fixed at 8, so it
will produce the same image as you get when production rendering with Saturn.
##Rendering
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:
Attribute | Description
---------------------|--------------------------
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.
Denoise | Enable denoising of the IPR render.
Navigation | Select between different application's navigation styles for the IPR.
[IPR settings.]
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:
## Navigation
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 key/mouse button combinations determined by the current IPR navigation
type.
While zooming the camera, its focus distance will be compensated, to keep the focus point at the same
point in the scene.
## Interactive Features
While rendering in the IPR, you may:
- Select objects to see their properties in the Node & Material editors.
- Hold CTRL and click on some point in the image, to focus the camera there.
- Hold CTRL and select a rectangle on the IPR image to set a render region.
- Hit the E key to frame the selected objects in the camera's view.
Menus
===================================================================================================
## File
Item | Function
---------------------|--------------------------
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.
[File menu.]
## Edit
Item | Function
---------------------|--------------------------
Undo | Undo the previous action.
Redo | Redo the previously-undone action.
Remove Unreferenced | Remove all nodes not referenced by the current scene state.
Simplify World | Remove intermediate xforms from the hierarchy.
[Edit menu.]
## Create
Item | Function
---------------------|--------------------------
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.
[Create menu.]
## Layout
Item | Function
---------------------|--------------------------
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.
[Layout menu.]
## Help
Item | Function
---------------------|--------------------------
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.
[Help menu.]
Toolbars
===================================================================================================
## File
Button | Function
---------------------|--------------------------
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.
[File toolbar.]
## Layout
Button | Function
---------------------|--------------------------
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.
[Layout toolbar.]
## Render
Button | Function
---------------------|--------------------------
RENDER | Start or stop production rendering.
IPR | Start or stop IPR (interactive) rendering.
[Render toolbar.]
Import
===================================================================================================
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.
Formats
The currently-supported import formats are these:
Formats | Notes
---------------------|--------------------------
3DS | Appears to work well, and to be quite a bit quicker than OBJ.
BLEND | It is unknown at this point how well this importer works.
DAE | Not yet well-tested. SketchUp Make can be used to write DAE files.
FBX | Appears to work well. Apparently supports FBX 2011-2013 formats.
OBJ | No special notes at this time, appears to work well.
STL | STL files have no normals, but the generated normals appear to be okay.
[Import formats.]
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.