Nuke

Shotgun Engine for Nuke

Shotgun Integration in Nuke
By: Shotgun Software
Latest Version: v0.6.13 (prod)
For our version numbers, we follow the Semantic Versioning standard.
System Name: tk-nuke

Table of Contents:

Overview Summary

Documentation

      Information for App Developers

            Context Tracking

            Apps with custom gizmos

            Apps Creating Nodes

      Using the Shotgun Engine for Nuke within Hiero

            How to Configure Hiero Menus

                  Apps which require the concept of a current scene

            Information for App Developers

                  get_menu_selection()

                  HieroEngine.get_menu_category()

                  How to configure your hooks to work with Hiero

                  Using debug logging to see menu events

Installation, Updates and Development

Configuration Options

Release Notes History

Overview

The Shotgun engine for Nuke establishes a bridge between Shotgun Pipeline Toolkit apps and Nuke, Hiero, and Nuke Studio. Because Nuke contains both PySide and Python, the engine is a relatively thin layer that mostly handles menus and startup. The engine exposes several menu handles through its interface, allowing an app to register items on the main menu as well as the node and pane menus in Nuke.

Supported Application Versions

This item has been tested and is known to be working on the following application versions: 7.0, 8.0, 9.0, 10.0, 10.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 Nuke contains a standard platform for integrating Shotgun Apps into Nuke, Nuke Studio, and Hiero. It is light weight and straight forward and adds a bunch of new things to Nuke.

It creates a Shotgun Menu in Nuke on which various items are displayed:

Tank Menu

It creates a Shotgun Node Menu in Nuke on which various items are displayed:

Tank Menu

It adds Shotgun shortcuts to the file dialogs which makes it easy to jump to various file system locations:

Tank Menu

You can add your own shortcuts based on template paths in your current environment with the favourite_directories setting. The "Shotgun Current Project" favourite is added automatically for each root defined. You can customize the name with the project_favourite_name setting, or disable these favourites by setting the value to an empty string ''


Note: There is currently a bug in Nuke 8.0 running specifically on CentOS 6.5 that causes Nuke to crash when running Toolkit. Other versions of CentOS are unaffected. The Foundry is aware of this issue (bug 43766). If you are running into this, please contact us so we can try and help you workaround it until it is resolved in a future update of Nuke.

Information for App Developers

Context Tracking

The Shotgun engine for Nuke will switch context automatically when files are loaded. Whenever a file is loaded, the engine will look at the file, try and resolve a context from it.

Apps with custom gizmos

The Shotgun engine for Nuke makes it easy to handle custom gizmos. If you are writing an app which uses custom gizmos, you can just drop them into a folder called gizmos and the engine will automatically add that location to the nuke path:

Nuke Gizmos

You can then easily access your gizmo via the create node functionality:

  • nuke.createNode("WriteTank")

Warning!! Please note that while the use of gizmos 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 a gizmo in the scene, you have introduced a dependency between that scene and the gizmo 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 gizmos being used in scenes.

Apps Creating Nodes

Apps that create custom nuke nodes need to be carefully crafted. We recommend not using gizmos since these require a dependency between the scene and the gizmo code. Instead, save your custom nodes as a nuke file and import them into the scene:

    group_node_script = os.path.join(self.disk_location, "resources", "my_group_node.nk")
    group_node = nuke.nodePaste(group_node_script)

Any code calling the node from within the app can just use the instance returned.

Any code needing to call the app from inside the group should do so carefully so that the code is backwards compatible. We recommend the following approach:

At app startup, register app handle as part of the nuke namespace:

    def init_app(self):

        nuke.tk_nuke_nameofmyapp = self

If you for example have a button on your group node and want to call some Shotgun app code, try to gracefully fail if the Shotgun Toolkit cannot be found. The below code is code that is associated with a python button knob that belongs to the group node that the app can create:

# have to gracefully support the case when 
# sgtk is not in the system at all!
import nuke
try:
  app = nuke.tk_nuke_nameofmyapp
  app.do_something_v1(nuke.thisNode())
except:
  nuke.warning("Could not do XYZ! Most likely Sgtk is not currently active.")

If you make changes to the app behaviour, just keep versioning up the version number on the app callback and that way your app code can support both the new and the old behaviour.

Using the Shotgun Engine for Nuke within Hiero

The Shotgun engine for Nuke is also used for Shotgun-aware integrations running within Hiero.

It allows you to place Shotgun App actions in several places in the application, both in a specific Shotgun menu on the main menu bar and in the various right click context menus that you find in the different Hiero panels.

How to Configure Hiero Menus

Because Hiero has several different menus, there are more options to configure where menu items go than in Maya or Nuke, for example. The Shotgun engine for Nuke's Hiero workflow configuration may look like this:

  tk-hiero:
    location: {name: tk-nuke, type: app_store, version: v0.6.9}
    debug_logging: false

    timeline_context_menu:
    - {app_instance: tk-hiero-openinshotgun, keep_in_menu: false, name: Open in Shotgun, requires_selection: true}

    spreadsheet_context_menu:
    - {app_instance: tk-hiero-openinshotgun, keep_in_menu: false, name: Open in Shotgun, requires_selection: true}

    bin_context_menu:
    - {app_instance: tk-multi-workfiles, keep_in_menu: false, name: "Shotgun Save As...", requires_selection: true}
    - {app_instance: tk-multi-workfiles, keep_in_menu: false, name: "Version up Current Scene...", requires_selection: true}
    - {app_instance: tk-multi-snapshot, keep_in_menu: false, name: "Snapshot...", requires_selection: true}
    - {app_instance: tk-multi-snapshot, keep_in_menu: false, name: "Snapshot History...", requires_selection: true}
    - {app_instance: tk-multi-publish, keep_in_menu: false, name: "Publish Project...", requires_selection: true}

    menu_favourites:
    - {app_instance: tk-multi-workfiles, name: Shotgun File Manager...}

Most engines have a menu_favourites option, a list where you can specify "shortcuts" which are put on the main Shotgun menu. In addition to this, the Hiero-specific configuration has three special sections:

  • timeline_context_menu represents the menu you get when you right click on a clip in the time line editor.
  • spreadsheet_context_menu represents the menu you get when you right click on a selection of items in the spreadsheet editor.
  • bin_context_menu represents the menu you get when you right click on a selection in of items in the bin editor, where you see all the different projects and media.

In order to add items to these menus, just make sure that the name field you define in the config matches what the App is displaying on its menus.

Apps which require the concept of a current scene

Some Toolkit Apps requires a notion of a default scene or default project. For example, the snapshot app knows how to snapshot the current scene. However, unlike Maya or Nuke, Hiero does not have a concept of a current scene. Several projects can be opened in Hiero at the same time. Therefore, you often need to add special logic in your hooks to help an app (like the snapshot app) to find out which project is being clicked on. We show how this works in the following doc sections.

Information for App Developers

Because Hiero does not have the notion of a current project, we have added more powerful tools so that Apps can easily find out what is being clicked on inside of Hiero. Therefore, two methods have been added to the Shotgun engine for Hiero:

get_menu_selection()

Returns the list of Hiero objects selected in the most recent menu click. This list may contain items of various types. To see exactly what is being returned by which methods, turn on debug logging - this will print out details of what is going on.

Examples of objects that are being returned are:

list engine_object.get_menu_selection()

Parameters & Return Value

  • Returns: List of Hiero Objects

Example

Get the objects selected in the most recent click, ensure that a single object was selected and that this object is a valid Hiero project. This can be useful for example if you want to trigger save, load or publish operations for a project in Hiero.

# get the menu selection from the engine
selection = engine_obj.get_menu_selection()

if len(selection) != 1:
    raise TankError("Please select a single Project!")

if not isinstance(selection[0] , hiero.core.Bin):
    raise TankError("Please select a Hiero Project!")

project = selection[0].project()
if project is None:
    # apparently bins can be without projects (child bins I think)
    raise TankError("Please select a Hiero Project!")

HieroEngine.get_menu_category()

Returns the UI area where the last menu click took place. This command is less likely to be used - you may need it in cases where you have an app command that you want to behave differently depending on which menu it was called from.

area_enum engine_object.get_menu_category()

Parameters & Return Value

Returns one of the following constants:

  • HieroEngine.HIERO_BIN_AREA
  • HieroEngine.HIERO_SPREADSHEET_AREA
  • HieroEngine.HIERO_TIMELINE_AREA
  • None for unknown or undefined

How to configure your hooks to work with Hiero

Multi Apps configured for Hiero will typically need to find out which project was being clicked on. For example, the tk-multi-workfiles App needs to do a "Shotgun Save As" of a project. We therefore add the Tank Save As command to the bin menu in Hiero so that a user can right click a project in the bin view and select the Save As option.

The engine configuration would look like this:

bin_context_menu:
- {app_instance: tk-multi-workfiles, keep_in_menu: false, name: "Shotgun Save As...", requires_selection: true}

Now, in the app itself, each engine needs to configure a hook which handles scene events such as save and load. For an application like Maya or Nuke, this is normally just doing a save, a load etc. But for Hiero, we need to start by finding out which project was actually clicked. The hook code in our example above would look like this:

class SceneOperation(Hook):
    """
    Hook called to perform an operation with the
    current scene
    """

    def execute(self, operation, file_path, context, **kwargs):
        """
        Main hook entry point

        :operation: String
                    Scene operation to perform

        :file_path: String
                    File path to use if the operation
                    requires it (e.g. open)

        :context:   Context
                    The context the file operation is being
                    performed in.

        :returns:   Depends on operation:
                    'current_path' - Return the current scene
                                     file path as a String
                    'reset'        - True if scene was reset to an empty
                                     state, otherwise False
                    all others     - None
        """

        if operation == "current_path":
            # return the current script path
            project = self._get_current_project()
            curr_path = project.path().replace("/", os.path.sep)
            return curr_path

        elif operation == "open":
            # open the specified script
            hiero.core.openProject(file_path.replace(os.path.sep, "/"))

        elif operation == "save":
            # save the current script:
            project = self._get_current_project()
            project.save()

        elif operation == "save_as":
            project = self._get_current_project()
            project.saveAs(file_path.replace(os.path.sep, "/"))

        elif operation == "reset":
            # do nothing and indicate scene was reset to empty
            return True

        elif operation == "prepare_new":
            # add a new project to hiero
            hiero.core.newProject()

    def _get_current_project(self):
        """
        Returns the current project based on where in the UI the user clicked
        """

        # get the menu selection from the engine
        selection = self.parent.engine.get_menu_selection()

        if len(selection) != 1:
            raise TankError("Please select a single Project!")

        if not isinstance(selection[0] , hiero.core.Bin):
            raise TankError("Please select a Hiero Project!")

        project = selection[0].project()
        if project is None:
            # apparently bins can be without projects (child bins I think)
            raise TankError("Please select a Hiero Project!")

        return project

Using debug logging to see menu events

If you want to see which objects are returned by Hiero when a certain selection is clicked on, just turn on the engine debug mode. In the script editor you get a summary of the objects that are selected with each click:

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-nuke

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

Special Requirements

  • You need Shotgun Pipeline Toolkit Core API version v0.17.0 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.

timeline_context_menu

Type: list

Description: Controls which apps are added to the context menu for the timeilne view. This is a list and each item is a dictionary with keys app_instance, keep_in_menu, requires_select, 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 add to the context menu. keep_in_menu is true if this item should be added to the main menu or not. requires_selection will disable the menu item when there are no items selected in the view.

use_sgtk_as_menu_name

Type: bool

Description: Optionally choose to use 'Sgtk' as the primary menu name instead of 'Shotgun'

spreadsheet_context_menu

Type: list

Description: Controls which apps are added to the context menu for the spreadsheet view. This is a list and each item is a dictionary with keys app_instance, keep_in_menu, requires_select, 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 add to the context menu. keep_in_menu is true if this item should be added to the main menu or not. requires_selection will disable the menu item when there are no items selected in the view.

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.

favourite_directories

Type: list

Description: Adds entries to the favourites section in the file chooser.

compatibility_dialog_min_version

Type: int

Default Value: 10

Description: Specify the minimum Application major version that will prompt a warning if it isn't yet fully supported and tested with Toolkit. To disable the warning dialog for the version you are testing, it is recomended that you set this value to the current major version + 1.

bin_context_menu

Type: list

Description: Controls which apps are added to the context menu for the bin view. This is a list and each item is a dictionary with keys app_instance, keep_in_menu, requires_select, 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 add to the context menu. keep_in_menu is true if this item should be added to the main menu or not. requires_selection will disable the menu item when there are no items selected in the view.

debug_logging

Type: bool

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

project_favourite_name

Type: str

Default Value: Shotgun Current Project

Description: Allows customizing the name of the favourite directory representing the current project root in the file chooser. eg. 'Shotgun Current Project'. In multi-root configs, there will be an entry for each root eg. 'Shotgun Current Project (secondary)'. Specifying an empty string will disable this menu from being added to the favourites automatically.

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!

v0.6.13

2017-Apr-06

Fixes a bug in Hiero usage reporting.

v0.6.12

2017-Feb-15

Updated Nuke version to support 10.5

v0.6.11

2016-Nov-08

Adds custom equality logic for the Nuke panel wrapper class.

v0.6.10

2016-Nov-03

Wrapped toolkit panel widgets are now accessible via their parent NukePanel objects.

v0.6.9

2016-Aug-09

Allows node menu commands to be context specific.

v0.6.8

2016-Aug-03

Switches to using onScriptLoad rather than onCreate to handle context setting.

Details:

This change is more efficient than the previous approach, and works around a Nuke bug that causes some node references in Python to not be properly attached to a back-end PythonObject under certain circumstances on some platforms.

v0.6.7

2016-Jul-28

Fixes a regression in the bootstrap process for Nuke that caused tk_nuke_qt to be inaccessible.

v0.6.6

2016-Jun-17

Only Disabling Parenting for Nuke 7

v0.6.5

2016-Jun-15

Changes a log_warning to a log_debug to reduce noisy output.

Details:

This is going to be triggered on most launches of Hiero and Nuke Studio, as both will cause a file read of a template file that is unlikely to be stored in an SGTK-aware location. We don't need to be scaring the user with nasty output containing Python tracebacks when it's completely harmless.

v0.6.4

2016-Jun-14

Adds an event callback for Hiero and Nuke Studio that will change Toolkit's context when opening a project file from File->Open and File->Recent Files if it is different from the current context.

v0.6.3

2016-Jun-10

Skips triggering a context change if the new context is the same as the current context.

v0.6.2

2016-Jun-09

Panel apps launch as dialogs when running in Hiero mode.

Details:

Hiero doesn't support embedding panels into its main window the way that Nuke and Nuke Studio do. As such, we redirect panel requests to show as dialogs to remain compatible.

v0.6.1

2016-May-11

Tweaks for Nuke/Hiero/Nuke Studio 10.0v1 compatibility.

v0.6.0

2016-Mar-29

Provides bootstrapping as part of Nuke's standard init.py startup.

Details:

Previously, we only bootstrapped and initialized Toolkit from a menu.py file. This menu.py is only sourced on launch when Nuke is running a GUI session, and as a result, running "nuke -t" did not initialize toolkit. We now have the same bootstrapping routine running from an init.py when Nuke is starting in batch mode.

v0.5.6

2016-Feb-29

Ensures that we only call clearMenu on nuke.Menu objects.

v0.5.5

2016-Feb-18

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

v0.5.4

Requires tk-core version 0.17.0 or later.

Details:

The context-changing behavior of tk-nuke requires functionality provided in v0.17.0 or newer of tk-core.

v0.5.3

Updated icons and bug fix for context changing.

v0.5.2

Cleans up context behavior when changing tabs in an empty Nuke Studio session.

v0.5.1

Adds full Nuke Studio integration.

Details:

Nuke Studio is now fully supported! When opening or focusing into a Nuke script within a Nuke Studio project, Toolkit will change to that context on the fly.

v0.4.1

Adds Hiero 9.0 support.

Details:

Hiero 9.0 support has been added to the Nuke engine. This allows for a single engine to be used for multiple modes of Nuke. Also, until full Nuke Studio support is added, the engine will treat it as if it were Hiero, allowing Hiero menus and apps to be used from Nuke Studio. Instructions on how to upgrade to using the new tk-nuke engine with Hiero 9.0, please see this knowledge base article.

v0.3.3

2015-Sep-18

Fixed an issue causing user login credentials not to be carried over on file open and file.

v0.3.2

2015-Sep-18

Fixed a bug causing QT import errors when files were loaded via the file manager.

v0.3.1

Adds panel support and new icons.

Details:

This implements the panel interfaces added in Core v0.16.15, allowing apps to dock panels into Nukes user interface. Panels can be saved to persist across sessions and launch at startup. This change also switches icons from the old T logo to the SG logo.

v0.2.24

Nuke 9 is now officially supported.

v0.2.23

Offical support for Nuke v8.0

Details: Default compatibility warnings have been bumped to any version of Nuke later than v8.0.x.

v0.2.22

Added setting to customize name of the "Shotgun Current Project" favourite directory entry in the file chooser.

Details: You may also disable it by assigning an empty value to this setting.

v0.2.21

Removed deprecated queue interface.

Details: This update removes the queue interface which was deprecated in Jaunary 2013. If any of the apps you use are still relying on these interfaces, please do not go ahead with this update but instead email us on toolkitsupport@shotgunsoftware.com.

v0.2.20

Added a setting to control the compatibility warning dialog that gets shown for untested versions of Nuke.

Details: - The compatibility_dialog_min_version setting allows you to set the minimum major version of Nuke that the dialog will get displayed for. - If you need to disable the warning dialog for an untested version of Nuke, it is recommended that you set this to the next major version (e.g. 9 if you are using Nuke 8.0v4).

v0.2.19

Fixed an issue with the error reporting which would cause it to fail when in non-ui mode.

v0.2.18

add setting to add favorites to the file chooser

Details: Setting allows adding favorites to the file chooser. Thanks to @tokejepson for the pull request!

v0.2.17

Errors emitted via the log_error() method are no longer shown via UI popups but just registered with the error log.

v0.2.16

Fixes crash on exit in Nuke 7

Details: Remove main window parenting for Nuke 7 to avoid a crash on exit where the PySide Shiboken cleanup is happening after the python interpreter has been shut down.

v0.2.15

Minor adjustments to how the menu items are sorted.

v0.2.14

Fixed a bug in the menu generation which would cause Nuke 7.x to crash on Linux when the engine was destroyed.

v0.2.13

Added a version warning for currently unsupported versions of Nuke to the engine startup

v0.2.12

Renames and support for the new name Sgtk.

v0.2.11

Renames and support for the new name Sgtk.

v0.2.10

Better bookmarks handling.

v0.2.9

Uses new API methods for file system access.

v0.2.8

Updated icon and manifest.

v0.2.7

Fixed a number of bugs

Details:

  • Fixed issued with gizmo UNC paths on windows
  • Fixed issues with the queue API being unstable
  • Deprecated the queue API as part of v0.12.5 compliance
  • added a has_ui property that reports when Nuke is running in batch mode

v0.2.6

Misc bug fixes

v0.2.3

Misc bug fixes.

v0.2.2

UI tweaks and bug fixes.

  • Widget library is now pyside/pyqt4 agnostic
  • Added icon support for all nuke menu items.
  • Tweaks to menu handling.

v0.2.1

Bug fixes.

  • Fixed a bug where multi selection would fail when item was substracted from the selected set.
  • Better handling of window destruction in pyside

v0.2.0

New UI and improved menu layouts.

(Requires Tank v0.10.8)

  • New context UI with information about apps and environments.
  • Improved menu with an option to add favourites.

v0.1.1

The nuke engine now works with project only contexts.

v0.1.0

First Release with the new Tank API.

v0.0.2

Minor bug fixes.

  • Fixed a bug which prevented the menu in Nuke from rendering correctly if the Core API returned unicode strings rather than std python strings.

v0.0.1

Initial release to the App Store.

Follow

9 Comments

  • 0
    Avatar
    Benoit Leveau

    Is Nuke 7.0 supported? I can't get it to show up in Nuke 7.0v8, though if I try to execute 'import sgtk' in the script editor it works (so the engine initialized the correct path environment variables).

    How is the menu launched and is there a way to debug that?

  • 0
    Avatar
    Benoit Leveau

    As usual, I found the problem just after sending this message...

    A conflict in the PATH with the Ocula plugin. So it seems to work fine in 7.0!

  • 0
    Avatar
    ivarrystad

    How can we configure the write nodes? I know we can configure the path in the templates file. But what about the name of the nodes? And can you set some of the write-node atributtes?

  • 0
    Avatar
    ivarrystad

    Sorry, just found the documentation for it here:

    https://support.shotgunsoftware.com/entries/95440797

    Just another example of rtfm :)

  • 0
    Avatar
    Ryan Mayeda

    No problem at all - glad you found it!  :)

  • 0
    Avatar
    Seth Lippman

    Is there a timeline for Nuke 8 support? (Or maybe its already supported?) 

  • 0
    Avatar
    Fabian Dittrich

    Hi!

    I didn't find the format of the favourite_directories entry documented, so I had to trial&error it. Maybe it's useful.

    So, it's a list of dictionaries, each having these keyes:

    display_name: A string that shows up in Nuke's filebrowser

    template_directory: A template defind in templates.yml pointing to a directory

    icon: An icon to display next to the entry in Nuke's filebrowser

    Cheers,

    Sebastian

  • 0
    Avatar
    Ryan Mayeda

    Hi Seth.

    You can run Toolkit with Nuke 8, but you'll get the "we haven't QA-ed this yet" message.  A couple of clients disabled the warning themselves and are using Nuke 8 with no reported problems yet (yay!), and I gave it a try myself to see if anything jumped out and thankfully nothing did.

    We have a ticket in our next sprint to do a full QA pass on all of the operating systems, and we are hoping to release a new Nuke engine that removes the warning for Nuke 8 in the next few weeks...

    Ryan.

  • 1
    Avatar
    Anthony Scudese

    For favourite_directories:

    Here is an example from my shot.yml:

    favourite_directories: [{'display_name':'Shotgun Current Shot Work Area', 'template_directory': shot_work_area_nuke, 'icon': '{self}/resources/sg_logo_80px.png'}]
Please sign in to leave a comment.