集成开发人员手册

目录:

            面板

                  配置显示的内容

                  配置动作

      发布器

      概述

                  发布阶段摘要

            收集器

                  发布项目

配置

            发布插件

                  插件界面

                  配置

                  日志记录

            路径信息挂钩

                  配置

      加载器

高级功能

      使用 Shotgun Toolkit 可轻松开发工具

面板

有关面板动作的示例,请参见 https://github.com/shotgunsoftware/tk-multi-shotgunpanel/tree/master/hooks

配置显示的内容

详细信息区域和列表中的值都可以通过 shotgun_fields 挂钩进行配置。您可以为此挂钩创建子类,并更改实现,以便显示您需要的值:

模板系统

此挂钩支持简单的模板语言,可提供出色的灵活性。它还支持 Qt 所支持的 HTML 子集,因此您可以控制显示的值的颜色、字体大小、粗细等。模板语言用法如下:

  • Shotgun 的值括在 {brackets} 中,例如 <b>Description:</b> {description}。此模板呈现时,{description} 部分将替换为 description 字段的值。

  • 如果您想为值添加一个仅当值不为空时才显示的可选前缀或后缀,可使用 {[Prefix]sg_field[suffix]} 语法。对于模板 {[Start: ]start_date} {[End: ]end_date},如果同时填充了两个值,将显示 Start: 12 July 2009 End: 14 July 2012,如果未设置结束日期,则显示 Start: 12 July 2009

  • 您可以定义回退机制,在某些值未设置的情况下进行回退。对于 Shotgun 版本而言,artist 字段优先于 created_by 字段,这是为了支持由制作人员代表美工人员提交版本的工作流。在这种情况下,版本将由制作人员创建,但 artist 字段会设置为美工人员。不过,情况并非总是如此。有时,在由美工人员自己提交工作的工作流中,artist 字段会留空。因此,在显示版本时,能够首先检查 artist 字段是一项有用的功能,如果发现此字段未设置,则回退到 created_by 字段。我们使用 {field1|field2} 语法实现这个机制,例如:Created By: {artist|created_by}。您可以将此语法与可选字段结合使用,例如 {[Created By: ]artist|created_by}

此挂钩包含以下方法:

控制列表中显示的列表项

get_list_item_definition() 方法接受 Shotgun 实体类型,会返回一个词典,该词典控制各种列表中列表项的外观。它返回的词典具有 top_lefttop_rightbody 键,例如:

{
 "top_left": "<big>{code}</big>",
 "top_right": "{updated_at}",
 "body": "By: {created_by}<br>Description: {description}"
}

控制顶部详细信息区域

get_main_view_definition() 方法接受 Shotgun 实体类型,会返回一个具有 titlebody 键的词典。这些值控制详细信息区域中对象的外观,例如:

{
 "title": "{type} {code}",
 "body": "By: {created_by}<br>Description: {description}"
}

控制“Info”选项卡中显示的字段

get_all_fields() 方法返回给定实体在“Info”选项卡上呈现时要显示的字段列表。

配置动作

动作是对一段 Shotgun 数据执行操作的代码片段。例如:

  • 一个为给定 Shotgun 版本启动 RV 的动作
  • 一个让用户可指派自己执行给定任务的动作
  • 一个将 Shotgun 发布加载到 Maya 中作为 Maya 参考的动作。

动作的实际负载在“动作挂钩”中定义。定义动作逻辑后,您可以在应用配置中将该动作映射到 Shotgun 对象。这些动作的映射关系可能类似如下:

action_mappings:
  PublishedFile:
  - actions: [reference, import]
    filters: {published_file_type: Maya Scene}
  - actions: [texture_node]
    filters: {published_file_type: Rendered Image}
  Task:
  - actions: [assign_task]
    filters: {}
  Version:
  - actions: [play_in_rv]
    filters: {}

在上面的示例中,我们使用了 referenceimporttexture_nodeassign_taskplay_in_rv 动作。然后,我们将这些动作映射到各种 Shotgun 对象和条件。例如,我们让所有 Maya 场景类型的发布都显示 import 动作。

将对象加载到面板中时,会读入并分析上面的动作配置。接下来确定当前对象适合的动作列表,然后执行 generate_actions() 挂钩方法。给定实体的 Shotgun 数据将在此时传递给挂钩,这样挂钩代码便可判断是否可以为这个特定的 Shotgun 对象运行该动作。这种方法让每个挂钩可在显示前运行检查。例如,play_in_rv 挂钩可能只有在本地有可用媒体时才有意义 - 配置中设置的动作映射会告诉面板为给定 Shotgun 实体启用哪些动作,但是这些动作可能不会全部显示,因为 generate_actions() 方法可能会判定某些动作不适合这个给定对象。

generate_actions() 方法返回的动作将显示在动作菜单上,当用户单击该菜单时,会调用 execute_acton() 挂钩方法运行动作。

对于面板支持的每个应用程序,都有一个动作挂钩来实现合适的动作。例如,在 Maya 这样的应用程序中,默认挂钩将实现 referenceimporttexture_node 动作,每个动作执行特定的 Maya 命令,将发布导入当前的 Maya 场景中。与所有挂钩一样,我们完全可以改写和更改这些设置,还可根据内置挂钩创建派生挂钩,这样不必复制大量代码就能轻松向内置挂钩中添加其他动作。

面板使用 Toolkit 第二代挂钩界面,具有更强的灵活性。此挂钩的格式采用经过改进的语法。您可以在默认配置设置中查看,语法类似如下:

actions_hook: '{self}/tk-maya_actions.py'

{self} 关键字指示 Toolkit 在应用的 hooks 文件夹中查找挂钩。如果您要使用自己的实现改写此挂钩,请将值更改为 {config}/panel/maya_actions.py。这将指示 Toolkit 使用您的配置文件夹中称为 hooks/panel/maya_actions.py 的挂钩。

有关详细信息,请参见应用随附的挂钩文件。挂钩还会利用继承性,这意味着您不需要改写挂钩中的所有内容,而是可以更轻松地用各种方式对默认挂钩进行扩展或补充,使挂钩更易于管理。

通过在挂钩中运用继承性,您可以像下面这样向默认挂钩中添加附加动作:

import sgtk
import os

# toolkit will automatically resolve the base class for you
# this means that you will derive from the default hook that comes with the app
HookBaseClass = sgtk.get_hook_baseclass()

class MyActions(HookBaseClass):

    def generate_actions(self, sg_data, actions, ui_area):
        """
        Returns a list of action instances for a particular object.
        The data returned from this hook will be used to populate the 
        actions menu.

        The mapping between Shotgun objects and actions are kept in a different place
        (in the configuration) so at the point when this hook is called, the app
        has already established *which* actions are appropriate for this object.

        This method needs to return detailed data for those actions, in the form of a list
        of dictionaries, each with name, params, caption and description keys.

        Because you are operating on a particular object, you may tailor the output 
        (caption, tooltip etc) to contain custom information suitable for this publish.

        The ui_area parameter is a string and indicates where the publish is to be shown. 

        - If it will be shown in the main browsing area, "main" is passed. 
        - If it will be shown in the details area, "details" is passed.

        :param sg_data: Shotgun data dictionary with all the standard publish fields.
        :param actions: List of action strings which have been defined in the app configuration.
        :param ui_area: String denoting the UI Area (see above).
        :returns List of dictionaries, each with keys name, params, caption and description
        """

        # get the actions from the base class first
        action_instances = super(MyActions, self).generate_actions(sg_data, actions, ui_area)

        if "my_new_action" in actions:
            action_instances.append( {"name": "my_new_action",
                                      "params": None,
                                      "caption": "My New Action",
                                      "description": "My New Action."} )

        return action_instances

    def execute_action(self, name, params, sg_data):
        """
        Execute a given action. The data sent to this be method will
        represent one of the actions enumerated by the generate_actions method.

        :param name: Action name string representing one of the items returned by generate_actions.
        :param params: Params data, as specified by generate_actions.
        :param sg_data: Shotgun data dictionary with all the standard publish fields.
        :returns: No return value expected.
        """

        if name == "my_new_action":
            # do some stuff here!

        else:
            # call base class implementation
            super(MyActions, self).execute_action(name, params, sg_data)

然后,我们可以在配置中将这个新动作绑定到一组发布类型:

action_mappings:
  PublishedFile:
  - actions: [reference, import, my_new_action]
    filters: {published_file_type: Maya Scene}
  Version:
  - actions: [play_in_rv]
    filters: {}

按上面所示从挂钩派生的自定义挂钩代码只需要包含实际添加的业务逻辑,因此维护和更新起来更加简单。

发布器

概述

发布应用可以采用挂钩形式进行高度自定义,控制如何将项目呈现给美工人员以供发布以及稍后如何处理这些文件。以下各节概述了工作室可使用的所有挂钩和 API。

有关如何使用发布应用的详细信息,请参见用户手册。如果要查找有关第一代发布器的详细信息,请访问经典发布器文档

发布阶段摘要

发布器具有多个执行阶段,开发人员对此应该有所了解。

  • 收集:启动发布器时,将通过收集器挂钩收集当前用户会话的项目。将文件拖放到发布 UI 中时也会进行收集。

  • 接受:完成收集后,配置的发布插件将有机会决定是否处理收集的项目。通过对照插件过滤器检查项目类型,完成初始接受过程。如果项目类型与插件过滤器匹配,则将在该插件上调用某种方法以执行更具体的接受逻辑。

  • 验证:用户单击 UI 中的 ValidatePublish 按钮后,会验证已被一个或多个插件接受的项目。验证阶段用于对项目的状态执行检查,以确保正确发布。

  • 发布:单击 Publish 按钮后,项目将由各个匹配的插件处理。插件可以执行工作室所需的任何动作,从在 Shotgun 中创建发布条目到上传可审核媒体。

  • 完成:发布阶段完成后,将会执行插件的完成阶段以处理所需的清理或摘要报告。

收集器

collector 挂钩负责为要发布的项目处理当前用户会话。还负责处理已拖放到发布器上的文件。其主要用途是对项目进行探索和分类,以显示给用户供其发布。有两种方法可用于实现该目的。

process_file(parent_item, path)

该方法接受已从外部源拖放到发布器 UI 上的路径。该方法将分析路径,并创建一个或多个发布项目以显示给用户供其发布。创建的这些项目应该作为所提供的父项目的子项。

process_current_session(parent_item)

该方法将分析用户的内容创建会话(Maya 场景、Nuke 脚本、Photoshop 文档等),并创建一个或多个发布项目。这些项目可以表示磁盘上已导出的文件或者在发布过程中将导出的会话内组件。创建的这些项目应该作为所提供的父项目下的子树。

发布项目

创建

通过现有项目的 create_item 方法(通常为提供给收集器方法之一的 parent_item)可创建发布项目:

create_item(item_type, display_type, name)

item_type 是一个表示项目类型的字符串。它可以是任意字符串,但通常根据工作室约定进行定义。发布插件使用该值来标识要对其执行操作的项目。基本 Shotgun 集成使用分层点符号。示例包括:file.imagefile.moviemaya.scene

display_type 参数对应于项目类型,但是仅用于显示目的。

示例包括:Image FileMovie FileMaya Scene

name 参数是项目实例的显示名称。它可以是文件名或者 Nuke 或 Houdini 中的节点名称,或者二者的组合。该值显示给用户,目的是帮助用户轻松识别项目所表示的当前会话或磁盘文件。

方法和属性

创建项目后,可以通过以下方法和属性对其进一步自定义以显示给用户:

关联项目

parent

父发布项目(只读)。

children

子发布项目(只读)的列表。

项目信息

context

与该项目关联的上下文。如果未定义上下文,则将返回父上下文;如果未定义父上下文,则将返回 None

description

该项目的发布说明,将显示给用户且与 Shotgun 中的最终发布关联。如果没有为该项目设置说明,则将返回父项目的说明。如果没有为父项目设置说明,则将返回 None

display_type

在创建发布项目时定义的显示类型。

name

在创建过程中定义的项目显示名称。

properties

自由形式的词典,可以在项目上存储任意数据。属性词典自身是只读的(调用 item.properties = my_properties 无效),但是在词典内可以设置任意键值对。该属性提供了一种方式,供您跨发布插件以及在一个插件内的各个发布阶段之间存储项目数据。

thumbnail

关联的缩略图,作为 QPixmap。缩略图是以可视方式表示项目的图像,如图像的缩略图或场景的屏幕截图。如果没有为项目定义缩略图,则将返回父缩略图。如果没有父缩略图,则将返回 None

type

在创建发布项目时定义的项目类型。

项目状态

checked

bool,指示默认情况下是否应该选中发布项目的复选框。请注意,项目的复选状态也受任何子项目和发布插件影响。默认值为 True

enabled

bool,指示在发布 UI 中应该启用还是禁用项目。这可与 checked 属性结合使用,以指示用户无法禁用的必需发布插件。默认值为 True

expanded

bool,指示在发布 UI 中应该展开还是折叠项目。默认值为 True

thumbnail_enabled

bool,指示为发布项目启用还是禁用缩略图生成。默认值为 True

图标和缩略图

set_thumbnail_from_path(path)

Helper 方法,用于从给定路径创建发布项目的缩略图。

set_icon_from_path(path)

Helper 方法,用于从给定路径创建发布项目的图标。

配置

通过发布应用的 hook 类型的 collector 设置,可以配置收集器挂钩。有关 hook 设置数据类型的详细信息,请参见开发人员文档

对于基本的 Shotgun 集成,约定是使用基类收集器来处理拖放到发布器中的文件。收集器的目的是处理特定内容创建软件并对基础收集器进行再分类。以下是收集器在基本配置中的外观的示例:

collector: "{config}/tk-multi-publish2/basic/collector.py:{config}/tk-multi-publish2/maya.basic/collector.py"

发布插件

发布插件是负责处理已收集的发布项目的挂钩。收集所有项目后,发布器会尝试将这些项目与相应的发布插件进行匹配。所有匹配的插件在发布项目层次结构内将显示为子任务。

插件界面

发布插件挂钩必须定义以下方法和属性:

icon

要用作此插件图标的磁盘上图像的路径。

name

该插件的一行名称。

description

有关插件用途的多行详细说明。可以包含简单的 HTML 格式。

settings

定义设置的词典,该插件期望通过 acceptvalidatepublishfinalize 方法中的设置参数接收这些设置。词典采用以下形式:

    {
        "Settings Name": {
            "type": "settings_type",
            "default": "default_value",
            "description": "One line description of the setting"
        },

        "Another Setting": {
            "type": "settings_type",
            "default": "default_value",
            "description": "One line description of the setting"
        }
    }

类型字符串应该是 Toolkit 作为其环境配置一部分接受的数据类型之一。

item_filters

该插件关注的项目类型的列表。只有与该列表中条目匹配的项目才显示给 accept 方法。字符串可以包含诸如 * 之类的 glob 模式,例如 ["maya.*", "file.maya"]

accept(settings, item)

由发布器调用以确定该插件是否关注某个项目。只有与通过 item_filters 属性定义的过滤器匹配的项目才显示给此方法。

将为此处接受的每个项目生成发布任务。返回包含以下布尔值的词典:

  • accepted:指示插件是否关注该值(必需)。
  • enabled:如果为 True,则将在 UI 中启用插件实例,否则将禁用它。(可选)默认情况下为 True
  • visible:如果为 True,则插件实例在 UI 中将可见,否则将隐藏它。(可选)默认情况下为 True
  • checked:如果为 True,则插件实例在 UI 中将处于选中状态,否则将取消选中它。(可选)默认情况下为 True

settings 参数是与设置属性中返回的键匹配的设置的词典。值是设置的已配置实例。

item 参数表示要处理的项目。

validate(settings, item)

验证给定项目,检查它是否可以发布。返回一个布尔值以指示有效性。

settings 参数是与设置属性中所返回键匹配的设置的词典。值是设置的已配置实例。

item 参数表示要处理的项目。

publish(settings, item)

对给定项目和设置执行发布逻辑。

settings 参数是与设置属性中所返回键匹配的设置的词典。值是设置的已配置实例。

item 参数表示要处理的项目。

finalize(settings, item)

执行完成过程。所有发布任务完成后,将会执行此过程。

settings 参数是与设置属性中所返回键匹配的设置的词典。值是设置的已配置实例。

item 参数表示要处理的项目。

配置

发布插件挂钩是通过发布应用的 publish_plugins 设置配置的。该设置定义为挂钩列表。有关 hook 数据类型的详细信息,请参见开发人员文档

基本 Shotgun 集成中的 Maya 集成的发布插件设置如下所示:

    publish_plugins:
        - '@common.settings.tk-multi-publish2.publish_file'
        - '@common.settings.tk-multi-publish2.upload_version'
        - name: Begin file versioning
          hook: "{config}/tk-multi-publish2/maya.basic/start_version_control.py"
          settings: {}
        - name: Publish to Shotgun
          hook: "{config}/tk-multi-publish2/maya.basic/publish_maya_session.py"
          settings: {}

已定义的前两个插件将包括在内,它们负责为标准文件发布和上传媒体。第三个和第四个插件负责发布 Maya 会话。

在发布器的实例中可以配置任何数量的发布插件。

登录

收集器和发布插件挂钩中的任何日志记录都将显示在发布器的进度详细信息控件中。使用标准日志记录方法可以将信息、警告、错误和调试消息显示给用户。

发布器具有特殊的日志记录处理程序,利用标准 extra 词典在日志消息的旁边显示动作按钮。以下示例表示已识别的动作按钮词典形式。

action_button

单击时执行回调方法的通用按钮。示例:

    {
        "label": "Hello, world!",
        "tooltip": "This button says hello to the world.",
        "callback": self._hello_world,
        "args": {"foo": 123, "bar": 456}
    }

label 是显示在按钮上的文本。tooltip 是按钮的工具提示。callback 是单击时要执行的方法。args 是提供给回调的参数。

action_show_folder

一个常见动作,用于在系统的文件浏览器中显示所提供路径的文件夹。示例:

    {
        "label": "Show Publish Folder",
        "tooltip": "Show the publish path in a file browser.",
        "path": path,
    }

path 是要在文件浏览器中显示的文件或文件夹的路径。label 和 tooltip 是可选的。默认值分别为“Show Folder”和“Reveal in the system's file browser”。

action_show_in_shotgun

一个常见动作,用于在 Shotgun 中显示实体的详细信息页面。示例:

    {
        "label": "Show Version",
        "tooltip": "Show uploaded Version in Shotgun.",
        "entity": entity,
    }

entity 是标准 Shotgun 实体词典,对应于要在 Shotgun 中显示的实体。label 和 tooltip 是可选的。默认值分别为“Show Entity”和“Reveal the entity in Shotgun”。

action_show_more_info

一个常见动作,用于显示比通常适合单行日志记录输出的内容更多的信息。输出将显示在文本浏览器的弹出对话框中。示例:

    {
        "label": "Show Error",
        "tooltip": "Show the full error stack trace.",
        "text": formatted_stack_trace,
    }

text 是要在弹出对话框中显示的长文本字符串。label 和 tooltip 是可选的。默认值分别为“More Info...”和“Show additional logging info”。

action_open_url

一个常见动作,用于在默认浏览器中打开提供的 URL。示例:

    {
        "label": "Show Docs",
        "tooltip": "Show the associated documentation.",
        "url": url,
    }

url 是要打开的 URL。label 和 tooltip 是可选的。默认值分别为“Open URL”和“Opens a url in the appropriate browser”。

路径信息挂钩

path_info 挂钩包含基本 Shotgun 集成用来通过文件路径推断信息的方法。它包括版本和帧编号标识、发布显示名称、图像序列路径等。 工作室可以覆盖这些路径处理方法,以解释自己的命名约定和路径结构。

path_info 挂钩的所有方法通过发布器的 util 模块进行公开,目的是在收集器挂钩和发布挂钩内轻松调用这些方法。在挂钩中定义的方法如下所示:

get_publish_name(path, sequence=False)

如果已指定文件路径,则返回要用于发布的显示名称。通常,这是已删除路径和版本号的名称,目的是在发布后续版本时保持发布名称一致。示例:

    # versioned file. remove the version
    in: /path/to/the/file/scene.v001.ma
    out: scene.ma

    # image sequence. replace the frame number with #s
    in: /path/to/the/file/my_file.001.jpg
    out: my_file.###.jpg

path 参数是文件(可能是要发布的文件)的路径。如果 sequence 参数为 True,则将路径视为序列名称并将帧编号替换为占位符。

该方法将返回一个字符串,即所提供路径的发布显示名称。

get_version_number(path)

从所提供的路径中提取版本号。如果在发布时插件需要知道要与文件关联的版本号,则可以使用该方法。

path 参数是文件(可能是要发布的文件)的路径。

该方法将返回一个整数,表示所提供路径中的版本号。如果未找到版本,则返回 None。

get_frame_sequence_path(path, frame_spec=None)

如果已指定带有帧编号的路径,则返回帧编号已替换为给定帧规格的序列路径,如 {FRAME}%04d$F

path 参数是带有帧编号的输入路径。frame_spec 参数表示用于替换帧编号的帧规格。

该方法将返回一个字符串,表示完整的帧序列路径。

get_frame_sequences(folder, extensions=None, frame_spec=None)

如果已指定文件夹,则检查所包含的文件以查找看起来带有帧编号的文件。

path 参数是有可能包含文件序列的文件夹的路径。

extensions 参数是要检索其路径的文件扩展名的列表。如果未提供,则将忽略扩展名匹配。

frame_spec 参数是一个字符串,用于表示返回的序列路径中的帧编号。

该方法将返回每个已识别帧序列的元组的列表。元组中的第一个项目是序列路径,其中的帧编号已替换为所提供的帧规格。如果未提供帧规格,则将使用文件中找到的填充返回 python 字符串格式的规格。示例:

    # method call:
    get_frame_sequences(
        "/path/to/the/folder",
        extensions=["exr", "jpg"],
        frame_spec="{FRAME}"

    )

    #results:
    [
        (
            "/path/to/the/supplied/folder/key_light1.{FRAME}.exr",
            [<frame_1_path>, <frame_2_path>, ...]
        ),
        (
            "/path/to/the/supplied/folder/fill_light1.{FRAME}.jpg",
            [<frame_1_path>, <frame_2_path>, ...]
        )
    ]

get_version_path(path, version)

如果已指定不带版本号的路径,则返回带有所提供版本号的路径。如果在所提供的路径中检测到版本号,则将原样返回该路径。

path 参数是注入版本号信息的路径。

version 参数是要注入路径中的编号。

该方法将返回修改后的路径,其中插入了所提供的版本号。

get_next_version_path(path)

如果已指定文件路径,则返回下一个版本的路径。在需要将当前工作文件保存到下一个版本号的插件中,自动版本控制逻辑通常会使用该方法。如果在所提供的路径中无法识别出任何版本,则将返回 None,指示无法确定下一个版本的路径。

path 参数是文件(可能是要发布的文件)的路径。

该方法将返回所提供路径的下一个版本的路径。

util 方法

发布器的 util 模块定义了其他方法,在编写发布插件时会很有用。这些方法如下所述。

get_file_path_components(path)

用于确定给定路径的文件组件的便捷方法。

path 参数是要组件化的文件的路径。

该方法将按以下形式返回文件路径组件:

    # path="/path/to/the/file/my_file.v001.ext"
    {
        "path": "/path/to/the/file/my_file.v001.ext",
        "folder": "/path/to/the/file" ,
        "filename": "my_file.v001.ext",
        "extension": "ext",
    }

    # path="/path/to/the/folder"
    {
        "path": "/path/to/the/folder",
        "folder": "/path/to/the" ,
        "filename": "folder",
        "extension": None,
    }

配置

路径信息挂钩可通过发布应用的 path_info 设置进行配置。有关 hook 数据类型的详细信息,请参见开发人员文档

加载器

有关加载动作的示例,请参见 https://github.com/shotgunsoftware/tk-multi-loader2/tree/master/hooks

高级功能

使用 Shotgun Toolkit 可轻松开发工具

我们有没有提到您可以编写自己的应用?每个引擎都基于 Python 和 PySide 公开了一个一致的接口,因此您可以编写一个适用于 Nuke、Photoshop 和 3dsmax 应用。有了核心 API 功能,开发资源可以专注于解决生产问题,而无需为工作室构建大型工作流堆栈。通过 Toolkit 可以在项目之间轻松地重用工具 - 如果文件命名约定或其他要求发生改变,只需重新配置应用即可。通过 Toolkit 的内置 Git 和 Github 支持可安全地推出工具,并在开发时快速地热加载代码。您只需在自己的 Dev Sandbox 中工作,并邀请 TD 和早期采用者测试您的代码,而不必将其展示给项目的每个参与者。

通过添加 TANK_NO_HEADER 这个特殊标记,指示文档生成系统不需要生成标题。

关注

0 评论

登录写评论。