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 - 11.3. 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:

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

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

You can add your own shortcuts based on template paths in your current environment with the favourite_directories setting. The setting expects a list of dictionaries, with each item in the list representing a new favourite directory. Here is an example of the format you would use: (the icon can also be left unspecified by providing "" as the value.)

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:

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:

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:

definit_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!importnuketry:app=nuke.tk_nuke_nameofmyappapp.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:

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.

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 engineselection=engine_obj.get_menu_selection()iflen(selection)!=1:raiseTankError("Please select a single Project!")ifnotisinstance(selection[0],hiero.core.Bin):raiseTankError("Please select a Hiero Project!")project=selection[0].project()ifprojectisNone:# apparently bins can be without projects (child bins I think)raiseTankError("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.

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:

classSceneOperation(Hook):""" Hook called to perform an operation with the current scene """defexecute(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 """ifoperation=="current_path":# return the current script pathproject=self._get_current_project()curr_path=project.path().replace("/",os.path.sep)returncurr_pathelifoperation=="open":# open the specified scripthiero.core.openProject(file_path.replace(os.path.sep,"/"))elifoperation=="save":# save the current script:project=self._get_current_project()project.save()elifoperation=="save_as":project=self._get_current_project()project.saveAs(file_path.replace(os.path.sep,"/"))elifoperation=="reset":# do nothing and indicate scene was reset to emptyreturnTrueelifoperation=="prepare_new":# add a new project to hierohiero.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 engineselection=self.parent.engine.get_menu_selection()iflen(selection)!=1:raiseTankError("Please select a single Project!")ifnotisinstance(selection[0],hiero.core.Bin):raiseTankError("Please select a Hiero Project!")project=selection[0].project()ifprojectisNone:# apparently bins can be without projects (child bins I think)raiseTankError("Please select a Hiero Project!")returnproject

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

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. An optional hotkey parameter can be included for triggering the menu action (Nuke only).

favourite_directories

Type:list

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

launch_builtin_plugins

Type:list

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

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

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.

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

2019-Jan-14

Updates Nuke version to support 11.3

v0.11.4

2018-Aug-06

added ability to set hotkeys in the tk-nuke.yml settings file

v0.11.3

2018-Jul-25

Updates Nuke version to support 11.2

v0.11.2

2018-Jul-09

Context changing now works correctly in non-ui mode.

v0.11.1

2018-Jun-19

Updates logic around parsing Flame openclip files during publish.

Details:

We now use more reliable means of finding the first video track in an openclip file produced by Flame. We also preserve the openclip version number during our update of its contents.

v0.11.0

This allows us to have something like tk-nuke-quickdailies configured for Nuke Studio without having it show up in the Shotgun menu on the main menu bar. Instead, we now separate out those engine commands and add them to the nodes menu, just like would be the case in Nuke.

v0.10.5

2018-May-11

When publishing it now ensures that the work folder exists before attempting to save the script/project, in both Nuke and Nuke Studio.

v0.10.4

2018-May-04

Updates Flame icon to the 2019 version.

v0.10.3

2018-May-03

Fixed a bug with the publish description for "Submit for Review" plugin. It should now display the correct description, and not cause an error.

v0.10.2

2018-Apr-16

No longer imports the QWebEngineWidgets submodule from PySide2 on Windows in Nuke 11+.

Details:

Importing QtWebEngineWidgets from PySide2 on Windows can cause an unrecoverable deadlock in some cases. Since we do not make use of it in any of the out-of-the-box Toolkit bundles or tk-core, we can safely skip importing that submodule. Any clients that require its use can import it directly from PySide2.

v0.10.1

2018-Apr-12

Fixes engine initialization problems when running in Nuke 9.x.

v0.10.0

2018-Feb-13

Supports updating of Flame OpenClip publishes when no templates are in use.

Details:

When no template exists to identify an OpenClip file for the current Shot, we attempt to find a published clip file that comes from the new-style Flame workflow that makes use of the publish2 app during sequence export. If a usable clip is found, we update its contents in the same way we've always done in template-driven workflows. This behavior drives the core of the Flame-to-Nuke workflow.

v0.9.4

2017-Nov-15

Updates hook icons to match current version of Nuke

v0.9.3

2017-Nov-15

Updated icons with proper gamma

v0.9.2

2017-Nov-14

Adds support for review submission publish2 plugin

v0.9.1

2017-Nov-08

Adds publish plugin for updating Flame clip files

v0.9.0

v0.8.5

2017-Aug-23

Fixes a regression related to File->New and File->Open operations.

Details:

Fixes introduced for Nuke 11.x compatibility caused a regression that resulted
in a failure to properly initialize SGTK when a File->New or File->Open operation
was performed from an already running session of Nuke.

v0.8.4

2017-Aug-17

Fixes yet another crash-on-close bug in Nuke 11 on Linux.

v0.8.3

2017-Aug-15

Fixes a crash on close in Nuke 11 on Linux.

v0.8.2

2017-Aug-09

Fixes a crash on close in Nuke 11.

v0.8.1

v0.8.0

2017-Aug-08

Compatibility with Nuke 11.0v1.

v0.7.3

2017-Aug-07

Fixed a regression in v0.7.0 where pre-existing NUKE_PATH and HIERO_PLUGIN_PATH paths were not respected. The engine would wipe the environment variable paths and add it own custom ones, causing custom init.py and menu.py files not to be run. It now appends the custom toolkit paths to the end of the existing paths.

v0.6.11

v0.6.10

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

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.

9 Comments

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

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