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 the About Katana dialog.

KATANA_SPLASH_IMAGE_FILE ✨ New in Katana 4.5v1

The filename of an image to show in the splash screen and the About Katana dialog.

The default size of the Katana splash screen image is 700 × 318 pixels.
Supports alpha channels.
Supports animated GIFs to some extent (see note below).
Supports animated WebP images to some extent (see note below). ✨ New in Katana 7.5v1
Can be a list of image filenames separated by the OS-specific path separator, in which case one of the images will be chosen at random, for example:

export KATANA_SPLASH_IMAGE_FILE=~/Pictures/taco.png:~/Pictures/bell.gif

export KATANA_SPLASH_IMAGE_FILE=`ls /path/to/splash_screens/*.png | tr '\n' ':'`

Note

While animated GIF and WebP images are supported by KATANA_SPLASH_IMAGE_FILE, they will not play back smoothly in the splash screen, as processing during startup focuses on launching Katana, rather than playing back a GIF. The animated image will be played back smoothly in the About Katana dialog though.

KATANA_SPLASH_CREDIT_NAME

A name to display after “Artwork by” on the splash screen and About Katana dialog. When set to 0, no credit will be displayed.

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 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 Viewer and the bundled Katana USD plug-ins). See Building Katana USD Plug-ins.

KATANA_USD_PLUGINS_DISABLED

Disables the startup environment setup for the KatanaUsdPlugins shipped with Katana by default. This will be required to set to 1 if you would like to use your own KatanaUsdPlugins, as two sets of Plugins cannot be used at the same time.

Python Search Path

Katana’s search paths for Python module files are built from different parts:

KATANA_DEBUG_PRE_PYTHONPATH (user-defined)
Katana’s own default search paths.
PYTHONPATH (user-defined) and site-specific configuration via sitecustomize.py (user-defined)
KATANA_POST_PYTHONPATH (user-defined)

Each of these parts is a list of filesystem paths, separated by the OS-specific path separator (colon : on Linux, semicolon ; on Windows).

The combined Python search paths are made available in the KATANA_INTERNAL_PYTHONPATH environment variable that is set by Katana. That variable is used to override the paths for the Python interpreter inside of renderboot when renderboot is started, after the Python interpreter is initialized. Note that sys.path may contain additional paths as a result of plug-in startup scripts.

Note

The Katana Queue Daemon (KQD) script and the Agent scripts that it spawns are run in a Python interpreter that is initialized via PYTHONPATH, in addition to the following paths:

$KATANA_ROOT/plugins/Resources/Core/Plugins/ – so that KQD can import the kq Python package of Katana Queue
$KATANA_ROOT/bin/python/ – so that KQD can import the zmq third-party Python package

Caution

KATANA_DEBUG_PRE_PYTHONPATH is meant to be used for debugging purposes only, as it may lead to unexpected application behavior due to non-supported modules loaded in place of the application’s ones.

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 to SIGTERM. The module then uses kill(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 to SIGKILL.

PRMAN_RENDER_TERMINATION_SIGNAL

See DEFAULT_RENDER_TERMINATION_SIGNAL.

KATANA_CANCELLED_RENDER_PROCESS_GRACE_PERIOD ✨ New in Katana 4.0v4

The time (in seconds) that a cancelled render process is allowed to continue running before Katana terminates it definitively. Default is 60 seconds. This environment variable is most relevant when the default SIGTERM signal is used in DEFAULT_RENDER_TERMINATION_SIGNAL, since sending that signal to the process does not necessarily guarantee that the render process will terminate in a timely manner.

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 to tile_@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 4

The 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_DISABLE_FORESIGHT_PLUS ✨ New in Katana 4.5v1

If set to 1, disables Foresight+. Foresight+ provides a new, more efficient live rendering experience. Foresight+ sends lightweight Op Tree changes to the render process, rather than much larger scene graph changes that were previously calculated and sent to the render process.

KATANA_LRUA_DEBUG ✨ New in Katana 4.5v1

If set to a file path, enables live render update attribute (LRUA) debug logging. Each live render update attribute generated by the Foresight+ will be written to the log file and can be viewed in the Foresight Services tab. Live render update attribute logging is only available with Foresight+ live rendering.

GEOLIB_REMOTE_RUNTIME_REQUEST_DEADLINE ✨ New in Katana 4.5v1

If set, overrides the default request timeout set by RPC clients when making requests to a remote runtime instance. Deadline should be specified as a positive integer in milliseconds.

KATANA_SERVICE_PROVIDER_DEADLINE ✨ New in Katana 4.5v1

If set, overrides the default request timeout set by RPC clients when making requests to a service provider registry instance. Deadline should be specified as a positive integer in milliseconds.

GEOLIB_REMOTE_RUNTIME_CLIENT_DEBUG ✨ New in Katana 4.5v1

If set, will result in each RPC client call to a remote runtime service to be logged (with its response time).

KATANA_LIVE_RENDERING_BATCH_UPDATES ✨ New in Katana 4.5v4

If set to 1, the render updates are sent as a single batch update. By default the render updates are streamed to the renderer plug-in as they become available.

Nuke Bridge

✨ New in Katana 4.5

KATANA_NUKE_EXECUTABLE: Path to a Nuke executable that should be used in Katana’s Nuke Bridge.
KATANA_NUKE_BRIDGE_DISABLED: If set, disables the automatic loading of the Nuke render plug-in. This doesn’t disable the Nuke Bridge tab itself, but without a valid render plug-in loaded, the tab’s contents will be disabled.
KATANA_NUKE_VERSION_OVERRIDE: If specified, the Nuke Bridge tab will not attempt to detect the version of the configured Nuke executable. For example, if set to 13.1, the Nuke plug-ins for Nuke 13.1 will be used. Note that if the user-defined version override does not match the Nuke version, the required Nuke plug-ins may fail to load in Nuke.
KATANA_NUKE_BRIDGE_MAXOUTPUTLAYERS: The maximum number of layers that KatanaWriter nodes in Nuke can deliver to Katana. Default is 20.

Katana Queue (KQ)

✨ New in Katana 4

Katana Queue was added in Katana 4.0v1.

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’s Configuration 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 during application startup. Is expected to be a positive integer number, or 0. Default is 2.

The kq.GetNumberOfLocalAgents() function can be used to check how many local Agents are managed by the Katana Queue, as specified in this environment variable.

KQ_DISABLED ✨ New in Katana 4.0v2

If set to 1, disables Katana Queue features by skipping the registration of the Katana Queue farm plug-in, and not starting the KQ Daemon (KQD) process or any of KQ’s Agent processes during application startup.

The kq.IsDisabled() function can be used to check whether KQ is disabled.

Note

When disabling KQ, the Katana Queue tab will still be available in the UI, but will not list any KQ jobs for the duration of the Katana session.

KQ_OVERRIDE_KATANA_ROOT ✨ New in Katana 4.0v3

By default KQ agents look for renderboot in the same installation directory as the artist workstation. In some circumstances, for example where KQ agents run remotely and Katana is installed in a different location on those hosts, the agents will fail to find renderboot.

Setting this environment variable overrides this behaviour allowing you to set an arbitrary Katana installation directory that will be used when deploying render jobs to agents.

KQ_OVERRIDE_<renderer name>_PLUGIN_PATH ✨ New in Katana 4.0v3

Similar to KQ_OVERRIDE_KATANA_ROOT, KQ_OVERRIDE_<renderer_name>_PLUGIN_PATH provides a mechanism to specify an alternative installation path for renderer plugins, for example, KQ_OVERRIDE_ARNOLD_PLUGIN_PATH specifies an alternative plugin directory for the Katana to Arnold plugin.

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 to 1, crash reporting is enabled in both GUI and terminal mode.

When KATANA_CRASH_HANDLING is set to 0, 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 to 1, crash reports are submitted automatically without displaying a crash reporter dialog.

When KATANA_NO_CRASH_PROMPT is set to 0, 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_CATALOG_MEMORY_WARNING ✨ New in Katana 4.0v5

Specify the memory usage threshold (as a percentage e.g. 70 would issue a warning when memory consumption reached 70% of the available RAM and disk space) above which a warning will be raised and further rendering will be suspended until memory is freed from the Catalog. By default this is 90% of the available RAM and disk space reserved for the Catalog.

KATANA_HARD_MEMORY_LIMIT ✨ New in Katana 4.0v5

If set, Katana will raise an un-recoverable OutOfMemory exception when it is unable to allocate image buffer memory for the Catalog. The raised exception will cause Katana to crash. If not set, Katana will continue to allocate memory (ignoring any soft limits set by KATANA_IMAGE_MEMORY and KATANA_IMAGE_DISK_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 or true, this memory-mapped I/O extension is disabled and Alembic_In will revert to using file-streams to read Alembic files.

UsdIn Options

USD_ABC_XFORM_PRIM_COLLAPSE: This environment variable is relevant when using Alembic files inside USD. Set this to 0 if you don’t want transforms with a single geometry or camera in an Alembic file to be collapsed into a single prim in USD.
USD_ABC_WRITE_UV_AS_ST_TEXCOORD2FARRAY: If set to 0 writing Alembic uv sets as primvars:st with type texCoord2fArray to USD. This affects how Alembic references are imported into Katana via UsdIn as well.
USD_IMPORT_USD_LUX_LIGHTS_WITH_PRMAN_SHADERS: If set to 1 basic UsdLux prims will import with RenderMan light shader information as well. Off by default. RfK must also be setup in the environment.
USD_KATANA_ADD_CUSTOM_PROPERTIES: If set to 0 UsdIn will not import custom properties set on Usd prims. Otherwise, and by default, custom attributes will be imported under customProperties.
USD_KATANA_ALLOW_CUSTOM_MATERIAL_SCOPES: If set to 0, this will limit material assignments to materials scoped under a Looks prim.
USD_KATANA_API_SCHEMAS_AS_GROUP_ATTR: If 1, API schemas will be imported as group attributes instead of an array of strings. This provides easier support for CEL matching based on API schemas and an easier way to access the instance name of Multiple Apply Schemas.
KATANA_USD_GLOBALS_TRAVERSE_MODEL_HIERARCHY: If set to 0 the UsdIn.UpdateGlobalLists Op will traverse the entire USD stage, rather than just the prims part of the model hierarchy. This affects lightList and globals.cameraList attribute creation on /root/world. In both cases, the UsdLuxLightListAPI can be used to store lightLists and control the cache behaviour for light lists.
USD_KATANA_LOOK_TOKENS: This environment variable defines which prim names will allow for any child Material prims which have sibling materials to become child materials where a Specializes composition arc exists between them. The defaults are Looks, looks and materials, separated by the OS path separator.

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_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 2D rendering to output additional log messages.

KATANA_RENDER_INTERCEPT

The file system location path of an executable script or binary to be called instead of renderboot when starting a render. Receives the arguments that renderboot normally receives.

Debugging using a Debugger

KATANA_RENDER_INTERCEPT is ideal for debugging the renderboot process. Consider the following Linux shell script:

debugging-interceptor.sh

#!/bin/bash

exec xterm -e gdb --args "$KATANA_ROOT/bin/renderboot" "$@"

If KATANA_RENDER_INTERCEPT is set to the file system location path of the debugging-interceptor.sh script, renders started from Katana will be run through gdb. Note that the script invokes renderboot in the $KATANA_ROOT/bin/ directory, passing along all of the arguments it receives, but the render process is run as an inferior process from within gdb, rather than directly.

The xterm terminal emulator for X is used here in order to be able to interact with gdb. Other terminal emulators with a similar -e command-line option can be used instead.

Debugging using a Profiler

Another usage of KATANA_RENDER_INTERCEPT is profiling. For instance, to run a renderboot session through the Intel® VTune™ Profiler, the following script could be used:

profiling-interceptor.sh

#!/bin/bash

exec vtune -collect hotspots -knob sampling-mode=hw -knob sampling-interval=1 "$KATANA_ROOT/bin/renderboot" "$@"

Debugging using Environment Variables

The program specified by KATANA_RENDER_INTERCEPT can be used to alter the environment in which renderboot is started. For example, PATH or LD_LIBRARY_PATH could be extended, or LD_PRELOAD or LD_DEBUG could be set.

Important

The script or binary specified by KATANA_RENDER_INTERCEPT must have executable permissions, and its file system location must be accessible from the environment in which Katana is run.

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 to LuaJIT_2_1). LuaJIT provides better performance.

KATANA_OPSCRIPT_LUAJIT_JIT_COMPILER_ENABLED

Defines the default enable state of the JIT compiler of the LuaJIT interpreter used by the OpScript node. LuaJIT’s JIT compiler is disabled by default due to memory allocation-related performance issues that can arise under normal usage. Enable it by setting this variable to 1.

KATANA_PYTHONWARNINGS

Sets the handling for warnings from the warnings module. The value set is passed to a simplefilter. See filter values from the warnings module for more information. Defaults to default.

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 and KATANA_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).