Environment Variables¶
Installation¶
Note
These variables are read-only and automatically set by Katana on start up.
KATANA_RELEASE
- The externally visible version displayed in the UI. (For example, 4.0v1.)
KATANA_VERSION
- Katana’s internal version number, which is used for things like upgrade
scripts. As this is principally an implementation detail,
KATANA_RELEASE
should usually be used instead. KATANA_ROOT
- Katana’s installation directory.
KATANA_DEFAULT_RESOURCES
- The path used for internal default resources. Default resources can be
overridden by resources in
KATANA_RESOURCES
directories.
Launch Mode¶
Note
These variables are read-only and automatically set by Katana on start
up. They can only be accessed through the Configuration
module, e.g.
Configuration.get('KATANA_UI_MODE')
.
KATANA_BATCH_MODE
- Defined when Katana is running in batch mode (
--batch
). KATANA_SCRIPT_MODE
- Defined when Katana is running in script mode (
--script
). KATANA_SHELL_MODE
- Defined when Katana is running in shell mode (
--shell
). KATANA_UI_MODE
- Defined when Katana is running in UI mode.
Plug-ins and Configuration¶
KATANA_RESOURCES
- List of paths from which Katana plug-ins are loaded, separated by the
OS-specific path separator (
:
on Linux,;
on Windows). KATANA_TAGLINE
- Text to display in the splash screen and about dialog.
KATANA_USER_RESOURCE_DIRECTORY
- Path from which user settings are loaded. User settings include preferences,
layouts, and user-defined macros, shelf scripts, startup scripts, and so
forth. If not set, user settings are loaded from a directory named
.katana
in the user’s home directory. KATANA_NODETYPETAB_NODETYPES
- Comma-separated list of node type names that determines which tabs are available under the Tabs > Node menu. Node Type Tabs show parameters for specific types of nodes.
KATANA_LOG_CONFIG
- Path to logger configuration file.
KATANA_DEFAULT_ASSET_PLUGIN
- The name of the default asset plug-in. If not defined, the default is
File
. KATANA_DEFAULT_FILE_SEQUENCE_PLUGIN
- The name of the default file sequence plug-in. If not defined, the default is
FileSeq
. KATANA_HYDRAVIEWER_DEBUG
- A flag that, if non-zero, will enable logging for custom Hydra Viewer Render Delegates.
FNPXR_PLUGINPATH
- Equivalent of the stock USD
PXR_PLUGINPATH_NAME
environment variable for locating USD plug-ins to be loaded by Katana’s namespaced USD library (used by the Hydra Viewer and the bundled Katana USD plug-ins). See Building Katana USD Plug-ins.
Python Search Path¶
Katana’s internal python search path is composed of four parts:
KATANA_DEBUG_PRE_PYTHONPATH
(user-defined)- Katana’s internal python library paths.
PYTHONPATH
(user-defined)KATANA_POST_PYTHONPATH
(user-defined)
Each of these parts is a list of filesystem paths, separated by the OS-specific
path separator (:
on Linux, ;
on Windows).
Once constructed, the internal python path can be read via sys.path
in
Python or via the read-only KATANA_INTERNAL_PYTHONPATH
environment
variable.
Rendering¶
DEFAULT_RENDER_TERMINATION_SIGNAL
On Linux, Katana uses signals to terminate the renderboot process. When a render is canceled, the module responsible for starting renderboot first checks for a specific environment variable, to determine which signal should be used.
Katana currently supports renderer-specific variables that are named
<renderer name>_RENDER_TERMINATION_SIGNAL
, for example,ARNOLD_RENDER_TERMINATION_SIGNAL
.Valid values for the variables are:
SIGABRT
,SIGKILL
,SIGTERM
. If no variable is set, the signal defaults toSIGTERM
. The module then useskill(pid, signal)
to terminate renderboot.ARNOLD_RENDER_TERMINATION_SIGNAL
- See
DEFAULT_RENDER_TERMINATION_SIGNAL
. By default, during application startup,ARNOLD_RENDER_TERMINATION_SIGNAL
is initialised toSIGKILL
. PRMAN_RENDER_TERMINATION_SIGNAL
- See
DEFAULT_RENDER_TERMINATION_SIGNAL
. DEFAULT_RENDERER
- Default renderer. If not set, defaults to
dl
, the 3Delight renderer. KATANA_RENDER_TILE_SIZE
- Global tile size to be used in the render system 2D. The variable is a scalar type used both for the width and height of the tile.
KATANA_RENDER_LOGFILE
- Path where render log should be saved.
KATANA_CATALOG_REFRESH_RATE
- Rate at which Katana’s Catalog subsystem will trigger a repaint event when new
areas of the rendered image have been received from the renderer. Default is
100
(Hz). KATANA_TILE_FILENAME
Used for defining custom filenames and path of tiles created as part of a tile render. By default, a
"tile_<column>_<row>."
prefix is prepended to the original name of render file. Users can set this environment variable to customize the tile filename and filepath. The following wildcards can be used:@STEM@
@EXT@
(includes dot)@COLUMN@
@ROW@
@COLUMNS@
@ROWS@
@DEFAULT@
(equivalent totile_@COLUMN@_@ROW@.@STEM@@EXT@
)
For example, the following setup would append the tile column and row, as well as the total number of columns and rows, to the original name of render file:
"@STEM@_(@COLUMN@,@ROW@)_@COLUMNS@x@ROWS@@EXT@"
KATANA_DISPLAYDRIVER_PRECISION
✨ New in Katana 4The data type to use for encoding pixels that are transmitted between a render process and Katana. Can be used to reduce the bandwidth required for transmitting images, but at the cost of a loss of fidelity.
Choose between one of three options:
float
(default): Single-precision floating-point format (32 bits).half
: Half-precision floating-point format (16 bits).byte
: Reduced precision resulting in the lowest bandwidth, but possibly visible banding artifacts, and a loss of fidelity when stopping images up or down (8 bits). Clamps pixel values to a range between 0 and 1.
The value set by this environment variable can be overridden using the interactivePrecision parameter of RenderSettings nodes.
KATANA_OVERRIDE_ALLOW_CONCURRENT_LIVE_RENDERS
✨ New in Katana 4If set to
1
, allows multiple simultaneous Live Renders to run in parallel.Warning
⚠ Experimental: Multiple simultaneous Live Renders currently share the same initial scene state, so running multiple Live Renders in parallel only works as expected when you are making changes intended to equally affect all renders.
LEGACY_2D_NODE_ACTIVE
- If set, enable the legacy 2D rendering subsystem built-in to Katana.
Katana Queue (KQ)¶
✨ New in Katana 4
KQ_AGENT_ENVIRONMENT_FILE
- Specifies the path to a file which is expected to contain a series of
newline-separated name/value pairs of the form
name=value
, defining environment variables that will be exported verbatim to the Agent’s process environment when rendering with KQ. KQ_MINIMAL_AGENT_ENVIRONMENT
- If set to
1
, initializes the environment in which Agent processes are launched to only contain names and values of variables that are set in Katana’sConfiguration
module, as well as a few other variables related to KQ. If not set, by default, Agent processes inherit the full environment from the Katana process, in addition to the minimal environment. KQ_DATA_ROOT
- If set, specifies the path to a folder that KQ will use to store files
related to rendering, such as Op tree files and render logs.
By default, the value of
KATANA_TMPDIR
will be used. KQ_NUM_AGENTS
- Specifies the number of local Agents KQ will spawn on start up. Default is
2
.
Color Management¶
KATANA_OCIO_LUT3D_EDGE_SIZE
- Defines the edge size for the 3D texture used by Katana to store the OCIO LUT
for color transformations. If not defined, the default is
64
. KATANA_OCIO_NO_FILMLOOK_COLORSPACE
- OCIO color space to use when no filmlook transformation is enabled. This might be used to enable gamma correction even when no transform is specified. The name of the profile is specified by the environment variable.
Projects and Live Groups¶
KATANA_DISABLE_LIVEGROUP_CACHING
- If defined, disables the storing of network contents in LiveGroup source files. This is useful when using projects with large numbers of deeply nested LiveGroups.
KATANA_DISABLE_LIVEGROUP_LOADING
- If defined, disables loading live group contents from the network, and instead uses cached contents from the project file. This is useful in debugging or reconstructing old projects.
KATANA_NEVER_SHARE_LIVE_GROUPS
- If defined, prevents LiveGroup nodes from being shared.
KATANA_ARCHIVE_AND_COMPRESS_LIVEGROUPS
- If defined, forces Katana to archive and compress LiveGroup files on saving.
KATANA_NEVER_ARCHIVE_SCENE_FILE
- If defined, prevents Katana from creating archives when saving project files or macros.
KATANA_NEVER_COMPRESS_SCENE_FILE
- If defined, prevents Katana from compressing project files or macros on saving.
Crash Handling¶
KATANA_CRASH_HANDLING
Crash reporting allows you to submit crash dumps to The Foundry in the unlikely event of a crash. By default, crash reporting is enabled in GUI mode and disabled in terminal mode.
When
KATANA_CRASH_HANDLING
is set to1
, crash reporting is enabled in both GUI and terminal mode.When
KATANA_CRASH_HANDLING
is set to0
, crash reporting is disabled in both GUI and terminal mode.KATANA_NO_CRASH_PROMPT
When crash handling is enabled in GUI mode, this allows you to control whether reports are automatically submitted or not:
When
KATANA_NO_CRASH_PROMPT
is set to1
, crash reports are submitted automatically without displaying a crash reporter dialog.When
KATANA_NO_CRASH_PROMPT
is set to0
, Katana always displays a crash reporter dialog before submitting a crash report.
Caching and Temporary Files¶
KATANA_IMAGE_DISK_MEMORY
- Maximum amount of swap disk memory usable by Katana while allocating image files, in megabytes. The default value is a fraction of available disk space in the temporary directory, or zero when Katana runs in batch mode.
KATANA_IMAGE_MEMORY
- Maximum amount of runtime memory usable by Katana while allocating image memory, in megabytes. The default value is a fraction of available system memory.
KATANA_TMPDIR
- Path to directory where Katana should store temporary files.
KATANA_KEEP_TMPDIR
- If defined, Katana won’t clean the temporary directory on exit.
KATANA_KEEP_TEMP_RENDER_FILES
- If defined, Katana won’t delete the temporary render files after a disk render.
KATANA_PERSISTENT_IMAGES_PATH
- Directory where persistent images (like the ones from the catalog) should be stored.
KATANA_PERSISTENT_IMAGES_PREFIX
- Filename prefix for persistent images to be used when they’re saved. The default is ‘default’.
KATANA_SPEC_CACHE_ENABLED
Lets the user enable or disable the render’s speculative caching. If defined, with a value greater than zero, it’s enabled; otherwise disabled. By default, it’s disabled only in Batch mode.
Enable or disable interframe caching of images. The interframe cache (that is, images generated for one render being used to help in another render) can make it difficult to debug some kinds of errors. By disabling the caching, you’re guaranteed a ‘clean’ render every time, but the rendering will be slower.
KATANA_PIPE_MAX_QUEUE_SIZE
- If defined, controls the maximum size of the message queue used by renderer plug-ins to communicate with Katana’s catalog.
Alembic_In Options¶
KATANA_ALEMBICIN_DISABLE_MMAP
The Alembic_In node and associated Op uses an extended Alembic library to read Ogawa format Alembic files using memory-mapped I/O. This allows faster reads in general, and better multi-threaded performance with fewer locks.
If set to
1
ortrue
, this memory-mapped I/O extension is disabled and Alembic_In will revert to using file-streams to read Alembic files.
Debugging¶
RUNTIME_OPTREE_GRAPH_DUMP
- Path to a file used to dump the optree graph while rendering. This is useful for debug or inspection, especially when writing Ops.
KATANA_DISABLE_EXIT_ON_ASSET_PROCESS_MANAGER_FAILURE
- If defined by the user, when running Katana in Batch mode, undefines
KATANA_EXIT_ON_ASSET_PROCESS_MANAGER_FAILURE
. KATANA_ASSET_INTERPRETER_ENABLE_DEBUG
- Enables additional debug messages in AssetPythonInterpreter.
KATANA_EVENT_DEBUG
- When defined, causes all events in the EventModule to be printed out.
KATANA_RENDER_DEBUG
- When defined with anything apart from
0
or''
causes rendering to output additional log messages. KATANA_EXIT_ON_ASSET_PROCESS_MANAGER_FAILURE
- If defined, makes the process manager exit on failure. Defaults to
1
. KATANA_INTERPROCESS_GC_TIMEOUT_SECONDS
- A ZeroMQ keep alive message is sent periodically from the render side of the Display Driver, to instruct Katana not to clean up image data references. If the Katana Catalog Server does not receive a keep alive message within a specified timeout, it cleans up references to any image structures it may have been holding on to in order to receive image data for the Catalog. By default, this garbage collection process occurs every 30 minutes, but can be controlled by setting this environment variable.
KATANA_OPSCRIPT_INTERPRETER
- Switches the Lua interpreter used by the OpScript node to either Lua 5.1 (if
set to
Lua_5_1
) or LuaJIT 2.1 (if unset, or set toLuaJIT_2_1
). LuaJIT provides better performance.
Advanced¶
KATANA_ORIG_STDERR
- (Read-only) when batch rendering, Katana currently captures both stdout
and stderr and, ultimately, redirects them to the Python logging system,
where a logging handler writes messages to the render log file as info
messages. It is not currently possible to disable this redirection of
standard streams. However, there is a way to access the original standard
streams from plug-ins like Ops through the use of the environment variables
KATANA_ORIG_STDOUT
andKATANA_ORIG_STDERR
. Each variable contains the numeric file descriptor (Linux) or file handle (Windows) for the original stream. KATANA_ORIG_STDOUT
- (Read-only) see above.
KATANA_DISABLE_UTF8
- Katana sets Python’s default string encoding to UTF-8, unless this environment variable is defined.
KATANA_DISABLE_WORKING_SETS_UI
- If defined, disables the working sets features for hiding or disabling the relative UI elements.
KATANA_DISABLE_MATERIALFILENAMERESOLVE
- If set to
1
, disables Katana’s use of the MaterialFilenameResolve Op (in the Implicit Resolver Op chain, the MaterialResolve node’s Op chain, and in the SceneGraphView terminal Op chain). KATANA_DISABLE_RENDERERPROCEDURALFILENAMERESOLVE
- If set to
1
, disables Katana’s use of the RendererProceduralFilenameResolve Op (in the Implicit Resolver Op chain, the MaterialResolve node’s Op chain, and in the SceneGraphView terminal Op chain). KATANA_VALUEPOLICY_MIMEDATA_ARRAY_SIZELIMIT
- When copying or dragging a parameter or attribute representing an array of
values, or a group containing such parameters or attributes, the
corresponding MIME data of format
'policy/xml'
is clamped to a maximum of values for each array. This limit was introduced to avoid generating large amounts of XML text for very large arrays of values. This variable can be set to a numeric value to customize this limit (default: 16).