Houdini

Shotgun Engine for Houdini

Shotgun Pipeline Toolkit integration in Houdini


By: Shotgun Software
Latest Version: v1.2.1 (prod)
For our version numbers, we follow the Semantic Versioning standard.
System Name: tk-houdini

Table of Contents:

Overview Summary

Documentation

      Information for App Developers

            Supported platforms

            PySide

            Menu loading

            Shotgun shelf

            Panels

            Apps with OTLs

            Startup Debugging via Terminal on OSX

Installation, Updates and Development

Configuration Options

Release Notes History

Overview

This document describes functionality only available if you have taken control over a Toolkit configuration. Please refer to the Shotgun Integrations Admin Guide for details. The Shotgun engine for Houdini establishes a bridge between the Shotgun Pipeline Toolkit apps and Houdini. It contains a Qt/PySide distribution for Windows, which is compatible with the python version bundled with Houdini, making it possible to write apps using Python and PySide that run right inside the engine.

Supported Application Versions

This item has been tested and is known to be working on the following application versions: 14.0, 15.0, 15.5. Please note that it is perfectly possible, even likely, that it will work with more recent releases, however it has not yet been formally tested with these versions.

Overview Video

The following video gives a quick overview of features and functionality.

Documentation

The Shotgun Engine for Houdini contains a standard platform for integrating Shotgun Apps into Houdini.

Shotgun Engine for Houdini

Information for App Developers

Supported platforms

The Shotgun Engine for Houdini is currently supported on Windows, Linux, and OSX.

On OSX, only more recent verisons of Houdini are supported (14 and 15). Due to the way that older verisons of Houdini were compiled for OSX (with operating system level garbage collection) there was no supported Qt build that was binary compatible with the application. As of Houdini 14, Houdini comes bundled with PySide so there is no need for an external build.

PySide

For older versions of Houdini (13 and older) an external build of PySide is required. On Windows, we have bundled a compatible PySide build that will work with the python that Houdini runs. On Linux, Houdini uses the system python (per http://www.sidefx.com/docs/houdini12.0/hom/) which needs to have PySide or PyQt support.

Menu loading

Shotgun menu

A dynamic menu system was introduced by Side Effects as of Houdini 15, so the engine now supports rebuilding of the Shotgun menu on context switches.

In Houdini 14 and older, the Shotgun menu in Houdini is generated before Houdini starts and is static throughout the session. Due to this, the toolkit commands registered in the menu will not update on context changes.

Shotgun shelf

Shotgun shelf

Release v0.2.4 introduced a dynamic Shotgun shelf to the engine. The shelf displays any registered app commands as tool buttons. The buttons will be displayed in roughly the same order as the menu commands.

Use the enable_sg_shelf setting to turn on the shelf within an environment. If using a version of Houdini (14 or older) that does not support dynamic menus, you may also want to turn off the Shotgun menu when using the shelf. This can be done by setting the enable_sg_menu setting to false.

To enable context switching via the shelf, you'll also need to add entity types to the sg_entity_types setting of the tk-multi-workfiles app in your engine configuration.

Here's a look at the settings related to the Shotgun shelf:

tk-houdini:
  apps:
    # ... other app definitions
    tk-multi-workfiles:
       # ... other app settings
       sg_entity_types: [Shot, Asset] # allow context switching to Shots or Assets
       # ... other app settings
  enable_sg_shelf: true
  enable_sg_menu: false
  # ... other engine settings

Once you've enabled the Shotgun shelf, you need to manually add it to a shelf set inside houdini.

Add the Shotgun shelf

Once added to a shelf set the Shotgun shelf will remain there between houdini sessions and will update dynamically as your shotgun context changes.

Panels

As of v0.2.8 the engine adds support for embedded toolkit panels.

The panel support currently requires Houdini version 15.0.272 or later for proper embedded panels. Registered panels will show up as panes in the pane menu for supported versions of Houdini.

Older versions of Houdini will display the registered panels as dialogs. SESI may backport some bug fixes to newer builds of Houdini 14. If and when that happens, we will make embedded panels work for those versions as well.

Apps with OTLs

The Shotgun Engine for Houdini makes it easy to load application supplied OTLs. If you are writing an app which uses OTLs, you can just drop them into a folder called otls and the engine will automatically load them into your session:

Houdini OTLs

You can then easily access your nodes via the usual Houdini methods.

Warning!! Please note that while the use of OTLs may be convenient, it is typically NOT the right solution if you want to create nodes that persist in a scene. The reason for this is because as soon as you have put an OTL in the scene, you have introduced a dependency between that scene and the OTL code. Not only will you need to load the Shotgun Toolkit every time you load the scene, but you also need to carefully manage your code so that any updates to the code does not break old OTLs being used in scenes.

Startup Debugging via Terminal on OSX

Turning on debug_logging for the tk-houdini engine on OS X will not send all debug messages to the Terminal. This is because, by default, the tk-multi-launchapp app uses the open command to launch executables. This does not spawn a new subprocess from the Terminal, but rather uses OS X's Launch Services to create a new process elsewhere. As a result, the log statements are not shown. Even having a python shell saved in the user's default desktop in houdini does not seem to show debugging statements during startup. After startup, and embedded python shell will show debug logging statements, but there is a gap in available output during startup. If you need access to debug logging statements during engine startup, you can make 2 changes.

First, change your houdini_mac path (temporarily) in your test configuration to point to the executable inside the Houdini app bundle. For example:

#houdini_mac: /Applications/Houdini 15.0.272/Houdini Apprentice.app
houdini_mac: /Applications/Houdini\ 15.0.272/Houdini\ Apprentice.app/Contents/MacOS/happrentice

Next, you can make a copy of the tk-multi-launchapp app's app_launch hook in your test configuration's config/hooks directory and point to it in your config/env/includes/app_launchers.yml file:

launch_houdini:
  defer_keyword: ''
  engine: tk-houdini
  extra: {}
  hook_app_launch: app_launch    # <----- use a custom app_launch hook
  hook_before_app_launch: default
  icon: '{target_engine}/icon_256.png'
  linux_args: ''
  linux_path: '@houdini_linux'
  location: {name: tk-multi-launchapp, type: app_store, version: v0.6.6}
  mac_args: ''
  mac_path: '@houdini_mac'
  menu_name: Launch Houdini
  versions: []
  windows_args: ''
  windows_path: '@houdini_windows'

Then all you have to do is modify the launch logic to launch the executable directly. As an example, you could keep the old behavior for directories (application bundles) and otherwise execute the command directly. Here's an example:

        elif system == "darwin":
            # on the mac, the executable paths are normally pointing
            # to the application bundle and not to the binary file
            # embedded in the bundle, meaning that we should use the
            # built-in mac open command to execute it
            if os.path.isdir(app_path):
                cmd = "open -n \"%s\"" % (app_path)
                if app_args:
                    cmd += " --args \"%s\"" % app_args.replace("\"", "\\\"")

            # not a directory, execute directly
            else:
                cmd = "%s %s" % (app_path, app_args.replace("\"", "\\\""))

The next time you run launch_houdini via tank in the Terminal, you should get all the debug output. Once you're done testing, don't forget to revert your path and undo your app launch changes. Happy debugging!

Installation and Updates

Adding this Engine to the Shotgun Pipeline Toolkit

If you want to add this engine to Project XYZ, and an environment named asset, execute the following command:

> tank Project XYZ install_engine asset tk-houdini

Updating to the latest version

If you already have this item installed in a project and you want to get the latest version, you can run the update command. You can either navigate to the tank command that comes with that specific project, and run it there:

> cd /my_tank_configs/project_xyz
> ./tank updates

Alternatively, you can run your studio tank command and specify the project name to tell it which project to run the update check for:

> tank Project XYZ updates

Collaboration and Evolution

If you have access to the Shotgun Pipeline Toolkit, you also have access to the source code for all apps, engines and frameworks in Github where we store and manage them. Feel free to evolve these items; use them as a base for further independent development, make changes (and submit pull requests back to us!) or simply tinker with them to see how they have been built and how the toolkit works. You can access this code repository at https://github.com/shotgunsoftware/tk-houdini.

Special Requirements

  • You need Shotgun Pipeline Toolkit Core API version v0.18.45 or higher to use this.

Configuration

Below is a summary of all the configuration settings used. These settings need to be defined in the environment file where you want to enable this App or Engine.

run_at_startup

Type: list

Description: Controls what apps will run on startup. This is a list where each element is a dictionary with two keys: 'app_instance' and 'name'. The app_instance value connects this entry to a particular app instance defined in the environment configuration file. The name is the menu name of the command to run when the Houdini engine starts up. If name is '' then all commands from the given app instance are started.

enable_sg_shelf

Type: bool

Default Value: True

Description: Controls whether a shelf will be built with commands registered by the installed apps. The shelf will be rebuilt dynamically as the Shotgun context changes.

menu_favourites

Type: list

Description: Controls the favourites section on the main menu. This is a list and each menu item is a dictionary with keys app_instance and name. The app_instance parameter connects this entry to a particular app instance defined in the environment configuration file. The name is a menu name to make a favourite.

launch_builtin_plugins

Type: list

Description: Comma-separated list of tk-houdini plugins to load when launching Houdini. Use of this feature disables the classic mechanism for bootstrapping Toolkit when Houdini is launched.

debug_logging

Type: bool

Description: Controls whether debug messages should be emitted to the logger

automatic_context_switch

Type: bool

Default Value: True

Description: Controls whether toolkit should attempt to automatically adjust its context every time the currently loaded file changes. Defaults to True.

enable_sg_menu

Type: bool

Default Value: True

Description: Controls whether a menu will be built with commands registered by the installed apps. It is not currently possible to rebuild the menu on a Shotgun context switch, so this option allows for the menu to be disabled in favor of the Shotgun shelf which can be rebuilt dynamically.

Release Notes

Welcome to the release notes for this Engine. Below you will find an overview of all the changes we did for each release. We try to be as detailed as possible and include all bugs we have fixed, features we have added and things that may have changed. If you have questions about a particular release, don't hesitate to contact our support team!

v1.2.1

2017-May-12

bumps required core version to v0.18.45

v1.2.0

2017-May-10

Adds support for launching Houdini using the new Software entity setup in Shotgun. It also includes a houdini plugin that can run standalone or directly from within the engine.

v1.1.0

2017-Apr-25

Removes bundled PySide and updates to new logging style

v1.0.11

2017-Feb-10

Guard automatic context switching with a check of the engine config setting

v1.0.10

2016-Aug-19

Use existing path separator, fallback to os.pathsep

v1.0.9

2016-Aug-17

Use existing path separator, fallback to os.pathsep

v1.0.8

2016-Aug-06

hot fix for houdini bug when mouse over shotgun menu buttons.

v1.0.7

2016-Jun-24

Safer logic for modifying HOUDINI_PATH during bootstrap

v1.0.6

2016-Jun-24

Safer logic for modifying HOUDINI_PATH during bootstrap

v1.0.5

2016-May-24

Adds support for context switching when using the Recent Files menu in Houdini

v1.0.4

2016-May-23

Adds support for context switching when using the Recent Files menu in Houdini

v1.0.3

2016-May-20

Adds support for context switching when using the Recent Files menu in Houdini

v1.0.2

2016-Mar-31

Fix for embedded panel regression

v1.0.1

2016-Feb-18

Adds a call to log a user metric for the DCC version

v1.0.0

2015-Nov-25

Houdini engine 1.0 release. Supports H14, H15, OSX, reloadable menus, tk panels and more.

v0.2.11

2015-Nov-25

QA polish and fixes for houdini engine update

v0.2.10

2015-Nov-06

Added dynamic Shotgun menu for Houdini 15+. Menu now updates with context switching.

v0.2.9

2015-Nov-04

Make toolkit apps look nice and consistent inside Houdini

v0.2.8

2015-Oct-29

Panel support in houdini

v0.2.7

2015-Oct-29

Limits engine support on OS X to Houdini 14+

v0.2.6

2015-Oct-25

Updates tk houdini engine for Houdini 14

v0.2.5

2015-Oct-06

Fix for UNC paths for shelf icons

v0.2.4

2015-Sep-28

fix to allow Shotgun shelf to work in houdini 13

v0.2.3

2015-Sep-25

Updated Houdini to support dynamic shelf for registered commands

v0.2.2

Fixed issue where an exception was raised whenever a dialog was shown using engine.show_dialog or engine.show_modal

v0.2.1

Fixed issue with UNC paths on Windows when creating menus

v0.2.0

Updated engine to use new dark theme. Misc tweaks and fixes.

Details: - The engine now uses the new dark theme introduced in 0.14.56. Toolkit UIs running in Houdini now look more similar to Maya's UI look and feel. - Error logging no longer pops up error messages in dialogs, instead it just logs a message. This is consistent with they way other engines work. - Since houdini runs its python console in a separate thread, running toolkit command from the console which results in UI generation would previously crash the system. Added protection for this so that if a UI is launched outside of the main UI thread, an error message is raised.

v0.1.11

Updated PySide version handling to support very old versions!

v0.1.10

Support for Houdini 13 and Python 2.7

Details: Support for Houdini 13 and Python 2.7

v0.1.9

Fix for PyQt on linux.

Details: Fix for PyQt on linux.

v0.1.8

Fix to let the engine run from houdini batch and hython.

Details: Fix to let the engine run from houdini batch and hython.

v0.1.7

Updated PyQt compatibility

v0.1.6

Updated to support PyQt

Details: Updated to support either PyQt or PySide. PySide will be preferred if it is available.

v0.1.5

PySide bundled for Windows. Houdini version check. Unicode support. Fix for debug output.

Details: PySide for Windows is now bundled. As linux uses the system python, docs updated to reflect that dependency. Version check added for Houdini version 12+ Unicode support in PySide Fix for being able to turn off debug output.

v0.1.4

sgtk windows now first appear above houdini.

Details: Added os specific support to make sure that sgtk dialogs do not appear behind Houdini

v0.1.3

Experimental Release of the new engine version to the app store.

v0.1.2

Updated manifest to be 0.12.5 compatible

v0.1.1

Minor changes to work nicely with core v0.12.5

v0.1.0

Initial release to the App Store.

Follow

7 Comments

  • 0
    Avatar
    Maxim Doucet

    Hi!

    Do you know if the engine works with houdini 14? It does not seem to work, even with everything configured the project environment (with "enable_sg_shelf: true" and "enable_sg_menu: true")

  • 0
    Avatar
    Josh Tomlinson

    Hi Maxim! 

    The houdini engine update is currently in QA and should be out soon with support for 14 and 15 as well as OS X. Can you tell me what version of the engine you're trying, what operating system, and what errors, if any, you're seeing? I'll be happy to help you figure out the issue here or you can submit a help ticket and I can grab that as well. 

    Thanks!

    Josh T.

  • 0
    Avatar
    Josh Tomlinson

    Hi Maxim!

    Just to follow up, we've pushed out v1.0.0 with support for Houdini 14 & 15. Feel free to open a ticket if you run into any issues and I'll jump on it. 

    Thanks!

    Josh T.

  • 0
    Avatar
    Marco Merletti

    Hi,

    I can't make it works with H15.5 Is is supposed to work with that Houdini version?

  • 0
    Avatar
    Josh Tomlinson

    Hi Marco! 

    Yes, the integration should work with Houdini 15.5. Would you mind submitting a support ticket to support@shotgunsoftware.com and summarize your setup? What operating system you're on, how you're launching Houdini (web, Desktop, command line, etc), and if there are any specific errors you're running into. 

    It would also be helpful if it is possible to provide a zipped up copy of your project configuration so that we can see if anything looks out of place there. 

    Thanks!

    -Josh T.

  • 0
    Avatar
    Marco Merletti

    Hi Josh! 

    I'll submit soon!

    Thanks a lot for the reply!

    Marco

  • 0
    Avatar
    Bradley Stilwell

    Hi guys is there an update to make it compatible with houdini 16?

Please sign in to leave a comment.