Scene Breakdown

Scene Breakdown

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

Table of Contents:

Overview Summary

Documentation

      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

Overview

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 an update button which will update all your selected items to use the latest published version.

Documentation

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

app_object.show_breakdown_dialog()

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.

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

# get list of breakdown items
items = breakdown_app.analyze_scene()

# 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

Loader

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.

Toolkit Pipeline Tutorial

This document provides a step-by-step tutorial for Technical Directors (TDs) setting up a simple end-to-end pipeline using Toolkit. New Toolkit users who finish this tutorial will understand the fundamental aspects of the platform as well as how to customize it based on their studio's specific needs. The tutorial also provides an introduction to the out-of-the-box Toolkit apps and how they fit together in the artist workflow.

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 https://github.com/shotgunsoftware/tk-multi-breakdown.

Special Requirements

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

hook_scene_operations

Type: hook

Default Value: {self}/{engine_name}_scene_operations.py

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.

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!

v1.4.6

2017-Mar-15

Removes problematic profiles from png files used as icons.

Details:

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.

v1.4.4

2016-Aug-25

Removed explicit dependency on shotgun utils that was not required.

v1.4.3

2016-Feb-02

QA fix to remove alembic archive support

v1.4.2

2016-Feb-01

QA fix with proper handling of alembicarchive updates in Houdini

v1.4.1

2016-Jan-22

Adds support for houdini alembic node updates

v1.4.0

Adds support for context changes.

v1.3.1

New red/green icons for better visibility

v1.3.0

Added API Support

Details:

For details, see the app documentation.

v1.2.0

Added API method to launch the UI programatically.

v1.1.1

Improved support for Sequence keys that are not called SEQ

Details:

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

v1.1.0

Added support for Mari

Details:

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

v1.0.2

Minor tweaks and improvements

Details:

  • 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

v1.0.1

First public version in the app store.

Follow

4 Comments

  • 0
    Avatar
    Manne Öhrström

    Hello Benoit!

    We will be slowly, gradually phasing out the nuke/maya specific breakdows in favour of this multi app. Right now, the code and functionality is the same for the multi app, apart from some compatibility updates to make the multi app code a bit more up to date with the rest of the toolkit code base.

    The biggest difference is currently the way the hooks are being structured. With the multi app, the new style hooks are used to make the hook layout a big cleaner. The old maya/nuke breakdown apps had two hooks - a scan scene hook and an update hook. The multi breakdown app instead uses a single hook file with two methods for scene scanning and updates.

    So to answer your question, "upgrading" to the multi app is a matter of reshuffling any custom hooks you may have. With the new style hooks, it is possible to inherit, so that you can run both the built-in behaviour and added custom rules at the same time without duplicating any code. We'll document this process in due course along with some additional updates and tweaks to the multi apps!

    Let us know if you need any help with any specific reshuffling of your configs!

  • 0
    Avatar
    Benoit Leveau

    Good to see you've merged tk-maya-breakdown and tk-nuke-breakdown. What is the recommended process to switch the old apps to the new one?

  • 0
    Avatar
    Daniel Wong

    Hi! May I know if we will have the breakdown code for Houdini in the near future?

    Thanks!

  • 0
    Avatar
    Darragh D

    Any development to get this working for Max 2017?

Please sign in to leave a comment.