Voxel Kit for HarmonyOS
Voxel Kit for HarmonyOS 是面向 ArkUI 的体素 SDK。它把“拿到一份 JSON、VOX 或 VFP 文件，安全地读取、显示、编辑和导出”拆成可以按需组合的能力：
- VoxelViewer：负责可见的模型预览，包括异步导入、ArkGraphics 场景、光照、载入动画、背景、单指旋转和双指平移/缩放。
- VoxelEditor：在同一 Viewer 上按需恢复权威体素，提供点击、滑动连续选择、框选、多选、自由颜色编辑、选区变换、撤销重做和 JSON/VFP 保存。
- Reader API：负责不依赖 3D 引擎的 VFP 容器读取、目录检查、CRC 校验以及区段、内嵌 GLB 预览和 PNG 缩略图提取。
- Native Compiler：负责在后台将 JSON 或单模型 VOX 编译为 VFP，并可从可信
VOX0重建缓存、PRVWGLB 与THMBPNG。 - Turntable GIF：通过 Native 优先、ArkTS 回退的离屏光栅生成透明 360° GIF，无需录屏或进入编辑模式。
- 视频导出与分享：将 VFP 导出为可保存到相册、发送或上传的 H.264/MP4；按需要选择是否同时保留可恢复的编辑源。
它适合在作品详情、资产浏览器、导入页和社区内容中展示 .json 或 .vfp 体素模型。宿主应用负责 Picker、网络、业务状态与页面布局；组件负责预览与资源生命周期。
获取 Kit
Voxel Kit for HarmonyOS 推荐通过字符科技 OHPM 仓安装：在宿主工程根目录直接执行 ohpm install voxel-kit --registry http://ohpm.charactech.cn/repos/ohpm/。可在 OHPM 获取 voxel-kit 查看包信息；完整安装步骤见安装与第一个预览。
先判断你需要哪一部分
| 你的目标 | 需要的能力 | 从哪里开始 |
|---|---|---|
| 页面上展示模型，让用户旋转、缩放、平移 | VoxelViewer | 快速开始 |
| 在预览基础上选择、放置、替换、删除和保存体素 | VoxelEditorController | 编辑器概览与接入 |
| 自己制作背景、加载状态或使用统一产品 Loading | VoxelViewer 的 Options/Builder | VoxelViewer 概览 |
| 选择 VFP 后先展示文件版本、区段与 META | VfpPackageReader | Reader API 概览 |
| 取出 VFP 中本来就带着的 GLB 预览 | extractPreviewGlb() | VFP Reader API |
| 取出 VFP 用于资产卡片的 PNG 缩略图 | extractThumbnail() | VFP Reader API |
| 将 JSON / 单模型 VOX 打包为 VFP，或重建 VFP 缓存 | VfpCompiler | VFP Compiler API |
| 编辑并按来源格式保存 JSON/VFP | VoxelEditorController | 保存、另存为与性能 |
| 生成透明 360° GIF | VoxelTurntableExporter / Editor 导出入口 | VoxelTurntableExporter |
| 导出视频到相册、发送或上传 | VoxelKit.createGltiExporter() | 导出到相册与分享 |
| 从保留编辑源的视频包取回 VFP | VoxelKit.createGltiReader() | 导出到相册与分享 |
五分钟内完成的事
- 在工程根目录执行
ohpm install voxel-kit --registry http://ohpm.charactech.cn/repos/ohpm/。 - 在页面字段中创建一个长期存在的
VoxelViewerController，不要在build()中创建。 - 将
voxel_grid.png放入宿主 HAP rawfile，并在首次加载前设置unitGridTexture = $rawfile('voxel/voxel_grid.png')，让单位体素描边首帧可见。 - 在
build()中放入VoxelViewer({ controller })。 - 通过
loadText()、loadBytes()或loadUri()串行导入模型，并在页面永久离开时dispose()。
完整代码见 安装与第一个预览。
选择正确能力
| 你要做的事 | 推荐入口 |
|---|---|
| 首次接入并显示模型 | 安装与第一个预览 |
| 管理加载、背景、手势和页面释放 | 接入与生命周期 |
| 按需进入编辑、选择和保存 | VoxelEditor 概览 |
| 查询公开 ArkTS API | Preview API |
| 在 HarmonyOS 中读取 VFP、校验容器或提取内嵌预览 | VFP Reader API |
| 在 HarmonyOS 中编译 JSON/VOX 或重建 VFP 缓存 | VFP Compiler API |
| 导出视频到相册或恢复其中保留的 VFP | 导出到相册与分享 |
| 判断“可预览”是否等于“可信资产” | VFP 可信边界 |
| 构建、真机验证、准备 OHPM 发布 | 开发与发布概览 |
预览成功不等于权威验证
Viewer 的快速预览可直接使用 PMSH 等派生缓存，因此预览成功不自动等价于 VOX0 与 source hash 已完成权威验证。显式调用 enterEdit()、validateAuthoritative() 或 Native 缓存重建时才会进入相应的权威数据流程。