Q100242: Creating a Katana launcher script for Windows



To start KATANA and work with the various renderer plugins available, you need to make sure that a few environment variables are set up correctly. The easiest way to manage these environment variables at present is to use a launcher batch script to start Katana.

This article provides and example script below that covers all the various renderer plugins, and is ready for usage. It is well commented and you only need delete the references to the renderer plugins you don't require using in your workflow.

NOTE: If your paths are different for the various components used in this script then you have to update those paths to the correct location on your system. 

If you are yet to install and license Katana on Windows, please see this article: Q100241: Installing Katana on Windows  




For instructions on how to modify and use this script, please follow these steps:

  1. Copy and paste the contents of the script below (below the line rem start here) into a text editor, for example Notepad.
    An example file is also attached, so alternatively download the attached zip folder and extract its contents. To edit the .bat file it contains, right-click on the file and choose 'Edit'. 
  2. Carefully read through the script, checking if the paths specified are the same on your machine. If not, update them so that they point to the right locations.
  3. Delete the sections specific to tools that you do not use, for example renderers or custom scripts.
  4. Save the file as Katana2.5v4.bat and close it.
  5. Now double-clicking the .bat file or right-click > Open should run the commands and launch Katana with all the necessary environment variables set. You can check if they have been set correctly for example by running these commands in the Python tab:

    import os
    print os.environ[‘KATANA_RESOURCES’]

    This should print the paths you have added to KATANA_RESOURCES in the launcher script. 
  6. If you would like a desktop icon to click and launch Katana from, you can add this in the following way:
  • Right-click on the .bat file > Create shortcut. 
  • Place the shortcut that is created on your Desktop.
  • Right-click the shortcut > Properties > Shortcut tab > Change Icon…
  • You may now see a warning saying the .bat file contains no icons. Click okay and you will get the option to choose an icon from a different location.
  • Click Browse… and browse to your Katana installation directory (KATANA_ROOT). Select the file WindowsIcon.ico and click Open. Click OK to close the Change Icon dialog and OK to close the Properties window.

    You should now have the Katana launcher script shortcut showing the Katana icon, available on your Desktop.



Key KATANA environment variables

KATANA_ROOT should point to your Katana installation directory.  
PATH is a Windows system variable specifying directories where executable programs are located.
KATANA_RESOURCES provides a list of paths under which to look for plug-ins and other customisations, for example shaders. For more information, please see the Katana Online Help.


Some batch file commands explained

rem marks a comment; Lines beginning with this command will be ignored when Windows runs the script.
@echo off stops the commands being executed in the batch file from being displayed in a command prompt.
set is the command to set an environment variable. Multiple paths can be separated by a semicolon(;).

The final line (
"%KATANA_ROOT%\bin\katanaBin.exe") runs the Katana executable. Once the batch file has reached this line, a command prompt will appear echoing the commands executed by Katana.


Example launcher batch script


rem start here
@echo off
rem ---------------------------------------------
rem -------- How to use this script ------------
rem ---------------------------------------------

rem --Change the "KATANA Specific" section to reflect your install path, custom tools, etc--
rem --Delete the settings for the renderers that you do not have installed or do not want to use at the same time.--

rem --"KATANA_RESOURCES" is the environment variable that drives what gets loaded at startup for KATANA. This is how you load tools and plug-ins--
rem --"DEFAULT_RENDERER" is the environment variable that drives which renderer plug-in is expected by default in a "RenderSettings" node.--
rem --Different renderer plug-ins have a range of needs for the PATH environment variable--
rem --Some renderer plug-ins are still in beta and their environment variable requirements may change.--

rem --------------------------------------
rem -------- KATANA Specific ------------
rem --------------------------------------
rem --Define the install location for KATANA and add binaries to the PATH--
set "KATANA_ROOT=C:\Program Files\Katana2.5v4"

rem --Make the example projects like the PyMock asset plugins available in KATANA

rem --This line is a simple example of how custom shelf scripts can be sourced--
rem http://help.thefoundry.co.uk/katana/current/#tg/shelf_item_scripts/shelf_item_scripts.html
set "KATANA_RESOURCES=%KATANA_RESOURCES%;C:\Users\jordan\Dropbox\katana_shelves"
set "KATANA_RESOURCES=%KATANA_RESOURCES%;C:\Users\Jordan\Dropbox\katana_tools"

rem -This is how you set the default renderer when more than one are used at once (arnold, prman, vray, dl)
rem - Change this to match the renderer you want to use by default.
rem !!--------------------------------!!



rem !!!!!!!!!!!!! Delete the tools you do not use from the section below !!!!!!!!!!!!!


rem ----------------------------------------
rem -------- 3Delight Specific ------------
rem ----------------------------------------
rem --This is the location of where the main 3Delight package is installed--
set "DELIGHT=C:\Program Files\3Delight"
rem --This is the location of the 3Delight for KATANA plugin--
set "DLFK_INSTALL_PATH=C:\Program Files\3Delight_for_Katana.09.windows"

rem --These make sure that all the shaders, and tools can be found by the plugin/renderer--
set "DL_DISPLAYS_PATH=C:\Program Files\3Delight\displays"
set "DL_SHADERS_PATH=C:\Program Files\3Delight\shaders"
set "PATH=%PATH%;C:\Program Files\3Delight\bin"

rem --This is the location of the 3Delight for KATANA plug-in--
rem !!--------------------------------!!



rem ------------------------------------------
rem -------- Multiverse Specific ------------
rem ------------------------------------------
rem --------------------------------



rem --------------------------------------
rem -------- Arnold Specific ------------
rem --------------------------------------
rem --Where you have installed the KtoA plug-in--
set "ARNOLD_INSTALL_PATH=C:\Program Files\KtoA-1.1-kat2.5-windows"

rem --Without these three KtoA will not function--

rem --To install the AlShaders
rem --http://www.anderslanglands.com/alshaders/index.html--
rem --Copy the Args folder itself to the bin folder of AlShaders folder--
rem --Set this line below to include the AlShaders into the Arnold shader path
set "ALSHADER_PATH=C:\Program Files\alShaders-win-1.0.0rc17-ai4.2.12.2\bin"

rem --This is how to load the KtoA plug-in--
rem !!--------------------------------!!


rem --------------------------------------------
rem -------- RenderMan 20 Specific ------------
rem --------------------------------------------
rem --This is the location of the PRman plugin for KATANA--
set "RFKTREE=C:\Program Files\Pixar\RenderManForKatana-20.9-katana2.5"
rem --This is the location of the RenderMan Pro Server installation--
set "RMANTREE=C:\Program Files\Pixar\RenderManProServer-20.10"

rem --These make sure that the programs can be found, shaders loaded, and all components used--
rem --This is different for PRman 21 so do not try to use the same for both versions once there is a PRman 21 RfK for Windows--
set "RMAN_RIXPLUGINPATH=%RISDIR%\bxdf;%RISDIR%\pattern;%RISDIR%\integrator;%RISDIR%\projection;%RISDIR%\light"
set "RMAN_SHADERPATH=%RMAN_SHADERPATH%;%RFKTREE%\Resources\PRMan20\Shaders;%RMANTREE%\lib\shaders;%RMANTREE%\lib\rsl\shaders"

rem --This is what is required to load the RfK plugin--
rem !!--------------------------------!!


rem --------------------------------------------
rem -------- RenderMan 21 Specific ------------
rem --------------------------------------------
rem --This is the location of the PRman plugin for KATANA in this case the one The Foundry compiled for testing--
set "RFKTREE=C:\Program Files\Pixar\RenderManForKatana-21.1-katana2.5\plugins"
rem --This is the location of the RenderMan Pro Server installation--
set "RMANTREE=C:\Program Files\Pixar\RenderManProServer-21.1"

rem --These make sure that the programs can be found, shaders loaded, and all components used--
rem --This is different for PRman 21 so do not try to use the same for both versions once there is a PRman 21 RfK for Windows--

rem --This is what is required to load the RfK plugin--
rem !!--------------------------------!!


rem -------------------------------------
rem -------- V-Ray Specific ------------
rem -------------------------------------
rem --Location of the V-Ray for KATANA install directory.--
rem --Not the syntax for Program Files as at the time of testing the plugin did not like spaces in directory names. This could be fixed--
set "VRAY_INSTALL_PATH=C:\Progra~1\vray_adv_30501_katana_2_5_x64"

rem --Specific location to call out the plug-in to itsef--

rem --This is required to access the tools that parse all the shaders--

rem --This is how the V-Ray plugin gets loaded--
rem !!--------------------------------!!


rem -------- Deadline Specific ------------
set "KATANA_RESOURCES=%KATANA_RESOURCES%;C:\Users\Jordan\AppData\Local\Thinkbox\Deadline8\submitters\KatanaSubmitter"
rem --------------------------------


rem !!!!!!!!!!!!! Stop deleting parts of the script. Leave the rest of this script alone !!!!!!!!!!!!!


rem -------- Start KATANA ------------

Was this article helpful?
0 out of 0 found this helpful


  • Avatar
    Chainarong Wanachaisong

    I have 3 folder content for arnold, katana and alShader but I have no idea after spend a long day to set enviroument varaible to work at all

    katana content

    arnold content

    /opt/solidangle/mtoa/shader/alShaders-linux-1.0.0rc19-ai4.2.12.2/bin (included Args folder)

    CentOS 6.8

    I add more line to /usr/local/Katana2.5v4/katana shell script

    export ARNOLD_PLUGIN_PATH=/opt/solidangle/ktoa/KtoA-1.1-kat2.5-linux/Plugins:/opt/solidangle/mtoa/shader/alShaders-linux-1.0.0rc19-ai4.2.12.2/bin
    export KATANA_HOME=/usr/local/Katana2.5v4
    export KTOA_HOME=/opt/solidangle/ktoa/KtoA-1.1-kat2.5-linux
    export DEFAULT_RENDERER=arnold
    export KATANA_TAGLINE="With KtoA 1.1 and Arnold"
    export PATH=$KTOA_HOME/bin:$PATH

  • Avatar
    Elisabeth Wetchy


    could you please try setting ALSHADER_PATH as a separate environment variable?

    It should look like this:

    export ARNOLD_PLUGIN_PATH=/opt/solidangle/ktoa/KtoA-1.1-kat2.5-linux/Plugins
    export ALSHADER_PATH=/opt/solidangle/mtoa/shader/alShaders-linux-1.0.0rc19-ai4.2.12.2/bin

    [... rest of your shell script goes here...]

    If this doesn't help, please raise a support ticket as described here: Q100064: Using the Support Portal.