# Spatial Video

[English](README.md) | [简体中文](README_zh.md)

Spatial Video 是一款基于 PICO OS 6 的参考示例应用，使用 PICO Spatial SDK 演示空间视频播放最佳实践，涵盖 3D 视频渲染、沉浸式播放与 Spatial UI 组件。

## 概览

Spatial Video 在空间环境中实现沉浸式视频播放，提供交互式控件与沉浸式场景体验。本示例是开发者的实践参考，演示了如何使用 Spatial SDK 实现视频播放、Spatial UI 设计与沉浸式媒体体验。

![Screenshot](.github/screenshot.png)

## 功能特性

Spatial Video 示例展示了 PICO Spatial SDK 的以下核心能力：

- **沉浸式视频播放**：支持 4K/8K 的左右格式（SBS）立体 3D 视频播放
- **双显示模式**：平面视频面板与沉浸式 360° 球形模式
- **交互式控件**：播放/暂停、进度拖拽、音量调节与沉浸模式切换
- **Spatial UI 设计**：遵循 PICO 设计规范的 3D UI 元素
- **高级视频管理**：播放状态处理、进度追踪与生命周期管理
- **WindowContainer 与 Stage 管理**：使用 PICO 空间容器进行空间布局管理

## 环境要求

构建和运行本项目前，请参照 PICO Spatial SDK 官方文档完成开发环境配置：

- [PICO Spatial SDK 环境配置指南（中国大陆）](https://developer-cn.picoxr.com/document/spatial-sdk/set-up-development-environment/)
- [PICO Spatial SDK 环境配置指南（非中国大陆）](https://developer.picoxr.com/document/spatial-sdk/set-up-development-environment/)

## 快速开始

### 1. 克隆项目

```bash
git clone <repository-url>
cd SpatialVideo
```

### 2. 在 Android Studio 中打开项目

启动 Android Studio，选择 **Open an Existing Project**，然后选择 `SpatialVideo` 目录。

### 3. 运行项目

#### 在模拟器上运行

1. 打开 **Device Manager**（可通过工具栏或 **Tools > Device Manager** 进入）
2. 点击 **Add a new device** > **Create a PICO Emulator**
3. 在 **Device Manager** 中启动模拟器
4. 点击 **Run 'app'** 启动应用

#### 在物理设备上运行

1. 将 PICO 设备连接至开发机
2. 在设备上启用 **USB 调试（USB Debugging）**
3. 点击 **Run 'app'** 将应用直接部署到设备

## 项目结构

Spatial Video 示例采用针对视频播放场景优化的模块化架构：

```txt
SpatialVideo/
├── app/                                  # 主应用模块
│   └── src/main/
│       ├── java/com/pico/spatial/sample/spatialvideo/ # Kotlin 源代码
│       │   ├── Main.kt                     # 应用入口
│       │   ├── data/                       # 数据与状态管理
│       │   │   ├── PlaybackManager.kt      # 视频播放控制
│       │   │   ├── PlaybackState.kt        # 播放状态定义
│       │   │   ├── VideoAssetBundle.kt     # 视频资源管理
│       │   │   └── VideoEffectManager.kt   # 视频特效控制
│       │   ├── di/                         # 依赖注入
│       │   │   └── VideoModule.kt          # 视频相关 DI 模块
│       │   ├── ecs/                        # 视频面板的 ECS 实现
│       │   │   └── VideoEntityAssembler.kt # 视频实体创建
│       │   ├── platform/                   # 平台相关实现
│       │   │   ├── LaunchActivity.kt       # Android 启动 Activity
│       │   │   └── SpatialApplication.kt   # 应用初始化
│       │   └── ui/                         # UI 组件
│       │       ├── ImmersiveScene.kt        # 沉浸式 3D 场景
│       │       ├── PlaybackToolbar.kt       # 播放控制工具栏
│       │       ├── SpatialVideoScreen.kt    # 主视频界面
│       │       └── VideoViewModel.kt        # UI 状态 ViewModel
│       ├── res/                            # Android 资源
│       └── AndroidManifest.xml             # 包含 Spatial 组件声明的应用清单
├── editor-asset/                         # 空间开发编辑器资源
│   └── src/main/res3d/videoSample/       # Spatial Editor 项目
│       ├── Build/                         # 已构建的资源包
│       ├── Sources/                       # 源资源与场景
│       │   ├── Assets/                    # 贴图与 3D 模型
│       │   ├── Components/                # ECS 组件
│       │   └── Scenes/                    # 场景定义（USDZ 文件）
│       └── ModelView                      # 3D 模型视图
├── gradle/                               # Gradle 依赖与构建脚本
├── build.gradle.kts                      # 根构建配置
└── settings.gradle.kts                   # 项目设置与 SDK 配置
```

## 编辑器资源与着色器图材质

`editor-asset/` 目录包含 Spatial Editor 项目文件及定义高级视频特效的着色器图材质：

### 着色器图材质

应用包含三种专用着色器图材质：

#### 1. DefaultVideo（`DefaultEffect.usda`）

标准渲染的基础视频播放材质。采用简单的纹理采样与转换，适用于常规视频播放场景。

#### 2. PortalEffectMaterial（`PortalEffect.usda`）

带有几何修改器的传送门式视频投影特效材质。核心功能包括：用于 3D 投影的光线-球体相交计算、基于视角与位置的动态 UV 生成，以及可自定义的参数（球体半径、FOV、距离缩放）。

#### 3. StereoMaterial（`StereoEffect.usda`）

用于沉浸式体验的立体视频渲染材质。核心功能包括：左右眼检测与切换、使用 `blurMask2.png` 的视频遮罩混合、用于 3D 效果的 IPD 调节，以及基于视口深度和摄像机位置的高级 UV 扭曲。

### 自定义着色器图材质

如需修改或自定义着色器图材质，请按以下步骤操作：

1. 在 Spatial Editor 中打开 `editor-asset/src/main/res3d/videoSample/videoSample.spatialproject`
2. 导航至 **Scenes** 文件夹访问 USD 文件
3. 使用着色器图编辑器编辑材质
4. 重新构建资源包以在应用中生效

## 3D 资源

应用使用的额外 3D 资源位于 `editor-asset/src/main/res3d/videoSample/Sources/Assets/`：

- **sphere.usdz**：用于沉浸式 360° 视频投影的 3D 球体模型
- **blurMask2.png**：用于视频边缘平滑过渡的 Alpha 遮罩

## 视频源

本示例通过远程 HTTPS URL 流式播放左右格式（SBS）立体视频。

- 默认视频源（模拟器）：`https://lf-devtools.picoxr.com/obj/spatial-toolbox/examples/cave_4096x2048_sbs.mp4`
- 高分辨率视频源（实体设备）：`https://lf-devtools.picoxr.com/obj/spatial-toolbox/examples/cave_8192x4096_sbs.mp4`
- 播放需要网络连接。

## 学习资源

深入了解空间应用开发，欢迎访问官方开发者网站获取完整资源：

- [PICO 开发者网站（中国大陆）](https://developer-cn.picoxr.com/)
- [PICO 开发者网站（非中国大陆）](https://developer.picoxr.com/)

## 许可证

© 2026 PICO。本项目的源代码依据 [Apache 2.0 License](LICENSE.txt) 协议开源。本项目的美术资产（包括但不限于纹理、3D 模型和音频）基于 [Creative Commons BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授权。

本示例使用的流式空间视频内容仍归各自版权方所有，仅授权**在本示例项目范围内有限使用**。

使用限制：

- 以任何形式对资源进行修改、编辑、改编或创作衍生作品
- 以任何形式复制、分发、发布或上传至外部平台或服务
- 超出本项目范围的任何商业、推广或其他未授权用途

使用上述资源即视为接受以上限制条款。**版权所有 © PICO。**

## 支持

如有任何问题、疑惑或功能建议，欢迎通过 [PICO 开发者支持门户](https://picodevsupport.freshdesk.com/support/home) 提交工单与我们联系。

---

为空间应用开发者提供的官方参考示例
