适用于 Visual Studio Code 的 glTF 工具扩展

命令名称：，默认键绑定：glTF: Preview 3D ModelALT + G

上述模型、其他示例模型和相关许可证可以从 glTF-Sample-Models 存储库中获取。

您可以在许多不同的渲染引擎中预览 glTF 文件：BabylonJS、Cesium 和 ThreeJS。ThreeJS 引擎将预览保存的模型，而不是打开的 VS Code 选项卡中的当前内容。Babylon 和 Cesium 引擎将首先尝试预览选项卡中当前的内容，只有当失败时，它才会回退显示保存在磁盘上的模型版本。

安装 Visual Studio Code 后，接下来的步骤很简单：

如果您希望从源代码构建此内容，请参阅开发人员环境。

命令名称：glTF: Export to GLB (Binary file)

glTF 3D 模型格式有两种类型：是基于 JSON 的文本文件，可使用此 VS Code 扩展轻松编辑，通常引用外部文件，例如纹理贴图和二进制网格数据。 是一个二进制版本，通常较小且独立，但不容易编辑。*.gltf*.glb

该命令会将基于文本的 glTF 从编辑器导出到二进制文件。在导出的版本中，JSON 中的空格被剥离，外部文件引用被读入并转换为 GLB 二进制 bufferViews，生成的文件成为一个易于共享的独立可传输文件。glTF: Export to GLB (Binary file).glb

命令名称：glTF: Import from GLB

该命令会将二进制文件转换为基于 JSON 进行编辑，为二进制文件创建一个单独的文件，并为每个包含的图像创建附加文件。请注意，在导入过程中，某些文件名是根据输出的目标文件名计算的。例如，将示例文件导入到可能会创建以下文件：glTF: Import from GLB.glb.gltf.gltfBoomBox.glb.gltf

• BoomBox.gltf– JSON 结构。
• BoomBox_data.bin– 二进制网格数据
• BoomBox_img0.png– 从 GLB 中提取的图像文件
• BoomBox_img1.png
• BoomBox_img2.png
• BoomBox_img3.png

用户将看到一个“另存为…”对话框，仅用于基本输出文件名。其他文件将保存到同一文件夹中，其名称通过附加到用户选择的基本名称中计算，并且任何具有相同名称的预先存在的文件都将被覆盖。.gltf

命令名称：，默认键绑定：glTF: Inspect DataALT + D

上面，用户正在检查官方示例模型存储库中作为模型一部分的第一个访问器。将文档光标放在着色器、图像、访问器或网格基元上，然后选择命令以检查数据。该命令适用于文件或数据 URI。BoomBox.gltfglTF: Inspect Data

如果您计划预览 GLSL 着色器代码，请考虑安装支持扩展的第三方语法荧光笔，例如 slevesque 对 VSCode 的着色器语言支持，以在着色器预览中启用语法突出显示。*.glsl

编辑 glTF 文件时，左侧栏中会出现一个带有 glTF 徽标的图标。此大纲视图显示了 glTF 文件的结构及其内部引用。这与按类型对对象进行分组的纯 JSON 大纲不同的结构。

您还可以检查所选网格图元中的顶点和三角形数据。

调试网格图元数据可以通过在检查网格图元数据的同时打开预览窗口来实现。

请注意，目前仅当Babylon.js是渲染引擎时才支持此功能。

例如，选择一个顶点将显示该顶点的轴。如果选择了多个顶点，则每个顶点将显示一个轴。

下面是选择三角形的示例。按住并使用箭头键可进行多选。SHIFT

使用 BabylonJS 引擎预览模型时，单击顶部的小调试图标以激活检查器。此检查器是最近添加的，目前并非所有工具都在 VSCode 中运行。但是，它可以显示模型线框、点云、法线矢量、单个纹理通道，甚至允许临时重新定位模型节点（尽管在此版本中不会将位置更改复制回 glTF 文档）。

有关此工具的更多信息，请参阅 Babylon Inspector 文档。

可以通过三种不同的方式验证文件：

• 官方的 Khronos glTF 验证器在 glTF 2.0 文件上自动运行，并将发现的任何问题报告到文档的“问题”窗口。所有此类消息都标有前缀。这远远超出了简单的 JSON 验证，因为它读取外部数据和图像文件，并查看网格数据本身是否存在错误，例如未规范化的法线向量和不准确的边界体积。[glTF Validator]

• 同一个 glTF 验证器也可以作为手动进程运行，通过发出命令 .这可以通过右键单击 VSCode 文件资源管理器侧边栏中的文件来完成，或者只是独立运行命令以打开文件对话框。这是此扩展中唯一可以直接验证 GLB 文件的方法，无需转换。验证报告的摘要将显示在弹出窗口中，以及用于保存 JSON 报告的选项。glTF: Validate a GLB or GLTF file

• glTF JSON 架构已向 VSCode 注册文件，VSCode 将使用自己的 JSON 架构验证来查找架构冲突，而无需 glTF 验证器的帮助。这会在“问题”窗口中生成未标记的消息。这不如完整的 glTF 验证彻底，但这是 glTF 1.0 文件唯一可用的方法。*.gltf[glTF Validator]

在下面的屏幕截图中，Khronos glTF 验证器显示一个、一个和一个。如果您在自己的文件中看到这些内容，则可以单击底部窗口中的一行以滚动到消息的来源。如果二进制数据出现错误，编辑器将滚动到引用该数据的 glTF 访问器。errorwarninginfo

即使“问题”窗口不可见，底部页脚中的某些图标也会显示验证消息的摘要。单击这些图标以显示“问题”窗口。

Khronos glTF 验证器提供的某些消息将伴随着此 VSCode 扩展提供的“快速修复”。这可能在文本编辑器中显示为蓝色灯泡、悬停弹出窗口中的链接和/或“问题”窗口中图标上的菜单。激活“快速修复”，以便此扩展尽最大努力应用自动更正验证器识别的问题。与本软件的所有功能一样，用户承担与其使用相关的所有风险。在使用此软件之前，请备份所有重要文件。

将新扩展添加到 glTF 文件中时，验证器可能会在 glTF 块中未声明的任何扩展上报告此代码。此问题的快速修复称为“将扩展添加到’extensionsUsed’”，它将尝试查找或创建块，并添加所选扩展的名称。用户可能不会注意到对文档的编辑结果，这可能发生在远离活动光标位置的地方，但很明显它有效，因为验证消息将立即消失。这是仅限 JSON 的更改。extensionsUsedextensionsUsed

默认情况下，glTF 验证器仅提供有关 bufferViews 中缺少的目标的最低严重性提示。这是 glTF 的一个相当深层的功能，大多数用户不需要直接编辑或理解，但最佳做法仍然是在 JSON 文档中正确设置这些值。这里提供了两个“快速修复”：“为此 bufferView 添加目标”和“为此文件中的所有 bufferView 添加所有需要的目标”。这些将相应地纠正一个或多个 bufferView 的问题。这是仅限 JSON 的更改，可以在同一编辑会话期间使用编辑器中的单个“撤消”命令撤消。

在 glTF bufferView 中存储动画数据时，不得使用参数（用于交错顶点属性）。此处的快速修复只是从 JSON 文档中删除有问题的参数，而不检查是否使用了某些自定义 byteStride 值（因为动画不允许使用此类内容）。这有可能将以前无效的 glTF 文件转换为标记为“有效”的文件，因此请务必事后测试 glTF 的动画以确保正确性。byteStride

此验证消息与蒙皮网格体相关，指示特定关节在零权重下调用的位置，这意味着它们对最终结果没有影响。此处的“快速修复”称为“清除权重为零的关节 ID”，它将尝试通过将未使用的关节 ID 归零来删除此验证警告。注意：接下来将发生一个保存文件对话框将打开。此修复所需的编辑发生在二进制数据中，通常是 glTF 部分引用的外部文件。保存对话框要求将此二进制数据的更新副本保存到包含对关节 ID 的调整的新文件中。新文件必须与文件放在同一文件夹中。*.binbuffers.bin*.gltf

更新文件的默认名称通常会添加到末尾，但可以在保存文件对话框中进行调整。保存到这个新文件名允许更新的 bin 文件与原始文件共存，以防以后需要比较或“撤消”。将编辑 JSON 文档的部分，以便该字段指示新选择的文件名。编辑器内置的“撤消”和“重做”功能将仅适用于该缓冲区字段的这个微小编辑，但这足以将验证器的工作引导到适当的旧或新二进制数据上，因此您应该会看到验证消息重新出现在“撤消”上，并再次被“重做”关闭。*_patch1.binbuffersuriuri

警告：如果覆盖现有文件，编辑器的“撤消”功能将无法撤消该作。

在命令列表 （ + + ） 中，有两个名为 和 的命令。要使用这些，请将文档光标放在包含字段的块上。如果此字段的值是有效的文件名，则将加载该文件，将其编码为 base64，并将文件名替换为文档中的 dataURI。 与此过程相反，但首先它会要求您提供要保存到的文件名。它会将文件保存在与 glTF 文件相同的文件夹中，因此它不需要路径，只需要一个名称。它将尝试根据 dataURI 的 MIME 类型选择适当的文件扩展名。如果您要覆盖现有文件，它还会警告您。如果保存成功，dataURI 将替换为新创建的文件的名称。CTRLSHIFTPglTF: Import file as Data URIglTF: Export a Data URI to a file"uri"ImportExport

将光标放在 3 英寸上，然后按下 导航到定义的访问器。"POSITION": 3F12

将鼠标悬停在数字枚举上以查看其含义。

在空白字段上按 + 弹出建议值列表。当您滚动列表时，将显示所选值的含义。CTRLSPACE

这也适用于数组，例如启用的渲染状态列表。例如，在这里，用户希望启用 BLEND 状态。

在动画采样器上按 + 将值导入 glTF JSON。ALTi

"samplers": [
{
    "input": 6,
    "interpolation": "LINEAR",
    "output": 7,
    "extras": {
    "vscode_gltf_input": [
        1.25,
        2.5
    ],
    "vscode_gltf_type": "VEC4",
    "vscode_gltf_output": [
        0,
        0,
        0,
        -1,
        1,
        0,
        0,
        4.4896593387466766e-11
    ]
},

根据需要修改 和 数组，然后按 + 使用新值重写 glTF 缓冲区和 JSON。这将使用缓冲区的数据 URI，以便可以完全撤消更改; 如果需要二进制文件，则可用。保存编辑后的文档并用于查看更改。vscode_gltf_inputvscode_gltf_outputALToglTF: Export a Data URI to a fileglTF: Preview 3D Model

也可以创建新的采样器，只需用于访问器引用，新的访问器将自动创建。-1

• glTF.defaultV1Engine– 选择将在预览窗口中渲染 glTF 1.0 模型的默认 3D 引擎。

• glTF.defaultV2Engine– 选择将在预览窗口中渲染 glTF 2.0 模型的默认 3D 引擎。

• glTF.Babylon.environment– 覆盖 BabylonJS glTF 预览窗口的默认反射映射。这指定了 Babylon ENV 或 DDS 预过滤环境文件的本地路径，例如通过使用 HDR 环境中的步骤创建的路径，或原始 HDR 文件（由于运行时预过滤，加载速度较慢）。

• glTF.Three.environment– 覆盖 ThreeJS glTF 预览窗口的默认反射贴图。这应该是环境文件的完整路径和文件名，例如来自 HDRI Haven 的文件。当文件名中出现时，不再推荐使用旧版非 HDR 模式。使用旧版模式时，有 6 个立方体面，面名为 、 、 、 和 。所有 6 个文件的其余路径和文件名应相同。路径和文件名指定为单个字符串，用于代替面名。旧环境文件必须采用可在 Web 上使用的格式，例如 PNG 或 JPEG。*.hdr{face}posxnegxposynegyposznegz{face}

• glTF.showToolbar3D– 在工具栏上显示一个按钮以激活 3D 预览窗口。

• glTF.alwaysOverwriteDefaultFilename– 某些命令会创建新文件，例如导入和导出 GLB、导出 DataURI 以及创建 glTF 验证报告。当这些文件将使用其默认名称保存时，这节省了每次与文件对话框交互的步骤，但确实使覆盖现有文件变得微不足道。将此设置为更安全。truefalse

• glTF.expandOutlineWithSelection– 当编辑器选择更改时，glTF 大纲将扩展以包含当前选择。

• glTF.Validation.enable– 当 true 时，自动运行 glTF 验证器并将发现的任何问题报告到文档问题窗口。

• glTF.Validation.debounce– 等待多个自动请求重新验证 glTF 文档的毫秒数。

• glTF.Validation.maxIssues– 控制 Khronos glTF 验证器报告的最大问题数（不包括 VSCode 自己的 JSON 模式验证生成的任何消息）。

• glTF.Validation.ignoredIssues– 验证期间要忽略的问题代码数组。问题应按问题代码列在数组中，例如 和 。有关完整列表，请参阅 ISSUES.md，或对现有文件运行手动 glTF 验证，并报告消息以查看其代码。例如，要完全禁用空节点的报告，可以使用：ACCESSOR_INDEX_TRIANGLE_DEGENERATENODE_EMPTY[ "NODE_EMPTY" ]

• glTF.Validation.severityOverrides– 这是一个 JSON 对象，用于将问题代码（作为键）映射到严重性代码（作为值）。问题代码与上述相同。严重性代码为：0 表示 ，1 表示 ，2 表示 ，3 表示 。例如，要将空节点的严重性降低到 ，可以指定：glTF.Validation.ignoredIssueserrorwarninginformationhinthint{ "NODE_EMPTY" : 3 }

VSCode 中的 JSON 模式验证支持某些 glTF 2.0 扩展。这意味着 VSCode 将提供悬停工具提示、自动完成 （ + ） 并记录扩展模式冲突的问题指示。这与官方 glTF 验证器执行的任何验证是分开的（并且是额外的）。此项目目前附带的扩展模式包括：CTRLspace

• KHR_animation_pointer
• KHR_draco_mesh_compression
• KHR_lights_punctual
• KHR_materials_anisotropy
• KHR_materials_clearcoat
• KHR_materials_diffuse_transmission
• KHR_materials_dispersion
• KHR_materials_emissive_strength
• KHR_materials_ior
• KHR_materials_iridescence
• KHR_materials_pbrSpecularGlossiness
• KHR_materials_sheen
• KHR_materials_specular
• KHR_materials_transmission
• KHR_materials_unlit
• KHR_materials_variants
• KHR_materials_volume
• KHR_texture_basisu
• KHR_texture_transform
• KHR_xmp
• KHR_xmp_json_ld
• EXT_lights_image_based
• EXT_mesh_gpu_instancing
• EXT_mesh_manifold
• EXT_meshopt_compression
• EXT_texture_webp
• AGI_articulations
• AGI_stk_metadata

可以通过向 GitHub 存储库提交问题或拉取请求来请求对其他扩展的支持。

在 GitHub 上。见 CONTRIBUTING.md。

此扩展使用以下开源项目：

• Babylon.js – 预览窗口中使用的 3D 引擎之一
• Basis Universal – 一种用于纹理的GPU超级压缩格式
• 铯 – 预览窗口中使用的 3D 引擎之一
• Draco – 来自 Google 的网格压缩库
• Filament – 预览窗口中使用的 3D 引擎之一
• 敲除 – 用于数据绑定预览窗口的菜单
• Three.js – 预览窗口中使用的 3D 引擎之一

Apache 2.0，参见 LICENSE.md。

见 CHANGELOG.md。