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, ‘2.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

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 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.
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, the “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@"
LEGACY_2D_NODE_ACTIVE
If set, enable the legacy 2D rendering subsystem built-in to Katana.

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_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.

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 to ‘LuaJIT_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 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).