# SpatialForge

**Repository Path**: yanxuefeng/spatial-forge

## Basic Information

- **Project Name**: SpatialForge
- **Description**: SpatialForge** 是一款运行在鸿蒙系统上的桌面级空间交互增强工具。它利用 **ArkGraphics 3D** 与 **无界动效引擎** 等原生能力，将普通的2D桌面图标、服务卡片甚至第三方应用内的图像元素，自动转化为可交互的3D空间对象。用户可以通过拖拽、旋转、缩放等手势与3D内容自然交互，且所有3D效果在手机、平板、智慧屏等设备上保持一致体验。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SpatialForge

**中文名称**：「3D空间交互助手」—— 鸿蒙桌面与应用3D化改造工具

> 🚀 2026 HarmonyOS创新赛·极客赛道 参赛作品
> 主题方向：**3D空间化**（主）+ **全场景一体协同**
> 核心理念：零侵入、一键3D、全场景空间交互

[https://img.shields.io/badge/HarmonyOS-6.0%252B-007D9C?logo=harmonyos](https://img.shields.io/badge/HarmonyOS-6.0%2B-007D9C?logo=harmonyos)
[https://img.shields.io/badge/License-Apache%25202.0-green.svg](https://img.shields.io/badge/License-Apache%202.0-green.svg)
https://img.shields.io/badge/Status-Prototype-orange
https://img.shields.io/badge/HDC-2026-red

------

## 📖 项目简介

**SpatialForge** 是一款运行在鸿蒙系统上的桌面级空间交互增强工具。它利用 **ArkGraphics 3D** 与 **无界动效引擎** 等原生能力，将普通的2D桌面图标、服务卡片甚至第三方应用内的图像元素，自动转化为可交互的3D空间对象。用户可以通过拖拽、旋转、缩放等手势与3D内容自然交互，且所有3D效果在手机、平板、智慧屏等设备上保持一致体验。

**与现有方案的本质不同**：传统的3D应用需要开发者单独适配，而 SpatialForge 采用系统级注入技术，**无需修改任何应用代码**，即可让整个鸿蒙桌面生态“跃入三维空间”。

> “让每一个应用都能‘跃出屏幕’，让每一次交互都充满空间感。”
> —— SpatialForge

------

## ✨ 核心功能

| 模块                 | 功能描述                                                     |
| :------------------- | :----------------------------------------------------------- |
| 🧊 **桌面图标3D化**   | 将桌面应用图标自动转换为轻量级3D模型，支持拖拽、旋转、倾斜等多点手势操作，图标实时响应手指动作。 |
| 🃏 **服务卡片3D化**   | 天气、时钟、日历等卡片呈现动态3D场景：雨天时雨滴打落、晴天光晕浮动、时钟指针立体旋转。 |
| 📸 **应用内UI 3D化**  | 对购物App的商品图、相册中的照片等，自动生成360°可交互的3D模型，无需开发者适配。 |
| ✨ **自定义3D动效**   | 用户可为不同应用设置个性化3D动效（如音乐图标跳动音符粒子、新闻图标旋转展开）。 |
| 🔄 **多设备一致体验** | 基于鸿蒙分布式能力，3D配置与交互状态在手机、平板、智慧屏间自动同步，并根据屏幕尺寸自适应渲染细节。 |
| ⚡ **零侵入适配**     | 所有3D效果通过系统级渲染拦截实现，不影响原应用任何功能，也无需应用开发者修改一行代码。 |

------

## 🎯 创新亮点

- ✅ **无侵入式3D化**：首创基于鸿蒙`WindowExtension`与渲染管线注入的3D增强方案，一键为所有应用开启空间体验。
- ✅ **低门槛个性化**：普通用户通过简单设置即可调整3D样式与动效强度，无需3D建模知识。
- ✅ **分布式3D协同**：在智慧屏上查看的3D商品模型，可一键流转至手机接续交互，实现真正的全场景空间计算。
- ✅ **性能友好**：基于ArkGraphics 3D的ECS架构，结合动态帧率调节（30~60FPS）与后台降频策略，中端机型也能流畅运行。

------

## 🧠 技术架构

text

```
┌─────────────────────────────────────────────────┐
│                HarmonyOS 6.0+ 桌面环境           │
├─────────────────────────────────────────────────┤
│              SpatialForge (主应用)               │
│  ┌───────────────────────────────────────────┐  │
│  │   配置中心 (用户偏好、设备适配、分布式同步)   │  │
│  └───────────────────────────────────────────┘  │
├─────────────────────────────────────────────────┤
│           核心能力层 (鸿蒙SDK集成)               │
│  • ArkGraphics 3D (ECS场景管理、glTF渲染)        │
│  • 无界动效引擎 (2D/3D融合、粒子系统)            │
│  • 窗口管理Kit (WindowExtension 注入3D图层)     │
│  • 分布式调度Kit (多设备状态同步)                │
│  • AI意图框架 (可选：语音控制3D效果)            │
├─────────────────────────────────────────────────┤
│                系统底层 (GPU/NPU)                │
└─────────────────────────────────────────────────┘
```



### 关键鸿蒙能力调用清单

| 能力/Kit                | 用途                                                         |
| :---------------------- | :----------------------------------------------------------- |
| **ArkGraphics 3D**      | 构建3D场景、加载glTF模型、管理空间交互。                     |
| **无界动效引擎**        | 实现图标“破框”过渡、卡片粒子系统（雨滴/光晕）。              |
| **窗口管理Kit**         | 通过`WindowExtension`捕获第三方应用渲染表面，叠加3D图层。    |
| **分布式数据管理**      | 存储用户3D配置，并利用`DistributedDataKit`实现多设备秒级同步。 |
| **BackgroundTasks Kit** | 后台保活，保证3D配置在桌面长期生效。                         |

------

## 🚀 快速开始

### 环境要求

- **操作系统**：HarmonyOS 6.0 及以上
- **开发工具**：DevEco Studio 5.0+
- **真机推荐**：华为 Pura 80 / Mate 80 系列或支持NPU的设备
- **必要权限**：
  - `ohos.permission.GET_WINDOW`（捕获窗口内容）
  - `ohos.permission.DISTRIBUTED_DATASYNC`（分布式同步）
  - `ohos.permission.VIBRATE`（触感反馈）

### 编译与安装

bash

```
# 1. 克隆仓库
git clone https://gitee.com/yourname/SpatialForge.git

# 2. 使用 DevEco Studio 打开项目

# 3. 完成签名（需华为开发者账号）

# 4. 连接真机，编译运行
```



> **注**：当前版本为概念验证原型，已实现桌面图标3D化与基础动效，应用内UI 3D化模块正在开发中。

------

## 📁 项目结构

text

```
SpatialForge/
├── entry/                         # 主应用模块
│   ├── src/main/
│   │   ├── ets/
│   │   │   ├── entryability/      # 应用入口
│   │   │   ├── pages/             # 设置界面、引导页
│   │   │   ├── 3dengine/          # ArkGraphics 3D封装与场景管理
│   │   │   ├── icon_inject/       # 桌面图标拦截与3D化核心逻辑
│   │   │   └── distributed/       # 分布式配置同步模块
│   │   ├── resources/             # 资源文件（glTF模型、着色器）
│   │   └── module.json5
│   └── ohosTest/                  # 单元测试
├── models/                        # 预置3D模型（开源glTF文件）
├── docs/                          # 架构设计文档、API说明
└── README.md
```



------

## 🔮 未来规划

- 完成 **应用内UI自动3D化** 原型，支持购物类App图片→可交互3D模型（基于AI单目深度估计）。
- 集成 **小艺智能体**，支持语音指令：“把这个商品变成3D”“关闭桌面3D效果”。
- 增加 **自定义模型上传功能**，用户可用自己的glTF文件替换默认图标模型。
- 针对折叠屏设备设计 **展开/折叠自动切换3D强度的自适应模式**。
- 建立 **3D动效组件市场**，允许开发者贡献动效模板并分享。

------

**参赛赛道**：2026 HarmonyOS创新赛·极客赛道
**创意归属**：「3D空间化」+「全场景一体协同」双主题驱动

------

## 📄 许可证

本项目使用 **Apache 2.0** 开源协议，详见 [LICENSE](https://license/) 文件。
内置3D模型资源来源于 [Poly Haven](https://polyhaven.com/) 及社区贡献，采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 协议。

------

## 🙏 致谢

- 华为鸿蒙团队提供的 **ArkGraphics 3D** 与 **无界动效引擎** 技术预览版
- 鸿蒙开发者社区提供的 `WindowExtension` 注入方案参考

------

## 📞 联系方式

- Gitee仓库：https://gitee.com/yanxuefeng/SpatialForge
- 问题反馈：[Issues](https://gitee.com/yourname/SpatialForge/issues)
- 赛事交流：[华为开发者论坛](https://developer.huawei.com/consumer/cn/forum/)

> **注**：本项目为2026 HarmonyOS创新赛参赛作品，目前处于原型验证阶段。欢迎对空间交互感兴趣的开发者提交PR或参与讨论！

**🌟 如果你相信未来的交互属于空间和3D，请为我们点亮一颗 Star！**