加载已发布的文件

加载器

定位已发布的文件并将它们引用到场景中。
最新版本:v1.19.2 (prod)
我们的版本号遵循语义化版本标准。
系统名称:tk-multi-loader2

请注意:本文档介绍仅当控制 Toolkit 配置时可用的功能。有关更多详细信息,请参见 Shotgun 集成用户手册
概述
文档
            配置
                  树视图
                  过滤发布
                  求助,不显示任何动作!
                  管理动作
            参考
                  open_publish()
安装、更新和开发
配置选项

使用 Shotgun 加载器可以快速简要了解和浏览已发布到 Shotgun 的文件。通过一个可搜索的树视图导航系统可以轻松快速地到达您要查找的任务、镜头或资产,之后,加载器显示相应项目的所有发布的缩略图式概况。通过可配置的挂钩,您便可以轻松地在您的当前场景中引用或导入发布。

概述视频

下面的视频对特性和功能进行了简要的介绍。

文档

本文档介绍仅当控制 Toolkit 配置时可用的功能。有关详细信息,请参见 Shotgun 集成用户手册

配置

加载器具有高度的可配置性,您可以通过多种不同的方式对其进行设置。加载器有两个主要的配置区域:

  • 设置左侧树视图中显示哪些选项卡和内容。
  • 控制针对不同的发布显示哪些动作,以及这些动作实际执行什么操作。

下面各部分将简要介绍如何配置加载器。有关配置方面的技术细节,请参见文档后面的单独章节。

树视图

树视图具有高度的可配置性,您可以使用标准 Shotgun 过滤语法控制各个选项卡的内容。每个选项卡包含一个 Shotgun API 查询,通过分组构成一个层次结构。您可以添加任意过滤器来控制要显示哪些项,并可使用特殊关键字 {context.entity}{context.project}{context.project.id}{context.step}{context.task}{context.user} 基于当前上下文确定查询范围。每个关键字将被替换为相关的上下文信息,可以是 None(当上下文的对应部分未填充数据时)或包含键 ID、类型和名称的标准 Shotgun 链接词典。

默认情况下,加载器将显示属于当前项目的资产和镜头。通过重新配置,可以轻松对此进行扩展,例如显示来自其他项目(或特定资产库项目)的内容项。您还可以使用过滤器仅显示具有某个审批状态的内容项,或者按状态或其他 Shotgun 字段对内容项进行分组。下面是一些配置设置示例,说明了树视图选项卡的设置方式:

# An asset library tab which shows assets from a specific
# Shotgun project
caption: Asset Library
entity_type: Asset
hierarchy: [sg_asset_type, code]
filters:
- [project, is, {type: Project, id: 123}]

# Approved shots from the current project
caption: Shots
hierarchy: [project, sg_sequence, code]
entity_type: Shot
filters:
- [project, is, '{context.project}']
- [sg_status_list, is, fin]

# All assets for which the current user has tasks assigned
caption: Assets
entity_type: Task
hierarchy: [entity.Asset.sg_asset_type, entity, content]
filters:
- [entity, is_not, null]
- [entity, type_is, Asset]
- [task_assignees, is, '{context.user}']
- [project, is, '{context.project}']

过滤发布

我们可以对加载器从 Shotgun 加载发布数据时所执行的发布查询应用 Shotgun 过滤器。此功能由 publish_filters 参数控制,可用于隐藏尚未获得批准的发布或其关联的审看版本尚未得到批准的发布。

求助,不显示任何动作!

加载器针对每个插件随附了一些不同的动作。例如,对于 Nuke,有两个动作:“导入脚本”和“创建读取节点”。动作在挂钩中定义,这意味着您可以修改它们的行为,或根据需要添加附加动作。然后,在加载器的配置中,可以将这些动作绑定至某些“发布类型”。将一个动作绑定至一个发布类型,也就意味着该动作将显示在加载器内该类型的所有项的动作菜单上。

例如,默认情况下,Nuke 的映射关系设置如下:

action_mappings:
  Nuke Script: [script_import]
  Rendered Image: [read_node]

如果您发现不显示任何动作菜单,可能是因为您为当前使用的发布类型选择了不同的名称。如果是这样,请进入配置并添加这些类型,以便在加载器内显示它们。

管理动作

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

在动作挂钩中定义了动作列表后,您便可以将这些动作绑定至发布文件类型。例如,如果您的工作流中有一个名为“Maya 场景”(Maya Scene)的发布文件类型,可以在配置中将此类型绑定至挂钩中定义的 referenceimport 动作。这样,Toolkit 会向显示的每个 Maya 场景发布中添加一个引用动作和一个导入动作。像这样将发布类型与实际挂钩分离开来,将更易于重新配置加载器,使其适用于默认配置随附的类型以外的发布类型设置。

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

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

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

加载器使用的第二代挂钩的另一个功能是,挂钩不再需要具有 execute() 方法。相反,挂钩更像一个普通类,并可包含一套适合组合在一起的方法。在使用加载器时,您的动作挂钩需要执行以下两个方法:

def generate_actions(self, sg_publish_data, actions, ui_area)
def execute_multiple_actions(self, actions)

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

请注意,在 v1.12.0 之前的版本中,应用程序会调用 execute_action 挂钩来执行动作。而较新的版本会调用 execute_multiple_actions 挂钩。为了向后兼容现有挂钩,execute_multiple_actions 挂钩实际为提供的每个动作调用 execute_action。如果应用程序在升级到 v1.12.0 或更高版本后提示未定义 execute_multiple_actions 挂钩,请确保环境中的 actions_hook 设置正确地从内置挂钩 {self}/{engine_name}_actions.py 继承设置。要了解有关如何从内置挂钩派生自定义挂钩的详细信息,请参见 Toolkit 参考文档

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

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_publish_data, actions, ui_area):
        """
        Returns a list of action instances for a particular publish.
        This method is called each time a user clicks a publish somewhere in the UI.
        The data returned from this hook will be used to populate the actions menu for a publish.

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

        The hook should return at least one action for each item passed in via the
        actions parameter.

        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 publish, 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.
        - If it will be shown in the history area, "history" is passed.

        Please note that it is perfectly possible to create more than one action "instance" for
        an action! You can for example do scene introspection - if the action passed in
        is "character_attachment" you may for example scan the scene, figure out all the nodes
        where this object can be attached and return a list of action instances:
        "attach to left hand", "attach to right hand" etc. In this case, when more than
        one object is returned for an action, use the params key to pass additional
        data into the run_action hook.

        :param sg_publish_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_publish_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_publish_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_publish_data: Shotgun data dictionary with all the standard publish fields.
        :returns: No return value expected.
        """

        # resolve local path to publish via central method
        path = self.get_publish_path(sg_publish_data)

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

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

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

action_mappings:
  Maya Scene: [import, reference, my_new_action]
  Maya Rig: [reference, my_new_action]
  Rendered Image: [texture_node]

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

参考

在应用实例上可以使用以下方法。

open_publish()

显示“打开文件”风格的加载器版本,让用户可以选择发布。然后将返回选定的发布。在此模式下运行时,不允许使用为应用配置的普通动作。

app.open_publish( str title, str action, list publish_types )

参数和返回值

  • str title - 打开发布对话框中显示的标题。
  • str action - 用于“打开”(Open)按钮的动作名称。
  • list publish_types - 一个发布类型列表,用于过滤可用的发布列表。如果此值为空/None,将显示所有发布。
  • 返回值:用户选择的 Shotgun 实体词典的列表。

示例

>>> engine = sgtk.platform.current_engine()
>>> loader_app = engine.apps.get["tk-multi-loader2"]
>>> selected = loader_app.open_publish("Select Geometry Cache", "Select", ["Alembic Cache"])
>>> print selected

相关应用和文档

场景细分

场景细分应用显示您在您的场景中加载(引用)的项目列表,并通知您哪些已过期。在此概览中,您可以选择多个对象并单击更新按钮,这将更新所有选定项目以使用最新的已发布版本。

发布

通过发布应用,美工人员可以发布他们的作品,以便其可供下游的美工人员使用。它支持在美工人员的内容创建软件中以传统方式发布工作流,以及在磁盘上单独发布任何文件。在内容创建软件中操作并使用基本 Shotgun 集成时,该应用将自动发现并显示项目以供美工人员发布。对于较复杂的生产需求,工作室可以编写自定义发布插件来推动美工人员工作流。

Shotgun 面板

通过 Shotgun 面板可以快速访问某个嵌入式面板中的 Shotgun 信息。可以使用它轻松访问有关用户当前正在处理的任务的信息,并且您可以即时访问活动流、注释、任务、版本和发布。可播放您团队中的其他成员发送以进行审核的版本。可在您的应用程序中直接回复注释。如果您的工作流跟踪依存关系信息,您也可以直接从 Shotgun 面板浏览此信息。

Shotgun 工作文件

此应用程序构成了在 Shotgun Pipeline Toolkit 中进行文件管理的基础。它允许您在各种 Shotgun 实体之间快速跳转,并让您快速开始工作。由于该应用程序在后台管理路径,因此无需指定路径。该应用程序会帮助您管理工作区中的工作文件,这样,您可以轻松地与其他人共享您的工作内容。

管理员手册

这是 Shotgun 集成的管理员手册。

Shotgun 工作流教程

此文档提供了一个分步教程,指导技术总监 (TD) 使用 Shotgun 集成和 Toolkit 平台设置简单的端到端工作流。本教程的目标是向用户介绍集成和平台的基本方面以及如何构建和自定义基于 Shotgun 的工作流以迎合其工作室的特定需求。

用户手册

这是 Shotgun 集成的用户手册。

安装和更新

将此应用添加到 Shotgun Pipeline Toolkit

如果您想将此应用添加到 Project XYZ 中名为 asset 的环境中,请执行以下命令:

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

更新至最新版本

如果您已在某个项目中安装了此应用,要获取最新版本,可运行 update 命令。您可以导航到该特定项目随附的 tank 命令,并在该项目中运行它:

> cd /my_tank_configs/project_xyz
> ./tank updates

或者,也可以运行您的工作室的 tank 命令并指定项目名称,指示该命令要对哪个项目运行更新检查:

> tank Project XYZ updates

协作和代码演进

如果您可以获取 Shotgun Pipeline Toolkit,意味着也可以获取我们在 GitHub 中存储和管理的所有应用、插件和框架的源代码。欢迎根据实际需要演进和完善这些内容,以它们为基础做进一步的独立开发,修改它们(以及向我们提交 Pull 请求!),或者只是随手玩一玩,简单了解它们的构建方式和 Toolkit 的工作原理。您可以通过以下网址访问此代码库:https://github.com/shotgunsoftware/tk-multi-loader2

特殊要求

  • 需要安装 Shotgun Pipeline Toolkit 核心 API 版本 v0.18.45 或更高版本才能使用此功能。

配置

下面是使用的所有配置设置的摘要。您需要在要启用此应用或插件的环境文件中定义这些设置。

publish_filters

类型:list

说明:要应用于发布列表的附加 Shotgun 过滤器的列表。这些过滤器将在其他任何过滤之前应用,让您可以例如隐藏某个状态的内容项。

entity_mappings

类型:dict

说明:将实体类型与动作关联。动作全部在动作挂钩内定义。

filter_publishes_hook

类型:hook

默认值:{self}/filter_publishes.py

说明:指定一个挂钩,当需要时,可过滤出 Shotgun 返回的当前位置的原始发布列表。

action_mappings

类型:dict

说明:将发布的文件类型与动作关联。动作全部在动作挂钩内定义。

menu_name

类型:str

默认值:Load

说明:Shotgun 菜单上显示的名称。

entities

类型:list

默认值:[{u'caption': u'Project', u'publish_filters': [], u'type': u'Hierarchy', u'root': u'{context.project}'}, {u'publish_filters': [], u'entity_type': u'Task', u'hierarchy': [u'entity', u'content'], u'caption': u'My Tasks', u'filters': [[u'task_assignees', u'is', u'{context.user}'], [u'project', u'is', u'{context.project}']], u'type': u'Query'}]

说明:此设置定义左侧将会显示的不同选项卡。每个选项卡代表一个 Shotgun 查询,它们按某些 Shotgun 字段分组形成一个树结构。此设置是一个词典列表。列表中的每个词典定义一个选项卡。type 键设置为“层次结构”(Hierarchy)的词典应具有以下键:caption 指定选项卡的名称,root 指定要显示的项目层次结构的根目录路径。type 键设置为“查询”(Query)的词典应具有以下键:caption 指定选项卡的名称;entity_type 指定要显示的 Shotgun 实体类型。filters 是标准 API Shotgun 过滤器的列表。hierarchy 是一系列 Shotgun 字段的列表,它定义了树结构的分组。(可选)您可以指定一个 publish_filters 键,其中包含要在发布列表加载到主视图时应用于该发布列表的 Shotgun API 过滤器。

actions_hook

类型:hook

默认值:{self}/{engine_name}_actions.py

说明:此挂钩包含用于动作管理的所有方法。

title_name

类型:str

默认值:Loader

说明:用户界面对话框标题中显示的名称。

download_thumbnails

类型:bool

默认值:True

说明:控制是否应从 Shotgun 下载缩略图。强烈建议下载缩略图,因为这样可以极大提升加载器的用户体验,但是在某些情况下,由于带宽或基础设施的限制,可能难以这样做。

关注

0 评论

登录写评论。