Houdini For TD
Houdini for TD - First Tools
September 10 2023 houdini , td

Note

This article is part of the serie Houdini for TD

Houdini Folder Structure

Houdini reads the user preferences and fetch HDA, presets and other user defined tools from the various paths defined in the environement variable `HOUDINI_PATH`.

As multiple folder are allowed here, this allow multiple packages to implement their own set of files which then will be loaded/merged by Houdini. Houdini will automaticly create one of those folders, with various files in it, at startup.

  • [houdini] - The root folder can be name as you wish. This is the path that need to be added into `HOUDINI_PATH` environement variable.
    • config
      • Icons - where to palce custom icons
      • NodeShapes - where to place custom node shapes
    • desktop - User defined desktop
    • gallery - User stored gallery files
    • otls - where to put HDA/OTLs
    • packages - where to install houdini packages
    • presets - store node value presets
    • python_panels - store user defined custom Qt interfaces
    • scripts
      • python - store python scripts
      • ... - store user hscript and commands
    • toolbar - store shelves and tools

Most of the tools and scripts you will be implementing will match this structure.

Environment

Environment variable used to be tradionally set in a file name `houdini.env`, though it is now recommended to use Houdini Packages as describred bellow.

Here are some environement variables that are worth knowing:

Name Usage
HOUDINI_PATH The path of directories where Houdini looks for configuration files.
HFS The path where Houdini is installed. This is usually set by Houdini wrapper.
HOUDINI_LMINFO_VERBOSE Typically, Houdini will print out warnings at start-up time if licenses are due to expire shortly. You can set this variable to change this behavior.
  • 0 No warnings will be shown when applications start up.
  • 1 (default) Warnings will only be shown in the terminal when applications start up.
  • 2 Warnings will only be shown as graphical pop-ups when applications start up.
  • 3 Warnings will be shown both in the terminal and as graphical pop-ups when applications start up.
HOUDINI_ANONYMOUS_STATISTICS If set to 1, this will forcibly allow Houdini to gather and send anonymous usage statistics to help improve the product. Setting to 0 will disable statistic collection. The default of -1 will use the anonymous usage statistics settings in the preferences.
HOUDINI_NO_START_PAGE_SPLASH If set to 1, Houdini will not attempt to open the Start Here splash page or the page that asks permission to turn on anonymous usage statistics.
HOUDINI_PACKAGE_DIR Specifies one or multiple custom directory paths Houdini can use for scanning package files.
HOUDINI_PACKAGE_VERBOSE Enables the logging of messages to the console during package processing.
JOB Work root folder. See project management for more details.

Read more: Houdini Environment Variable Documentation

Houdini Packages

Houdini Packages allow to separate and organize files into packages that can be indivudually managed. In addition, packages can be used to define environement variables. Packages can be used at studio or user level.

A package is defined by a json file and a houdini config like folder. I recommend placing those file and folder in a directory that is referenced by the environement variable `HOUDINI_PACKAGE_DIR`.

Here is the content of the json file I use for most of my packages:

{
    "hpath": "/path/to/the/package",
    "load_package_once": true
}

Then follow the folder structure as described earlier for `/path/to/the/package` content.

Read more: Houdini Packages Documentation

Tool Creation

Let's open Houdini and start to create our first tool.

We will start by creating a new shelf that will be used to store our tools.

Tools are scripts that can be triggered from various places in Houdini. A common place to store them is on a Shelf. Shelves is any easy way to create and organize tools while keeping them easiliy accessible to sue. Shelves are added to ShelfSets, which are collection of Shelves. Houdini come with a huge collection of ShelfSets, Shelves and Tools.

flowchart LR ShelfSet_A --> Shelf_A ShelfSet_A --> Shelf_B ShelfSet_B --> Shelf_B ShelfSet_B --> Shelf_C Shelf_A --> Tool_A Shelf_A --> Tool_B Shelf_B --> Tool_B Shelf_C --> Tool_C

Creating a Shelf

To create a new Shelve, click one of the + icon in the shelves bar, then New Shelf....

A dialog will open letting you choose a name and label, but also define where to store the shelf on the disk. Click Accept and you should now have an empty Shelf in your Shelves bar.

Creating a Tool

`Right click` on an empty area of the shelf and select New Tool...

Once again a dialog open letting you choose a name and label and a location where to store the tool. You can store all your tools in the same file or indivudual one. Let's save it in a separate file for this test.

In the Script tab, you can type Python code or Hscript. We'll just do a simple hello world python script for this one and click Accept once done.

print("Hello World")

Click on the newly created Tool to execute it. In the python shell or your terminal you should now see "Hello World" written.

Tools and Shelves as files

We will now open in a text editor the tool that you wrote on the disk. Houdini use XML to define tools, menus and others.

<?xml version="1" encoding=""UTF-8>
<shelfDocument>
    <tool name="my_tool" label="My Tool" icon="PLASMA_App">
        <script scriptType="python"><![CDATA[print("Hello World")]]></script>
    </tool>
</shelfDocument>

As you may notice, editing the code in this file should be fairly simple. At the exception of changing the name of the tool, changing all the other elements of the tool from the text editor should be reflected almost imediatly in Houdini, no need to restart!

Though you might ask yourself what is the `<![CDATA[...]]>` in the script. This is a houdini syntax to say the code should be executed in a background thread. If not, your houdini session would be blocked until the end of the execution of the script.

Let's now also open the file where you store the shelf and it should contains similar elements to this:

<?xml version="1" encoding=""UTF-8>
<shelfDocument>
    <!-- This is where a ShelfSet is defined and what shelves it contains. -->
    <shelfSet name="my_shelf_set">
        <!-- You can add more shelves before -->
        <memberToolshelf name="my_shelf"/>
        <!-- and after! -->
    </shelfSet>

    <!-- This is where a Shelf is defined and what tools it contains. -->
    <toolshelf name="my_shelf" label="My Shelf">
        <!-- You can add more tools before -->
        <memberTool name="my_tool"/>
        <!-- and after! -->
    </toolshelf>
</shelfDocument>

Adding Tools to a package

Following the folder structure defined above, you can add the XML files defining your ShelfSet, Shelf and Tool in the folder: `[houdini]/toolbar/my_custom_tools.shelf`

Creating Menu

Similarly to tools, tools/scripts can be invoked from menu. Menu files are stored at the root of the folder structure. Menus cannot be edited from code and usually require restarts to be refreshed.

Each Houdini menu has it's own speficic file for the menu that define it. Here are some of the most common menu you would come to edit:

  • MainMenuCommon.xml - control the main window menu
  • OPmenu.xml - control the menu when you right click on a node
  • PARMmenu.xml - control the menu when you right click on a parameter
  • ParmGearMenu.xml - control the "Gear Menu" in the parameter interface

I invite you to read more about menu with the official documentation.

Example of menu:

<!-- MainMenuCommon.xml -->
<?xml version="1.0" encoding="UTF-8"?>
 <mainMenu>
   <menuBar>
     <subMenu id="my_submenu">
       <label>My Submenu</label>

       <scriptItem>
         <label>My Tool</label>
         <scriptPath>$HOME/scripts/my_tool.py</scriptPath>
       </scriptItem>
     </subMenu>
   </menuBar>
 </mainMenu>

Next Chapter

In the next chapter, we will start looking into Houdini Python API.