Flow Production Tracking Hiero Export API reference, v0.8.1

Overview

The tk-hiero-export app adds custom Flow Production Tracking export processors to the Hiero/Nuke Studio export framework.

By way of custom export processors, the user can create and update entities in the current Project in Flow Production Tracking.

During the export process a number things can happen:

Status of associated Shot entities can be updated
Nuke scripts can be written into the project’s filesystem structure for each Shot that’s processed
Sequence and Shot entity data can be updated in Flow Production Tracking
Cuts can be update to include new CutItems built from the exported sequences

Documentation from The Foundry concerning the Hiero Python API can be found here.

Hooks

Hooks provided by the Hiero Export app allow for customization of various aspects of the export process and its UI.

Updating Shot entities

class base_hooks.HieroUpdateShot(parent)[source]

This class defines methods that handle updating the Shot entity in Shotgun, as well as whether and how the filesystem structure is created for a Shot during export.

create_filesystem_structure(entity_type, entity_id, preset_properties)[source]

Handles creating the filesystem structure for the shot that was exported. The preset properties dictionary is provided to allow for the lookup of any custom properties that might have been defined in other hooks, like can be achieved when using the hiero_customize_export_ui hook.

Example Implementation:

# Check our custom property to know whether we should create the filesystem
# structure or not.
if preset_properties.get("custom_create_filesystem_property", True):
    self.parent.logger.debug(
        "Creating file system structure for %s %s..." % (entity_type, entity_id)
    )
    self.parent.sgtk.create_filesystem_structure(entity_type, [entity_id])
else:
    self.parent.logger.debug("Not creating the filesystem structure!")

Parameters:

entity_type (str) – The entity type that was created or updated as part of the export. Most likely this will be “Shot”.
entity_id (int) – The id of the entity that was created or updated as part of the export.
preset_properties (dict) – The export preset’s properties dictionary.

update_shotgun_shot_entity(entity_type, entity_id, entity_data, preset_properties)[source]

Handles updating the Shot entity in Shotgun with the new data produced during the export. The preset properties dictionary is provided to allow for the lookup of any custom properties that might have been defined in other hooks, like can be achieved when using the hiero_customize_export_ui hook.

Example Implementation:

# If the custom bool property is False, we don't update the
# sg_cut_in field on the Shot entity.
if not preset_properties.get("custom_update_cut_in_property", True):
    del entity_data["sg_cut_in"]

self.parent.sgtk.shotgun.update(entity_type, entity_id, entity_data)

Parameters:

entity_type (str) – The entity type to update.
entity_id (int) – The id of the entity to update.
entity_data (dict) – The new data to update the entity with.
preset_properties (dict) – The export preset’s properties dictionary.

Updating and Creating Cut and CutItem entities

class base_hooks.HieroUpdateCuts(parent)[source]

This class defines methods that control if and how Cuts and CutItems are created or updated during the export process.

allow_cut_updates(preset_properties)[source]

Determines whether to process the associated Cut entity during export. The preset properties provided allow for customization of this behavior based on custom properties added to the shot processor preset via other hooks, such as the customize_export_ui hook.

Example Implementation:

# The my_custom_property is a bool property that controls
# whether we update cuts or not.
return preset_properties.get("my_custom_property", True)

Parameters:: preset_properties (dict) – The properties dictionary of shot processor preset.
Returns:: True to allow Cut updates, False to disallow.
Return type:: bool

create_cut_item(cut_item_data, preset_properties)[source]

Handles the creation of the CutItem entity in Shotgun. This hook method can be overridden in order to put conditions on whether or how this creation occurs. The preset’s properties are provided to allow for looking up custom properties that might have been added to the preset in other hooks, like can be achieved when using the hiero_customize_export_ui hook.

Parameters:

cut_item_data (dict) – The dictionary of field/value pairs to use when creating the CutItem entity in Shotgun.
preset_properties (dict) – The export preset’s properties dictionary.

Returns:

The created CutItem entity dictionary, or None if no CutItem entity was created.

Return type:

dict or None

get_cut_thumbnail(cut, task_item, preset_properties)[source]

Gets the path to a thumbnail image to use when updating the export’s associated Cut’s thumbnail image. If None is returned by this method, the Cut’s thumbnail will not be updated.

Parameters:

cut (dict) – The Cut entity dictionary associated with the export.
task_item – The TrackItem object associated with the export task. Hiero API docs are available here.
preset_properties (dict) – The export preset’s properties dictionary.

Returns:

The path to the thumbnail image, or None if no thumbnail is to be uploaded to Shotgun.

Return type:

str or None

Getting Shot entities for Hiero TrackItems

class base_hooks.HieroGetShot(parent)[source]

This class implements a hook that can determines which Shotgun entity should be associated with each task and track item being exported.

execute(task, item, data, **kwargs)[source]

Takes a hiero.core.TrackItem as input and returns a data dictionary for the shot to update the cut info for.

Parameters:

task – The Hiero task being processed. Hiero API docs are available here.
item – The Hiero track item being processed. Hiero API docs are available here.
data (dict) – A dictionary with cached parent data.

Returns:

A Shot entity.

Return type:

dict

get_shot_parent(hiero_sequence, data, **kwargs)[source]

Given a Hiero sequence and data cache, return the corresponding entity in Shotgun to serve as the parent for contained Shots.

Note

The data dict is typically the app’s preprocess_data which maintains the cache across invocations of this hook.

Parameters:

hiero_sequence – A Hiero sequence object. Hiero API docs are available here.
data (dict) – A dictionary with cached parent data.

Returns:

A Shotgun entity.

Return type:

dict

Customizing Quicktime export settings

class base_hooks.HieroGetQuicktimeSettings(parent)[source]

This class defines a hook that allows for customization of encoding settings for any Quicktimes written by the export process.

execute(for_shotgun, **kwargs)[source]

Gets encoding settings for Quicktimes generated by the export process.

Parameters:: for_shotgun (bool) – Whether the settings are being gathered for Quicktime output intended for use within the Shotgun web app.
Returns:: A tuple, where the first item is the file_type of a Nuke write node, and the second item is a dictionary of knob names and values.
Return type:: tuple

Customizing PublishedFile data

class base_hooks.HieroGetExtraPublishData(parent)[source]

This class defines a hook that can be used to gather additional data and add it to the data dictionary that’s used to register any new PublishedFile entities in Shotgun during the given Task’s execution.

execute(task, **kwargs)[source]

Get a data dictionary for a PublishedFile to be updated in Shotgun.

Note

The track item associated with this task can be accessed via task._item.

Parameters:: task – The Hiero task that is currently being processed. Hiero docs are available here.
Returns:: A dictionary to update the data for the PublishedFile in Shotgun, or None if there is no extra information to publish.
Return type:: dict

Executing logic after Version entity creation

class base_hooks.HieroPostVersionCreation(parent)[source]

This class implements a hook that can be used to add custom logic to be run after a Version entity is created in Shotgun as part of the export process.

execute(version_data, **kwargs)[source]

Runs following the creation of the Version entity in Shotgun. The provided version data is the data structure containing information about the Version entity, including its ID in Shotgun.

Example version_data:

{'code': 'Scene_v031_abc',
 'created_by': {'id': 39, 'name': 'Jeff Beeland', 'type': 'HumanUser'},
 'entity': {'id': 1166, 'name': 'ABC', 'type': 'Shot'},
 'id': 6039,
 'project': {'id': 74, 'name': 'DevWindows', 'type': 'Project'},
 'published_files': [{'id': 108,
                      'name': 'scene_v031_ABC.mov',
                      'type': 'PublishedFile'}],
 'sg_path_to_movie': '/shotgun/projects/devwindows/sequences/123/ABC/editorial/2015_11_24/plates/scene_v031_ABC.mov',
 'sg_task': {'id': 2113, 'name': 'Comp', 'type': 'Task'},
 'type': 'Version',
 'user': {'id': 39, 'name': 'Jeff Beeland', 'type': 'HumanUser'}}

Parameters:: version_data (dict) – The Version entity that was created in Shotgun.

Executing logic prior to export

class base_hooks.HieroPreExport(parent)[source]

This class implements a hook that can be used to run custom logic prior to the start if the export process.

execute(processor, **kwargs)[source]

Called just prior to export. One use case for would be to clear cached data here, just before the export begins.

Parameters:: processor – The processor object that is about to be started. Hiero API docs are available here.

Resolving strings into Shotgun-queried values

class base_hooks.HieroResolveCustomStrings(parent)[source]

This class implements a hook that is used to resolve custom tokens into their concrete value when paths are being processed during the export.

execute(task, keyword, **kwargs)[source]

The default implementation of the custom resolver simply looks up the keyword from the Shotgun Shot entity dictionary. For example, to pull the shot code, you would simply specify ‘code’. To pull the sequence code you would use ‘sg_sequence.Sequence.code’.

Parameters:

task – The export task being processed. Hiero API docs are available here.
keyword (str) – The keyword token that needs to be resolved.

Returns:

The resolved keyword value to be replaced into the associated string.

Return type:

str

Resolving Flow Production Tracking templates into export string representations

class base_hooks.HieroTranslateTemplate(parent)[source]

This class implements a hook that’s responsible for translating a Toolkit template object into a Hiero export string.

execute(template, output_type, **kwargs)[source]

Takes a Toolkit template object as input and returns a string representation which is suitable for Hiero exports. The Hiero export templates contain tokens, such as {shot} or {clip}, which are replaced by the exporter. This hook should convert a template object with its special custom fields into such a string. Depending on your template setup, you may have to do different steps here in order to fully convert your template. The path returned will be validated to check that no leftover template fields are present, and that the returned path is fully understood by Hiero.

Parameters:

template – The Toolkit template object to be translated.
output_type (str) – The output type associated with the template.

Returns:

A Hiero-compatible path.

Return type:

str

Customizing Version entity data

class base_hooks.HieroUpdateVersionData(parent)[source]

This class implements a hook that can be used to customize the data dictionary for a Version entity that is going to be created by the export process.

execute(version_data, task, **kwargs)[source]

Updates the version_data dictionary to change the data for the Version that will be created in Shotgun. Updating the given version_data dictionary in place will ensure your customizations are used when creating the new Version entity.

Parameters:

version_data (dict) – The data dictionary that will be used by the export process to create a new Version entity in Shotgun.
task – The Hiero export task being processed. Hiero API docs can be found here.

Uploading Thumbnails to Flow Production Tracking

class base_hooks.HieroUploadThumbnail(parent)[source]

This class implements a hook that’s responsible for uploading a thumbnail to a given Shotgun entity for a given Hiero source item.

execute(entity, source, item, **kwargs)[source]

Uploads a thumbnail to the given entity in Shotgun.

Parameters:

entity (dict) – The entity dictionary that will receive the new thumbnail image.
source – The Hiero source sequence object being exported.
item – The Hiero task item being processed.
task – The Hiero task being processed.

Creating custom UI elements and properties

class base_hooks.HieroCustomizeExportUI(parent)[source]

This class defines methods that can be used to customize the UI of the various Shotgun-related exporters. Each processor has its own set of create/get/set methods, allowing for customizable UI elements for each type of export.

Example properties embedded into a custom QGroupBox:

Creating custom UI elements for the Hiero export app involves three steps:

Creating a widget
Defining custom properties to add to the associated preset
Setting the widget up to display controls for the custom properties

create_shot_processor_widget(parent_widget)[source]

Builds and returns a custom widget to be embedded in the parent exporter. If a custom widget is returned by this method, it will be added to the parent exporter’s layout.

Example Implementation:

widget = QtGui.QGroupBox("My Custom Properties", parent_widget)
widget.setLayout(QtGui.QFormLayout())
return widget

Parameters:: parent_widget – The parent widget.
Returns:: A custom widget.

get_shot_processor_ui_properties()[source]

Gets a list of property dictionaries describing the custom properties required by the custom widget. This method will only be run if the associated create widget hook method returns a widget. The dictionaries will be turned into property widgets by the app before being passed to the associated set properties hook method. The order that the dictionaries are returned by this method is maintained when they are passed to the associated set hook method.

Example Implementation:

return [
    dict(
        label="Create Cut:",
        name="custom_create_cut_bool_property",
        value=True,
        tooltip="Create a Cut and CutItems in Flow Production Tracking...",
    ),
    dict(
        label="Head In:",
        name="custom_head_in_bool_property",
        value=True,
        tooltip="Update 'sg_head_in' on the Shot entity.",
    ),
]

Returns:: A list of dictionaries.
Return type:: list

set_shot_processor_ui_properties(widget, properties)[source]

Sets any custom properties described by get_shot_processor_ui_properties on the custom widget returned by create_shot_processor_widget. This method will only be called if the create method is implemented to return a custom widget. The order of the properties within the dictionary passed in is the same as the order they’re returned in the get properties hook method.

Example Implementation:

layout = widget.layout()
for label, prop in properties.iteritems():
    layout.addRow(label, prop)

Parameters:

widget – The Qt widget that was created by the associated create widget hook method.
properties (OrderedDict) – A dict containing property widget objects, keyed by label, that were constructed from the data built by the associated get properties hook method.

create_transcode_exporter_widget(parent_widget)[source]

Builds and returns a custom widget to be embedded in the parent exporter. If a custom widget is returned by this method, it will be added to the parent exporter’s layout.

Note

See the create_shot_processor_widget() method for more detailed documentation.

Parameters:: parent_widget – The parent widget.
Returns:: A custom widget.

get_transcode_exporter_ui_properties()[source]

Gets a list of property dictionaries describing the custom properties required by the custom widget. This method will only be run if the associated create widget hook method returns a widget. The dictionaries will be turned into property widgets by the app before being passed to the associated set properties hook method. The order that the dictionaries are returned by this method is maintained when they are passed to the associated set hook method.

Note

See the get_shot_processor_ui_properties() method for more detailed documentation.

Returns:: A list of dictionaries.
Return type:: list

set_transcode_exporter_ui_properties(widget, properties)[source]

Sets any custom properties described by get_transcode_exporter_ui_properties on the custom widget returned by create_transcode_exporter_widget. This method will only be called if the create method is implemented to return a custom widget. The order of the properties within the dictionary passed in is the same as the order they’re returned in the get properties hook method.

Note

See the set_shot_processor_ui_properties() method for for an example implementation.

Parameters:

widget – The Qt widget that was created by the associated create widget hook method.
properties (OrderedDict) – A dict containing property widget objects, keyed by label, that were constructed from the data built by the associated get properties hook method.

create_audio_exporter_widget(parent_widget)[source]

Builds and returns a custom widget to be embedded in the parent exporter. If a custom widget is returned by this method, it will be added to the parent exporter’s layout.

Note

See the create_shot_processor_widget() method for more detailed documentation.

Parameters:: parent_widget – The parent widget.
Returns:: A custom widget.

get_audio_exporter_ui_properties()[source]

Gets a list of property dictionaries describing the custom properties required by the custom widget. This method will only be run if the associated create widget hook method returns a widget. The dictionaries will be turned into property widgets by the app before being passed to the associated set properties hook method. The order that the dictionaries are returned by this method is maintained when they are passed to the associated set hook method.

Note

See the get_shot_processor_ui_properties() method for more detailed documentation.

Returns:: A list of dictionaries.
Return type:: list

set_audio_exporter_ui_properties(widget, properties)[source]

Sets any custom properties described by get_audio_exporter_ui_properties on the custom widget returned by create_audio_exporter_widget. This method will only be called if the create method is implemented to return a custom widget. The order of the properties within the dictionary passed in is the same as the order they’re returned in the get properties hook method.

Note

See the set_shot_processor_ui_properties() method for for an example implementation.

Parameters:

widget – The Qt widget that was created by the associated create widget hook method.
properties (OrderedDict) – A dict containing property widget objects, keyed by label, that were constructed from the data built by the associated get properties hook method.

create_nuke_shot_exporter_widget(parent_widget)[source]

Builds and returns a custom widget to be embedded in the parent exporter. If a custom widget is returned by this method, it will be added to the parent exporter’s layout.

Note

See the create_shot_processor_widget() method for more detailed documentation.

Parameters:: parent_widget – The parent widget.
Returns:: A custom widget.

get_nuke_shot_exporter_ui_properties()[source]

Gets a list of property dictionaries describing the custom properties required by the custom widget. This method will only be run if the associated create widget hook method returns a widget. The dictionaries will be turned into property widgets by the app before being passed to the associated set properties hook method. The order that the dictionaries are returned by this method is maintained when they are passed to the associated set hook method.

Note

See the get_shot_processor_ui_properties() method for more detailed documentation.

Returns:: A list of dictionaries.
Return type:: list

set_nuke_shot_exporter_ui_properties(widget, properties)[source]

Sets any custom properties described by get_nuke_shot_exporter_ui_properties on the custom widget returned by create_nuke_shot_exporter_widget. This method will only be called if the create method is implemented to return a custom widget. The order of the properties within the dictionary passed in is the same as the order they’re returned in the get properties hook method.

Note

See the set_shot_processor_ui_properties() method for for an example implementation.

Parameters:

widget – The Qt widget that was created by the associated create widget hook method.
properties (OrderedDict) – A dict containing property widget objects, keyed by label, that were constructed from the data built by the associated get properties hook method.