Scene Breakdown

Scene Breakdown

Tools to see what in the scene is out of date.
Latest Version: v1.8.0 (prod)
For our version numbers, we follow the Semantic Versioning standard.
System Name: tk-multi-breakdown

Please Note: This document describes functionality only available if you have taken control over a Toolkit configuration. Please refer to the Shotgun Integrations User Guide for more details.
Overview Summary
      Scanning the Scene
      Accessing Shotgun Data
      API Access
                  Showing the breakdown UI
                  Running the scene analysis
                  Computing the highest version for an item
                  Updating a scene item
                  Breakdown API example
Installation, Updates and Development
Configuration Options
Release Notes History

The Scene Breakdown App shows you a list of items you have loaded (referenced) in your scene and tells you which ones are out of date. From this overview, you can select multiple objects and click the update button which will update all your selected items to use the latest published version.


The Scene breakdown shows you a list of referenced content and tells you which items are out of date. You access it from the Shotgun Menu.

Overview of the breakdown

You can select one more more items and hit update selected. This will switch the items to use the latest version of the content.

Scanning the Scene

When the breakdown app scans the scene for references, it will call a special scanning hook. The scanning hook will return a list of nodes with file corresponding paths. For each reference it finds, it returns the file path, and tank will look at the file path and first check if it recognizes it as a publish, and if it does, see if there is a more recent version available.

If the user clicks the update button that is shown for outdated versions, the app will call another hook to do the actual update work. This means that by customizing these hooks it is relatively simple to add new custom nodes to the breakdown.

Accessing Shotgun Data

If you need to access Shotgun data for the publish you are about to update to in the hook, this is straight forward; a single call to find_publish will retrieve metadata for all the items passed in from the app, like this:

class BreakdownHook(Hook):

    def update(self, items):
        Perform replacements given a number of scene items passed from the app.

        Once a selection has been performed in the main UI and the user clicks
        the update button, this method is called.

        The items parameter is a list of dictionaries on the same form as was
        generated by the scan_scene hook above. The path key now holds
        the that each node should be updated *to* rather than the current path.

        engine = self.parent.engine

        # resolve shotgun data for all paths passed via the items dictionary
        sg_data = tank.util.find_publish(engine.sgtk,
                                         [i["path"] for i in items],
                                         fields=["id", "code", "version_number"])

        for i in items:
            node_name = i["node"]
            node_type = i["type"]
            new_path = i["path"]
            # now that each item is processed, it is easy to access the
            # shotgun data via a dictionary lookup:
            sg_data = sg_data.get(i["path"])

            # once we have all our desired info and metadata, we can go ahead
            # and apply the update business logic.
            # [-business logic here-]

API Access

You can access the breakdown app programatically using its API. The following methods exist:

Showing the breakdown UI


If you want to show the breakdown UI, execute the show_breakdown_dialog() method. Assuming the app is included under a tk-multi-breakdown section in your currently running environment, this could for example be done like this:

>>> import sgtk
>>> e = sgtk.platform.current_engine()
>>> e.apps["tk-multi-breakdown"].show_breakdown_dialog()

Running the scene analysis

items = app_object.analyze_scene()

You can programmatically run the scene analysis logic by executing the analyze_scene() method. This executes exactly the same logic that the breakdown UI uses when it builds the listing of scene items.

The method returns a list of breakdown items. Each item is represented by a dictionary with a number of keys to describe the item. Only files whose path corresponds to a template in the Toolkit templates file will be detected. Files do not need to exist as publishes in Shotgun, however if they do, this method will return basic Shotgun publish metadata for them.

The two keys node_name and node_type are used to return a DCC-centric "address" or representation which makes it possible to identify the path within the DCC. In for example Maya and Nuke, this will return the node name and type. The logic for this is implemented in the hooks and will vary between DCCs. This method will attempt to connect to shotgun, but the number of calls made are constant and independent of the scene complexity.

Here is an example of what a dictionary in the return data typically looks like:

{'fields': {'Sequence': 'aaa',
            'Shot': 'aaa_00010',
            'Step': 'Comp',
            'eye': '%V',
            'height': 1556,
            'name': 'test',
            'output': 'output',
            'version': 1,
            'width': 2048},
 'template': <Sgtk TemplatePath nuke_shot_render_pub_mono_dpx>,

 'node_name': 'Read2',
 'node_type': 'Read',

 'sg_data': {'code': 'aaa_00010_test_output_v001.%04d.dpx',
             'entity': {'id': 1660, 'name': 'aaa_00010', 'type': 'Shot'},
             'id': 1424,
             'name': 'test',
             'published_file_type': {'id': 3,
                                     'name': 'Rendered Image',
                                     'type': 'PublishedFileType'},
             'task': {'id': 4714, 'name': 'Comp', 'type': 'Task'},
             'type': 'PublishedFile',
             'project': {'id': 234, 'name': 'Climp', 'type': 'Project'},
             'version_number': 1},

Handy Tip!: As you can see above, each item returns a template object and a fields dictionary to represent the path. If you want to see the actual raw path for the item, you can simply run template_obj.apply_fields(fields_dict). In the context of one of the item dictionaries returned by this method, the code would be

breakdown_items = analyze_scene()
for item in breakdown_items:
   path = item["template"].apply_fields(item["fields"])

Computing the highest version for an item

highest_version = app_object.compute_highest_version(template, fields)

In order to figure out the highest version for an item, use the compute_highest_version(template, fields) method. The template and fields parameters represent a path that should be analyzed are typically grabbed from the output of the analyze_scene() method. With the breakdown app, the template key containing the version number is always required to be named {version}.

This will perform a scan on disk to determine the highest version. The method returns the highest version number found on disk. See the usage example below for more details.

Updating a scene item

app_object.update_item(node_type, node_name, template, fields)

In order to update an item, you can use the update_item(node_type, node_name, template, fields) method. The template and fields parameters represent a path that should be updated to. The node_name and node_type parameters are used to identify which node in the scene should be modified. Typically, these values are grabbed from the output of the analyze_scene() method.

This is similar to running the update in the breakdown UI. The actual update call will be dispatched to a hook which handles the DCC specific logic. See the usage example below for more details.

Breakdown API example

Below is an example showing how to retrieve the scene breakdown and update all items that are not using the latest version.

<a name="find the breakdown app instance"></a>
# find the breakdown app instance
import sgtk
engine = sgtk.platform.current_engine()
breakdown_app = engine.apps["tk-multi-breakdown"]

<a name="get list of breakdown items"></a>
# get list of breakdown items
items = breakdown_app.analyze_scene()

<a name="now loop over all items"></a>
# now loop over all items
for item in items:

    # get the latest version on disk
    latest_version = breakdown_app.compute_highest_version(item["template"], item["fields"])

    # if our current version is out of date, update it!
    current_version = item["fields"]["version"]
    if latest_version > current_version:

        # make a fields dictionary representing the latest version
        latest_fields = copy.copy(item["fields"])
        latest_fields["version"] = latest_version

        # request that the breakdown updates to the latest version
        breakdown_app.update_item(item["node_type"], item["node_name"], item["template"], latest_fields)

Related Apps and Documents


The Shotgun Loader lets you quickly overview and browse the files that you have published to Shotgun. A searchable tree view navigation system makes it easy to quickly get to the task, shot or asset that you are looking for and once there the loader shows a thumbnail based overview of all the publishes for that item. Through configurable hooks you can then easily reference or import a publish into your current scene.

Shotgun Pipeline Tutorial

This document provides a step-by-step tutorial for Technical Directors (TDs) wishing to set up a simple, end-to-end pipeline using Shotgun integrations and the Toolkit platform. The goal of the tutorial is to provide users with an understanding of the fundamental aspects of the integrations and platform as well as the know how to build and customize a Shotgun-base pipeline to fit their studio's specific needs.

Installation and Updates

Adding this App to the Shotgun Pipeline Toolkit

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

> tank Project XYZ install_app asset tk-maya tk-multi-breakdown

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

Special Requirements

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


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.


Type: hook

Default Value: {self}/{engine_name}

Description: Scan the scene for input files. Returns A list of nodes and file names. Each item in the list returned should be a dictionary containing a node, type and a path key. The node key should be a maya node name, the type key is a reference type and the path key is a full path to the file currently being referenced.


Type: hook

Default Value: {self}/

Description: Perform a scan on disk to determine the highest version. Given a template and some fields, return the highest version number found on disk. The template key containing the version number is assumed to be named {version}.

Release Notes

Welcome to the release notes for this App. 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!



Rebranded to ShotGrid



Bug Fix for an issue gathering references in Maya.


Fixes an issue in Maya if there was more than one instance of a reference in the scene, only one would be shown in the breakdown app.



Fixes a deadlock in VRED.



Fixes crash when there are many items in the scene



Adds support for Python 3.



Publishes now show the entity display name instead of the entity name.



Bug fix for public methods.


Fixes a regression from v1.6.0 with the public methods app.compute_highest_version and app.analyze_scene. Both methods should no longer throw a the 'module' object has no attribute ... error..

app.compute_highest_version should now make use of the hook.



Moves some internal version computation logic into a new hook!


Moves the logic for determining the highest version number available for a publish into a new hook so that it can be easily customized without having to fork the app



Adds support for clips in Nuke Studio and Hiero.



Removes problematic profiles from png files used as icons.


This will silence libpng warnings from Qt when the png files are loaded as pixmaps. This is a second attempt as this profile stripping, and uses ImageMagick's "mogrify" command to achieve the desired result, which maintains color consistency.



Removed explicit dependency on shotgun utils that was not required.



QA fix to remove alembic archive support



QA fix with proper handling of alembicarchive updates in Houdini



Adds support for houdini alembic node updates


Adds support for context changes.


New red/green icons for better visibility


Added API Support


For details, see the app documentation.


Added API method to launch the UI programatically.


Improved support for Sequence keys that are not called SEQ


  • All sequence keys/fields are now supported in the same generic way


Added support for Mari


  • Shotgun aware geometry in Mari can now be updated when there are new versions using this app


Minor tweaks and improvements


  • Added 'breakdown' short command name
  • Added detection of geometry & camera nodes for Nuke
  • Updated to use Widget framework v0.2.x which uses the Shotgun Utils framework to download all thumbnails


First public version in the app store.