探索 Spatial Preview 框架

了解新的 Spatial Preview 框架如何将 Mac 上的内容直接带到 visionOS。探索如何通过跨两个平台进行实时同步和双向编辑来构建动态工作流程。了解 SpatialPreview API、设备发现、2D 和 3D 会话集成，以及新的快速查看功能，为你的 Mac App 提升空间体验。

章节

资源

相关视频

WWDC26

WWDC22

掌握 USD 基础知识

大家好我是Quincy German visionOS团队的软件工程师 Apple Vision Pro上我最常用的功能之一是Mac Virtual Display 它让我能通过Vision Pro提供的虚拟屏幕在Mac上工作在macOS和visionOS 27中将Mac内容预览到Vision Pro变得更简单我很高兴为大家介绍Spatial Preview 这是一个框架让人们在Mac上处理内容时能充分利用 visionOS的空间计算能力你可以通过macOS的Preview App 来体验Spatial Preview框架的实际效果以及其他帮助人们处理空间内容的功能包括3D内容编辑照片级真实渲染相机视角以及空间媒体输出如Apple沉浸式视频帧和空间照片使用Mac Virtual Display 人们可以将内容无缝共享到Vision Pro 在visionOS上 QuickLook App接收这些内容现在允许他们以沉浸式方式工作比如环顾为这个客厅场景设置的不同相机角度这些工具非常有助于感受3D设计的比例和布局比如这个作品有了Spatial Preview 人们现在可以将Mac上的内容延伸到周围的世界中这些功能不只在Preview App中可用它们也作为API向你开放你可以为新的或现有的macOS应用添加功能充分发挥Vision Pro的强大能力这些工具支持空间内容的动态工作流包括跨设备的实时同步和编辑通过实时同步 Cinema 4D和SketchUp 等应用正在改变创作流程解锁实时协作3D工作流比如实时迭代材质变更在本节中我将介绍你也可以做到的方法我将首先概述这个框架它专为开发内容创作工具或任何处理空间内容的应用的开发者设计接下来我将通过一个示例工作流演示如何就地共享和更新文档例如Apple沉浸式视频帧最后我将展示如何创建应用让人们实时完全沉浸在他们正在处理的 3D内容中通过使用Universal Scene Description 这是一种用于描述3D场景的格式本节结束时你将拥有充分利用空间预览框架所需的一切让人们能在visionOS上处理Mac上的内容现在让我们看看框架提供的组件以了解设置起来有多简单

第一步是选择一个端点指向要共享的目标设备如果有人正在使用Mac Virtual Display 可以轻松使用已连接的设备或者你可以在应用中添加设备选择器UI 让人们从同一iCloud账户下附近的任意Vision Pro中选择接下来为内容创建一个空间预览会话预览会话有两种类型文稿预览会话涵盖空间照片视频以及PDF等文稿类型 USD预览会话处理3D内容

会话启动后 Vision Pro上的QuickLook 会被打开你的应用提供给会话的内容随即显示出来在visionOS端无需任何代码来完成设置现在你了解了空间预览会话的工作原理让我们看一个如何通过文稿预览发送和更新文档的示例在这个示例中我将提取一帧 Apple沉浸式视频的静帧该视频由Mac上的Preview App生成然后我将使用Mac Virtual Display端点启动一个文稿预览会话接着我将把图像提供给会话使其显示在QuickLook中让我们看看设置所需的代码

首先创建一个已连接的空间端点观察器从Mac Virtual Display获取空间预览端点然后创建一个文稿预览会话指定文稿类型和会话名称

使用返回的端点在所选设备上启动会话并提供内容URL 请记住 Mac Virtual Display并非始终处于活跃状态因此请考虑将Spatial Preview设备选择器作为UI中的一个视图来集成以便选择其他设备使用SwiftUI中的Sheet来控制其显示时机然后继续创建文稿预览会话就像之前看到的那样使用在UI中选择的设备端点开始使用Spatial Preview就这么简单让我们来看看效果将我编写的代码放入UI中的一个按钮按下后会在visionOS上启动内容我可以在沉浸式模式下查看它这真的很酷让我们更进一步构建一个沉浸式建筑渲染图库

当你调用update contents时你在重用启动会话时打开的同一场景如果你创建一个新的文稿预览会话并调用start 那将启动一个新场景因此对于图库视图我将使用 update contents来确保重用同一场景在这个视图中我将为图库中的所有视频帧创建一排按钮并让按钮在选中时调用会话上的update contents来切换到不同的文件我还设置了一个任务来观察会话状态如果场景在visionOS上被关闭我将在这里收到一个状态变更通知表明会话已失效当你完成一个会话后调用close来结束它 visionOS会自动关闭该场景现在图库使用文稿预览会话的 Update Contents功能在同一场景中实时切换沉浸式渲染图这是让人们审阅设计渲染图并更好地感受其正在处理的内容实际比例的好方法除了Apple沉浸式视频之外许多其他内容类型也能很好地与Spatial Preview配合使用包括空间照片 PDF 标准图像和文件以及3D内容现在你已经了解了如何轻松发送和更新文档让我们看看如何使用 USD Kit与Spatial Preview处理3D内容如果你是USD新手我建议先观看《了解USD基础知识》要了解如何使用新的Swift USD Kit框架我建议观看《探索USD Kit》和《OpenUSD的新功能》在本节中我将介绍如何使用USD Kit 在visionOS上通过你的macOS应用处理3D内容我将介绍如何轻松设置 USD预览会话并开始浏览3D场景浏览相机视角并应用材质覆盖然后我将介绍如何编辑内容以及人们如何在visionOS上与USD进行交互并做出更改包括添加注释和移动对象最后我将介绍空间预览会话的事件和可观察属性包括动画播放和会话同步进度的事件以及如何自定义会话中可用的功能创建USD预览会话与文稿预览会话类似不同之处在于内容是一个USD Kit Stage 当你调用session start时 visionOS上会打开一个场景 USD内容显示在一个体积视图中然后人们可以选择进入沉浸式视图以实际比例查看让我们看看设置此功能的代码与文稿共享一样首先选择目标设备端点然后使用USD Kit将USD内容加载到Stage中将该Stage提供给USD预览会话然后在所选设备端点上启动会话

内容以3D形式显示在 visionOS的这个有界视图中我可以旋转场景来检视它然后进入沉浸式模式以实际比例查看这个场景中设置了一些相机正如你之前看到的选择其中一个将把我移动到该视角我还可以通过将材质覆盖为线框模式来更仔细地检查几何结构这些都是使用Spatial Preview时 visionOS内置的功能你的Mac应用无需额外设置 USD场景可能包含极高保真度的内容这可能对Vision Pro来说渲染负担过重默认情况下 Spatial Preview会在共享前自动优化USD内容包括网格精简纹理降采样以及必要时进行完整场景重建所有这些都是为了确保其在Vision Pro上运行流畅如果场景需要重建它将无法编辑但人们仍然可以查看并添加注释

要退出此优化请在创建会话时传入unmodified参数但是如果禁用优化复杂场景可能无法共享到Vision Pro 且start函数将抛出错误有关如何降低内容渲染成本的指导请查看开发者文档现在让我们看看在macOS和visionOS上编辑USD内容是如何工作的在USD预览会话中人们可以从任一设备进行更改调用常规USD Kit API时会使用实时USD Stage在macOS 和visionOS之间同步内容如果有人想在Mac上对内容进行更改并在visionOS上空间化地查看效果或在visionOS的审阅会话中捕获编辑内容这非常有用在深入代码之前让我们先了解一下 USD Stage是什么以及一些USD术语一个Stage由一层或多层Layer组成 Layer包含USD Prim USD Prim是一个对象可以代表许多不同的特性如3D变换或网格 Variant Set可以在Prim上替换为备用数据我在这个客厅场景中设置了一些USD变体使用Variant Set来改变家具的位置和旋转当我在USD Kit中选择这些变体之一时 Stage会发生变化移动家具到不同位置的编辑会被应用并在macOS和visionOS之间同步工具栏上的按钮在macOS上切换变体产生的家具布局会在visionOS上得到体现我也可以在QuickLook菜单中选择一个变体并在Mac上看到这个变化这是在visionOS上快速迭代 Mac上内容的好方法现在让我们看看如何监听来自visionOS的变更 USD Stage的变更会自动同步你可以使用标准USD通知观察会话中发生的更新例如当有人添加注释时在这里我订阅了对象变更通知它提供了关于哪些USD Prim路径已发生变化的信息我可以遍历这些路径找到注释并在UI中更新它们

对于文字注释除实际文字内容外你还需要作者和注释唯一标识符等信息以这种方式设置注释数据可以让注释显示在visionOS上只要它们是被指定为文稿注释组的USD Prim的子项为了让USD Prim在visionOS上可通过手势编辑需要在其上设置空间可编辑元数据人们也可以在macOS上通过Preview 轻松地在其USD资产上进行设置让我们看看实际效果当我在macOS上应用注释时它会出现在visionOS上如果我在这里评论说我喜欢布局A 这会反映回macOS上的应用中由于这件家具具有空间可编辑元数据我可以移动它比如我想把这把椅子移到窗外这也会在macOS上显示出来让我们回顾一下你可以监听的事件以及可以在USD预览会话中配置的选项

你可以使用USD Preview Session Start上设置的选项来控制 visionOS上QuickLook中可用的功能默认情况下注释对象操控和USD导出都已启用你还可以通过空间预览API事件订阅非USD事件如动画播放时间你可以使用Progress Reporter 监控会话的共享进度如果你希望在大量数据同步到 Vision Pro时在macOS上显示加载进度条这非常有用例如在这里我挂载了USD预览会话提供的时间和播放事件现在我可以按下播放按钮在两个应用中都能看到这只蜂鸟在窗外飞翔的动画当你在应用中采用Spatial Preview时为创作者解锁了许多全新工作流 visionOS内置了SharePlay支持因此协作者可以加入同一个实时会话同时审阅和编辑空间内容我的朋友Joy在这里标记了我的房间布局中的一个问题我将实时进行调整每位参与者的视图立即更新消除了传统资产审阅中的反复沟通

那么你今天如何开始使用Spatial Preview呢我们建议使用USD Kit Swift API 因为Spatial Preview与它无缝配合如果你的Mac应用中已有USD 你可以设置桥接在你的USD安装和USD Kit之间传输编辑内容欲了解更多信息请查看 Spatial Preview开发者文档接下来探索如何充分利用每种类型的预览会话文稿预览会话和USD预览会话它们可以轻松集成到你的Mac应用中无论你是想预览和更新文档还是以沉浸式方式处理3D内容只需几行代码即可开始你可以使用USD Kit和Spatial Preview 更深入地探索3D 以支持USD Stage的实时编辑实现跨设备实时协作包括通过SharePlay 最后充分利用资产审阅工具如材质覆盖相机视角对象操控变体和注释我和团队迫不及待地想看到你的应用如何充分利用Spatial Preview 无论你是在开发创意应用内容审阅工具还是全新的应用类型感谢收看

3:58 - Document Preview Session with Device Picker

// Send and update documents using the Spatial Preview framework

import SwiftUI
import SpatialPreview
let deviceObserver = ConnectedSpatialEndpointObserver()

let previewSession = DocumentPreviewSession(name: "Immersive.aivu", contentType: .aivu)

func startPreview(contentURL: URL, endpoint: SpatialPreviewEndpoint) async throws {
    let endpoint = try await deviceObserver.endpoint
    try await previewSession.start(endpoint: endpoint)
    try await previewSession.updateContents(url: contentURL)
}

@State var showDevicePicker: Bool = false

var body: some View {
    ...
    .sheet(isPresented: $showDevicePicker) {
        SpatialPreviewDevicePicker(isPresented: $showDevicePicker) { endpoint in
            showDevicePicker = false
            Task {
                try await startPreview(filename: filename, endpoint: endpoint)
            }
        }
    }
}

5:20 - Update Document Contents

// Send and update documents using the Spatial Preview framework

import SwiftUI
import SpatialPreview

ForEach(contentURLs, id: \.self) { url in
    Button {
        Task { try await previewSession?.updateContents(url: url) }
    }
}
.task(id: previewSession.map { ObjectIdentifier($0) }) {
    for await state in Observations({ session.state }) {
        if state.isInvalidated {
            previewSession = nil
            break
        }
    }
}

try await previewSession?.close()

7:36 - Edit USD Live

// Edit USD live using USDKit and Spatial Preview

import SpatialPreview
import USDKit

let deviceObserver = ConnectedSpatialEndpointObserver()

var usdSession: USDPreviewSession?

func shareStage(to endpoint: SpatialPreviewEndpoint) async throws -> USDPreviewSession {
    let endpoint = try await deviceObserver.endpoint

    let stageURL = Bundle.main.url(forResource: "sampleScene", withExtension: "usdz")
    let stage = try USDStage.open(stageURL)
    usdSession = USDPreviewSession(stage: stage)

    try await usdSession?.start(endpoint: endpoint)
}

8:56 - Opt out of optimization

// Optimization

import SpatialPreview




let endpoint = try await deviceObserver.endpoint
do {
    try await usdSession.start(endpoint: endpoint, parameters: .unmodified)
} catch USDPreviewSession.Error.assetUnshareable {
    // Handle Asset Unshareable error
}

10:10 - USD Layout Variants

// LayoutVariants.usda
#usda 1.0
over "furniture" (
    variantSets = "Layout"
    variants = { string Layout = "LayoutA" }
)
{
    variantSet "Layout" = {
        "LayoutA" {
            // Default furniture position and rotation
        }
        "LayoutB" {
            // Moves furniture prims to a different position and rotation
        }
        ...
    }
}

10:17 - Edit USD live using USDKit and Spatial Preview

// Edit USD live using USDKit and Spatial Preview

import SpatialPreview
import USDKit

func applyLayoutVariant(named layoutVariantName: String) throws {
    let prim = stage.prim(at: SdfPath("/root/furniture"))
    try prim.variantSets?.setSelection("Layout", variantName: layoutVariantName)
}

10:49 - USD Stage Observations

// Edit USD live using Spatial Preview

import SpatialPreview
import USDKit

let observerToken: ObservationToken

observerToken = stage.addObserver(for: UsdStage.ObjectsDidChange.self) { notice in
    for path in notice.resyncedPaths {
        let prim = notice.stage.prim(at: path)
        guard prim.isValid else { continue }
        if prim.isAnnotation {
            // Handle annotation change
            break
        }
    }
}

11:13 - Annotation Spec

// Annotation spec example

AppleTextAnnotation {
    // The textual representation of this annotation
    string text

    // The identifier for this specific author
    uniform string author

    // An identifier that is unique to your data tracking system
    uniform string identifier
}

/__documentAnnotationGroup__

11:33 - Metadata for Object Manipulation

// Metadata required for object manipulation in Quick Look

customData = {
    dictionary apple = {
        bool spatialEditable = 1
    }
}

12:16 - Session Options and Events

// Spatial Preview session options and events

import SpatialPreview
import USDKit

session.start(endpoint: endpoint, options: [.annotations, .perObjectManipulation, .export])

func listenForEvents(session: USDPreviewSession) async {
    for await event in session.events {
        if case .timeChanged(let time) = event {
            playbackModel.timeCode = time
        } else if case .playbackStateChanged(let isPlaying) = event {
            playbackModel.playbackStateChanged(isPlaying)
        }
    }
}

12:38 - Observe Session Progress

// Observe Spatial Preview session progress

import SpatialPreview
import USDKit

@State private var sessionProgress: Double = 0

var body: some View {
    ...
    .task(id: usdSession.map { ObjectIdentifier($0) }) {
        guard let session = usdSession else { return }
        for await fraction in Observations({ session.progress.fractionCompleted }) {
            sessionProgress = fraction
        }
    }
    .overlay(alignment: .bottom) {
        ProgressView(value: sessionProgress)
            .padding()
    }
}

0:00 - Introduction
The Spatial Preview framework, which lets developers extend content from Mac into visionOS using Mac Virtual Display. Previews what the session covers: an overview of the framework, document preview, and USD preview for live 3D workflows.
2:37 - Learn about Spatial Preview
Explores the core components of the Spatial Preview framework: selecting a spatial endpoint, creating a preview session, and launching Quick Look on visionOS. Covers the two session types—Document Preview Session and USD Preview Session—and explains that no visionOS code is required.
3:30 - Document Preview
Walks through using DocumentPreviewSession to send files like Apple Immersive Video frames from a Mac app to visionOS. Covers obtaining a Mac Virtual Display endpoint with ConnectedSpatialEndpointObserver, starting a session, providing content URLs, integrating SpatialPreviewDevicePicker in SwiftUI, and using updateContents to build a gallery experience that reuses the same scene.
6:36 - USD Preview
Shows how to share and live-edit USD content from a Mac app on visionOS using USDPreviewSession with a USDKit stage. Covers selecting a device, opening a USD stage, starting the session, and handling unshareable assets via the optimization parameter.
9:16 - Editing Features
Covers the rich set of Quick Look editing features available through USD Preview: USD layout variants, annotation authoring with AppleTextAnnotation, object manipulation with spatialEditable metadata, and session options including playback events and progress monitoring via ProgressReporter.
13:28 - Next steps
Summarizes how to get started with Spatial Preview using USDKit Swift APIs and bridging for existing USD apps. Encourages developers to explore Document Preview Session, USD Preview Session, live editing, SharePlay collaboration, and the full suite of asset review tools.

探索“入门汇总”

及时了解最新动态

探索“平台”

精选

探索“技术”

精选

探索“社区”

精选

探索“文档”

发布说明

探索“下载”

精选

探索“支持”

精选

快速链接

探索 Spatial Preview 框架

章节

资源

相关视频

WWDC26

WWDC22