**Bella CLI**
[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/DqCAvAXH6C)
Overview
===================================================================================================
Bella CLI is a command-line application for automating the rendering of Bella scenes, and may
therefore be used to create a render farm.
## Scope
This document pertains specifically to the Bella CLI, 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 CLI, download the package appropriate for you operating system (.zip for Windows,
.dmg for MacOS, .tar.gz for linux) and follow these steps:
## Windows
- Unzip the downloaded .zip file on your desktop.
- Double-click on the installer .exe file and follow the directions.
## MacOS
- Double-click the downloaded .dmg to mount it.
- Drag bella_cli.app to the Applications folder.
## linux
- Untar the downloaded .tar.gz file.
- bella_cli is ready to run.
Arguments
===================================================================================================
Following is a listing of currently-supported Bella CLI arguments. You can always print this in the
console by using `bella_cli --help`.
## Listing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ SHELL
C:\Program Files\Diffuse Logic\Bella CLI 23.4.0>bella_cli -h
Bella CLI 23.6.0.0, Copyright (c) 2023, Diffuse Logic
USAGE
bella_cli [-i:path] [-o:path] [-v|-h|-i|-o|-mi|-li|-tp|-vo|-hg|-sc|-bm|-se|-gl|-vk|-vi|-pf|-res|-od|-on|-fbd|-fbn|-rtt|-tta|-tts|-m|-fo|-fm|-ln|-qa]
OPTIONS
version
-v [ --version ]
/v [ /version ]
NOTES: Print application version to the console.
help
-h [ --help ]
/h [ /help ]
/?
NOTES: Print this help text.
input
-i: [ --input: ]
/i: [ /input: ]
NOTES: Input file path.
output
-o: [ --output: ]
/o: [ /output: ]
NOTES: Output file path.
machineInfo
-mi [ --machineinfo ]
/mi [ /machineinfo ]
NOTES: Print machine/os info and exit.
licenseInfo
-li [ --licenseinfo ]
/li [ /licenseinfo ]
NOTES: Print license info and exit.
thirdParty
-tp [ --thirdparty ]
/tp [ /thirdparty ]
NOTES: Print third-party licenses used by Bella and exit.
verboseOutput
-vo [ --verboseoutput ]
/vo [ /verboseoutput ]
NOTES: Enable verbose output.
helpGen
-hg [ --helpgen ]
/hg [ /helpgen ]
NOTES: Generate html help from a .bnd file. If no input path is given, help will be
generated for the built-in Bella node definitions. If no output path is given, the path
of the input .bnd will be used (renamed to .html). If neither input nor output paths
are given, the command will fail.
showConsole
-sc [ --showconsole ]
/sc [ /showconsole ]
NOTES: Show the console when using a GUI.
benchmark
-bm [ --benchmark ]
/bm [ /benchmark ]
NOTES: Run the Bella benchmark.
sceneEditor
-se [ --sceneeditor ]
/se [ /sceneeditor ]
NOTES: Run Bella in Scene Editor mode.
opengl
-gl [ --opengl ]
/gl [ /opengl ]
NOTES: Render GUI using OpenGL.
vulkan
-vk [ --vulkan ]
/vk [ /vulkan ]
NOTES: Render GUI using Vulkan.
vulkanInfo
-vi [ --vulkaninfo ]
/vi [ /vulkaninfo ]
NOTES: Print Vulkan info and quit.
parseFragment
-pf [ --parsefragment ]
/pf [ /parsefragment ]
NOTES: Provide a BSA fragment, or BSA file path, to be parsed by the scene. You can use
magic nicknames starting with 'nn' in the fragment to refer generically to well-known nodes,
for example writing 'nnsettings', which will be replaced with the actual settings nodename
prior to parsing. Currently supported are nnsettings, nnbeautyPass, nncameraXform, nncamera,
nnlens, nnsensor, nnregion, nnenvironment, nnsun, and nngroundPlane. These nicknames are
case sensitive.
resolution
-res [ --resolution ]
/res [ /resolution ]
NOTES: Overrides camera::resolution in the BSX. Accepts values formatted as WxH.
outputDir
-od [ --outputdir ]
/od [ /outputdir ]
NOTES: Force override of output dir for settings, and all solvers and passes.
outputName
-on [ --outputname ]
/on [ /outputname ]
NOTES: Force override of output name for settings, and all solvers and passes.
finalBsiDir
-fbd [ --finalbsidir ]
/fbd [ /finalbsidir ]
NOTES: A directory where local BSI files (saved as according to beautyPass:saveBsi) will
be copied at end of rendering.
finalBsiName
-fbn [ --finalbsiname ]
/fbn [ /finalbsiname ]
NOTES: A custom name to use when copying BSI files to --finalBsiDir. Specify with or without
the extension.
renderTurnTable
-rtt [ --renderturntable ]
/rtt [ /renderturntable ]
NOTES: Tells the CLI to render a turntable animation of the input file. The animation will
be 360 degrees, by 1 degree steps, unless the --turnTableAngle and/or --turnTableStep args
are given. Turntable animations ignore customized output and BSI naming args. Also, at this
time, BSI-generation is disabled for animations.
turnTableAngle
-tta:<360> [ --turntableangle:<360> ]
/tta:<360> [ /turntableangle:<360> ]
NOTES: Sets the total angle covered by a turntable animation.
turnTableStep
-tts:<1> [ --turntablestep:<1> ]
/tts:<1> [ /turntablestep:<1> ]
NOTES: Sets the angle between frames for a turntable animation.
merge
-m [ --merge ]
/m [ /merge ]
NOTES: Merge a list of BSI files. -o: must specify the output BSI.
forceOverwrite
-fo [ --forceoverwrite ]
/fo [ /forceoverwrite ]
NOTES: Force overwrite of existing files.
forceMerge
-fm [ --forcemerge ]
/fm [ /forcemerge ]
NOTES: Force merging of BSI files with mismatched scene hashes.
listNodes
-ln [ --listnodes ]
/ln [ /listnodes ]
NOTES: Print all node names (comma-separated) of a given type or types, sorted topologically.
Accepts one or more comma-separated type names, for example 'material,camera,xform'.
queryAttr
-qa [ --queryattr ]
/qa [ /queryattr ]
NOTES: Given the path to a particular attribute in the scene, print its value,
for example: xform.steps[0].xform
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Cooperative Rendering
===================================================================================================
The Atlas solver can be used to render on multiple machines. Each rendering process produces a
BSI file, which can be merged with other BSI files using the Bella CLI.
## Setup
1. Let's say we have a file named *cooperative.bsx* that we want to render on multiple machines -- let's first make sure the Beauty Pass is set up to save a BSI file while rendering:
2. Next, save the file as *cooperative.bsz* to include its resources, and ensure that we cannot inadvertently modify the file, as it will be needed later in the process.
## Rendering
3. Next, we copy *cooperative.bsz* to our various machines and render it, which produces a *cooperative.bsi* file on each machine.
4. Once finished rendering, we will copy all of our BSI files into a directory and use Bella CLI to merge them. I will name mine *cooperative-0.bsi*, *cooperative-1.bsi*, and *cooperative-2.bsi*:
## Merging
5. Now we will use Bella CLI to merge the BSI files into a final *cooperative.bsi* file; we can use a simple batch file like this:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ SHELL
@echo off
set PATH=%PATH%;c:/program files/diffuse logic/bella cli 23.4.0
bella_cli.exe --merge --output:cooperative.bsi ^
cooperative-0.bsi ^
cooperative-1.bsi ^
cooperative-2.bsi
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Running this batch file produces the output:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ SHELL
D:\cooperative>merge.bat
[INFO] Loading D:\cooperative\cooperative-0.bsi
[INFO] Loading D:\cooperative\cooperative-1.bsi
[INFO] Loading D:\cooperative\cooperative-2.bsi
[INFO] BSIs merged to D:\models\cooperative\cooperative.bsi
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
And we see our output *cooperative.bsi* file has been written in the directory:
## Resuming
6. Now, we can open *cooperative.bsz* in Bella GUI and click Render to resume rendering our merged *cooperative.bsi* file:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ SHELL
============================ OPEN: cooperative.bsz ============================
[INFO][07:43:55] Open: D:\cooperative\cooperative.bsz
[INFO][07:43:55] File successfully opened in 285.815ms [7653059290190196109].
[INFO][07:45:02] Preparing to render scene [7653059290190196109].
[INFO][07:45:03] Resume BSI: D:\cooperative\cooperative.bsi [60 7653059290190196109]
[INFO][07:45:03] Started: beautyPass [solver: Atlas]
[INFO][07:45:10] Saved PNG: D:\cooperative\cooperative.png [8-bit PNG, sRGB, 1280 x 1280]
[INFO][07:45:15] Saved BSI: D:\cooperative\cooperative.bsi [81 7653059290190196109]
[INFO][07:45:15] Stopped: beautyPass
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As usual, we are now free to make adjustments to exposure, enable the denoiser, apply different tonemappings, save different versions of our image, and so forth.